8.5. 원격 모델 제어¶

Backend.AI GO를 사용하면 헤드 노드에서 원격 머신에 직접 접근하지 않고도 연결된 원격 노드의 모델을 로드 및 언로드할 수 있습니다. 이것으로 분산 추론 워크플로우가 완성됩니다. 노드를 연결하고, 노드 간에 추론 요청을 라우팅하며, 이제 각 노드에서 실행 중인 모델을 단일 인터페이스에서 관리할 수 있습니다.

개요¶

원격 노드가 등록되면 헤드 노드는 해당 노드의 기본 URL과 API 키를 저장합니다. 원격 모델 제어는 이 정보를 사용하여 사용자를 대신해 원격 노드의 Management API로 모델 관리 명령을 전송합니다.

다음 작업이 지원됩니다:

• 모델 로드 — 원격 노드에 모델 서빙을 시작하도록 지시
• 모델 언로드 — 원격 노드에서 실행 중인 모델 중지
• 로드된 모델 목록 — 원격 노드에서 현재 활성화된 모델 조회

API 레퍼런스¶

세 가지 작업 모두 Tauri IPC 명령(데스크탑 앱)과 REST API 엔드포인트(헤드리스 모드)로 사용할 수 있습니다.

원격 노드에 모델 로드¶

Tauri IPC: load_model_on_remote_node

REST: POST /api/v1/nodes/{fingerprint}/models/load

요청 본문:

{
  "modelId": "llama-3-8b-q4",
  "modelPath": "/path/to/model.gguf",
  "contextLength": 4096,
  "gpuLayers": -1
}

응답:

{
  "success": true,
  "modelId": "llama-3-8b-q4",
  "nodeFingerprint": "fp_abc123"
}

실패 시 success는 false이며 error 필드에 문제가 설명됩니다.

원격 노드에서 모델 언로드¶

Tauri IPC: unload_model_on_remote_node

REST: POST /api/v1/nodes/{fingerprint}/models/unload

요청 본문:

{
  "modelId": "llama-3-8b-q4"
}

응답:

{
  "success": true,
  "modelId": "llama-3-8b-q4",
  "nodeFingerprint": "fp_abc123"
}

원격 노드의 모델 목록 조회¶

Tauri IPC: get_remote_node_models

REST: GET /api/v1/nodes/{fingerprint}/models

응답:

{
  "data": [
    {
      "id": "llama-3-8b-q4",
      "path": "/models/llama-3-8b-q4.gguf",
      "endpoint": "http://127.0.0.1:8081",
      "healthy": true
    }
  ]
}

실시간 업데이트¶

원격 노드에서 모델이 성공적으로 로드되거나 언로드되면 헤드 노드는 distributed-pool-changed 이벤트를 전송합니다. 프론트엔드 nodeStore는 이 이벤트를 구독하여 자동으로 다음을 수행합니다:

1. 영향을 받은 노드의 원격 모델 목록 새로고침 (fetchRemoteModels).
2. 전체 분산 풀 상태 새로고침 (getDistributedPoolStatus).

이를 통해 수동으로 페이지를 새로고침하지 않아도 UI가 동기화 상태를 유지합니다.

헤드리스 모드에서는 동일한 이벤트가 GET /api/v1/events의 SSE(Server-Sent Events) 스트림을 통해 브로드캐스트됩니다.

타임아웃¶

대용량 모델을 고려하여 작업에는 여유 있는 타임아웃이 적용됩니다:

타임아웃이 발생하면 응답에 "success": false와 함께 타임아웃 시간을 나타내는 오류 메시지가 포함됩니다.

오류 처리¶

모델 ID는 네트워크 요청 전에 검증됩니다. 빈 모델 ID와 .. 시퀀스가 포함된 ID는 URL 경로 조작을 방지하기 위해 거부됩니다.

프론트엔드 스토어¶

useNodeStore Zustand 스토어는 원격 모델 제어를 위한 다음 셀렉터와 액션을 제공합니다:

언로드는 낙관적 업데이트를 수행합니다. 모델은 즉시 로컬 캐시에서 제거되고, distributed-pool-changed 이벤트가 백엔드에서 전체 새로고침을 트리거합니다.

보안¶

원격 노드에 대한 모든 요청은 Authorization: Bearer <api_key> 헤더를 사용합니다. API 키는 로컬 노드 레지스트리에 안전하게 저장되며 로그나 UI에 노출되지 않습니다. 모델 ID는 경로 인젝션을 방지하기 위해 URL에서 퍼센트 인코딩됩니다.

관련 페이지¶

• 분산 라우팅 — 노드 간 자동 요청 라우팅
• 수동 등록 — 원격 노드 연결
• 자동 발견 — 로컬 네트워크에서 노드 자동 검색