8.1. 슈퍼바이저 에이전트¶

슈퍼바이저 에이전트는 실행 중인 모든 모델의 상태와 리소스 사용량을 지속적으로 모니터링하고, 안정성과 효율성을 보장하기 위해 조율된 조치를 취하는 중앙 집중식 의사결정 시스템입니다. 장애가 발생한 모델을 자동으로 재시작하고, 유휴 모델을 퇴출하여 리소스를 확보하며, 잠재적인 문제를 사전에 예측할 수도 있습니다.

개념¶

Backend.AI GO는 여러 모델을 동시에 실행할 수 있으며, 각 모델은 GPU 메모리, 시스템 RAM, CPU를 소비합니다. 관리 체계 없이는 장애가 발생한 모델이 감지되지 않거나, 유휴 모델이 귀중한 리소스를 무기한으로 낭비할 수 있습니다.

슈퍼바이저 에이전트는 3계층 아키텍처를 도입하여 이 문제를 해결합니다:

┌─────────────────────────────────────────────────────┐
│  지능 계층                                           │
│  예측 분석 · 적응형 튜닝 · 웹훅                        │
└──────────────────────┬──────────────────────────────┘
┌──────────────────────▼──────────────────────────────┐
│  의사결정 계층                                        │
│  슈퍼바이저 에이전트 · 정책 엔진 · 리소스 중재자         │
└──────────────────────┬──────────────────────────────┘
┌──────────────────────▼──────────────────────────────┐
│  기반 계층                                           │
│  이벤트 버스 · 하트비트 모니터 · 훅 레지스트리           │
└─────────────────────────────────────────────────────┘

• 기반 계층: 문제를 감지합니다 — 하트비트 검사, 유휴 추적, 생명주기 이벤트.
• 의사결정 계층: 무엇을 할지 결정합니다 — 정책 평가, 충돌 해결, 조치 실행.
• 지능 계층: 문제를 예측합니다 — 사용량 예측, 적응형 파라미터 튜닝, 외부 알림.

시작하기¶

슈퍼바이저 활성화¶

1. 설정 > 슈퍼바이저로 이동합니다.
2. 슈퍼바이저 에이전트 스위치를 켜서 활성화합니다.
3. 구성 프리셋을 선택합니다 (아래 참조).

활성화되면 슈퍼바이저는 다중 티어 의사결정 루프를 시작하여 모델 상태와 시스템 리소스를 주기적으로 확인합니다.

구성 프리셋¶

세 가지 내장 프리셋으로 슈퍼바이저의 동작을 빠르게 조절할 수 있습니다:

• 보수적: 최소한의 개입. 장애 모델 재시작과 고정 모델 보호만 수행합니다. 안정적인 장기 운영 환경에 적합합니다.
• 균형: 유휴 퇴출과 최적화가 활성화된 적절한 리소스 관리. 대부분의 사용자에게 권장됩니다.
• 적극적: 선제적 리소스 회수. 짧은 유휴 타임아웃, 낮은 압력 임계값, 더 많은 재시작 시도. GPU 메모리가 제한된 장비에 적합합니다.

상태 모니터링¶

슈퍼바이저는 로드된 각 모델의 추론 서버가 정상 응답하는지 주기적으로 확인하는 하트비트 모니터를 모델별로 실행합니다.

상태 전이¶

각 모델은 네 가지 상태를 거칩니다:

Unknown → Healthy → Degraded → Dead
                  ↑           ↓
                  └───────────┘
                    (복구)

• Healthy (정상): 모델이 상태 검사에 정상적으로 응답합니다.
• Degraded (저하): 연속으로 여러 번 상태 검사에 실패했지만, 아직 Dead 임계값에 도달하지 않았습니다.
• Dead (중단): 모델이 완전히 응답을 멈췄습니다.

모델이 Dead 상태로 전환되면 슈퍼바이저가 설정된 최대 횟수까지 자동으로 재시작할 수 있습니다.

모델 고정¶

모델 고정 기능을 사용하면 유휴 추적이나 리소스 최적화 정책에 의해 모델이 퇴출되는 것을 방지할 수 있습니다. 고정된 모델은 항상 실행 상태를 유지하며, 다른 정책과 관계없이 장애 시 자동으로 재시작됩니다.

모델을 고정하려면 모델 목록에서 우클릭하고 모델 고정을 선택하거나, API를 사용합니다:

curl -X POST http://localhost:8090/api/v1/lifecycle/pin \
  -H "Content-Type: application/json" \
  -d '{"model_id": "my-important-model"}'

유휴 추적¶

슈퍼바이저는 각 모델이 마지막으로 사용된 시점(추론 요청 기준)을 추적합니다. 설정된 유휴 타임아웃을 초과한 모델은 퇴출 대상이 되어 GPU 메모리와 RAM을 다른 모델에게 양보합니다.

• 자동 갱신: 모든 추론 요청이 모델의 마지막 활동 타임스탬프를 자동으로 업데이트합니다. 별도의 설정이 필요 없습니다.
• 고정 모델은 제외: 고정된 모델은 비활성 상태로 인한 퇴출 대상에서 제외됩니다.

정책 엔진¶

슈퍼바이저는 우선순위 기반 정책 엔진을 사용하여 어떤 조치를 취할지 결정합니다. 다섯 가지 내장 정책이 매 의사결정 주기마다 평가됩니다:

두 정책이 상충하는 조치를 제안하면(예: 하나는 모델 유지, 다른 하나는 퇴출) 항상 더 높은 우선순위의 정책이 우선합니다. 모든 충돌은 투명성을 위해 감사 로그에 기록됩니다.

감사 로그¶

슈퍼바이저가 내린 모든 결정은 상세한 감사 로그에 기록됩니다. 각 항목에는 다음이 포함됩니다:

• 타임스탬프 및 결정 ID
• 결정 시점의 시스템 스냅샷 (로드된 모델, 상태, 리소스 사용량)
• 평가된 정책 및 제안된 조치
• 해결된 충돌 (어떤 정책이 이겼는지와 그 이유)
• 수행된 조치 및 결과 (성공, 실패, 또는 건너뜀)

감사 로그 보기¶

설정 > 슈퍼바이저로 이동하여 최근 결정 섹션을 확인하세요. 항목을 클릭하면 전체 스냅샷 요약, 조치 목록, 충돌 기록 등 세부 정보가 표시됩니다.

Management API를 통해서도 감사 로그를 조회할 수 있습니다:

curl "http://localhost:8090/api/v1/supervisor/audit?limit=20"

폴백 라우팅¶

슈퍼바이저는 Continuum Router와 연동하여 자동 장애 조치를 제공합니다. 기본 모델이 응답하지 않을 때:

1. 슈퍼바이저가 하트비트 모니터링을 통해 장애를 감지합니다.
2. 폴백 경로를 활성화하여 추론 요청을 지정된 백업 모델로 전환합니다.
3. 기본 모델이 복구되면 폴백 경로가 비활성화되고 트래픽이 정상으로 돌아옵니다.

이를 통해 모델 장애 중에도 API 클라이언트가 최소한의 중단만 경험하도록 보장합니다.

예측 분석¶

슈퍼바이저는 과거 사용 패턴을 분석하여 선제적으로 결정을 내릴 수 있습니다:

• 사용량 예측: 지수 가중 이동 평균(EWMA) 분석을 사용하여 각 모델이 다음 한 시간 동안 받을 요청 수를 예측합니다.
• 장애 예측: 불안정성, 메모리 누수, 열 스로틀링, 레이턴시 저하의 초기 징후를 감지합니다.
• 수요 기반 사전 로드: 사용 추세에 따라 곧 필요할 것으로 예측되는 모델을 자동으로 로드합니다.

예측 결과 보기¶

슈퍼바이저 설정 페이지의 예측 분석 섹션에서 다음을 확인할 수 있습니다:

• 모델별 사용량 예측 테이블 (예측 요청/시간, 추세 방향, 신뢰도)
• 권장 조치와 함께 장애 예측을 보여주는 위험 지표

적응형 튜닝¶

슈퍼바이저는 결과를 추적하여 자체 결정으로부터 학습할 수 있습니다:

• 결과 피드백: 조치를 실행한 후(예: 모델 재시작) 시스템이 목표가 달성되었는지 확인합니다.
• 파라미터 조정: 성공률을 기반으로 슈퍼바이저가 안전 범위 내에서 내부 파라미터를 조정하여 향후 결정을 개선합니다.
• 변경 속도 제한: 진동을 방지하기 위해 조정은 사이클당 설정 가능한 최대 비율로 제한됩니다.

설정 > 슈퍼바이저에서 튜닝 히스토리를 확인하여 어떤 파라미터가 조정되었는지, 이전 및 새 값, 각 변경의 이유를 확인할 수 있습니다.

외부 연동¶

웹훅¶

슈퍼바이저 이벤트에 대한 실시간 알림을 받을 수 있도록 웹훅 엔드포인트를 등록할 수 있습니다:

• 상태 변경
• 자동 재시작
• 모델 퇴출 및 사전 로드
• 폴백 활성화
• 리소스 경고
• 장애 예측

각 웹훅 전송에는 페이로드 검증을 위한 HMAC-SHA256 서명이 포함됩니다 (서명 시크릿이 설정된 경우).

웹훅 추가 방법:

1. 설정 > 슈퍼바이저로 이동합니다.
2. 웹훅 섹션으로 스크롤합니다.
3. 이름, URL을 입력하고 수신할 이벤트 유형을 선택합니다.
4. 웹훅 추가를 클릭합니다.

테스트 버튼을 사용하여 연결을 확인할 수 있습니다.

Prometheus 메트릭¶

Prometheus 메트릭 엔드포인트를 활성화하여 슈퍼바이저 및 모델 상태 데이터를 수집할 수 있습니다:

curl http://localhost:8090/metrics

사용 가능한 메트릭은 다음과 같습니다:

• bgo_model_health_status — 모델별 상태 (0=중단, 1=저하, 2=정상)
• bgo_model_request_total — 모델별 총 요청 수
• bgo_model_inference_latency_seconds — 추론 레이턴시 백분위수 (p50, p95, p99)
• bgo_supervisor_decisions_total — 조치 유형별 결정 수
• bgo_resource_gpu_memory_usage_ratio — GPU 메모리 사용률
• bgo_resource_system_memory_usage_ratio — 시스템 RAM 사용률

OpenTelemetry (OTLP)¶

OpenTelemetry 수집기를 사용하는 환경에서는 슈퍼바이저 구성에서 OTLP 내보내기를 활성화하고 수집기 엔드포인트를 지정하세요.

생명주기 이벤트 (SSE)¶

헤드리스 또는 웹 클라이언트의 경우, 슈퍼바이저는 Server-Sent Events (SSE)를 통해 생명주기 이벤트를 스트리밍합니다:

curl -N http://localhost:8090/api/v1/lifecycle/events

이벤트에는 모델 로드/언로드, 상태 변경, 유휴 타임아웃, 자동 재시작, 리소스 압력 경고가 포함됩니다. 이를 통해 외부 도구가 폴링 없이 실시간으로 시스템 변경에 대응할 수 있습니다.

API 레퍼런스¶

슈퍼바이저 엔드포인트¶

생명주기 엔드포인트¶

안전 설계¶

슈퍼바이저는 fail-open(장애 시 개방) 철학으로 설계되었습니다:

• 기반 훅이 항상 활성 상태: 기반 계층의 하트비트 및 생명주기 훅은 절대 비활성화되지 않습니다. 슈퍼바이저 에이전트 자체에 장애가 발생하더라도 이 훅들이 기본적인 상태 모니터링과 자동 재시작을 계속 제공합니다.
• 에이전트 자체 하트비트: 슈퍼바이저는 자체 하트비트를 발신합니다. 프론트엔드나 Management API가 슈퍼바이저의 하트비트 손실을 감지하면 기반 계층의 훅 기반 동작으로 폴백합니다.
• Continuum Router 폴백: 슈퍼바이저 다운타임 중에도 Continuum Router의 폴백 모델 구성이 API 요청이 계속 처리되도록 보장합니다.

이 계층적 접근 방식은 단일 컴포넌트의 장애가 전체 시스템을 중단시키지 못하도록 보장합니다.