YoVinchen
75592af33a
Some checks failed
verify / verify (push) Has been cancelled
The API and ingestion tools now use a fixed internal model gateway while governed profiles, embedding cache assignments, traceable citations, and stable API errors establish the boundaries required by later workflows. Constraint: The current Alibaba Cloud workspace rejects all three live model calls with authentication failures Rejected: Give the API or seed tools the Bailian key and direct egress | combines database access, cloud credentials, and public network access Rejected: Mix offline and Bailian vectors in one demo namespace | makes profile activation and retrieval ambiguous Confidence: high Scope-risk: moderate Reversibility: clean Directive: Keep Bailian credentials and egress exclusive to model-gateway and create a new immutable profile hash for any embedding identity change Tested: make verify; 121 backend tests; 14 frontend tests; fresh and populated Alembic upgrade-downgrade-upgrade; two idempotent offline seeds; Docker health and HTTP retrieval; isolated provider smoke Not-tested: Successful live Bailian responses because the supplied workspace credential currently fails authentication
69 lines
4.8 KiB
Markdown
69 lines
4.8 KiB
Markdown
# ADR-0005：使用独立 Model Gateway 隔离百炼出口
|
||
|
||
- **状态：** accepted
|
||
- **日期：** 2026-07-13
|
||
|
||
## 背景
|
||
|
||
在线 RAG 必须同步完成 Query Embedding、Rerank 和 Chat SSE，但 ADR-0004 又要求数据库感知 API 不持有百炼 Key、没有公网默认出口。让 API 或 Worker 直接调用百炼，会把业务数据、数据库凭据、模型凭据和公网出口集中到同一信任边界；只保留一次性 smoke/seed 工具则无法支持在线问答。
|
||
|
||
## 决策
|
||
|
||
新增与 API 共用 backend 镜像的长期 `model-gateway` 服务：
|
||
|
||
```text
|
||
browser
|
||
-> web (edge + ingress)
|
||
-> gateway (ingress + data)
|
||
-> api (data + model)
|
||
-> PostgreSQL/pgvector (data)
|
||
-> model-gateway (model + egress)
|
||
-> Alibaba Cloud Model Studio
|
||
|
||
worker (data + model)
|
||
-> PostgreSQL/pgvector
|
||
-> model-gateway
|
||
```
|
||
|
||
- 只有 `model-gateway` 挂载 `bailian_api_key` 并连接 `egress`；它不连接 `data`、不挂数据库 Secret、上传卷或宿主端口。
|
||
- API 与 Worker 不挂百炼 Key、不连接 `egress`，只通过 internal `model` 网络访问固定的 `http://model-gateway:8000`。
|
||
- API 与 Worker 使用不同的内部令牌。调用必须同时携带 `Authorization: Bearer ...` 与 `X-RAG-Caller`；Gateway 用常量时间比较把令牌映射到调用者，不能只信任 header 或 Docker 来源地址。
|
||
- API 允许 Query Embedding、Rerank、Chat 和受控 provider health；Worker 额外允许 Document Embedding。任意越权调用失败关闭。
|
||
- Model Gateway 只接受固定 profile、固定模型和固定端点的 vendor-neutral DTO，不接受客户端提供 URL、模型名、维度或任意转发目标。
|
||
- Embedding、Rerank 和 Chat 继续复用现有 provider ports 与百炼 adapter，不引入 SDK、Redis、消息队列、服务网格或第二套实现。
|
||
- 日志只允许 trace、调用者、操作、profile、输入数量、usage、耗时、request ID 和脱敏错误码；禁止记录 Key、Authorization、URL、query、messages、候选正文或响应正文。
|
||
- 容器 readiness 只验证本地配置、Secret 和客户端初始化，不产生模型费用；真实探测使用受控内部端点和显式命令。
|
||
|
||
## 内部接口
|
||
|
||
- `POST /internal/v1/embeddings`：接收 `texts` 和 `input_type=query|document`；Query 恰好一条，Document 为 1–10 条；返回 1024 维向量、resolved model、usage、request ID 和耗时。
|
||
- `POST /internal/v1/rerank`：接收 query、候选正文和 Top N；返回原始下标、score、受校验正文与 provider 元数据。
|
||
- `POST /internal/v1/chat/completions`：非流式内部调用，用于需要先完成引用校验的场景。
|
||
- `POST /internal/v1/chat/stream`：vendor-neutral SSE；流开始后的 provider 错误转换为终态 `error` 事件，取消必须关闭上游流。
|
||
- `GET /health/live` 与 `GET /health/ready`：不调用百炼。
|
||
|
||
公共 API 不把 Model Gateway 的内部 401/403 原样返回浏览器；这类错误统一映射为可观测的 503 配置故障。429、timeout、5xx 和非法响应分别映射为稳定、脱敏的错误码。首个输出之后不得自动重试 Chat，避免重复文本。
|
||
|
||
## 被否决方案
|
||
|
||
1. **API 直接挂 Key 与 egress：** 数据库感知进程同时拥有数据、模型凭据和公网出口。
|
||
2. **Worker 直接调用百炼：** 会形成两个供应商调用实现和两个 Key 边界。
|
||
3. **Model Gateway 连接数据库验证审批：** 重新形成“数据 + Key + egress”的高风险组合。
|
||
4. **只依赖 Docker DNS 或来源 IP：** 网络成员不是应用层身份，不能替代内部令牌。
|
||
5. **引入通用 API Gateway、Redis、Celery 或服务网格：** 当前单机毕设规模没有足够收益，并增加部署与恢复面。
|
||
|
||
## 后续约束
|
||
|
||
- `provider-smoke` 与真实 seed 必须使用 Model Gateway 客户端，不允许恢复直连百炼旁路。
|
||
- 普通在线查询只能使用知识库已激活的 embedding profile；Fake 与 Bailian profile 永不混查。
|
||
- Docker bridge 不是域名白名单。生产环境仍需主机防火墙或出口代理只放行获批的百炼域名。
|
||
- 改变模型调用者、内部鉴权、网络成员、Key 边界或 SSE 协议时，必须更新本 ADR 并重跑容器网络、Secret、取消和错误脱敏验收。
|
||
|
||
## 验证要求
|
||
|
||
- Compose 合同证明百炼 Key 与 `egress` 只存在于 `model-gateway`。
|
||
- Model Gateway 无数据库 Secret、`data` 网络、上传卷和宿主端口；API/Worker 无百炼 Key和 `egress`。
|
||
- 缺失/错误令牌、调用者冒充、scope 越权、URL/模型/维度注入均有失败测试。
|
||
- Embedding、Rerank、Chat 的成功、401、429、timeout、5xx、非法响应、SSE 取消均由 hermetic contract test 覆盖。
|
||
- `make verify`、镜像 Secret 扫描、Docker 健康检查、网络隔离与真实三模型 smoke 全部通过后，才能宣称在线百炼模型边界可用。
|