通用協定規則 | LMSP 1.0 草案

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。

冪等鍵的作用域是客戶端和介面。它應是不超過 255 個字元的唯一值，例如 ULID 或 UUID。服務應至少儲存冪等鍵 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	否	任務已經 succeeded 或 failed。
`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。

健康介面只回傳執行狀態，不得回傳模型路徑、提示詞、存取權杖等敏感資訊。