Made for Agent
言語: 日本語

共通ルール

9.1 バージョンと拡張

LMSP のリクエストは、次のヘッダーを携えてもよい。

LMSP-Version: 1.0
LMSP-Client: example-client/1.2.0

LMSP-Version は、クライアントが対象とするプロトコルのバージョンである。LMSP-Client は、診断用にクライアントソフトウェアを name/version の形式で識別する。サービスは、これに基づいてプロトコルの動作を変更してはならない。

規則:

  • パス中の v1 はメジャーバージョンを表す。
  • 未知のメジャーバージョンを指定するリクエストには、426 Upgrade Required とエラーコード unsupported_protocol_version で応答する。
  • 新しい任意フィールドは、1.x の互換性を壊してはならない。
  • サービスとクライアントは、知らないフィールドを無視しなければならない。
  • 非公開の拡張は extensions オブジェクトに入れ、逆ドメイン表記で名前を付ける。
{
  "extensions": {
    "com.example.cache": {
      "enabled": true
    }
  }
}

9.2 冪等性

レスポンスの作成、タスクの作成、モデルのロードのように、何かを作成するリクエストは、冪等キーを受け付ける。

Idempotency-Key: <client-generated-unique-value>

サービスは、キーを、リクエスト本文のダイジェストと結果と併せて保存する。

  • 同じキーで同じ本文なら、元の結果を返す。
  • 同じキーで異なる本文なら、409 Conflict と idempotency_conflict で応答する。

キーのスコープは、クライアントとエンドポイントである。キーは、ULID や UUID のような、最大 255 文字の一意な値であるべきである。サービスは、キーを少なくとも 24 時間保持するべきである。

サービスは、ストリーミングリクエストではキーを無視してもよい。安全な再試行が必要なクライアントは、タスクを使う。

9.3 エラー

LMSP インターフェース上のすべてのエラーは application/problem+json（RFC 9457）を使う。

{
  "type": "urn:lmsp:error:model-not-found",
  "title": "Model not found",
  "status": 404,
  "code": "model_not_found",
  "detail": "No local model with id 'qwen3:14b-q4_k_m'",
  "request_id": "req_01J8M9S6Y4W8C3P5R1V7Z2A0DH",
  "retryable": false
}
フィールド 必須 意味
type はい エラーの種類を識別する URI。LMSP は urn:lmsp:error: に、アンダースコアをハイフンに置き換えたコードを続けたものを使う。
title はい 人間が読める短い要約。
status はい HTTP ステータスコード。
code はい 下の一覧にある、機械可読なエラーコード。
detail いいえ このエラーの発生についての、人間が読める説明。シークレット、プロンプト、生成内容を含んではならない。
request_id いいえ リクエストの識別子。サービスのログとの突き合わせに使う。
retryable はい 後でリクエストを繰り返せば成功し得るかどうか。

一般的なエラーコード:

コード HTTP ステータス 再試行可 意味
invalid_request 400 いいえ リクエストの形式が正しくないか、パラメーターが無効である。
unauthorized 401 いいえ トークンがない、無効、期限切れ、または失効している。あるいはペアリングコードが誤っている。
forbidden 403 いいえ トークンに必要なスコープがない、または Origin か Host の検査に失敗した。
model_not_found 404 いいえ この ID のローカルモデルがない。
model_not_ready 409 はい モデルがロードされておらず、オンデマンドでもロードされない。
model_load_failed 500 はい モデルのロードに失敗した。
context_length_exceeded 400 いいえ 入力がモデルのコンテキストウィンドウに収まらない。
unsupported_capability 400 または 501 いいえ モデルまたはサービスが、リクエストに必要なものに対応していない。未実装の任意エンドポイントは 501 で応答する。
unsupported_protocol_version 426 いいえ サービスが、要求されたメジャーバージョンに対応していない。
response_not_found 404 いいえ この ID の保存済みレスポンスがない。
task_not_found 404 いいえ この ID のタスクがない。
task_not_cancelable 409 いいえ タスクはすでに成功または失敗している。
idempotency_conflict 409 いいえ その冪等キーは、すでに別のリクエスト本文で使われている。
event_history_expired 410 いいえ 要求されたイベントが保持期間より古い。
rate_limited 429 はい リクエストが多すぎる。
resource_exhausted 503 はい デバイスのメモリまたはその他のリソースが不足している。
backend_unavailable 503 はい モデルランタイムに到達できない。
server_restarted 503 はい タスクが未完了の間にサービスが再起動した。
internal_error 500 場合による サービス内部での予期しない障害。

retryable フィールドが正である。上の列は通常の値を示している。サービスは、さらにコードを定義してもよい。クライアントは、知らないコードを、その HTTP ステータスと retryable フィールドによって処理しなければならない。

9.4 ヘルスチェック

GET /lmsp/v1/health
{
  "status": "ready",
  "service_id": "svc_01J8M4Y8K6M5E6K6Z7Z0Y8W3M2",
  "uptime_seconds": 86420,
  "loaded_models": 1,
  "active_tasks": 2,
  "storage": "ok"
}
フィールド 意味
status starting、ready、degraded、stopping。
service_id サービス記述にあるサービス ID。
uptime_seconds サービスの起動からの秒数。
loaded_models ready 状態のモデルの数。
active_tasks queued、loading、running、cancelling のタスクの数。
storage ok または error。

status が ready または degraded のときは 200 OK、それ以外は 503 Service Unavailable を返す。

ヘルスエンドポイントが返すのは、運用上のステータスだけである。モデルのパス、プロンプト、アクセストークン、その他の機微な情報を返してはならない。