콘텐츠로 이동

8.4. 분산 추론 라우팅

로드 밸런싱이 활성화되면 Backend.AI GO는 추론 요청을 원격 노드로 투명하게 라우팅합니다. 요청된 모델이 로컬에 로드되어 있지 않으면 추론 프록시가 분산 모델 인덱스에서 모델을 조회하여 해당 모델을 보유한 원격 노드로 요청을 전달합니다.

작동 원리

추론 프록시는 로컬 우선 전략을 사용합니다:

  1. 로컬 해석: 요청된 모델이 Continuum Router 포트 또는 모델 서버 포트를 통해 로컬에 로드되어 있는지 확인합니다.

  2. 원격 폴백: 모델을 로컬에서 찾지 못하고 로드 밸런싱이 활성화된 경우, InferenceRouter가 모델을 해당 모델을 보유한 접근 가능한 원격 노드로 해석합니다.

  3. 인증된 전달: 프록시는 노드의 API 키와 함께 Authorization: Bearer 헤더를 추가하여 원격 노드의 API로 요청을 전달합니다.

이 과정은 호출자에게 완전히 투명합니다. 요청 및 응답 형식은 변경되지 않으며, 라우팅 레이어는 OpenAI 호환 API를 사용하는 클라이언트에게 보이지 않습니다.

분산 라우팅 활성화

분산 라우팅은 로드 밸런싱 설정으로 제어됩니다. 활성화하려면:

  1. 설정 > 노드를 엽니다.
  2. 로드 밸런싱을 활성화합니다.
  3. 라우팅 전략을 선택합니다 (아래 참조).

로드 밸런싱이 비활성화되면 모든 추론 요청은 로컬에서 처리됩니다. 로드 밸런싱이 활성화된 상태에서 로컬 노드에 요청된 모델이 없으면 요청이 자동으로 원격 노드로 라우팅됩니다.

라우팅 전략

InferenceRouter는 네 가지 전략을 지원합니다:

전략 동작
priority 우선순위가 가장 높은 노드를 선호합니다 (노드별로 설정 가능).
round-robin 사용 가능한 노드를 순서대로 순환합니다.
least-loaded 현재 진행 중인 요청 수가 가장 적은 노드로 라우팅합니다 (실시간 부하 기준).
fastest 측정된 지연 시간이 가장 낮은 노드로 라우팅합니다.

설정 > 노드 > 로드 밸런싱에서 전략을 설정합니다.

서킷 브레이커

각 원격 노드에는 연쇄 장애를 방지하는 서킷 브레이커가 연결되어 있습니다.

  • 임계값: 특정 노드에 3번 연속 장애가 발생하면 서킷이 열리고 해당 노드는 후보 선택에서 제외됩니다.
  • 초기화: 60초 후 서킷이 반열림(half-open) 상태로 전환되어 단일 프로브 요청이 통과할 수 있습니다. 프로브 성공 시 서킷이 닫히고, 또 다른 장애가 발생하면 즉시 재개방됩니다.
  • 라우팅 영향: 서킷이 열린 노드는 엔드포인트 해석 시 건너뜁니다. 모든 후보의 서킷이 열려 있는 경우 요청은 503을 반환합니다.

서킷 브레이커는 페일오버 메커니즘과 독립적으로 동작합니다. 서킷이 열린 노드는 페일오버 대상으로도 요청을 받지 않습니다.

자동 페일오버

로드 밸런싱 설정에서 failoverEnabled가 true(기본값)인 경우, 프록시는 실패한 요청을 대체 노드에서 재시도합니다.

페일오버는 다음 상황에서 트리거됩니다:

  • 선택된 노드에 연결 오류가 발생하거나,
  • 노드가 5xx 상태 코드로 응답하는 경우.

트리거 시 프록시는 실패한 노드를 제외하고 엔드포인트를 재해석하여 요청을 한 번 재시도합니다. 원본 요청 본문이 그대로 재전송됩니다.

스트리밍 페일오버 제한

페일오버는 첫 번째 SSE 청크가 클라이언트에 전송되기 전에만 가능합니다. 스트리밍이 시작된 후에는 응답이 커밋되고 오류가 클라이언트에 직접 전파됩니다. 비스트리밍 요청은 대체 노드에서 전체 재시도를 지원합니다.

통합 모델 목록

GET /api/v1/inference/models (OpenAI 호환) 엔드포인트는 통합된 목록을 반환합니다:

  • 로컬 모델 — 로컬 추론 서버에서 직접 보고된 모델.
  • 원격 모델 — 분산 모델 인덱스를 통해 발견된 모델로, "owned_by": "remote"로 표시됩니다.

중복된 모델 ID는 중복 제거됩니다. 동일한 ID가 로컬과 원격 모두에 있는 경우 로컬 모델이 항상 우선합니다.

{
  "object": "list",
  "data": [
    { "id": "llama-3-8b-instruct", "object": "model", "owned_by": "llama.cpp" },
    { "id": "mistral-7b-instruct", "object": "model", "owned_by": "remote" }
  ]
}

분산 풀 상태

두 개의 API 엔드포인트가 분산 풀의 상태를 제공합니다.

추론 상태 (요약)

GET /api/v1/inference/status는 로드 밸런싱이 활성화된 경우 distributed 필드를 반환합니다:

{
  "available": true,
  "routerRunning": true,
  "routerPort": 8080,
  "loadedModels": 1,
  "llmModels": 1,
  "diffusionModels": 0,
  "distributed": {
    "enabled": true,
    "strategy": "priority",
    "totalNodes": 2,
    "onlineNodes": 2,
    "remoteModels": 3
  }
}

전체 분산 상태

GET /api/v1/pool/distributed-status는 노드별 세부 정보를 포함한 전체 풀 보기를 반환합니다:

{
  "enabled": true,
  "strategy": "priority",
  "totalNodes": 2,
  "onlineNodes": 2,
  "models": [
    {
      "id": "mistral-7b-instruct",
      "availableOn": ["node-fingerprint-abc"]
    }
  ],
  "endpoints": [
    {
      "fingerprint": "node-fingerprint-abc",
      "baseUrl": "http://192.168.1.50:8080",
      "status": "online",
      "latencyMs": 12,
      "loadedModelCount": 2,
      "priority": 5
    }
  ]
}

이 엔드포인트는 get_distributed_pool_status Tauri IPC 명령을 통해 프론트엔드에서도 접근할 수 있습니다.

라우팅 통계

GET /api/v1/pool/routing-stats는 노드별 요청 메트릭과 서킷 브레이커 상태를 반환합니다:

{
  "nodes": [
    {
      "fingerprint": "node-fingerprint-abc",
      "totalRequests": 150,
      "successCount": 147,
      "failureCount": 3,
      "avgLatencyMs": 42.5,
      "activeRequests": 2,
      "circuitOpen": false,
      "consecutiveFailures": 0
    }
  ],
  "totalRequests": 150,
  "totalSuccesses": 147,
  "totalFailures": 3,
  "circuitBreaker": {
    "failureThreshold": 3,
    "resetTimeoutSecs": 60
  }
}

동일한 데이터는 get_routing_stats Tauri IPC 명령과 프론트엔드 스토어의 nodeStore.getRoutingStats() 액션을 통해서도 조회할 수 있습니다.

원격 노드 인증

요청이 원격 노드로 라우팅될 때 프록시는 Authorization: Bearer <api_key> 헤더를 추가합니다. API 키는 로컬 노드 레지스트리에 안전하게 저장되며, 로그나 UI에 노출되지 않습니다.

원격 노드에 API 키가 설정되어 있는지 확인하세요. 원격 노드가 인증을 요구하는 경우, API 키가 없는 노드로의 요청은 실패합니다.

폴백 동작

조건 동작
로드 밸런싱 비활성화 로컬에서만 처리, 모델이 로드되지 않은 경우 503 반환.
로드 밸런싱 활성화, 모델이 로컬에 있음 로컬에서 처리.
로드 밸런싱 활성화, 모델이 원격 노드에 있음 원격 노드로 전달.
로드 밸런싱 활성화, 어디에도 모델 없음 503 서비스 이용 불가 반환.
원격 노드 연결 불가, 페일오버 활성화 대체 노드에서 한 번 재시도.
원격 노드 연결 불가, 페일오버 비활성화 업스트림 오류를 클라이언트에 반환.
노드 서킷 열림 라우팅 시 노드 건너뜀, 사용 가능한 경우 대체 노드 사용.

관련 페이지