文档

文档

网关输入护栏

在用户提示到达 AI 提供商之前在网关进行扫描。按项目配置执行、监控或禁用模式，并始终开启未成年人保护。

概述

ModelRiver 输入护栏在请求转发给 AI 提供商之前，于网关层扫描用户提供的文本。护栏在所有支持的入口点上自动运行——原生 API、流式传输、异步、Playground 和 OpenAI 兼容路由。

被拦截的请求永远不会到达提供商，不会产生计费，也不会在日志或错误响应中保留原始提示。

护栏如何工作

每个请求都会经过分层决策流程：

  1. 文本提取 — 扫描 messages、prompt 和 input 字段。当存在文本部分时，支持多模态消息内容。
  2. 始终开启的未成年人检查 — 无论项目设置如何，CSAM 和未成年内容都会被拦截。
  3. 本地分类器 — 快速的基于正则表达式的模式检测明显违规。
  4. 远程审核 — 当远程审核启用时，模糊情况会升级到 OpenAI omni-moderation-latest。
  5. 决策 — 根据项目策略允许、拦截，或在监控模式下记录并允许。
  6. 审计日志 — 记录类别、来源、延迟和操作。被拦截请求的 request body 永远不会被存储。

重复提示会按项目策略进行指纹化和缓存，以减少相同输入的延迟。

策略模式

在 Settings → Project settings → Content Safety 中按项目配置执行模式：

模式行为
enforce违规请求被拦截，返回 HTTP 403（或 OpenAI 兼容的 400）
monitor违规被记录，但请求继续发往提供商
disabled可配置类别关闭；未成年人保护仍然强制执行

新项目默认使用 enforce 模式，并启用全部四个可配置类别。自托管部署可设置 GUARDRAILS_FORCE_ENFORCE=true，强制所有项目使用执行模式。

内容类别

每个项目可配置四个类别：

类别描述
sexual露骨或色情内容
self-harm自杀或自残指令
hate侮辱性言论、种族灭绝或种族清洗
violence武器、爆炸物、谋杀或尸体处理

未成年人/CSAM 保护始终强制执行，无法禁用。即使项目模式为 disabled 或全局 GUARDRAILS_ENABLED 标志关闭，此保护仍然有效。

配置护栏

  1. 在控制台中打开项目
  2. 进入 Settings → Project settings
  3. 滚动到 Content Safety
  4. 选择模式：Enforce、Monitor 或 Disabled
  5. 切换要强制执行的类别
  6. 点击 Save

访问控制

  • 仅限所有者/管理员：只有组织所有者和管理员可以削弱护栏——从执行切换到监控/禁用，或移除类别
  • 成员可加强策略：成员可以重新启用类别或切换回执行模式
  • 按项目隔离：护栏策略按项目独立配置

覆盖的入口点

护栏在以下位置自动运行：

  • 原生同步：POST /api/v1/ai
  • 原生异步：POST /api/v1/ai/async
  • 流式传输：SSE 开始前进行预检
  • OpenAI 兼容：POST /api/v1/chat/completions
  • 控制台 Playground（同步和异步）

仅包含图片或空文本的请求返回 not_checked，在没有文本分类的情况下继续处理。护栏仅适用于输入——AI 输出不会在服务端被审核。

错误处理

在执行模式下，被拦截的请求会显示清晰的错误：

API状态错误代码消息
原生 API403content_policy_violationRequest blocked by content policy.
OpenAI 兼容400content_policy_violationRequest blocked by content policy.
流式传输（预检）403content_policy_violationSSE 开始前的 JSON 响应
滥用节流429rate_limited重复拒绝后的冷却期

被拦截的响应在可用时包含触发的 categories。原始提示永远不会在错误正文中返回。当同一 API 密钥或用户反复在执行模式下被拒绝后，ModelRiver 会返回带有 Retry-After 标头的 HTTP 429（默认：每个项目 900 秒窗口内 5 次拒绝）。

隐私与计费

  • 无提示泄露：被拦截的提示不会存储在请求日志中，也不会在 API 错误中返回
  • 无提供商计费：被拦截和节流的请求不会增加组织请求计数器，也不会消耗提供商 Token
  • 审计而不暴露：护栏日志记录 guardrail_result、guardrail_action、guardrail_source、guardrail_categories 和 guardrail_latency_ms，且 request_body: nil

在监控模式下，违规请求会继续发往提供商，但护栏决策仍会记录为 guardrail_action: allow。

最佳实践

  • 从监控模式开始：在对生产流量强制执行拦截之前，先观察违规率
  • 保持执行模式为默认：面向公众的应用和生产 API 密钥应使用执行模式
  • 将削弱权限限制给管理员：使用组织角色，确保只有所有者/管理员可以禁用或削弱护栏
  • 审查护栏日志：使用控制台请求日志审计类别和延迟，无需访问被拦截的提示文本

下一步