feat(provider): 完成阶段E协议适配、国内预设与模型路由
This commit is contained in:
@@ -1,107 +1,105 @@
|
||||
# 模型提供商与模型发现开发说明
|
||||
# 模型提供商、协议适配与模型路由开发说明
|
||||
|
||||
> 更新日期：2026-09-02。OpenAI、DeepSeek、Ollama 预设、模型自动发现、默认模型选择和开发阶段加密凭据存储均已实现并接入设置页。
|
||||
> 更新日期：2026-09-04。阶段 E 实现记录。本地小模型的实际安装与多模态队列属于阶段 F；本阶段保留并测试可注入的本地后端接口。
|
||||
|
||||
## 1. 本次目标
|
||||
## 1. 设置与凭据
|
||||
|
||||
本次完善设置页的模型提供商配置，不改变 Agent、Chat 和 Skill 对统一 Model Core 接口的依赖：
|
||||
设置 → 模型提供商 → 新增 Provider 提供可搜索的 logo 预设网格，包含 DeepSeek、Kimi、阿里云百炼、智谱 GLM、火山方舟、硅基流动、百度千帆、腾讯混元、MiniMax、阶跃星辰，以及 OpenAI Chat / Responses、Anthropic 和 Ollama。图标打包到前端，使用时不请求第三方图片服务；来源和许可见前端 assets/providers 目录。
|
||||
|
||||
- 提供 OpenAI、DeepSeek 和 Ollama 配置预设；
|
||||
- 保存 Provider 后自动获取该账号或服务当前可用的模型列表；
|
||||
- 支持手动刷新模型列表和选择默认模型；
|
||||
- 保留自定义 OpenAI-Compatible 服务入口；
|
||||
- 不在 Vue、FastAPI 配置或仓库文件中保存、回显 API Key 明文。
|
||||
预设返回 `preset_id`、`logo_id`、`name`、`provider_type`、`base_url`、`requires_credential`、`description` 和 `capabilities`。能力标签表示预设接入范围，不保证该账号的每个模型支持全部能力。厂商专用媒体协议、Coding Plan 和海外地域需要使用对应地址，不能仅凭厂商名称推断协议兼容。
|
||||
|
||||
## 2. 接口与实现
|
||||
预设和自定义服务都可以直接输入 API Key。每个新配置分配独立 Credential ID，避免同厂商多账号相互覆盖。明文只留在密码输入框和专用请求中，提交、失败、切换预设及关闭时清空；密钥不进入 Pinia、localStorage、Provider 配置响应或模型路由。
|
||||
|
||||
### 2.1 Provider 预设
|
||||
凭据继续使用独立的 `PUT /api/credentials/{credential_id}` 和 Fernet 开发存储。`plugin.*`、`mcp.*` 是保留命名空间。桌面端阶段仍需要把主密钥管理迁移到 Stronghold。保存密钥与保存 Provider 是两个请求，Provider 保存失败时可能留下未引用的加密凭据，可通过凭据删除接口清理。
|
||||
|
||||
新增接口：
|
||||
Provider 配置和 Credential ID 写入 SQLite `provider_configs`，重启后恢复。Mock 为内置 Provider，不能编辑或删除。PATCH 已支持变更 `provider_type` 并重新创建 Adapter；Base URL 限制为不带用户信息、查询或 fragment 的 HTTP(S) 地址。
|
||||
|
||||
```http
|
||||
GET /api/providers/presets
|
||||
## 2. 协议适配
|
||||
|
||||
支持的协议是 OpenAI Chat Completions、OpenAI-Compatible、OpenAI Responses、Anthropic Messages 和 Ollama。Agent、Chat、Skill 仍只依赖内部 `ModelRequest` / `ModelEvent` / `ProviderTurn`，不直接解释厂商协议。
|
||||
|
||||
Adapter 负责消息及 Tool 历史转换、增量文本、可用的 reasoning delta、工具参数片段、usage、终止与统一错误。外部错误正文不原样返回；HTTP 鉴权、限流、超时、无效数据、流中断分别映射为内部错误。取消继续传播并关闭上游连接，不触发第二次本地推理。
|
||||
|
||||
`GET /api/providers/{provider_id}/models` 用于发现模型。模型列表不等于每个模型的能力承诺；部分厂商或代理不提供 `/models` 时，允许直接手动输入模型 ID。连接测试验证模型发现接口，不代表每一种媒体模型已完成真实推理验收。
|
||||
|
||||
## 3. 三类模型路由
|
||||
|
||||
接口：
|
||||
|
||||
| 方法 | 路径 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| GET | `/api/model-routing` | 读取配置和本地后端状态 |
|
||||
| PUT | `/api/model-routing` | 带版本更新三类模型绑定 |
|
||||
| POST | `/api/models/embeddings` | 文本向量，返回来源和回退原因 |
|
||||
| POST | `/api/media/transcriptions` | 附件转写作业 |
|
||||
| GET | `/api/media/transcriptions/{job_id}` | 获取转写作业 |
|
||||
| POST | `/api/media/speaker-matches` | 两个音频附件的声纹相似度 |
|
||||
|
||||
设置 → 索引与模型分别选择 Embedding、音频转文本和声纹匹配。三种绑定互相独立，可使用不同提供商、模型、密钥和 API 路径。
|
||||
|
||||
GET / PUT 响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"config": {
|
||||
"version": 1,
|
||||
"embedding": {
|
||||
"provider_id": "provider_example",
|
||||
"model": "your-embedding-model",
|
||||
"endpoint": "/embeddings",
|
||||
"dimensions": null
|
||||
},
|
||||
"transcription": null,
|
||||
"speaker_matching": null
|
||||
},
|
||||
"local_backends": [
|
||||
{"capability": "embedding", "status": "placeholder", "message": "当前为 hash-v1 占位向量"},
|
||||
{"capability": "transcription", "status": "not_installed", "message": "阶段 F 接入"},
|
||||
{"capability": "speaker_matching", "status": "not_installed", "message": "阶段 F 接入"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
预设由后端 `ProviderFactory` 提供，前端只消费名称、协议类型、Base URL 和是否需要凭据等配置元数据，不直接实现厂商协议。
|
||||
PUT body 只提交 `config` 的内容。`version` 为读取时的版本，成功递增；并发更新返回 `MODEL_ROUTING_VERSION_CONFLICT`。绑定为空表示使用本地后端。删除仍被路由引用的 Provider 返回 `PROVIDER_IN_USE`，须先解除绑定。
|
||||
|
||||
当前预设：
|
||||
本阶段三类远程路由使用 `openai_chat` / `openai_compatible` 的 Bearer HTTP 配置，endpoint 只能是该提供商下的路径。Responses、Anthropic 和 Ollama 原生协议不冒充上述媒体协议；Ollama 用户需要另建兼容 HTTP 配置才能用于当前远程 Embedding 接口。
|
||||
|
||||
| 提供商 | Provider Type | Base URL | 默认 Credential ID |
|
||||
| --- | --- | --- | --- |
|
||||
| OpenAI | `openai_chat` | `https://api.openai.com/v1` | `openai` |
|
||||
| DeepSeek | `openai_compatible` | `https://api.deepseek.com` | `deepseek` |
|
||||
| Ollama | `ollama` | `http://127.0.0.1:11434` | 无 |
|
||||
调用规则：无绑定 → 本地接口；有绑定 → API → 校验结果 → 失败或无效时调用本地接口。Provider 停用、密钥缺失、鉴权失败、限流、网络超时及无效结果均可回退；用户取消不会回退。附件不存在、大小非法等输入错误直接返回，不把用户输入错误当成模型故障。
|
||||
|
||||
OpenAI 和 DeepSeek 都通过项目已有的 `OpenAICompatibleProvider` 访问。模型发现分别请求 Base URL 下的 `/models`，不引入厂商 SDK。
|
||||
## 4. Embedding 与索引一致性
|
||||
|
||||
### 2.2 自动获取模型
|
||||
请求使用 `model`、`input`、`encoding_format: float`；只有明确配置维度时才发送 `dimensions`。按最多 32 条分批请求，全部批次有效才使用 API 结果。校验返回数量、连续唯一 index、维度一致性、有限数值、非零范数，并 L2 归一化。维度可为 1–16384，不截断、补零或混用不同模型的向量。
|
||||
|
||||
模型列表继续使用既有接口：
|
||||
返回 `vectors`、`source`、`model_id`、`dimensions`、`fallback_reason`。远程空间 ID 由完整 API URL、模型和实际维度生成；即使维度相同，不同模型的空间也不同。
|
||||
|
||||
```http
|
||||
GET /api/providers/{provider_id}/models
|
||||
```
|
||||
笔记索引始终保留现有 hash/sqlite-vec 本地基线，远程向量写入独立 `routed_block_vectors` 表。远程查询只搜索对应空间，并要求覆盖全部当前 Block。API 失败、索引缺失、不完整或损坏时使用完整本地索引。切换模型、URL、维度后应在设置中重建全部索引。旧空间与当前文本不会混合打分，删除笔记或重建索引会通过外键清理远程向量。
|
||||
|
||||
设置页在以下时机调用该接口：
|
||||
当前远程侧索引采用 SQLite JSON 向量和精确余弦扫描，复杂度 O(Block 数量 × 维度)，适用于当前小型 Vault；后续大规模索引需替换为按空间隔离的 ANN。网络等待发生在数据库写事务之前，当前仍会增加保存或重建延迟，异步索引队列尚未接入。
|
||||
|
||||
- Provider 列表加载完成后，为所有已启用 Provider 自动刷新；
|
||||
- 新增或编辑 Provider 保存成功后自动刷新；
|
||||
- 用户点击“刷新模型”时手动刷新；
|
||||
- 打开已有 Provider 的编辑窗口时刷新可选模型。
|
||||
无 API 时使用的 `HashEmbeddingProvider` 是确定性特征哈希占位实现，**不是已集成的小型语义模型**。真实本地 Embedding 可实现既有 `EmbeddingProvider` 接口注入。
|
||||
|
||||
前端按模型名称排序并按 `model_id` 去重。获取结果保存在 `providerStore.modelsByProvider`，加载状态和错误按 Provider 隔离，单个外部服务失败不会阻止其他服务展示。
|
||||
## 5. 音频与声纹边界
|
||||
|
||||
获取成功后，Provider 卡片展示模型数量和默认模型下拉框。更换默认模型会调用 Provider PATCH 接口写回配置；编辑窗口仍允许手动输入模型 ID，以兼容未出现在列表中的代理模型或部署别名。
|
||||
转写默认请求 `/audio/transcriptions`，multipart 字段 `model`、可选 `language` 和 `file`，响应必须包含非空字符串 `text`。已有纯文本附件和 Host 旁路 `.txt` 导入保留，来源标记 `sidecar`，不伪称 ASR。转写作业新增 `source`、`fallback_reason`；回退失败的作业记录 `LOCAL_MODEL_NOT_INSTALLED` 等明确错误。作业目前同步执行、限量保存在内存中，不是持久化异步队列。
|
||||
|
||||
### 2.3 错误处理
|
||||
声纹匹配使用**本项目自定义 HTTP 契约**，默认 `/audio/speaker-matches`，multipart 字段 `model`、`file`、`reference_file`；响应为 `{"score": 0.85}`，score 必须为有限的 0–1 数值。公共入口只接受 `attachment_id` 和 `reference_attachment_id`，不接收任意文件路径。此接口用于一对一声纹比对，不等同于 pyannote 说话人分离，也不声称任意国内厂商原生支持该路径。
|
||||
|
||||
Provider Adapter 的错误在 FastAPI 路由转换为统一 API Error：
|
||||
媒体文件限制 1 字节至 25 MiB，API 响应限制 16 MiB，单次请求超时 30 秒。文件从后端受控附件目录读取，使用结束或取消时关闭句柄。
|
||||
|
||||
| Provider Error | HTTP 状态 |
|
||||
| --- | --- |
|
||||
| `PROVIDER_AUTH_FAILED` | 401 |
|
||||
| `MODEL_NOT_FOUND` | 404 |
|
||||
| `PROVIDER_RATE_LIMITED` | 429 |
|
||||
| `PROVIDER_TIMEOUT` | 504 |
|
||||
| 其他 Provider 可用性错误 | 502 |
|
||||
`LocalSpeechBackend` 提供 `transcribe` 和 `match` 接口。阶段 E 默认 `PendingSpeechBackend` 明确报告未安装；阶段 F 接入 faster-whisper、pyannote.audio 及模型资源后替换。当前 `diarization=true` 明确返回失败作业 `DIARIZATION_NOT_IMPLEMENTED`，不会静默忽略。视频解码、TTS、视频生成及厂商专用异步媒体协议不在本次交付内。
|
||||
|
||||
前端在对应 Provider 卡片内展示失败原因，并允许用户修正 Credential ID、Base URL 后重新获取。
|
||||
## 6. 官方协议依据与验证
|
||||
|
||||
## 3. 凭据边界
|
||||
国内通用地址核对依据：[阿里云百炼兼容接口](https://help.aliyun.com/zh/model-studio/compatibility-of-openai-with-dashscope)、[百度千帆兼容接口](https://cloud.baidu.com/doc/qianfan/s/Hmh4suq26)、[腾讯混元兼容接口](https://cloud.tencent.com/document/product/1729/111007)、[MiniMax 文本接口](https://platform.minimaxi.com/docs/guides/text-generation)、[阶跃星辰通用与套餐地址区别](https://platform.stepfun.com/docs/zh/step-plan/overview)、[火山方舟 API](https://www.volcengine.com/docs/82379/1795150)、[智谱开放接口](https://docs.bigmodel.cn/api-reference/文件-api/文件列表)。模型 ID 以账号实际开通列表为准，不写死“最新模型”。
|
||||
|
||||
设置页选择 OpenAI 或 DeepSeek 预设后展示密码类型的 API Key 输入框，不再要求用户理解 Credential ID。输入值只存在于表单的临时 `ref`，不会写入 Pinia 或 localStorage；请求完成、取消表单或失败后都会清空。
|
||||
流式事件依据：[OpenAI Responses streaming](https://platform.openai.com/docs/api-reference/responses-streaming)、[Anthropic streaming](https://platform.claude.com/docs/en/build-with-claude/streaming)。音频请求依据：[SiliconFlow transcription](https://docs.siliconflow.com/en/api-reference/audio/create-audio-transcriptions)。
|
||||
|
||||
API Key 通过独立接口写入：
|
||||
自动化验证使用虚构凭据、本地附件、httpx.MockTransport 和可注入本地模型，覆盖流式 Tool/Usage/取消、错误映射、回退、索引空间隔离、版本冲突、重启恢复和界面凭据行为。没有使用真实 API Key 或向厂商发送推理请求。最终验证：后端全量 410 项、前端 76 项测试通过，Vue/TypeScript 类型检查和生产构建通过，浅色/深色预设页面与路由保存经过浏览器检查，git diff --check 通过。后端仅保留既有 Starlette 测试客户端弃用提示，前端保留既有大 bundle 提示。
|
||||
|
||||
```http
|
||||
GET /api/credentials/{credential_id}
|
||||
PUT /api/credentials/{credential_id}
|
||||
DELETE /api/credentials/{credential_id}
|
||||
```
|
||||
|
||||
PUT 请求使用 Pydantic `SecretStr` 接收密钥，响应仅包含 Credential ID 和 `configured` 状态。后端使用 Fernet 认证加密，将密文保存到 `data/credentials/credentials.json`，主密钥保存到 `data/credentials/master.key`；目录和文件尽可能设置为仅当前用户可访问并整体排除版本控制。写入采用临时文件替换，避免进程中断留下半写文件。Provider 发起请求时按 Credential ID 解密，解密失败转换为统一 Provider Error，任何读取接口均不返回明文。
|
||||
|
||||
本地开发存储的主密钥与密文仍位于同一用户数据目录，因此它解决的是仓库泄漏、普通配置误提交和静态明文暴露，不等同于操作系统安全硬件或 Stronghold。Tauri 集成后应以 Stronghold 实现替换 `EncryptedCredentialStore`。无界面环境仍兼容 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 和 Host 注入的 `AINOTE_CREDENTIAL_<ID>`；设置页保存的本地密钥优先，环境变量仅作为回退。
|
||||
|
||||
自动化测试仅使用虚构测试值，验证磁盘文件不包含明文、加解密往返、API 响应不泄密，以及 Provider 能用解密后的值构造 Authorization Header。本次没有使用真实 OpenAI 或 DeepSeek Key，也没有向厂商发起真实请求。
|
||||
|
||||
## 4. 验证
|
||||
|
||||
后端：
|
||||
|
||||
```bash
|
||||
```powershell
|
||||
cd backend
|
||||
uv run pytest -q -p no:cacheprovider
|
||||
```
|
||||
|
||||
前端：
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
cd ../frontend
|
||||
pnpm test
|
||||
pnpm build
|
||||
```
|
||||
|
||||
自动化验证覆盖 Provider 预设、OpenAI-Compatible `/models` 请求与鉴权头、模型映射、前端自动刷新、排序去重及按 Provider 隔离错误。生产构建同时执行 Vue 和 TypeScript 类型检查。
|
||||
|
||||
当前完整回归基线：后端 136 项测试、前端 29 项测试通过，前端类型检查和生产构建通过。Provider 配置目前仍保存在内存 Registry，AI Core 重启后需要重新创建；凭据密文会保留。`plugin.*` 为 Plugin Secret 保留命名空间，Provider 配置、临时测试凭据和通用凭据 API 均拒绝该前缀。OpenAI Responses 与 Anthropic Messages Adapter 尚未实现，设置页正式预设不会使用这两种协议。
|
||||
|
||||
Reference in New Issue
Block a user