GPU Relay

인증

관리자 메뉴에서 발급한 API 키를 bearer token으로 전달합니다.

Authorization: Bearer <relay-api-key>

GET /v1/models

현재 연결된 worker에 로드되어 사용 가능한 모델과 GPU 슬롯 alias를 OpenAI-compatible 목록으로 반환합니다. gpu_relay.gpus에는 gpu, gpu-0 같은 라우팅 항목과 로드 모델, 큐 상태가 포함됩니다.

curl https://gpu-translation.develeste.com/v1/models \
  -H "Authorization: Bearer $GPU_RELAY_API_KEY"

POST /v1/chat/completions

OpenAI-compatible chat completion입니다. model에는 gpu, gpu-0 같은 GPU 번호 또는 실제 모델명을 사용할 수 있습니다. queue_priority는 normal, priority, highest 중 하나입니다. temperature를 생략하면 모델 관리에서 저장한 GPU+모델별 기본값이 적용되고, 저장값이 없으면 0입니다.

curl https://gpu-translation.develeste.com/v1/chat/completions \
  -H "Authorization: Bearer $GPU_RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpu",
    "stream": true,
    "queue_priority": "highest",
    "failover": true,
    "messages": [
      {"role": "system", "content": "Translate accurately. Return only translated text."},
      {"role": "user", "content": "Hello, this is a GPU relay test."}
    ]
  }'

라우팅 규칙

model: "gpu"는 모델명과 무관하게 가장 여유 있는 GPU 큐로 들어갑니다. model: "gpu-1"은 해당 GPU 큐에 들어갑니다. 모델명을 지정하면 그 모델이 로드된 GPU 중 가장 여유 있는 큐를 선택합니다.

failover를 요청에 넣으면 GPU별 설정과 전역 기본값보다 우선합니다. 요청에 없으면 GPU 슬롯의 failover 설정을 따르고, GPU별 설정이 없으면 라우팅 화면의 전역 기본값을 사용합니다.

Structured Output

response_format이 있으면 worker가 LM Studio /api/v1/chat의 system prompt 끝에 JSON 출력 규칙을 주입하고, 응답 JSON을 검증해 반환합니다. reasoning은 LM Studio 모델 메타데이터의 capabilities.reasoning.allowed_options에 있을 때만 전달합니다.

{
  "model": "gpu-0",
  "messages": [{"role": "user", "content": "Translate Hello to Korean"}],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "translation",
      "schema": {
        "type": "object",
        "properties": {"text": {"type": "string"}},
        "required": ["text"]
      }
    }
  }
}

응답 메타데이터

최종 응답에는 실제 처리한 worker, GPU, 모델 정보가 gpu_relay로 포함됩니다.

{
  "gpu_relay": {
    "worker_id": "home-gpu-01",
    "gpu_index": 0,
    "gpu_alias": "gpu-0",
    "model": "qwen/qwen3-vl-4b",
    "requested_model": "gpu-0"
  }
}

GET /status

대시보드와 동일한 worker, GPU별 priority queue, circuit, active request 상태를 반환합니다.

curl https://gpu-translation.develeste.com/status \
  -H "Authorization: Bearer $GPU_RELAY_API_KEY"

요청 로그와 통계

최근 API 호출 로그와 GPU별 응답 시간, 호출 건수, 오류 수를 조회합니다.

curl https://gpu-translation.develeste.com/requests \
  -H "Authorization: Bearer $GPU_RELAY_API_KEY"

curl https://gpu-translation.develeste.com/stats/summary \
  -H "Authorization: Bearer $GPU_RELAY_API_KEY"

관리 API

세션 로그인한 관리자만 호출합니다. 대시보드에서 GPU 슬롯, worker 동시성, 라우팅 설정, 모델 백엔드 관리를 수행합니다.

• GET /gpu-slots
• PUT /gpu-slots/{worker_id}
• PUT /gpu-slots/{worker_id}/failover
• PUT /gpu-slots/{worker_id}/disabled
• PUT /workers/{worker_id}/max-concurrency
• GET /routing/config, PUT /routing/config
• GET /workers/{worker_id}/lmstudio/models
• POST /workers/{worker_id}/lmstudio/models/load
• POST /workers/{worker_id}/lmstudio/models/unload
• POST /workers/{worker_id}/lmstudio/models/download
• GET /huggingface/models?q={query}