111 lines
6.7 KiB
Markdown
111 lines
6.7 KiB
Markdown
# 神识模型网关
|
||
|
||
> 状态：重写目标态（rewrite/1.0 基线），重写期间新建，一次性替换灵台 Python `ai_provider`
|
||
> 参考项目只借设计不复制源码：octopus（IR 双向转换、首字超时切道）、new-api（计费不变量、渠道 adaptor 分层）、lens（模型组与冷却粒度）、metapi（路由可解释）、axonhub（协议集成测试矩阵）。
|
||
|
||
## 1. 定位与边界
|
||
|
||
神识是魂镜唯一的模型出口（Go 1.25+ 单服务）：
|
||
|
||
**拥有**：Provider/Endpoint 目录、模型能力槽位、协议转换（内部 IR ↔ 各厂商方言）、路由与故障切换、流式转发、BYOK 密钥保管、配额与成本计量、用量日志。
|
||
|
||
**不拥有**：人物身份解释、道体、记忆、关系、缘契、长期状态、工具授权决策。神识不因模型差异产生"人格变化"语义；模型与人格的解耦由灵台保证。
|
||
|
||
## 2. 模块划分
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
IG[ingress<br/>入站协议] --> TF[transform<br/>IR 双向转换]
|
||
TF --> RT[route<br/>候选生成+健康+冷却]
|
||
RT --> RL[relay<br/>流式转发]
|
||
RL --> MT[metering<br/>用量与成本]
|
||
MT --> QT[quota<br/>配额三段式]
|
||
RG[registry<br/>目录管理]
|
||
KV[keyvault<br/>密钥与 BYOK]
|
||
RT --> KV
|
||
IG --> QT
|
||
```
|
||
|
||
- `transform` 做成独立 Go module（内无业务依赖，可独立构建与测试）；
|
||
- 其余模块按包组织在单服务内，不拆进程。
|
||
|
||
## 3. 数据模型（神识自有库）
|
||
|
||
| 表 | 要点 |
|
||
| --- | --- |
|
||
| `providers` | 厂商协议类型（openai/anthropic/gemini/local 等） |
|
||
| `endpoints` | 多 BaseUrl + 多凭证 + 权重/优先级 + 健康状态；`type=local` 的 Endpoint 指向元炁 |
|
||
| `model_slots` | 能力槽位：chat/vision/asr/tts/image/embedding/rerank/safety；逻辑模型 → 槽位声明 |
|
||
| `routes` | 逻辑模型名 → 候选 Endpoint×上游模型 绑定列表 + 路由策略（优先级/加权/故障切换） |
|
||
| `byok_keys` | 用户自带密钥：归属 `user_id`，加密存储，API 永远脱敏返回；使用范围与用途受限 |
|
||
| `usage_logs` | 每次尝试一条：请求级终态 + 尝试链 + 流时序（首字/总时长）+ token 三段（输入/输出/缓存）+ 成本明细 |
|
||
|
||
逻辑模型与物理模型解耦：灵台只请求逻辑模型名与槽位，神识负责落到具体 Endpoint。
|
||
|
||
## 4. 路由与故障切换
|
||
|
||
1. **候选迭代器**：按策略（优先级排序 / 加权随机）生成候选序列，逐个尝试；
|
||
2. **首字超时**：流式请求在首 token 超时内无响应即切下一候选；已写出字节后不换道（`Written` 判断），失败如实上报；
|
||
3. **冷却粒度**（避免整渠道误杀）：401/403 只冷却凭证；404/429/5xx/超时只冷却"该渠道上的具体模型绑定"，同渠道其他模型不受影响；
|
||
4. **熔断**：滑动窗口健康评分作轮询权重；
|
||
5. **粘性会话**：同一 Run 的连续请求优先成功通道（模型输出风格稳定）；
|
||
6. **路由可解释**：每次选择记录决策摘要（候选、健康、冷却状态），可审计；
|
||
7. **配对保护**：tool_call 与 tool_result 在转换、重试、压缩中永不拆散。
|
||
|
||
## 5. 协议与流式
|
||
|
||
- **入站（灵台 → 神识）**：单一内部 IR（版本化 Schema）；灵台 `shenshi_client` 是唯一调用方；
|
||
- **出站（神识 → Provider）**：各厂商 adaptor（每 Provider 一个包：adaptor + dto + relay），SSE 逐事件转换透传；
|
||
- 流式响应统一 SSE；`X-Accel-Buffering: no`；校验上游 Content-Type 防"假流"；
|
||
- **DTO 细节纪律**：可选标量一律指针 + `omitempty`，防显式零值被静默丢弃；
|
||
- 响应回传 `X-Request-Id`、用量头，与灵台 `run_id`/`trace_id` 关联（usage_logs 双向可查）。
|
||
|
||
## 6. BYOK 与密钥
|
||
|
||
- 密钥分层：平台密钥（神识 keyvault）与用户 BYOK（`byok_keys`，用户级加密）；
|
||
- 配置继承顺序（产品 PRD §9.2）：平台硬边界 → 平台目录 → 用户偏好/BYOK → 人物覆写 → 镜树临时选择；该层叠在灵台 Profile 计算，神识只接收最终解析结果中的密钥引用；
|
||
- 神识对 BYOK 的使用范围（可用槽位、地区限制）受平台硬边界约束；高敏数据可配置"仅本地 Endpoint"。
|
||
|
||
## 7. 配额与计量
|
||
|
||
计费不变量（借鉴 new-api 教训）：
|
||
|
||
1. 任何计费乘数（图片张数、时长、max_tokens）在请求校验期设上限；
|
||
2. 配额换算集中单一函数，饱和截断（防溢出变负）；
|
||
3. 钳位与截断事件写审计日志；
|
||
4. 三段式：预扣（按上限）→ 结算（实际-预扣差额）→ 退款（失败幂等退款）；
|
||
5. 透传字段与 multipart 是校验绕过高危路径，adaptor 层显式白名单。
|
||
|
||
1.0 官方云计费属 P2；P0/P1 只做计量（usage_logs 完整）与用户级软配额（预算提醒与熔断）。
|
||
|
||
## 8. API 形态
|
||
|
||
| 面 | 端点 | 说明 |
|
||
| --- | --- | --- |
|
||
| 数据面 | `POST /v1/chat/completions`（IR 入站 + SSE） | 灵台唯一推理入口；附 embeddings/rerank/images/audio 端点按槽位启用 |
|
||
| 健康面 | `GET /healthz`、`GET /readyz` | 供 Compose 与天门探活 |
|
||
| 管理面 | `/admin/providers` `/admin/endpoints` `/admin/routes` `/admin/slots` | 目录 CRUD、健康探测、定价表（平台管理员） |
|
||
| 计量面 | `/admin/usage`、`/me/usage` | 用量查询（按用户/模型/时间） |
|
||
|
||
错误码段与事件名见[契约词典](../contracts/contract-glossary.md)；服务间鉴权：灵台 ↔ 神识用服务令牌 + 请求签名，管理面走 RBAC。
|
||
|
||
## 9. 与元炁的关系
|
||
|
||
元炁是 `type=local` 的 Endpoint：神识按普通候选路由到它（本地零成本、隐私友好）。embedding/rerank 槽位默认路由元炁（BGE-M3），无本地模型时回退云厂商。天目 OCR 不经神识（非生成模型），由灵台直接调用。
|
||
|
||
## 10. 迁移与退役
|
||
|
||
1. 神识上线并接入元炁 + 至少一个云 Provider（OpenAI 兼容）；
|
||
2. 灵台 `shenshi_client` 切换流量，双写用量对比一个验证周期；
|
||
3. 删除 Python `ai_provider` 模块及其配置（`config/models.yaml`、`config/providers.yaml`、`config/pricing.yaml` 移交神识目录）；
|
||
4. 能力矩阵更新"神识网关"行证据。
|
||
|
||
**禁止**：把玄关改名冒充神识；灵台领域模块直接 import 任何 Provider SDK；神识读写灵台库表。
|
||
|
||
## 11. 测试策略
|
||
|
||
- adaptor 单元测试：IR ↔ 方言的往返（round-trip）一致性；可选标量零值用例；
|
||
- 集成测试矩阵：入站协议 × Provider 面板（最小集合：OpenAI 兼容、Anthropic、本地元炁）；
|
||
- 故障注入：首字超时切道、凭证冷却粒度、熔断恢复、流中断如实上报；
|
||
- 计量一致性：预扣-结算-退款幂等；usage_logs 与 Provider 用量对账抽样。
|