guardrails-ai

Guardrails AI 的输入输出校验与结构化输出框架。

补充说明

Guardrails AI 在 LLM 前后插入校验器（validator），处理 JSON 结构、PII、敏感话题、竞品提及和格式约束。校验失败时可以抛异常、自动修复、重新询问模型或过滤内容。

核心概念：Guard 是校验容器，Hub 上的 validator 是可安装的规则包。LLM 类 validator 会增加一次模型调用，成本和延迟要计入预算。

安装与启动

pip install -U guardrails-ai
guardrails configure

guardrails configure 会询问 Hub token；CI 中先在有网环境安装 validator，再把依赖固化进镜像。

guardrails hub install hub://guardrails/valid_json
guardrails hub install hub://guardrails/detect_pii
guardrails hub list

常用示例

校验模型输出是否为合法 JSON：

python - <<'PY'
from guardrails import Guard
from guardrails.hub import ValidJson

guard = Guard().use(ValidJson, on_fail="exception")
try:
    outcome = guard.validate('{"service": "api", "port": 8080}')
    print("ok:", outcome.validated_output)
except Exception as exc:
    print("invalid json:", exc)
PY

检测并脱敏 PII：

python - <<'PY'
from guardrails import Guard
from guardrails.hub import DetectPII

guard = Guard().use(DetectPII(pii_entities="pii", on_fail="fix"))
outcome = guard.validate("联系人手机号 13800138000，请回拨。")
print(outcome.validated_output)
PY

在调用模型时直接套 Guard：

python - <<'PY'
from guardrails import Guard
from guardrails.hub import ValidJson

guard = Guard().use(ValidJson, on_fail="reask")
outcome = guard(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "返回包含 name 和 port 的 JSON"}],
)
print(outcome.validated_output)
PY

易错点与排错

• Hub validator 需要 token 和网络，离线 CI 会在 guardrails hub install 阶段失败；提前缓存 wheel 并锁定版本。
• guardrails-ai 与旧包名 guardrails 不能混装，否则 import 到旧代码；虚拟环境里先 pip list | grep guardrails。
• on_fail="fix" 会静默改写内容，审计场景要同时记录原始输出和修复后输出。
• ValidJson 只校验语法，不校验业务 schema；字段缺失或类型错误要用 Pydantic/JSON schema 再校验一层。
• DetectPII 依赖 Presidio 和 spaCy 模型，首次运行会下载模型；离线环境需预装语言模型。
• 把 dict 直接传给 Guard.validate 会报类型错误；先序列化成字符串，或使用结构化输出的专用接口。
• LLM 型 validator 会再调一次模型，延迟翻倍；高 QPS 服务应缓存结果或改成规则校验。
• validator 与 pydantic 版本经常冲突；升级前在同一环境跑一遍现有 Guard 测试。
• 多个 validator 串联时，前一个的 fix 可能破坏后一个的输入；明确执行顺序并分别测试。

读完自测

合上页面，先回答，再展开对照。

1. on_fail 常见取值有哪些，分别做什么？
2. 为什么 ValidJson 通过了仍然可能出错？
3. Hub validator 在离线环境怎么用？

相关条目

• llama-guard
• promptfoo
• langchain
• ragas
• vllm