# モデルカタログ

> LMSP サービスがローカルモデルを一覧する方法、モデルオブジェクトとその機能フラグ、モデルのライフサイクル状態、安定したモデル ID、カタログのリビジョンを説明します。

Source: https://madeforagent.com/ja/lmsp/1.0/models/
Language: ja
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/ja/lmsp/1.0/models.md#lifecycle)）。 |
| `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 節](https://madeforagent.com/ja/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}` は 1 つのモデルオブジェクトを返す。未知の ID では `404` と `model_not_found` を返す。

2 つの任意エンドポイントで、ロードを明示的に制御できる。これらは `model_management` 機能が `true` の場合に利用でき、`models:manage` スコープを必要とする（[10.3 節](https://madeforagent.com/ja/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/ja/lmsp/1.0/common-rules.md#idempotency)）を受け付ける。