模型目录 | 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 节）。