모델 카탈로그 | LMSP 1.0 초안

5.1 모델 나열

GET /lmsp/v1/models?capability=chat&ready_only=false
Authorization: Bearer <token>

쿼리 매개변수	의미
`capability`	지정한 기능을 가진 모델만 반환한다. 예: `chat`, `embeddings`, `tools`.
`ready_only`	`true`이면 `status`가 `ready`인 모델만 반환한다. 기본값은 `false`.

{
  "object": "list",
  "catalog_revision": "42",
  "data": [
    {
      "id": "qwen3:14b-q4_k_m",
      "object": "model",
      "display_name": "Qwen3 14B Q4_K_M",
      "owned_by": "local",
      "family": "qwen3",
      "revision": "sha256:8f27c1a4e9b05d36f2a7c8e1b4d90a63c5e2f7b8a1d4c9e60b3f5a7d2c8e1b04",
      "status": "ready",
      "capabilities": {
        "chat": true,
        "completion": true,
        "embeddings": false,
        "tools": true,
        "vision": false,
        "structured_output": true,
        "streaming": true
      },
      "input_modalities": ["text"],
      "output_modalities": ["text"],
      "context_window": 32768,
      "max_output_tokens": 8192,
      "runtime": {
        "backend": "llama.cpp",
        "device": "metal",
        "load_on_demand": true
      }
    }
  ]
}

클라이언트가 전체 카탈로그를 반복해서 가져오지 않도록, 서비스는 ETag 헤더, catalog_revision 필드, 또는 둘 다를 반환하는 것이 좋다.

catalog_revision은 카탈로그가 바뀔 때마다 바뀌는 불투명한 문자열이다.
ETag를 보내는 서비스는 일치하는 If-None-Match에 304 Not Modified로 응답하는 것이 좋다.

5.2 모델 객체

필드	의미
`id`	안정적인 모델 식별자. 모델을 지정하는 모든 요청에서 쓴다.
`object`	항상 `"model"`.
`display_name`	사람이 읽을 수 있는 이름. 사용자가 바꿀 수 있다.
`aliases`	다른 이름의 선택적 목록. 참고용일 뿐이다.
`owned_by`	모델의 출처. 이 기기에 설치된 모델은 `local`.
`family`	모델 계열. 예: `qwen3`.
`revision`	모델 내용의 다이제스트. 예: `sha256:8f27...`.
`status`	수명 주기 상태(5.3절).
`capabilities`	불리언 플래그: `chat`, `completion`, `embeddings`, `tools`, `vision`, `structured_output`, `streaming`.
`input_modalities`, `output_modalities`	모델이 읽고 쓰는 콘텐츠의 종류. 1.0에서 정의된 모달리티는 `text`뿐이다.
`context_window`	컨텍스트의 최대 토큰 수.
`max_output_tokens`	응답 하나의 최대 토큰 수.
`runtime`	`backend`(예: `llama.cpp`), `device`(예: `metal`), `load_on_demand`.
`error`	`status`가 `error`일 때 존재한다. problem 객체(9.3절).

모델 id는 안정적이어야 한다. 표시 이름과 별칭은 사용자가 바꿀 수 있으므로 기본 키로 써서는 안 된다.

5.3 모델 수명 주기

installed --> loading --> ready --> unloading --> installed
                 |
                 +-----> error

상태	의미
`installed`	모델은 있지만 로드되지 않았다.
`loading`	메모리를 할당하는 중이거나 런타임을 초기화하는 중이다.
`ready`	모델이 즉시 요청을 처리할 수 있다.
`unloading`	리소스를 해제하는 중이다.
`error`	로드에 실패했다. 모델 객체는 구조화된 오류를 담는 것이 좋다.

error 상태의 모델은 새 로드 요청이 오면 loading으로 돌아간다.

요청이 installed 상태이면서 runtime.load_on_demand가 true인 모델을 지정하면, 서비스는 요청의 일부로 그 모델을 로드한다. 모델을 바로 쓸 수 없고 요청 시 로드되지도 않으면, 서비스는 409와 model_not_ready로 응답한다. 로드에 실패하면 오류는 model_load_failed이다.

5.4 모델 작업

GET /lmsp/v1/models/{model_id}는 모델 객체 하나를 반환한다. 알 수 없는 id는 404와 model_not_found를 반환한다.

두 개의 선택적 엔드포인트로 로드를 명시적으로 제어한다. 이들은 model_management 기능이 true일 때 사용할 수 있으며, models:manage 스코프가 필요하다(10.3절).

엔드포인트	동작
`POST /lmsp/v1/models/{model_id}/load`	모델을 미리 로드한다. 로드가 시작되면 `202 Accepted`와 함께, 이미 `ready`이면 `200`과 함께 모델 객체를 반환한다.
`POST /lmsp/v1/models/{model_id}/unload`	모델을 언로드한다. 모델 객체를 반환한다. 요청을 반복해도 해가 없다.

둘 다 Idempotency-Key(9.2절)를 받는다.