Files

verify / verify (push) Has been cancelled

Details

Isolate cloud model access before enabling product RAG workflows

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

2026-07-13 04:09:06 +08:00

4.8 KiB

Raw Permalink Blame History

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 服务：

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，避免重复文本。

被否决方案

API 直接挂 Key 与 egress： 数据库感知进程同时拥有数据、模型凭据和公网出口。
Worker 直接调用百炼： 会形成两个供应商调用实现和两个 Key 边界。
Model Gateway 连接数据库验证审批： 重新形成“数据 + Key + egress”的高风险组合。
只依赖 Docker DNS 或来源 IP： 网络成员不是应用层身份，不能替代内部令牌。
引入通用 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 全部通过后，才能宣称在线百炼模型边界可用。

4.8 KiB Raw Permalink Blame History Unescape Escape