# 神识模型网关

> 状态：rewrite/1.0 M4 已落地（2026-08-27）——数据面/路由/故障切换/BYOK/配额三段式/计量落库/Anthropic+Gemini 适配器/用户面（灵台 /me/* 代理 + 前端神识阁）；官方云计费（P2）与生产 PG 档联调随标准档部署复核
> 参考项目只借设计不复制源码：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 用量对账抽样。