# 模型目錄

> LMSP 服務如何列出本地模型，包括模型物件及其能力旗標、模型生命週期狀態、穩定的模型 id 和目錄修訂號。

Source: https://madeforagent.com/zh-tw/lmsp/1.0/models/
Language: zh-TW
Specification: LMSP 1.0 (draft)
Updated: 2026-11-08

## 5.1 取得模型列表 {#list}

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

| 查詢引數 | 含義 |
| --- | --- |
| `capability` | 只回傳具備指定能力的模型，例如 `chat`、`embeddings` 或 `tools`。 |
| `ready_only` | 為 `true` 時只回傳 `status` 為 `ready` 的模型，預設為 `false`。 |

```json
{
  "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 模型物件 {#object}

| 欄位 | 含義 |
| --- | --- |
| `id` | 穩定的模型識別碼，所有指明模型的請求都使用它。 |
| `object` | 始終為 `"model"`。 |
| `display_name` | 便於閱讀的名稱，使用者可以修改。 |
| `aliases` | 可選的別名列表，僅供參考。 |
| `owned_by` | 模型的來源。安裝在本裝置上的模型為 `local`。 |
| `family` | 模型家族，例如 `qwen3`。 |
| `revision` | 模型內容的摘要，例如 `sha256:8f27...`。 |
| `status` | 生命週期狀態（[第 5.3 節](https://madeforagent.com/zh-tw/lmsp/1.0/models.md#lifecycle)）。 |
| `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 節](https://madeforagent.com/zh-tw/lmsp/1.0/common-rules.md#errors)）。 |

模型 `id` **必須**穩定。顯示名和別名可由使用者修改，因此**不得**用作主鍵。

## 5.3 模型生命週期 {#lifecycle}

```text
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 模型操作 {#operations}

`GET /lmsp/v1/models/{model_id}` 回傳單個模型物件。未知的 id 回傳 `404` 和 `model_not_found`。

兩個可選介面用於顯式控制載入。它們在 `model_management` 能力為 `true` 時可用，並要求 `models:manage` 許可權範圍（[第 10.3 節](https://madeforagent.com/zh-tw/lmsp/1.0/security.md#scopes)）：

| 介面 | 行為 |
| --- | --- |
| `POST /lmsp/v1/models/{model_id}/load` | 預載入模型。載入已開始時回傳模型物件和 `202 Accepted`，模型已經是 `ready` 時回傳 `200`。 |
| `POST /lmsp/v1/models/{model_id}/unload` | 解除安裝模型，回傳模型物件。重複請求無害。 |

兩者都接受 `Idempotency-Key`（[第 9.2 節](https://madeforagent.com/zh-tw/lmsp/1.0/common-rules.md#idempotency)）。