# 模型目录

> LMSP 服务如何列出本地模型，包括模型对象及其能力标志、模型生命周期状态、稳定的模型 id 和目录修订号。

Source: https://madeforagent.com/zh-cn/lmsp/1.0/models/
Language: zh-CN
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-cn/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-cn/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-cn/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-cn/lmsp/1.0/common-rules.md#idempotency)）。