docs(api): api-client → v0.58 登记 LLM_MULTIMODAL（env-only 部署的主模型收图声明）
- §2 的 .env 键表：9 键 → **10 键**（v0.53 首登 9 键，v0.58 追加 LLM_MULTIMODAL），语义写全 （默认 false；**仅供 .env 合成组**，有 models.json 时以组为准，与 LLM_REASONING_KIND 同口径； true = 图直进主模型上下文；非 bool 启动即报错，不静默回退；与两个工具模型键互不代表） - §1 行 3（chat.image）补指针；§5 新增 v0.58 条（纯新增 env 键、默认 false ⇒ 老部署行为逐字不变） - api-reference：版本指针 → v0.58，并在 §0.3 / §3.1 / §4.9 四处补明 env 等价键 - 表计数逐行核对一致（标题 10 键 ↔ 表体 10 行）
This commit is contained in:
AskaEth committed
1 parent
94b882f4d9
commit
1728addcfe
2 files changed
+10
-8
No files matched your search
@@ -1,6 +1,6 @@
|
||||
# Cyrene v2 后端 API 参考（api-reference.md）
|
||||
|
||||
> **权威归属（先读这条）**：**契约以 `Docs/api-client.md` 为准**——那是版本化的跨平台客户端契约，每个端点的形状 / 语义 / 版本变更都记在那里（当前 `v0.57`）。**本文件是内部与运维参考**：端点全集索引 + 示例 + 部署细节。**凡是与 api-client 重复的契约性描述，一律以 api-client 为准（本文件不再维护第二份契约）；发现两者不一致时，改本文件而不是改 api-client。**
|
||||
> **权威归属（先读这条）**：**契约以 `Docs/api-client.md` 为准**——那是版本化的跨平台客户端契约，每个端点的形状 / 语义 / 版本变更都记在那里（当前 `v0.58`）。**本文件是内部与运维参考**：端点全集索引 + 示例 + 部署细节。**凡是与 api-client 重复的契约性描述，一律以 api-client 为准（本文件不再维护第二份契约）；发现两者不一致时，改本文件而不是改 api-client。**
|
||||
> **本文件的正确用法**：查「有哪些端点、大致形状、错误码、部署注意事项」可以；**写客户端代码时请以 `Docs/api-client.md` 为准**，本文件的字段表 / 示例可能滞后。
|
||||
> **历史包袱（如实）**：本文件长期自称「全部后端 API 的唯一详细参考 / 超详细主文档 / 每变更必同步」，但实际**系统性滞后于实现与 api-client**（2026-10-03 的 16 路 design-vs-code 审计结论）。本次已修正与实现**直接矛盾**的陈述、并把若干复述型段落改为引用 api-client；**§1 的 REST 端点表已于 2026-10-04 按 `internal/services/gateway/routes.go` 逐条核对并补登记**（补上此前缺失的 `POST /auth/refresh`、`POST /auth/logout`、`POST /upload`、`GET /files/{name}`、三支 `/audio/*`、`GET /admin/llm/catalog`、`GET /admin/observability/logs`、`GET /admin/notifications`、`GET /admin/plugins/installed`、`GET|PUT /admin/owner-profile`、`POST /admin/automations/reminders`）。**仍未补全的是 WS 事件帧清单**：§6.4 自述「并非全表」，`DevDocs/audit/00-总览.md` §4④ 列出的 `session_read` / `message_edited` / `message_deleted` 等仍未逐行登记。
|
||||
> **其余仍成立**：所有字段名、取值、鉴权规则、状态码最终**以代码为准**（`internal/services/gateway/*.go`）；契约变更版本化（REST 走 `/api/v1`，破坏性变更升 v2），不得破坏既有客户端（版本化承诺本身记在 api-client §5）。
|
||||
@@ -45,7 +45,7 @@
|
||||
|
||||
### 0.3 上传 / 媒体（重要确认）
|
||||
|
||||
- **`POST /api/v1/upload`**（B1）上传图片 → 返回**同源 URL**（`/api/v1/files/<name>`），可直接作 `chat.image`；也可继续用 **base64 data: URI** 或 http(s) URL 走 `POST /api/v1/chat` / WS `chat` 的 `image` 字段（入视觉路由，见 §6 流式与直连）。**语义（v0.53 修正，见 api-client §1 行 3）**：**主模型能否收图 = 生效 `models.json` 组的 `multimodal`**（不是「有没有配独立视觉模型」）；`LLM_VISION_MODEL` / `LLM_OCR_MODEL` **只配视觉/OCR 工具用的模型**；主模型不收图时由 vision/OCR 工具返回**文本描述**（另有 `image-crop` 工具可裁区域后重读，便于大图分区精读）。**内联上限（v0.56，2026-10-04 起可配）**：`chat.image` 解码后默认 **5 MiB**（与 `POST /api/v1/upload` 同口径；换算成字符串上限 `ceil(n/3)*4 + 64` 字符，已含 data: 前缀余量），超限 `400 {"error":{"code":"image_too_large",...}}`；字节上限由 `.env` 的 **`CHAT_IMAGE_MAX_BYTES`** 配置（默认 `5242880`；**≤0 视为「用默认」**，不存在「禁用上限」的取值），换配置时错误文案里的 MiB 数字会自动跟随；WS `chat` 帧受 4096 字节读上限约束（超限断连），故 WS 发大图必须走「上传 → URL」。**视觉链路的 URL 取回（v0.56，实现事实）**：`chat.image` 的 http(s) URL（含 `/api/v1/files/<name>`）由**服务端自己取回并内联为 `data:` URI** 再交 provider，**不再把 URL 原样转给上游**（同源 upload 产物优先走**本地文件读取**，`vision.WithUploadsDir`；取回沿用 http/https 白名单 + 50MiB 上限 + 取回超时）。**类型裁决（同一批实现事实）**：**字节嗅探是唯一裁决权**——按真实字节判白名单光栅图（png/jpeg/gif/webp/bmp），声明的 Content-Type / 扩展名只作参考且可被否决；嗅探为文本（HTML/PROXY 错误页、SVG）或判不定且来源没声明 `image/*` → **明确报错**（`vision.ErrNotImage`），**绝不静默回退成 `image/png`**（旧文若写「非图片响应会被当 PNG」即按此更正）。
|
||||
- **`POST /api/v1/upload`**（B1）上传图片 → 返回**同源 URL**（`/api/v1/files/<name>`），可直接作 `chat.image`；也可继续用 **base64 data: URI** 或 http(s) URL 走 `POST /api/v1/chat` / WS `chat` 的 `image` 字段（入视觉路由，见 §6 流式与直连）。**语义（v0.53 修正，见 api-client §1 行 3）**：**主模型能否收图 = 生效 `models.json` 组的 `multimodal`**（不是「有没有配独立视觉模型」）；`LLM_VISION_MODEL` / `LLM_OCR_MODEL` **只配视觉/OCR 工具用的模型**；**env-only 部署（无有效 `models.json`，走 `.env` 合成组）用 `LLM_MULTIMODAL`（默认 `false`，v0.58）声明这个能力**——它才是该组 `multimodal` 的 env 等价物，且**非 bool 值启动报错**；主模型不收图时由 vision/OCR 工具返回**文本描述**（另有 `image-crop` 工具可裁区域后重读，便于大图分区精读）。**内联上限（v0.56，2026-10-04 起可配）**：`chat.image` 解码后默认 **5 MiB**（与 `POST /api/v1/upload` 同口径；换算成字符串上限 `ceil(n/3)*4 + 64` 字符，已含 data: 前缀余量），超限 `400 {"error":{"code":"image_too_large",...}}`；字节上限由 `.env` 的 **`CHAT_IMAGE_MAX_BYTES`** 配置（默认 `5242880`；**≤0 视为「用默认」**，不存在「禁用上限」的取值），换配置时错误文案里的 MiB 数字会自动跟随；WS `chat` 帧受 4096 字节读上限约束（超限断连），故 WS 发大图必须走「上传 → URL」。**视觉链路的 URL 取回（v0.56，实现事实）**：`chat.image` 的 http(s) URL（含 `/api/v1/files/<name>`）由**服务端自己取回并内联为 `data:` URI** 再交 provider，**不再把 URL 原样转给上游**（同源 upload 产物优先走**本地文件读取**，`vision.WithUploadsDir`；取回沿用 http/https 白名单 + 50MiB 上限 + 取回超时）。**类型裁决（同一批实现事实）**：**字节嗅探是唯一裁决权**——按真实字节判白名单光栅图（png/jpeg/gif/webp/bmp），声明的 Content-Type / 扩展名只作参考且可被否决；嗅探为文本（HTML/PROXY 错误页、SVG）或判不定且来源没声明 `image/*` → **明确报错**（`vision.ErrNotImage`），**绝不静默回退成 `image/png`**（旧文若写「非图片响应会被当 PNG」即按此更正）。
|
||||
- **REST 语音端点已存在**：`POST /api/v1/audio/transcribe`（STT）、`POST /api/v1/audio/speech`（TTS）、`POST /api/v1/audio/voice-clone`（声音复刻），均 owner-only + 审计，绕开 WS 4KB 帧限。语音也可走 WS `voice_input`（上行）/`voice_output`（下行）。
|
||||
- 管理端导入知识文档（RAG）走 JSON body 文本（`POST /api/v1/admin/rag`），非文件上传。
|
||||
|
||||
@@ -230,7 +230,7 @@ curl -s -X POST http://<host>:8080/api/v1/auth/login \
|
||||
|------|------|:---:|------|
|
||||
| `sessionId` | string | 否 | 目标会话 id；缺省 `"web"`（主会话）。子会话用 `web:<uuid>` |
|
||||
| `text` | string | 是* | 用户文本。`text` 与 `image` 至少一项非空 |
|
||||
| `image` | string | 否 | 视觉输入：base64 **data: URI** 或 http(s) URL；入 vision/OCR 工具或主模型多模态（design/06）。图文并存则为带图 + 文本的 turn。**语义（v0.53）**：主模型能否收图看生效组的 `multimodal`；`LLM_VISION_MODEL`/`LLM_OCR_MODEL` 只配视觉/OCR **工具**的模型（见 api-client §1 行 3） |
|
||||
| `image` | string | 否 | 视觉输入：base64 **data: URI** 或 http(s) URL；入 vision/OCR 工具或主模型多模态（design/06）。图文并存则为带图 + 文本的 turn。**语义（v0.53）**：主模型能否收图看生效组的 `multimodal`；`LLM_VISION_MODEL`/`LLM_OCR_MODEL` 只配视觉/OCR **工具**的模型；**env-only 部署（无有效 `models.json`，走 `.env` 合成组）用 `LLM_MULTIMODAL`（默认 `false`，v0.58）声明该能力**（见 api-client §1 行 3） |
|
||||
| `deviceId` | string | 否 | 客户端生成的端标识（design/16 §4.5，如 `web:chrome:a1b2c3`），落库到消息，可选 |
|
||||
| `mode` | string | 否 | 行为模式（design/01 §3、design/16 §5.1，如 `chat`/`code`/…）；随该轮落库供气泡渲染；**IM 恒 `chat`、缺省回落 `chat`**（`chatRequest.Mode`） |
|
||||
| `clientMsgId` | string | 否 | **客户端幂等键（v0.56，G4）**：同一会话内同一个非空值只承认第一条，重复到达回 `200 {"data":{"duplicate":true,"messageId":...,"sessionId":...}}` 且**不落库、不起回合**；省略 = 与加入该字段前逐字相同（老客户端零影响）。原生端用它把本地乐观气泡对齐到服务端真相 |
|
||||
@@ -569,13 +569,13 @@ curl -s http://<host>:8080/api/v1/admin/iot -H "Authorization: Bearer $TOKEN" -H
|
||||
|
||||
### 4.9 GET /api/v1/admin/llm
|
||||
- **响应**：`200 {"data":{"providers":[<AdminLlmProvider>...]}}`（`AdminLlmConfig`）。
|
||||
- `AdminLlmProvider`：`{id, name, provider, baseUrl, model, multimodal, enabled, fallback?, maxTokens?, reasoning, personaModels?, personaProviders?}`（**v0.53 新增三键**，见 api-client 的「模型配置契约（v0.53）」）；顶层 response 另含 `reasoningKinds` / `personaProviderOptions` 两个取值域数组（面板表单选项的唯一来源）。**`multimodal` = 主模型自己能否收图**（裁决 14.4.1）——它**不**表示「本部署有视觉能力」；视觉/OCR **工具**的模型由 `.env` 的 `LLM_VISION_MODEL` / `LLM_OCR_MODEL` 单独配置，与 `multimodal` 无关。`reasoning` 恒下发（`{kind}`，`kind:""` = 未声明形状）。
|
||||
- `AdminLlmProvider`：`{id, name, provider, baseUrl, model, multimodal, enabled, fallback?, maxTokens?, reasoning, personaModels?, personaProviders?}`（**v0.53 新增三键**，见 api-client 的「模型配置契约（v0.53）」）；顶层 response 另含 `reasoningKinds` / `personaProviderOptions` 两个取值域数组（面板表单选项的唯一来源）。**`multimodal` = 主模型自己能否收图**（裁决 14.4.1）——它**不**表示「本部署有视觉能力」；视觉/OCR **工具**的模型由 `.env` 的 `LLM_VISION_MODEL` / `LLM_OCR_MODEL` 单独配置，与 `multimodal` 无关（**env-only 部署**——无有效 `models.json`、走 `.env` 合成组——该字段由 **`LLM_MULTIMODAL`** 声明，默认 `false`，v0.58）。`reasoning` 恒下发（`{kind}`，`kind:""` = 未声明形状）。
|
||||
- `provider` 协议 ∈ `openai|anthropic`；`name` 为友好标签（OpenAI/Anthropic 或组 id）。
|
||||
- `enabled`：index 0 的组为生效组 = `true`。
|
||||
- `maxTokens`：该组的 token 预算（`omitempty`，缺省/0 = 未设）；缺省时链末端回退步回落 `LLM_FALLBACK_MAX_TOKENS`（`.env`，默认 8192），再回落适配器默认（anthropic 8192）。
|
||||
- `reasoning`（v0.53，恒下发）：`{kind}` —— `kind` ∈ `auto|deepseek|openai|vllm|dashscope`，决定该组用哪种**提供商开关形状**下发推理指令（`""`/`auto` = 按模型名/baseURL 推断，形状有歧义就不下发）；详见 api-client「模型配置契约（v0.53）」。
|
||||
- `personaModels` / `personaProviders`（v0.53，`omitempty`）：**角色级模型 / 协议路由表**（`{personaId: modelId}` / `{personaId: "openai"|"anthropic"}`）；未配置 = 该键不出现。
|
||||
- `multimodal`：**主模型自己能否收图**（= 面板的「多模态」勾选）；视觉/OCR **工具**的模型是 `.env` 的 `LLM_VISION_MODEL`/`LLM_OCR_MODEL`，与本字段无关（裁决 14.4.1 修语义）。
|
||||
- `multimodal`：**主模型自己能否收图**（= 面板的「多模态」勾选）；视觉/OCR **工具**的模型是 `.env` 的 `LLM_VISION_MODEL`/`LLM_OCR_MODEL`，与本字段无关（裁决 14.4.1 修语义）；**env-only 部署（无有效 `models.json`，走 `.env` 合成组）由 `LLM_MULTIMODAL`（默认 `false`，v0.58）声明本字段**。
|
||||
- **API key 永不返回**（wire 无 key 字段）。
|
||||
- 数据源：`models.json` 各组（index 0 = 生效组）；无 `models.json` 时按 `.env` 合成单组。curl：
|
||||
|
||||
|
||||
Reference in new issue
Block a user