模型目錄 | 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`	上下文的最大 token 數。
`max_output_tokens`	單次回應的最大 token 數。
`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 節）。