文档: aichat 走查与集成可行性研究

2026-10-01 02:41:21 +08:00
parent c978d9cb60
commit 3f3f5053a4
4 changed files with 374 additions and 0 deletions
@@ -0,0 +1,53 @@
+# u-switch 接入 devflow 分析
+
+> 2026-09-28 · 目标：评估让 devflow 的 AI 调用走 u-switch（本地 Anthropic 协议模型路由网关）需要做哪些。
+> 结论先行：**协议层已天然兼容，零代码改动即可打通主链**；真正要做的是 devflow 侧接入配置 + 两个小缺口决策（旁路端点、额度码透传）；多租户/管理面属产品化远期，当前不需要。
+
+## 一、两舱现状
+
+| 维度 | devflow（客户端） | u-switch（网关） |
+|------|------------------|-----------------|
+| 协议 | 双协议适配器：OpenAI 兼容 + Anthropic 兼容（`crates/df-ai/src/anthropic_compat.rs`） | 仅 Anthropic `/v1/messages` + `GET /v1/models`（`main.go:800-802`） |
+| 供应商模型 | 一个供应商 = base_url + key + 模型池，weight 负载均衡 + 跨供应商 fallback | 模型别名→物理名映射 + 主备有序 failover + provider 级分级熔断 |
+| 密钥 | OS keyring，DB 不存 key | 手写 switch.yml（auth_key admin + auth_keys 成员） |
+| 流式 | 自研 SSE 解析，兼容各厂商 chunk 变体 | SSE 首事件预读回退 + 中断补 error + usage 流式采集（纯透传不改写） |
+| 用量 | 上游 usage 回传 + 缺失降级估算 | 透传原样 + SQLite 事后明细（无限流/配额/计费） |
+| 工具调用 | 双协议标准 tool-use 语义 | 纯透传（Anthropic 语义内无障碍） |
+
+## 二、零改动已具备（已源码核对）
+
+1. **协议匹配**：devflow `provider_type="anthropic"` 走 `{base}/v1/messages`（anthropic_compat.rs:98-107）→ u-switch 数据面唯一数据端点即此。
+2. **鉴权头**：devflow 发 `x-api-key`（anthropic_compat.rs:501-506）；u-switch checkAuth 接受 `X-Api-Key`（main.go:658-683）。
+3. **模型目录**：u-switch `GET /v1/models` 返回 `{data:[{id,display_name,type}]}` 字典序别名（main.go:763-785）；devflow anthropic 探测恰好吃该形状（model_fetch.rs:103-126），字段交集设计命中。
+4. **header 透传**：u-switch sendUpstream 透传除 Authorization/X-Api-Key/Content-Length 外全部头（main.go:1081-1085），`anthropic-version` 原样到达上游。
+5. **SSE / usage**：u-switch 逐行保真透传不改写 → devflow 收到的 chunk/usage 与直连上游同构（message_start/message_delta 累计 output 等 anthropic_helpers.rs 假设不被破坏）。
+6. **工具调用 / thinking**：两边都是 Anthropic 语义透传；u-switch 的 thinking 自愈 + drop_thinking 与 devflow 的 thinking 处理互补不冲突。
+
+## 三、要做的事
+
+### A. devflow 侧接入动作（无代码，纯配置）
+
+1. Settings→ProviderPanel 新建供应商：provider_type=Anthropic，base_url=u-switch 地址（如 `http://127.0.0.1:6816`），key=u-switch 的 auth_key/成员令牌；default_model 填 u-switch 别名（逻辑名）。
+2. `ai_fetch_models` 拉别名列表 → **手工校准模型元数据**（关键）：u-switch 返回的是逻辑别名，devflow 的 probe 按名字推断 context_window/模态会失真；路由过滤 `context_window >= estimated_context`（router.rs:101）可能误过滤 → 前端模型表手工改对 context_window 或关掉该模型。
+3. **路由双层决策**（人定）：devflow 自带 ProviderPool weight + 跨供应商 fallback，与 u-switch 路由/failover 职责重叠。推荐起步姿势 = devflow 只保留 u-switch 一个启用 provider（本地 LB 自然退化，网关全权路由，保 prompt cache 亲和）；或保留 devflow 多 provider 直连兜底、u-switch 只管其中一路。
+
+### B. u-switch 侧小缺口（可选，按需排期）
+
+1. **旁路端点不接管**（真实缺口）：u-switch 只认 `/v1/messages` + `/v1/models`。devflow 的知识库 embedding（`/v1/embeddings`）与图像生成（`/v1/images/generations`）走网关会 404。二选一：
+   - devflow 侧把这两类功能指向别的直连 provider（当前架构旁路本就不经主链，配置可分离）；
+   - u-switch 加透传端点（违背其「Anthropic 协议专用」极简定位，不推荐）。
+2. **额度码透传**（体验优化）：u-switch 全渠道耗尽固定回 502，devflow 的额度耗尽识别（429+「额度/上限」文本 → Fatal 不重试，stream_recv.rs:639-660）在网关后失效，会白重试 3 次。可选：全渠道耗尽时若最后根因是 402/401/429，透传该状态码而非 502。
+
+### C. 产品化远期（仅 devflow 分发给多用户时才需要，当前不做）
+
+key 签发/撤销 API（现手写 yml）、配额/限流（现仅事后明细）、管理 UI（现仅 `/_switch` 三端点）、多租户渠道视图。u-switch 定位是单用户自用本地路由器，与 devflow「现自用」阶段匹配。
+
+## 四、验证清单（打通步骤）
+
+1. [ ] u-switch 起本地实例，switch.yml 配 auth_key + ≥1 个 Anthropic 兼容渠道别名
+2. [ ] devflow 新建 Anthropic provider 指向 u-switch，`ai_test_connection` 通过
+3. [ ] `ai_fetch_models` 拉到别名列表，手工校准 context_window
+4. [ ] 非流式对话一轮 → 流式长对话一轮（验证 SSE 透传 + usage 落库非估算）
+5. [ ] 带工具调用会话一轮（验证 tool_use/tool_result 透传闭环）
+6. [ ] 人为断上游验证 failover：devflow 侧应无感或收到可重试错误
+7. [ ] u-switch SQLite 核对 u_requests 明细与 devflow 消息级 usage 一致