モデルカタログ | 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`	1 回のレスポンスの最大トークン数。
`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} は 1 つのモデルオブジェクトを返す。未知の ID では 404 と model_not_found を返す。

2 つの任意エンドポイントで、ロードを明示的に制御できる。これらは 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 節）を受け付ける。