安全厂商接入指南
安全厂商把检测能力接入网关的两条路：内容安全检测 HTTP 接口与 WASM 网关扩展
安全厂商接入指南
安全厂商把自己的检测能力接入网关有两条路，都已在产品中实现，不需要定制开发：
| 内容安全检测 HTTP 接口 | WASM 网关扩展 | |
|---|---|---|
| 厂商交付物 | 一个实现平台契约的 HTTP 服务 | 一个扩展包（Rust 或 Lua 编译为 WASM） |
| 运行位置 | 厂商自己的服务，平台调用它 | 网关进程内，随请求执行 |
| 能做什么 | 对输入、输出（含多轮历史）给出 6 类风险分数与提示注入分数；拦截、放行由流量规则的「内容检测」动作按阈值决定 | 放行或拒绝请求、改写请求正文与请求头、增量检查流式响应；逻辑由厂商自己写 |
| 时间预算 | 单次调用 8 秒 | 单次执行 20 ms，最多 4 次受控 HTTP 请求 |
| 适用服务 | 模型调用 | 模型服务、MCP 服务、API 服务、外部智能体（按扩展声明） |
| 平台侧配置 | 添加模型供应商 + 选为默认内容安全模型 + 在流量规则里使用「内容检测」 | 上传扩展包 + 安装 + 绑定到服务 |
1. 怎么选
- 检测依赖模型推理或厂商云端服务、单次耗时在几十毫秒以上：选 HTTP 接口。平台按固定契约调用，结果进入统一的内容检测、试判与审计链路，阈值与失败策略由管理员在流量规则里配置。
- 规则型、本地可算的判断（请求头、身份、关键字、格式校验、改写脱敏、流式输出截断），或需要作用于 MCP、API 服务、外部智能体：选 WASM 网关扩展。
- 两者可以同时使用：扩展做轻量前置判断与改写，HTTP 接口做语义风险评分。
2. 路径一：内容安全检测 HTTP 接口
契约
完整字段见《自定义内容安全检测服务接口》，要点：
POST {base_url}/v1/content-safety，Authorization: Bearer <API 密钥>，JSON 请求与响应。- 请求含
direction（input/output）、userText，输出方向带responseText，开启多轮检测时带history。 - 响应必须给出
categories的 6 个固定类别分数与jailbreak分数，均为 0–1；可选labels只用于审计。缺键、未知键、分数越界都判为响应不合法。 - 超时 8 秒；超时、连接失败或响应不合法按规则的「检测失败时」动作处置，不会静默放行。
上线步骤
- 厂商部署检测服务，确认网关能访问其 Base URL（内网地址需经平台出站防护放行）。
- 管理员在「模型供应商」中添加供应商，选择预设「自定义内容安全检测服务」，填写 Base URL 与 API 密钥。
- 在「全局设置 › 默认模型」的「内容安全」一行选择该服务，「模型类型」选「自定义内容安全检测服务」并保存。保存时平台用一句违规样例和一句安全样例实际调用核对，核对失败不保存并给出原因。
- 在流量规则中使用「内容检测」动作，选择风险分类、阈值与「检测失败时」的处置。
- 用「试一句」与「验证规则」分别发送安全样例与业务真实风险样例，确认命中符合预期，再对试点调用方生效。
3. 路径二：WASM 网关扩展
契约
开发、构建、校验与发布的完整说明见《网关扩展开发》，要点：
- 包合同
zenova.gateway-plugin/v4，清单声明supportedServiceKinds（model、mcp、http_proxy、a2a）。 - 三种接口：
request-gate（放行或拒绝）、request-transform（改写请求）、gateway-response-transform（检查流式响应）。 - 每次执行 2,000,000 指令预算、20 ms、4 MiB 内存；访问外部服务只能经
http_request，目的地必须在清单中声明并由安装时的密钥绑定授权。 - 上传时平台用生产宿主真实编译并执行一次合成请求，不通过即拒绝。
上线步骤
- 厂商用「网关扩展 › 下载 SDK」或
zr-plugin init生成模板，编写逻辑后zr-plugin build与zr-plugin validate。 - 管理员在「网关扩展」上传扩展包（或厂商用具备网关扩展管理权限的用户令牌
zr-plugin publish）。 - 在扩展详情的「权限」标签核对网络目标、密钥、安全与 PII 要求；需要访问厂商云端时，在「绑定」中配置密钥绑定与允许目的地。
- 填写配置并安装（安装后为停用），状态「已生效」后启用；在「绑定」中选择服务类型与服务范围。安全关键扩展的失败策略配置为
fail_closed。 - 用命中与不命中的请求分别验证，在「执行统计」核对拦截、失败与 p95 耗时；耗时接近 20 ms 时应把重计算移到 HTTP 接口一侧。
4. 验收清单
- 安全样例放行、风险样例按预期拦截或改写。
- 检测服务停机或扩展出错时，请求按配置的失败策略处置，而不是放行。
- 可观测中心与审计中能看到每次检测的结果与原因。