5.2 KiB
5.2 KiB
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 语义内无障碍） |
二、零改动已具备（已源码核对）
- 协议匹配：devflow
provider_type="anthropic"走{base}/v1/messages（anthropic_compat.rs:98-107）→ u-switch 数据面唯一数据端点即此。 - 鉴权头：devflow 发
x-api-key（anthropic_compat.rs:501-506）；u-switch checkAuth 接受X-Api-Key（main.go:658-683）。 - 模型目录：u-switch
GET /v1/models返回{data:[{id,display_name,type}]}字典序别名（main.go:763-785）；devflow anthropic 探测恰好吃该形状（model_fetch.rs:103-126），字段交集设计命中。 - header 透传：u-switch sendUpstream 透传除 Authorization/X-Api-Key/Content-Length 外全部头（main.go:1081-1085），
anthropic-version原样到达上游。 - SSE / usage：u-switch 逐行保真透传不改写 → devflow 收到的 chunk/usage 与直连上游同构（message_start/message_delta 累计 output 等 anthropic_helpers.rs 假设不被破坏）。
- 工具调用 / thinking：两边都是 Anthropic 语义透传；u-switch 的 thinking 自愈 + drop_thinking 与 devflow 的 thinking 处理互补不冲突。
三、要做的事
A. devflow 侧接入动作（无代码，纯配置）
- Settings→ProviderPanel 新建供应商：provider_type=Anthropic，base_url=u-switch 地址（如
http://127.0.0.1:6816），key=u-switch 的 auth_key/成员令牌；default_model 填 u-switch 别名（逻辑名）。 ai_fetch_models拉别名列表 → 手工校准模型元数据（关键）：u-switch 返回的是逻辑别名，devflow 的 probe 按名字推断 context_window/模态会失真；路由过滤context_window >= estimated_context（router.rs:101）可能误过滤 → 前端模型表手工改对 context_window 或关掉该模型。- 路由双层决策（人定）：devflow 自带 ProviderPool weight + 跨供应商 fallback，与 u-switch 路由/failover 职责重叠。推荐起步姿势 = devflow 只保留 u-switch 一个启用 provider（本地 LB 自然退化，网关全权路由，保 prompt cache 亲和）；或保留 devflow 多 provider 直连兜底、u-switch 只管其中一路。
B. u-switch 侧小缺口（可选，按需排期）
- 旁路端点不接管（真实缺口）：u-switch 只认
/v1/messages+/v1/models。devflow 的知识库 embedding（/v1/embeddings）与图像生成（/v1/images/generations）走网关会 404。二选一：- devflow 侧把这两类功能指向别的直连 provider（当前架构旁路本就不经主链，配置可分离）；
- u-switch 加透传端点（违背其「Anthropic 协议专用」极简定位，不推荐）。
- 额度码透传（体验优化）：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「现自用」阶段匹配。
四、验证清单（打通步骤）
- u-switch 起本地实例，switch.yml 配 auth_key + ≥1 个 Anthropic 兼容渠道别名
- devflow 新建 Anthropic provider 指向 u-switch，
ai_test_connection通过 ai_fetch_models拉到别名列表，手工校准 context_window- 非流式对话一轮 → 流式长对话一轮（验证 SSE 透传 + usage 落库非估算）
- 带工具调用会话一轮（验证 tool_use/tool_result 透传闭环）
- 人为断上游验证 failover：devflow 侧应无感或收到可重试错误
- u-switch SQLite 核对 u_requests 明细与 devflow 消息级 usage 一致