神识模型网关

状态：重写目标态（rewrite/1.0 基线），重写期间新建，一次性替换灵台 Python ai_provider 参考项目只借设计不复制源码：octopus（IR 双向转换、首字超时切道）、new-api（计费不变量、渠道 adaptor 分层）、lens（模型组与冷却粒度）、metapi（路由可解释）、axonhub（协议集成测试矩阵）。

1. 定位与边界

神识是魂镜唯一的模型出口（Go 1.25+ 单服务）：

拥有：Provider/Endpoint 目录、模型能力槽位、协议转换（内部 IR ↔ 各厂商方言）、路由与故障切换、流式转发、BYOK 密钥保管、配额与成本计量、用量日志。

不拥有：人物身份解释、道体、记忆、关系、缘契、长期状态、工具授权决策。神识不因模型差异产生"人格变化"语义；模型与人格的解耦由灵台保证。

2. 模块划分

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. 路由与故障切换

候选迭代器：按策略（优先级排序 / 加权随机）生成候选序列，逐个尝试；
首字超时：流式请求在首 token 超时内无响应即切下一候选；已写出字节后不换道（Written 判断），失败如实上报；
冷却粒度（避免整渠道误杀）：401/403 只冷却凭证；404/429/5xx/超时只冷却"该渠道上的具体模型绑定"，同渠道其他模型不受影响；
熔断：滑动窗口健康评分作轮询权重；
粘性会话：同一 Run 的连续请求优先成功通道（模型输出风格稳定）；
路由可解释：每次选择记录决策摘要（候选、健康、冷却状态），可审计；
配对保护：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 教训）：

任何计费乘数（图片张数、时长、max_tokens）在请求校验期设上限；
配额换算集中单一函数，饱和截断（防溢出变负）；
钳位与截断事件写审计日志；
三段式：预扣（按上限）→ 结算（实际-预扣差额）→ 退款（失败幂等退款）；
透传字段与 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`	用量查询（按用户/模型/时间）

错误码段与事件名见契约词典；服务间鉴权：灵台 ↔ 神识用服务令牌 + 请求签名，管理面走 RBAC。

9. 与元炁的关系

元炁是 type=local 的 Endpoint：神识按普通候选路由到它（本地零成本、隐私友好）。embedding/rerank 槽位默认路由元炁（BGE-M3），无本地模型时回退云厂商。天目 OCR 不经神识（非生成模型），由灵台直接调用。

10. 迁移与退役

神识上线并接入元炁 + 至少一个云 Provider（OpenAI 兼容）；
灵台 shenshi_client 切换流量，双写用量对比一个验证周期；
删除 Python ai_provider 模块及其配置（config/models.yaml、config/providers.yaml、config/pricing.yaml 移交神识目录）；
能力矩阵更新"神识网关"行证据。

禁止：把玄关改名冒充神识；灵台领域模块直接 import 任何 Provider SDK；神识读写灵台库表。

11. 测试策略

adaptor 单元测试：IR ↔ 方言的往返（round-trip）一致性；可选标量零值用例；
集成测试矩阵：入站协议 × Provider 面板（最小集合：OpenAI 兼容、Anthropic、本地元炁）；
故障注入：首字超时切道、凭证冷却粒度、熔断恢复、流中断如实上报；
计量一致性：预扣-结算-退款幂等；usage_logs 与 Provider 用量对账抽样。

6.7 KiB Raw Blame History Unescape Escape