接入模型服务

换模型服务改名册，开关在库表缺省关，业务代码不直连模型

所有模型调用只经 SZV 自写的一个网关，业务代码不直连模型：换模型服务，改名册里的一项；开关是库里的一行，改它不发版。开关缺省关闭，开启后网关只把聚合数与令牌交给模型，自由文本原文到不了模型，敏感分类的调用只走本地推理。需要模型自己调用工具，或需要成品网关的缓存、配额、多服务编排时，这套做法不合适。

一次调用经过什么

业务里用到模型的一处，叫一个调用面，比如付款说明。调用面只与网关打交道，网关把请求交给适配器，适配器调用名册里登记的推理服务。

部件	做什么
调用面	业务里用到模型的一处，各有自己的开关
网关	查开关、做投影、校验输出、写留痕，集中在这一处，业务代码不直连模型
适配器	把请求装成 chat-completions 兼容协议的格式，用 HTTP 发给具体服务
名册	登记可用的推理服务，每项声明位置：机房内，或机房外
开关	每个调用面一个，缺省关；关闭时直接返回规则生成的文本，标「降级」

网关里每一步检查的理由与剩余风险，见模型能碰什么不能碰什么；这一页只讲它们怎样配置。

各项配置存在哪里

「模型接入是配置」容易被说成一句话，实际有几处不同的存放，改法也不同：

对象	存在哪里	怎样改	缺省
调用面开关	PostgreSQL 的功能开关表，一行一个调用面	改一行，不发版，不读环境变量	关
名册	配置	增减服务改配置，不改程序	无
投影白名单与输出契约	代码与契约包	随版本发布	白名单为空，契约外的字段拒收
密钥	环境变量	运行环境提供，只在进程里读	无

开关在库表里，打开或关闭一个调用面是改一行数据。白名单与契约在代码与契约包里，决定模型能看到什么、能写出什么，它们的改动随版本发布，要经代码审查。同一个调用面的开关与白名单因此不在同一处，核对时要分开看。

敏感数据只走本地

名册里每个服务声明位置。路由约束由网关执行：

敏感分类的调用只许走位置为「本地」的服务，兜底路由不得放宽这条限制。
敏感调用不带投影版本即拒绝。没有「原始数据直通模型」的路径。

私有部署时，名册里登记的是企业机房内的推理服务，敏感数据不出机房，见私有部署概览和在自己的机房运行模型。

名册的结构允许登记机房外的服务。是否启用、启用哪一家，由企业评估并批准；批准之前，开关保持关闭。

防止绕过网关

SZV 的后端没有引入任何大模型 SDK，适配器直接用 HTTP 调用。仓库另有机器扫描，禁止直连模型 SDK 的写法，并检查个人信息规则，扫描纳入发布前校验。扫描拦得住常见的直连写法，证明不了语义上只有一个入口，所以网关里的投影、校验、留痕不依赖它。

接入一个调用面

示例：给「付款说明」接入模型。

企业评估并批准：是否接入，接哪家。批准之前，开关保持关闭。
在名册登记服务，声明位置。私有部署时登记机房内的推理服务。
登记调用面：投影白名单与输出契约。
打开该调用面的开关。
之后每次调用都留痕，含被拒与降级。任一步失败，页面显示规则生成的文本，转人工。

模型输出要落库的，只是待审批的草案，经权限、审批、留痕之后才写入业务数据。只用于展示的说明文本不落库。

限制与不适用

网关要自己维护，没有成品网关的缓存、配额和多服务编排。
协议只用请求格式最通用的一种，不接工具。
密钥只从环境变量读，不进数据库，也不进配置文件。同机其他进程、崩溃转储有可能读到它；密钥管理服务加轮换更稳妥。

与常见做法对照

层	SZV	通行做法
网关	自写，在服务端内，只做开关、投影、校验、留痕、路由约束	成品 AI 网关，如开源的 LiteLLM，提供统一的接口、用量统计、限流与多服务路由
协议	chat-completions 兼容协议	同样是这一格式；需要工具时用 tool calling 或 MCP
密钥	环境变量	密钥管理服务或文件挂载，加轮换，见 OWASP 密钥管理备忘

自写网关的取舍是依赖少、攻击面小，同时功能也少：它的职责是开关、投影、校验、留痕与路由约束，不含缓存、配额和多服务负载均衡。需要这些功能时，成品网关能提供，但敏感数据的投影、校验与留痕不能交给它。

其他做法

做法	它解决什么	为什么不用
业务代码各自直连模型服务	接入最快	开关、投影、校验、留痕各写一份，改一处漏一处；有人问「模型看到了什么」，没有一个地方答得出
采用厂商提供的调用库	少写适配器	调用格式跟着厂商走，换服务要改代码；用通用的请求格式，换服务只改名册
开关放在环境变量或配置文件	实现简单	改开关要重启或发版，且与库里其他功能开关成了两个来源
让模型调用工具，取数、查询由它自己决定	流程更自动	同时凑齐私有数据、可能带指令的内容与对外通道；SZV 的模型不接工具，是有意的取舍

验收时可以问的问题

请演示一次被拒的调用：敏感分类的调用不带投影版本，网关怎样拒绝，留痕里记成什么。
请演示发布前校验里禁止直连模型 SDK 的扫描，拦下一处直连写法时的输出。
使用外部服务时，密钥由谁管理、轮换由谁做，按什么约定。