Skip to main content
网关护栏在绑定到某个 API 密钥的每次补全请求周围,叠加一层确定性的输入/输出策略。SDK 提供以下能力:
  • theo.guardrails.policies — 创建和管理策略。
  • theo.guardrails.presets — 只读的预设模板。
  • theo.guardrails.executions — 追溯审计日志。
  • theo.keys.getGuardrailPolicy / setGuardrailPolicy — 将策略绑定到某个密钥。
关于严格的可选启用约定、内置防护措施以及裁定语义,参见护栏指南。底层的 HTTP 结构见API 参考。

严格的可选启用约定

策略仅在通过 theo.keys.setGuardrailPolicy() 显式绑定到某个 API 密钥时才会生效。未绑定的密钥永远不会触发护栏——不存在自动的组织级或用户级默认回退。创建策略(或从预设生成策略)不会自动绑定它。

策略

列出

获取

创建

scope: "team" 需要一个有效的组织以及团队配置权限。通过 Idempotency-Key 请求头实现幂等。

更新

发送 rules 会替换整个规则集。

删除

会级联移除所有指向该策略的密钥绑定——此前绑定的密钥将回归严格可选启用的默认状态(即不执行任何护栏检查)。

测试(重放提示词)

针对该策略重放一个固定的提示词(以及可选的模型输出),并返回裁定链路——供仪表盘的测试台使用,无需消耗一次真正的补全调用。

绑定关系

列出当前绑定到某个策略的活跃(未撤销)密钥。在生产环境依赖某个策略之前,可用它来确认该策略正在预期的密钥上生效。

预设

仪表盘在空状态下提供的只读蓝图。目前上线的四个预设分别是 pii-safe、strict-json、cost-conscious 和 enterprise-default。 从预设创建策略,本质上就是一次普通的 policies.create() 调用,只是用预设的 rules 作为初始值:

执行记录(审计日志)

记录每一次护栏评估的只追加日志。个人调用方只能看到自己的记录;团队调用方可以看到当前活跃组织所拥有的策略下所有成员的记录。记录保留 90 天。

密钥绑定

错误处理

当输入阶段触发 deny 裁定时,SDK 会抛出一个与 REST 响应体结构一致的结构化错误:
对于流式补全,同样的响应体会在 done 之前以 error 类型的 SSE 事件发出。完整的错误分类见错误处理。

类型

SDK 为每一种数据结构都导出了对应的类型:
  • GuardrailPolicySummary — 完整的策略记录行。
  • GuardrailRuleInput — 单条规则(guardrail_id、phase、verdict,可选的 config、enabled、rule_order)。
  • GuardrailId — "pii_redactor" | "prompt_injection" | "json_repair" | "max_length" | "profanity"。
  • GuardrailPhase — "input" | "output"。
  • GuardrailVerdict — "flag" | "redact" | "truncate" | "repair" | "deny"。
  • GuardrailPolicyPreset — presets.list() 返回的预设模板。
  • GuardrailPolicyBinding — 绑定关系端点返回的单条记录。
  • GuardrailPolicyTestResult — policies.test() 返回的裁定链路。
  • GuardrailExecutionRecord — 执行记录审计日志中的单条记录。