{
"canonical_name": "guardrails-ai/guardrails",
"compilation_id": "pack_8e05c50167024007be6c654a2a6206ff",
"created_at": "2026-05-11T13:45:21.471141+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install guardrails-ai` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install guardrails-ai",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_30eca47d4c774492a3214c468ad9b477"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_85e45fa2bef2a40f01fa3b66fcd9a8d9",
"canonical_name": "guardrails-ai/guardrails",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/guardrails-ai/guardrails",
"slug": "guardrails",
"source_packet_id": "phit_e9ea46b293f64b34915485deb0d15835",
"source_validation_id": "dval_4e8dcba9fe0c48c2ac835e2e5a64cd86"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 chatgpt的用户",
"github_forks": 601,
"github_stars": 6853,
"one_liner_en": "Adding guardrails to large language models.",
"one_liner_zh": "Adding guardrails to large language models.",
"primary_category": {
"category_id": "software-development",
"confidence": "medium",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git"
},
"target_user": "使用 chatgpt 等宿主 AI 的用户",
"title_en": "guardrails",
"title_zh": "guardrails 能力包",
"visible_tags": [
{
"label_en": "Knowledge Retrieval",
"label_zh": "知识检索",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-knowledge-retrieval",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Checkpoint Resume",
"label_zh": "断点恢复流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-checkpoint-resume",
"type": "workflow_pattern"
},
{
"label_en": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_e9ea46b293f64b34915485deb0d15835",
"page_model": {
"artifacts": {
"artifact_slug": "guardrails",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install guardrails-ai",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/guardrails-ai/guardrails#readme",
"verified": true
}
],
"display_tags": [
"知识检索",
"知识库问答",
"流程自动化",
"断点恢复流程",
"本地优先"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 chatgpt的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Adding guardrails to large language models."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "chatgpt",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：FIX action silently mutates output - should there be a 'quarantine' tier between LOG and FIX?",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_69600563346341a386aa86c6af5d1274 | https://github.com/guardrails-ai/guardrails/issues/1448 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：FIX action silently mutates output - should there be a 'quarantine' tier between LOG and FIX?",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Portable evidence artifacts for validation outcomes",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_ef2970465bbe44c89b513edd115b682c | https://github.com/guardrails-ai/guardrails/issues/1457 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Portable evidence artifacts for validation outcomes",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: PromptDefenseAudit Hub validator — static system prompt hardening check",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_d7163e193eb54aab837d87b3ecd73991 | https://github.com/guardrails-ai/guardrails/issues/1453 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Proposal: PromptDefenseAudit Hub validator — static system prompt hardening check",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：[docs] Fix double logo display in pypi",
"category": "能力坑",
"evidence": [
"community_evidence:github | cevd_084985c7cb4d4238a44e452b14b2eaf9 | https://github.com/guardrails-ai/guardrails/issues/1362 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[docs] Fix double logo display in pypi",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Integration proposal: Cryptographic audit trail validator with asqav",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_8db542ceccff4a71bc11c254ce3abfde | https://github.com/guardrails-ai/guardrails/issues/1446 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Integration proposal: Cryptographic audit trail validator with asqav",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Integration proposal: styxx hallucination validator (8-benchmark cross-validated)",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_da275c0a112848ed920af00c76fd3e1b | https://github.com/guardrails-ai/guardrails/issues/1463 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Integration proposal: styxx hallucination validator (8-benchmark cross-validated)",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: Agent Threat Rules detection integration",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_9d25561995774521a21051373d95b431 | https://github.com/guardrails-ai/guardrails/issues/1471 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Proposal: Agent Threat Rules detection integration",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] Guardrails CLI start command broken with guardrails-api 0.4.2",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_f411132764b84c17b318b5cc7a32ef56 | https://github.com/guardrails-ai/guardrails/issues/1464 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[bug] Guardrails CLI start command broken with guardrails-api 0.4.2",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.3",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_95f33a7ff8014d78a13752aa7fd56d6e | https://github.com/guardrails-ai/guardrails/releases/tag/v0.7.3 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.7.3",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.8.2",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_559ad38ac0504cff91377804f004c57c | https://github.com/guardrails-ai/guardrails/releases/tag/v0.8.2 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.8.2",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.2",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_ae34ce00e8554a5199b5e78e3465942d | https://github.com/guardrails-ai/guardrails/releases/tag/v0.9.2 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.9.2",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.3",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_f2b73a33cb2f47d3bba9b9f2dd07ed62 | https://github.com/guardrails-ai/guardrails/releases/tag/v0.9.3 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.9.3",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.8.0",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_160840f6f00644f2bcd25339973d1d82 | https://github.com/guardrails-ai/guardrails/releases/tag/v0.8.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.8.0",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.9.0",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_91ae72d0a0f74305b8b5b3f66d4048e4 | https://github.com/guardrails-ai/guardrails/releases/tag/v0.9.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.9.0",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 23 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：安装坑 - 来源证据：FIX action silently mutates output - should there be a 'quarantine' tier between LOG and FIX?。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 77,
"forks": 601,
"license": "unknown",
"note": "GitHub API 快照，非实时质量证明；用于开工前背景判断。",
"stars": 6853,
"open_issues": 32,
"pushed_at": "2026-05-12T20:53:45.000Z"
},
"source_url": "https://github.com/guardrails-ai/guardrails",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Adding guardrails to large language models.",
"title": "guardrails 能力包",
"trial_prompt": "# guardrails - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 guardrails 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Adding guardrails to large language models. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：Guardrails 简介。围绕“Guardrails 简介”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装与配置。围绕“安装与配置”模拟一次用户任务，不展示安装或运行结果。\n3. page-guard-class：Guard 类详解。围绕“Guard 类详解”模拟一次用户任务，不展示安装或运行结果。\n4. page-schema-system：Schema 系统。围绕“Schema 系统”模拟一次用户任务，不展示安装或运行结果。\n5. page-validation-flow：验证流程与 Runner。围绕“验证流程与 Runner”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“Guardrails 简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装与配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-guard-class\n输入：用户提供的“Guard 类详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-schema-system\n输入：用户提供的“Schema 系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-validation-flow\n输入：用户提供的“验证流程与 Runner”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“Guardrails 简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装与配置”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-guard-class：Step 3 必须围绕“Guard 类详解”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-schema-system：Step 4 必须围绕“Schema 系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-validation-flow：Step 5 必须围绕“验证流程与 Runner”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/guardrails-ai/guardrails\n- https://github.com/guardrails-ai/guardrails#readme\n- README.md\n- guardrails/__init__.py\n- guardrails/guard.py\n- CONTRIBUTING.md\n- guardrails/cli/configure.py\n- Makefile\n- guardrails/async_guard.py\n- guardrails/prompt/__init__.py\n- guardrails/prompt/prompt.py\n- guardrails/prompt/instructions.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 guardrails 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Proposal: Agent Threat Rules detection integration（https://github.com/guardrails-ai/guardrails/issues/1471）；github/github_issue: Integration proposal: Cryptographic audit trail validator with asqav（https://github.com/guardrails-ai/guardrails/issues/1446）；github/github_issue: Portable evidence artifacts for validation outcomes（https://github.com/guardrails-ai/guardrails/issues/1457）；github/github_issue: [docs] Fix double logo display in pypi（https://github.com/guardrails-ai/guardrails/issues/1362）；github/github_issue: Integration proposal: styxx hallucination validator (8-benchmark cross-v（https://github.com/guardrails-ai/guardrails/issues/1463）；github/github_issue: MCP Server Compliance Scanning: OWASP MCP Top 10 guardrails（https://github.com/guardrails-ai/guardrails/issues/1435）；github/github_issue: [bug] Guardrails CLI start command broken with guardrails-api 0.4.2（https://github.com/guardrails-ai/guardrails/issues/1464）；github/github_issue: Proposal: PromptDefenseAudit Hub validator — static system prompt harden（https://github.com/guardrails-ai/guardrails/issues/1453）；github/github_issue: FIX action silently mutates output - should there be a 'quarantine' tier（https://github.com/guardrails-ai/guardrails/issues/1448）；github/github_release: v0.9.3（https://github.com/guardrails-ai/guardrails/releases/tag/v0.9.3）；github/github_release: v0.9.2（https://github.com/guardrails-ai/guardrails/releases/tag/v0.9.2）；github/github_release: v0.9.0（https://github.com/guardrails-ai/guardrails/releases/tag/v0.9.0）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Proposal: Agent Threat Rules detection integration",
"url": "https://github.com/guardrails-ai/guardrails/issues/1471"
},
{
"kind": "github_issue",
"source": "github",
"title": "Integration proposal: Cryptographic audit trail validator with asqav",
"url": "https://github.com/guardrails-ai/guardrails/issues/1446"
},
{
"kind": "github_issue",
"source": "github",
"title": "Portable evidence artifacts for validation outcomes",
"url": "https://github.com/guardrails-ai/guardrails/issues/1457"
},
{
"kind": "github_issue",
"source": "github",
"title": "[docs] Fix double logo display in pypi",
"url": "https://github.com/guardrails-ai/guardrails/issues/1362"
},
{
"kind": "github_issue",
"source": "github",
"title": "Integration proposal: styxx hallucination validator (8-benchmark cross-v",
"url": "https://github.com/guardrails-ai/guardrails/issues/1463"
},
{
"kind": "github_issue",
"source": "github",
"title": "MCP Server Compliance Scanning: OWASP MCP Top 10 guardrails",
"url": "https://github.com/guardrails-ai/guardrails/issues/1435"
},
{
"kind": "github_issue",
"source": "github",
"title": "[bug] Guardrails CLI start command broken with guardrails-api 0.4.2",
"url": "https://github.com/guardrails-ai/guardrails/issues/1464"
},
{
"kind": "github_issue",
"source": "github",
"title": "Proposal: PromptDefenseAudit Hub validator — static system prompt harden",
"url": "https://github.com/guardrails-ai/guardrails/issues/1453"
},
{
"kind": "github_issue",
"source": "github",
"title": "FIX action silently mutates output - should there be a 'quarantine' tier",
"url": "https://github.com/guardrails-ai/guardrails/issues/1448"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.9.3",
"url": "https://github.com/guardrails-ai/guardrails/releases/tag/v0.9.3"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.9.2",
"url": "https://github.com/guardrails-ai/guardrails/releases/tag/v0.9.2"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.9.0",
"url": "https://github.com/guardrails-ai/guardrails/releases/tag/v0.9.0"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Adding guardrails to large language models.",
"effort": "安装已验证",
"forks": 599,
"icon": "code",
"name": "guardrails 能力包",
"risk": "可发布",
"slug": "guardrails",
"stars": 6843,
"tags": [
"知识检索",
"知识库问答",
"流程自动化",
"断点恢复流程",
"本地优先"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/guardrails-ai/guardrails 项目说明书\n\n生成时间：2026-05-11 13:44:06 UTC\n\n## 目录\n\n- [Guardrails 简介](#page-introduction)\n- [安装与配置](#page-installation)\n- [Guard 类详解](#page-guard-class)\n- [Schema 系统](#page-schema-system)\n- [验证流程与 Runner](#page-validation-flow)\n- [验证器基础](#page-validators)\n- [Guardrails Hub](#page-hub)\n- [CLI 命令行工具](#page-cli)\n- [Guardrails 服务器](#page-server)\n- [框架集成](#page-integrations)\n\n\n\n## Guardrails 简介\n\n### 相关页面\n\n相关主题：[安装与配置](#page-installation), [Guard 类详解](#page-guard-class)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n- [guardrails/guard.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/guard.py)\n- [guardrails/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)\n- [guardrails/cli/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/install.py)\n- [guardrails/cli/hub/create_validator.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/create_validator.py)\n- [guardrails/llm_providers.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/llm_providers.py)\n- [guardrails/classes/history/call.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call.py)\n- [guardrails/classes/history/call_inputs.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call_inputs.py)\n \n\n# Guardrails 简介\n\n## 概述\n\nGuardrails 是一个用于验证和纠正大型语言模型（LLM）输出的 Python 库。它提供了输入/输出验证、格式约束和结构化数据生成等功能，帮助开发者确保 LLM 应用的可靠性和安全性。\n\nGuardrails 的核心设计理念是将验证逻辑与 LLM 调用解耦，使开发者能够以声明式的方式定义输出规范，然后自动验证和纠正 LLM 响应。\n\n资料来源：[README.md:1]()\n\n## 核心概念\n\n### Guard（守卫）\n\n`Guard` 是 Guardrails 框架的核心类，它包装 LLM 调用并自动执行验证和纠正流程。\n\n```python\nfrom guardrails import Guard, OnFailAction\n\nguard = Guard().use(\n RegexMatch, regex=\"\\(?\\d{3}\\)?-? *\\d{3}-? *-?\\d{4}\", on_fail=OnFailAction.EXCEPTION\n)\n\nguard.validate(\"123-456-7890\") # 验证通过\n```\n\n资料来源：[README.md:32](), [guardrails/guard.py:1]()\n\n### Validator（验证器）\n\n验证器是 Guardrails 的核心组件，用于定义具体的验证逻辑。验证器可以通过 Guardrails Hub 安装，也可以自定义创建。\n\n资料来源：[guardrails/cli/hub/create_validator.py:1]()\n\n### OnFailAction（失败动作）\n\n| 动作 | 描述 |\n|------|------|\n| `EXCEPTION` | 抛出异常 |\n| `REASK` | 重新请求 LLM 修正输出 |\n| `FIX` | 自动修复无效输出 |\n| `FILTER` | 过滤无效部分 |\n| `REFRAIN` | 返回空值 |\n\n资料来源：[README.md:35]()\n\n## 系统架构\n\n### 组件架构图\n\n```mermaid\ngraph TD\n A[用户代码] --> B[Guard]\n B --> C[LLM Provider]\n C --> D[LLM 响应]\n D --> E[Validators]\n E -->|通过| F[结构化输出]\n E -->|失败| G[纠正流程]\n G -->|重新请求| C\n G -->|抛出异常| H[Exception]\n \n I[Guardrails Hub] -->|安装验证器| B\n```\n\n### 调用流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant G as Guard\n participant L as LLM\n participant V as Validators\n participant H as History\n \n U->>G: 调用 Guard.__call__\n G->>L: 调用 LLM\n L-->>G: 返回响应\n G->>V: 验证响应\n V-->>G: 验证结果\n alt 验证通过\n G-->>U: 返回验证结果\n G->>H: 记录 Call\n else 验证失败\n G->>G: 重新请求\n G->>L: 重新调用 LLM\n end\n```\n\n## Guard 类 API\n\n### 创建 Guard 的方式\n\n| 方法 | 用途 |\n|------|------|\n| `Guard()` | 创建空 Guard |\n| `Guard.for_rail(rail_string)` | 从 RAIL 字符串创建 |\n| `Guard.for_pydantic(output_class)` | 从 Pydantic 模型创建 |\n\n资料来源：[guardrails/guard.py:1]()\n\n### for_pydantic 方法参数\n\n```python\n@classmethod\ndef for_pydantic(\n cls,\n output_class: ModelOrListOfModels,\n *,\n reask_messages: Optional[List[Dict]] = None,\n messages: Optional[List[Dict]] = None,\n name: Optional[str] = None,\n description: Optional[str] = None,\n output_formatter: Optional[Union[str, BaseFormatter]] = None,\n):\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `output_class` | `ModelOrListOfModels` | Pydantic 模型类 |\n| `reask_messages` | `Optional[List[Dict]]` | 重新请求时的消息 |\n| `messages` | `Optional[List[Dict]]` | 发送给 LLM 的消息 |\n| `name` | `Optional[str]` | Guard 实例名称 |\n| `description` | `Optional[str]` | Guard 实例描述 |\n| `output_formatter` | `Optional[Union[str, BaseFormatter]]` | 输出格式化器 |\n\n资料来源：[guardrails/guard.py:18]()\n\n## LLM 集成\n\nGuardrails 支持多种 LLM 提供商，包括 OpenAI、LiteLLM 和 Manifest。\n\n### LiteLLM 集成示例\n\n```python\nfrom litellm import completion\n\nraw_llm_response, validated_response = guard(\n completion,\n model=\"gpt-3.5-turbo\",\n prompt_params={...},\n temperature=...,\n)\n```\n\n资料来源：[guardrails/llm_providers.py:1]()\n\n### 支持的 LLM 提供商\n\n| 提供商 | 调用类 | 依赖包 |\n|--------|--------|--------|\n| OpenAI | `OpenAIClientCallable` | `openai` |\n| LiteLLM | `LiteLLMCallable` | `litellm` |\n| Manifest | `ManifestCallable` | `manifest-ml` |\n\n## 历史记录系统\n\nGuardrails 内置了调用历史记录功能，每次执行 `Guard.__call__`、`Guard.parse` 或 `Guard.validate` 都会创建一个 `Call` 对象。\n\n### Call 数据结构\n\n```python\nclass Call:\n _id: str | None = None\n iterations: Stack[Iteration] = Field(default_factory=Stack)\n inputs: CallInputs = Field(default_factory=CallInputs)\n exception: Optional[Exception] = None\n```\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `_id` | `str \\| None` | 唯一标识符 |\n| `iterations` | `Stack[Iteration]` | 迭代堆栈 |\n| `inputs` | `CallInputs` | 调用输入参数 |\n| `exception` | `Optional[Exception]` | 执行中的异常 |\n\n### CallInputs 参数\n\n| 字段 | 说明 |\n|------|------|\n| `llm_api` | LLM API 回调函数 |\n| `prompt_params` | 格式化到消息中的参数 |\n| `num_reasks` | 重新请求的最大次数 |\n| `metadata` | 验证器执行时使用的额外数据 |\n| `full_schema_reask` | 是否对整个 schema 执行重新请求 |\n| `stream` | 是否使用流式输出 |\n| `args` | LLM 的额外位置参数 |\n| `kwargs` | LLM 的额外关键字参数 |\n\n资料来源：[guardrails/classes/history/call.py:1](), [guardrails/classes/history/call_inputs.py:1]()\n\n## Guardrails Hub\n\nGuardrails Hub 是验证器的共享平台，开发者可以从中安装预构建的验证器。\n\n### 安装验证器\n\n```bash\npip install guardrails-ai\nguardrails configure\nguardrails hub install hub://guardrails/regex_match\n```\n\n资料来源：[README.md:10]()\n\n### 安装 API\n\n```python\nfrom guardrails.hub.install import install\n\nRegexMatch = install(\"hub://guardrails/regex_match\").RegexMatch\nRegexMatch = install(\"hub://guardrails/regex_match~=1.4\").RegexMatch\n```\n\n### Hub CLI 命令\n\n| 命令 | 说明 |\n|------|------|\n| `guardrails configure` | 配置 Guardrails Hub |\n| `guardrails hub install ` | 安装验证器 |\n| `guardrails hub create-validator ` | 创建验证器模板 |\n\n资料来源：[guardrails/hub/install.py:1](), [guardrails/cli/hub/install.py:1]()\n\n## 创建自定义验证器\n\n### 验证器模板\n\n使用 CLI 创建验证器模板：\n\n```bash\nguardrails hub create-validator MyValidator\n```\n\n这会生成一个模板文件 `my_validator.py`。\n\n资料来源：[guardrails/cli/hub/create_validator.py:1]()\n\n### 验证器基本结构\n\n```python\nclass MyValidator(Validator):\n \"\"\"验证器描述\"\"\"\n \n def __init__(self, ...):\n super().__init__(...)\n \n def validate(self, value, ...):\n # 验证逻辑\n pass\n```\n\n## 安装与配置\n\n### 环境要求\n\n| 要求 | 说明 |\n|------|------|\n| Python | >= 3.8 |\n| pip | 最新版本 |\n| LLM API Key | 对应提供商的密钥 |\n\n### 安装步骤\n\n1. 安装 guardrails-ai 包：\n\n```python\npip install guardrails-ai\n```\n\n2. 配置 Hub CLI：\n\n```bash\nguardrails configure\n```\n\n3. 安装验证器：\n\n```bash\nguardrails hub install hub://guardrails/competitor_check\nguardrails hub install hub://guardrails/toxic_language\n```\n\n资料来源：[README.md:10-20]()\n\n## 使用示例\n\n### 基本验证\n\n```python\nfrom guardrails import Guard, OnFailAction\nfrom guardrails.hub import RegexMatch\n\nguard = Guard().use(\n RegexMatch, regex=\"\\(?\\d{3}\\)?-? *\\d{3}-? *-?\\d{4}\", on_fail=OnFailAction.EXCEPTION\n)\n\nguard.validate(\"123-456-7890\") # 验证通过\n\ntry:\n guard.validate(\"1234-789-0000\") # 验证失败\nexcept Exception as e:\n print(e)\n```\n\n### 多验证器组合\n\n```python\nfrom guardrails import Guard, OnFailAction\nfrom guardrails.hub import CompetitorCheck, ToxicLanguage\n\nguard = Guard().use(\n CompetitorCheck([\"Apple\", \"Microsoft\", \"Google\"], on_fail=OnFailAction.EXCEPTION),\n ToxicLanguage(threshold=0.5, validation_method=\"sentence\", on_fail=OnFailAction.EXCEPTION)\n)\n\nguard.validate(\"An apple a day keeps a doctor away.\") # 两个验证器都通过\n```\n\n### 使用 Pydantic 模型生成结构化数据\n\n```python\nfrom pydantic import BaseModel, Field\nfrom guardrails import Guard\n\nclass Pet(BaseModel):\n pet_type: str = Field(description=\"宠物种类\")\n name: str = Field(description=\"宠物名字\")\n\nguard = Guard.for_pydantic(Pet)\n```\n\n资料来源：[README.md:32-80]()\n\n## 参与贡献\n\n### 开发环境设置\n\n1. 克隆仓库：`git clone https://github.com/guardrails-ai/guardrails.git`\n2. 安装开发依赖：`make dev`\n3. 安装 pre-commit：`pre-commit install`\n\n### 开发工作流\n\n| 步骤 | 命令 | 说明 |\n|------|------|------|\n| 运行测试 | `make test` | 确保所有测试通过 |\n| 代码格式化 | `make autoformat` | 格式化代码 |\n| 类型检查 | `make type` | 运行静态分析 |\n| 更新文档 | `make docs-gen` | 生成文档 |\n\n资料来源：[CONTRIBUTING.md:1]()\n\n## 相关资源\n\n- 官方文档：[Guardrails AI](https://guardrailsai.com/)\n- 验证器市场：[Guardrails Hub](https://guardrailsai.com/hub/)\n- Discord 社区：[加入讨论](https://discord.gg/Jsey3mX98B)\n- GitHub 仓库：[guardrails-ai/guardrails](https://github.com/guardrails-ai/guardrails)\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[Guardrails 简介](#page-introduction), [CLI 命令行工具](#page-cli)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)\n- [guardrails/cli/configure.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/configure.py)\n- [guardrails/cli/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/install.py)\n- [guardrails/cli/start.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/start.py)\n- [Makefile](https://github.com/guardrails-ai/guardrails/blob/main/Makefile)\n \n\n# 安装与配置\n\n## 概述\n\nGuardrails 是一个用于 LLM（大型语言模型）输出验证和结构化数据生成的 Python 库。本页面详细介绍 Guardrails 的安装方法、开发环境配置、CLI 工具设置以及 Hub 验证器的安装流程。\n\nGuardrails 支持两种主要的安装场景：\n\n- **生产环境安装**：仅安装核心库和必要的依赖\n- **开发环境安装**：安装所有开发依赖，支持本地测试、格式化、类型检查等\n\n资料来源：[CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)\n\n---\n\n## 基础安装\n\n### 使用 pip 安装\n\nGuardrails 可以通过 pip 包管理器快速安装：\n\n```bash\npip install guardrails-ai\n```\n\n此命令将安装 Guardrails 的核心功能，包括：\n\n- Guard 类和验证框架\n- 内置验证器支持\n- LLM 提供商集成\n- CLI 工具\n\n资料来源：[README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n\n### Python 版本要求\n\n| 要求 | 说明 |\n|------|------|\n| Python 版本 | 请参考 PyPI 上的版本要求 |\n| 包格式 | 支持 wheel 和 source distribution |\n\n资料来源：[README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n\n---\n\n## 开发环境配置\n\n### 克隆仓库\n\n首先从 GitHub 克隆 Guardrails 仓库：\n\n```bash\ngit clone https://github.com/guardrails-ai/guardrails.git\ncd guardrails\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)\n\n### 安装开发依赖\n\nGuardrails 提供了一个便捷的 `Makefile` 命令来配置完整的开发环境：\n\n```bash\nmake dev\n```\n\n此命令会：\n\n1. 以开发模式（editable mode）安装 guardrails 包\n2. 安装所有开发依赖\n3. 配置 pre-commit 钩子\n\n> **注意**：建议在虚拟环境中执行此操作，以隔离项目依赖。\n\n资料来源：[CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)\n\n### 开发工作流程命令\n\nGuardrails 项目定义了标准化的开发命令：\n\n| 命令 | 功能 |\n|------|------|\n| `make test` | 运行所有测试，确保代码正确性 |\n| `make autoformat` | 自动格式化代码 |\n| `make type` | 运行静态类型检查（pyright） |\n| `make docs-gen` | 生成项目文档 |\n\n```bash\n# 示例：开发过程中的完整流程\nmake test # 确保测试通过\nmake autoformat # 格式化代码\nmake type # 类型检查\nmake docs-gen # 更新文档\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)\n\n---\n\n## CLI 工具配置\n\n### Guardrails CLI 概述\n\nGuardrails 提供了命令行工具来管理验证器、启动服务等。CLI 工具支持多种命令：\n\n```bash\nguardrails configure # 配置 Guardrails\nguardrails hub install # 安装验证器\nguardrails start # 启动 Guardrails API 服务\n```\n\n资料来源：[guardrails/cli/configure.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/configure.py)\n\n### 配置命令\n\nGuardrails CLI 需要首次配置以初始化必要的设置：\n\n```bash\nguardrails configure\n```\n\n此命令会引导用户完成初始配置过程，包括：\n\n- 设置 API 端点（如需要）\n- 配置验证器缓存路径\n- 设置日志级别\n\n资料来源：[README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n\n### API 服务启动\n\nGuardrails 提供了一个可选的 API 服务，可通过 CLI 启动：\n\n```bash\nguardrails start [OPTIONS]\n```\n\n**可用选项：**\n\n| 参数 | 说明 |\n|------|------|\n| `--env` | 环境变量配置文件路径 |\n| `--config` | 服务配置文件路径 |\n| `--port` | 服务监听端口 |\n| `--env-override` | 运行时环境变量覆盖 |\n\n启动服务前会检查必要的依赖：\n\n```python\n# 伪代码：启动前检查\nif not api_is_installed():\n installer_process(\"install\", \"guardrails-api>=0.2.1\")\n```\n\n资料来源：[guardrails/cli/start.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/start.py)\n\n---\n\n## Pre-commit 钩子配置\n\n### 安装 Pre-commit\n\n安装项目提供的 pre-commit 钩子：\n\n```bash\npre-commit install\n```\n\n此步骤在执行 `make dev` 时会自动完成，但也可以手动单独执行。\n\n资料来源：[CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)\n\n### Pre-commit 钩子功能\n\nPre-commit 钩子会在每次提交前自动运行：\n\n- 代码格式检查\n- 语法验证\n- 基础测试\n\n> **好处**：减少代码审查中的格式问题，加快开发流程。\n\n资料来源：[CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)\n\n---\n\n## Hub 验证器安装\n\n### Hub CLI 安装流程\n\nGuardrails Hub 提供了丰富的预构建验证器。安装流程如下：\n\n1. **安装验证器包**\n\n```bash\nguardrails hub install hub://guardrails/regex_match\n```\n\n2. **在代码中使用**\n\n```python\nfrom guardrails import Guard, OnFailAction\nfrom guardrails.hub import RegexMatch\n\nguard = Guard().use(\n RegexMatch, \n regex=r\"\\(?\\d{3}\\)?-? *\\d{3}-? *-?\\d{4}\", \n on_fail=OnFailAction.EXCEPTION\n)\n\nguard.validate(\"123-456-7890\") # 通过验证\n```\n\n资料来源：[README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n\n### 安装多个验证器\n\n可以同时安装多个验证器：\n\n```bash\nguardrails hub install hub://guardrails/competitor_check\nguardrails hub install hub://guardrails/toxic_language\n```\n\n### 本地模型安装\n\n某些验证器支持本地推理。安装时可选择是否下载本地模型：\n\n```python\n# CLI 参数\nguardrails hub install hub://guardrails/ --local-models\n```\n\n验证器安装服务会：\n\n1. 验证包 URI 和版本\n2. 获取模块清单\n3. 下载依赖项\n4. 执行 pip 安装\n\n```python\n# 安装服务流程伪代码\ndef install_multiple(package_uris, install_local_models, quiet, upgrade):\n for package_uri in package_uris:\n validator_id, validator_version = ValidatorPackageService.get_validator_id(package_uri)\n module_manifest = ValidatorPackageService.get_manifest_and_site_packages(validator_id)\n ValidatorPackageService.install_hub_module(validator_id, validator_version=validator_version)\n```\n\n资料来源：[guardrails/cli/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/install.py)\n\n---\n\n## 项目结构概览\n\n```mermaid\ngraph TD\n A[guardrails-ai/guardrails] --> B[核心库]\n A --> C[CLI 工具]\n A --> D[Hub 验证器]\n A --> E[开发工具]\n \n B --> B1[guard.py - Guard 类]\n B --> B2[schema/ - 输出模式]\n B --> B3[validators/ - 验证器]\n \n C --> C1[configure.py - 配置命令]\n C --> C2[hub/install.py - Hub 安装]\n C --> C3[start.py - 服务启动]\n \n D --> D1[manifest.json - 验证器清单]\n D --> D2[本地/远程模型]\n \n E --> E1[Makefile - 开发命令]\n E --> E2[pre-commit - 钩子]\n```\n\n---\n\n## 常见问题排查\n\n| 问题 | 解决方案 |\n|------|----------|\n| `manifest` 包未安装 | 运行 `pip install manifest-ml` |\n| API 服务启动失败 | 确认 `guardrails-api>=0.2.1` 已安装 |\n| Hub 安装静默失败 | 使用 `--verbose` 参数查看详细日志 |\n| 类型检查失败 | 运行 `make autoformat` 后再执行 `make type` |\n\n---\n\n## 进阶配置\n\n### 环境变量配置\n\nGuardrails 支持通过环境变量进行高级配置：\n\n| 变量 | 说明 |\n|------|------|\n| `OPENAI_API_KEY` | OpenAI API 密钥 |\n| 自定义端点 | 通过 `--env` 参数指定 |\n\n资料来源：[guardrails/cli/start.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/start.py)\n\n### 自定义验证器开发\n\nGuardrails 支持开发自定义验证器：\n\n```bash\nguardrails create-validator \n```\n\n这会生成验证器模板文件，包含：\n\n- 验证逻辑框架\n- 单元测试模板\n- 文档注释结构\n\n资料来源：[guardrails/cli/hub/create_validator.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/create_validator.py)\n\n---\n\n## 总结\n\nGuardrails 提供了灵活的安装和配置选项，适应不同的使用场景：\n\n- **快速上手**：使用 `pip install guardrails-ai` 即可开始\n- **完整开发环境**：通过 `make dev` 配置一切\n- **生产部署**：使用 CLI 配置和 Hub 验证器管理\n\n建议按照本文档的步骤顺序进行配置，以确保所有依赖和工具链正确设置。\n\n---\n\n\n\n## Guard 类详解\n\n### 相关页面\n\n相关主题：[验证流程与 Runner](#page-validation-flow), [Schema 系统](#page-schema-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [guardrails/guard.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/guard.py)\n- [guardrails/classes/history/call.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call.py)\n- [guardrails/llm_providers.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/llm_providers.py)\n- [guardrails/api_client.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/api_client.py)\n- [guardrails/call_tracing/trace_handler.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/call_tracing/trace_handler.py)\n- [guardrails/schema/rail_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/rail_schema.py)\n \n\n# Guard 类详解\n\n## 概述\n\nGuard 是 Guardrails AI 框架的核心类，负责验证和约束大语言模型（LLM）的输入和输出。它提供了一个统一的接口，用于定义验证规则、调用 LLM、以及对输出进行结构化验证。\n\nGuard 类的设计目标包括：\n\n- **输出验证**：确保 LLM 生成的输出符合预定义的模式和约束\n- **结构化生成**：支持从 Pydantic 模型生成结构化数据\n- **多步骤验证**：支持重试机制（reask）和多次验证迭代\n- **历史追踪**：完整记录每次调用的输入、输出和验证结果\n\n资料来源：[guardrails/guard.py:1-100]()\n\n## 核心架构\n\n### 类层次结构\n\n```mermaid\ngraph TD\n A[Guard] --> B[for_rail]\n A --> C[for_pydantic]\n A --> D[__call__]\n A --> E[validate]\n A --> F[parse]\n \n G[PromptCallableBase] --> H[LiteLLMCallable]\n G --> I[ManifestCallable]\n \n J[Call] --> K[iterations]\n J --> L[inputs]\n J --> M[exception]\n \n K --> N[Iteration]\n N --> O[Stack]\n```\n\n### 执行流程\n\n```mermaid\nsequenceDiagram\n participant 用户\n participant Guard\n participant LLM\n participant Validator\n participant TraceHandler\n \n 用户->>Guard: __call__(prompt, model)\n Guard->>LLM: 调用模型生成响应\n LLM-->>Guard: 原始输出\n Guard->>Validator: 验证输出\n alt 验证失败 & 需要重试\n Guard->>Guard: 执行 reask\n Guard->>LLM: 重新调用\n end\n Guard->>TraceHandler: 记录调用历史\n Guard-->>用户: 返回验证后的结果\n```\n\n## Guard 类的创建方式\n\n### 从 RAIL 规范创建\n\nRAIL（Regression AI Language）是一种 XML 格式的规范，用于定义输出验证规则。\n\n```python\nguard = Guard.from_rail_string(rail_string)\n```\n\n资料来源：[guardrails/guard.py:100-120]()\n\n### 从 Pydantic 模型创建\n\n这是最常用的方式，直接使用 Pydantic BaseModel 定义输出结构：\n\n```python\nfrom pydantic import BaseModel, Field\nfrom guardrails import Guard\n\nclass Pet(BaseModel):\n pet_type: str = Field(description=\"宠物种类\")\n name: str = Field(description=\"宠物名称\")\n\nguard = Guard.for_pydantic(Pet)\n```\n\n资料来源：[guardrails/guard.py:150-180]()\n\n### for_pydantic 方法签名\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| output_class | ModelOrListOfModels | 是 | Pydantic 模型类或列表 |\n| reask_messages | Optional[List[Dict]] | 否 | 重试时的消息模板 |\n| messages | Optional[List[Dict]] | 否 | 发送给 LLM 的消息 |\n| name | Optional[str] | 否 | Guard 实例名称 |\n| description | Optional[str] | 否 | Guard 实例描述 |\n| output_formatter | Optional[Union[str, BaseFormatter]] | 否 | 输出格式化器 |\n\n## 验证机制\n\n### 验证流程\n\n```mermaid\ngraph TD\n A[接收 LLM 输出] --> B[解析输出]\n B --> C{是否需要结构化?}\n C -->|是| D[JSON 解析]\n C -->|否| E[保持原样]\n D --> F[应用验证器链]\n F --> G{所有验证器通过?}\n G -->|是| H[返回验证结果]\n G -->|否| I{on_fail 配置}\n I -->|EXCEPTION| J[抛出异常]\n I -->|FIX| K[尝试修复]\n I -->|REASK| L[重新请求 LLM]\n I -->|FILTER| M[过滤无效部分]\n I -->|CUSTOM| N[执行自定义处理]\n```\n\n### OnFailAction 枚举\n\n| 动作 | 说明 | 使用场景 |\n|------|------|----------|\n| EXCEPTION | 验证失败时抛出异常 | 需要严格验证的场景 |\n| FIX | 尝试自动修复输出 | 允许自动修正的场景 |\n| REASK | 重新请求 LLM 生成 | 需要模型重新生成 |\n| FILTER | 过滤掉无效部分 | 保留部分有效输出 |\n| CUSTOM | 执行自定义回调 | 自定义错误处理 |\n\n## 调用历史系统\n\n### Call 数据结构\n\n每次调用 Guard 时，系统会创建一个 Call 对象记录完整的执行历史。\n\n```mermaid\nclassDiagram\n class Call {\n +str id\n +Stack~Iteration~ iterations\n +CallInputs inputs\n +Optional~Exception~ exception\n +get_id() str\n }\n \n class Iteration {\n +Step[] steps\n +CallMetadata metadata\n }\n \n class CallInputs {\n +str prompt\n +str model\n +Dict kwargs\n }\n \n Call \"1\" *-- \"*\" Iteration : contains\n Iteration \"1\" *-- \"*\" Step : contains\n```\n\n资料来源：[guardrails/classes/history/call.py:1-80]()\n\n### Call 类的属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| _id | str \\| None | 唯一标识符 |\n| iterations | Stack[Iteration] | 迭代栈，包含每次重试的迭代 |\n| inputs | CallInputs | 调用输入参数 |\n| exception | Optional[Exception] | 执行过程中的异常 |\n\n资料来源：[guardrails/classes/history/call.py:20-50]()\n\n## LLM 集成\n\n### 支持的 LLM 提供者\n\nGuard 类支持与多种 LLM 提供者集成：\n\n```python\n# OpenAI\nfrom guardrails import Guard\nguard = Guard.for_pydantic(Pet)\nresult = guard(\n client=openai.ChatCompletion,\n prompt=\"生成一只宠物的信息\",\n model=\"gpt-4\"\n)\n\n# LiteLLM\nguard = Guard.for_pydantic(Pet)\nresult = guard(\n client=\"openai/gpt-3.5-turbo\",\n prompt=\"生成一只宠物的信息\"\n)\n\n# Manifest\nguard = Guard.for_pydantic(Pet)\nresult = guard(\n client=manifest_client,\n prompt=\"生成一只宠物的信息\"\n)\n```\n\n资料来源：[guardrails/llm_providers.py:1-100]()\n\n### PromptCallableBase 基类\n\n```mermaid\nclassDiagram\n class PromptCallableBase {\n +_invoke_llm() LLMResponse\n +_validate() ValidationResponse\n }\n \n class LiteLLMCallable {\n +_invoke_llm() LLMResponse\n }\n \n class ManifestCallable {\n +_invoke_llm() LLMResponse\n }\n \n PromptCallableBase <|-- LiteLLMCallable\n PromptCallableBase <|-- ManifestCallable\n```\n\n## API 客户端集成\n\nGuard 类可以与 Guardrails API 服务集成，实现远程存储和管理：\n\n```python\nfrom guardrails import Guard\nfrom guardrails.api_client import GuardrailsClient\n\nclient = GuardrailsClient(base_url=\"https://api.guardrails.ai\")\n\n# 上传 Guard 配置\nclient.upsert_guard(guard)\n\n# 获取已存储的 Guard\nremote_guard = client.fetch_guard(\"my-guard-name\")\n```\n\n### API 客户端方法\n\n| 方法 | 说明 | 异步版本 |\n|------|------|----------|\n| upsert_guard | 创建或更新 Guard | aupsert_guard |\n| fetch_guard | 获取指定名称的 Guard | afetch_guard |\n| list_guards | 列出所有 Guard | alist_guards |\n\n资料来源：[guardrails/api_client.py:1-150]()\n\n## 调用追踪系统\n\n### TraceHandler\n\nTraceHandler 是一个线程安全的追踪系统，用于记录 Guard 的调用历史：\n\n```python\nfrom guardrails.call_tracing.trace_handler import TraceHandler\n\n# 写入日志\nwriter = TraceHandler()\nwriter.log(\n \"my_guard\", # guard 名称\n 0.0, # 开始时间\n 1.0, # 结束时间\n \"原始输出\", # LLM 原始输出\n \"处理后输出\", # 验证后输出\n \"异常信息\" # 异常（如有）\n)\n\n# 读取日志\nreader = TraceHandler.get_reader()\nfor trace in reader.tail_logs():\n print(trace)\n```\n\n资料来源：[guardrails/call_tracing/trace_handler.py:1-80]()\n\n### 日志存储\n\n默认情况下，日志存储在临时目录中：\n\n```bash\n${TMPDIR}/guardrails_calls.db\n```\n\n可通过环境变量覆盖：\n\n```bash\nexport GUARDRAILS_LOG_FILE_PATH=\"/path/to/logs.db\"\n```\n\n## 使用示例\n\n### 基础验证示例\n\n```python\nfrom guardrails import Guard, OnFailAction\nfrom guardrails.hub import RegexMatch\n\n# 创建带验证规则的 Guard\nguard = Guard().use(\n RegexMatch,\n regex=r\"\\(?\\d{3}\\)?-? *\\d{3}-? *-?\\d{4}\",\n on_fail=OnFailAction.EXCEPTION\n)\n\n# 验证通过\nresult = guard.validate(\"123-456-7890\")\nprint(result) # Validation passed\n\n# 验证失败\ntry:\n guard.validate(\"1234-789-0000\")\nexcept Exception as e:\n print(e) # Result must match \\(?\\d{3}\\)?-? *\\d{3}-? *-?\\d{4}\n```\n\n### 结构化输出示例\n\n```python\nfrom pydantic import BaseModel, Field\nfrom guardrails import Guard\n\nclass Pet(BaseModel):\n pet_type: str = Field(description=\"宠物种类\")\n name: str = Field(description=\"宠物名称\")\n\nguard = Guard.for_pydantic(Pet)\n\n# 调用 LLM 并获取结构化输出\nresult = guard(\n client=openai.ChatCompletion,\n prompt=\"给我推荐一只宠物\",\n model=\"gpt-4\"\n)\n\nprint(result.validated_output)\n# 输出: Pet(pet_type=\"dog\", name=\"Max\")\n```\n\n### 多验证器组合示例\n\n```python\nfrom guardrails import Guard, OnFailAction\nfrom guardrails.hub import CompetitorCheck, ToxicLanguage\n\nguard = Guard().use(\n CompetitorCheck(\n competitors=[\"Apple\", \"Microsoft\", \"Google\"],\n on_fail=OnFailAction.EXCEPTION\n ),\n ToxicLanguage(\n threshold=0.5,\n validation_method=\"sentence\",\n on_fail=OnFailAction.EXCEPTION\n )\n)\n\n# 验证通过的场景\nguard.validate(\"An apple a day keeps a doctor away.\")\n\n# 验证失败的场景\ntry:\n guard.validate(\"Shut the hell up! Apple just released a new iPhone.\")\nexcept Exception as e:\n print(e)\n```\n\n## 最佳实践\n\n### 1. 合理的重试配置\n\n```python\n# 设置合理的重试次数和消息\nguard = Guard.for_pydantic(\n Pet,\n reask_messages=[\n {\"role\": \"user\", \"content\": \"请重新生成，必须包含 pet_type 和 name 字段\"}\n ]\n)\n```\n\n### 2. 使用适当的 on_fail 策略\n\n| 场景 | 推荐策略 |\n|------|----------|\n| 严格数据验证 | EXCEPTION |\n| 允许自动修正 | FIX |\n| 非关键字段 | FILTER |\n| 自定义处理 | CUSTOM |\n\n### 3. 调用历史记录\n\n```python\n# 获取最近一次调用的历史\ncall = guard.history[-1]\nprint(f\"调用 ID: {call.id}\")\nprint(f\"迭代次数: {len(call.iterations)}\")\nfor iteration in call.iterations:\n print(f\" - 步骤数: {len(iteration.steps)}\")\n```\n\n## 总结\n\nGuard 类是 Guardrails AI 框架的核心组件，它：\n\n- 提供了统一的接口来验证 LLM 输出\n- 支持多种创建方式（RAIL、Pydantic、自定义验证器）\n- 内置完整的调用历史追踪系统\n- 支持与多种 LLM 提供者无缝集成\n- 提供了灵活的错误处理机制\n\n通过合理使用 Guard 类，开发者可以确保 LLM 应用的输出质量和可靠性。\n\n---\n\n\n\n## Schema 系统\n\n### 相关页面\n\n相关主题：[Guard 类详解](#page-guard-class), [验证器基础](#page-validators)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [guardrails/schema/pydantic_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/pydantic_schema.py)\n- [guardrails/schema/rail_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/rail_schema.py)\n- [guardrails/schema/parser.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/parser.py)\n- [guardrails/schema/primitive_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/primitive_schema.py)\n- [guardrails/schema/validator.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/validator.py)\n- [guardrails/classes/schema/processed_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/schema/processed_schema.py)\n \n\n# Schema 系统\n\n## 概述\n\nSchema 系统是 Guardrails 框架的核心组件之一，负责定义和管理 LLM 输出的验证规范。该系统提供了从多种模式定义（RAIL、Pydantic、JSON Schema）到内部验证结构的转换能力，确保 LLM 生成的内容符合预定义的结构和约束条件。\n\nSchema 系统的主要职责包括：\n\n- **模式解析**：将用户定义的 RAIL 字符串、Pydantic 模型或 JSON Schema 解析为内部表示\n- **类型映射**：支持字符串、日期、时间、日期时间、百分比、枚举等多种数据类型的映射\n- **验证器集成**：将验证器（Validator）绑定到特定的 Schema 字段\n- **输出规范生成**：将 JSON Schema 反向转换为 RAIL 输出规范\n\n资料来源：[guardrails/schema/rail_schema.py:1-50]()\n\n## 架构设计\n\n### 核心组件\n\n```mermaid\ngraph TD\n A[用户定义 Schema] --> B{输入格式}\n B --> C[RAIL 字符串]\n B --> D[Pydantic 模型]\n B --> E[JSON Schema]\n \n C --> F[rail_schema.py]\n D --> G[pydantic_schema.py]\n E --> H[primitive_schema.py]\n \n F --> I[Schema Parser]\n G --> I\n H --> I\n \n I --> J[ProcessedSchema]\n J --> K[Guard 验证器]\n```\n\n### 目录结构\n\n```\nguardrails/schema/\n├── __init__.py # 模块初始化\n├── pydantic_schema.py # Pydantic 模型转换\n├── parser.py # 核心解析器\n├── primitive_schema.py # 基础类型处理\n├── rail_schema.py # RAIL 格式转换\n├── validator.py # 验证器绑定\n└── processed_schema.py # 处理后的模式类\n```\n\n## 核心模块详解\n\n### RailSchema 模块\n\n`rail_schema.py` 负责 RAIL（Rail Action Markup Language）格式与内部 Schema 之间的转换。\n\n#### 主要功能\n\n| 函数 | 功能描述 |\n|------|----------|\n| `build_element()` | 递归构建 XML 元素树 |\n| `build_string_element()` | 构建字符串类型元素 |\n| `json_schema_to_rail_output()` | JSON Schema 转 RAIL 输出规范 |\n\n#### 支持的数据类型\n\n| RailTypes | 说明 | 格式属性 |\n|-----------|------|----------|\n| `STRING` | 字符串类型 | 无 |\n| `DATE` | 日期类型 | `date-format` |\n| `TIME` | 时间类型 | `time-format` |\n| `DATETIME` | 日期时间类型 | `datetime-format` |\n| `PERCENTAGE` | 百分比类型 | 无 |\n| `ENUM` | 枚举类型 | `values` 属性 |\n| `FLOAT` | 浮点数 | 无 |\n| `INTEGER` | 整数 | 无 |\n| `BOOL` | 布尔值 | 无 |\n\n资料来源：[guardrails/schema/rail_schema.py:50-120]()\n\n#### 类型映射逻辑\n\n```python\ndef build_string_element(...):\n if format.internal_type == RailTypes.DATE:\n type = RailTypes.DATE\n date_format = format.internal_format_attr\n if date_format:\n attributes[\"date-format\"] = date_format\n elif format.internal_type == RailTypes.TIME:\n type = RailTypes.TIME\n # ...\n```\n\n资料来源：[guardrails/schema/rail_schema.py:80-95]()\n\n### JSON Schema 转换流程\n\n```mermaid\ngraph LR\n A[JSON Schema] --> B[jsonref.replace_refs]\n B --> C[解引用后的 Schema]\n C --> D[build_element]\n D --> E[XML Element 树]\n E --> F[canonicalize]\n F --> G[RAIL 输出字符串]\n```\n\n关键转换函数：\n\n```python\ndef json_schema_to_rail_output(\n json_schema: Dict[str, Any], \n validator_map: ValidatorMap\n) -> str:\n dereferenced_json_schema = jsonref.replace_refs(json_schema)\n output_element = build_element(\n dereferenced_json_schema,\n validator_map,\n json_path=\"$\",\n elem=Element,\n tag_override=\"output\",\n )\n return canonicalize(ET.tostring(output_element, pretty_print=True))\n```\n\n资料来源：[guardrails/schema/rail_schema.py:35-45]()\n\n### Pydantic Schema 模块\n\n`pydantic_schema.py` 提供了将 Pydantic `BaseModel` 转换为 Guardrails Schema 的能力。\n\n#### 创建 Guard 实例\n\n```python\nfrom guardrails import Guard\nfrom pydantic import BaseModel, Field\n\nclass Pet(BaseModel):\n pet_type: str = Field(description=\"Species of pet\")\n name: str = Field(description=\"a unique pet name\")\n\n# 从 Pydantic 模型创建 Guard\nguard = Guard.for_pydantic(Pet)\n```\n\n资料来源：[guardrails/guard.py:100-120]()\n\n### ProcessedSchema 类\n\n`processed_schema.py` 定义了处理后的 Schema 数据结构，包含以下关键属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `_id` | `str \\| None` | 唯一标识符 |\n| `iterations` | `Stack[Iteration]` | 执行迭代栈 |\n| `inputs` | `CallInputs` | 调用输入参数 |\n| `exception` | `Exception \\| None` | 异常信息 |\n\n```python\nclass Call:\n \"\"\"表示 Guard 的单次执行\"\"\"\n \n _id: str | None = None\n iterations: Stack[Iteration] = Field(\n description=\"迭代栈\",\n default_factory=Stack,\n )\n inputs: CallInputs = Field(\n description=\"调用输入\",\n default_factory=CallInputs,\n )\n exception: Optional[Exception] = Field(\n description=\"异常\",\n default=None,\n )\n```\n\n资料来源：[guardrails/classes/schema/processed_schema.py:20-45]()\n\n### Validator 模式绑定\n\n`validator.py` 负责将验证器与 Schema 字段进行绑定，支持以下配置选项：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `on_fail` | `OnFailAction` | 验证失败时的动作 |\n| `args` | `List[Any]` | 验证器位置参数 |\n| `kwargs` | `Dict[str, Any]` | 验证器关键字参数 |\n\n## Guard 与 Schema 的集成\n\n### 从 RAIL 创建 Guard\n\n```python\nfrom guardrails import Guard\n\nrail_string = \"\"\"\n\n \n\n\"\"\"\n\nguard = Guard.from_rail_string(rail_string)\n```\n\n内部调用流程：\n\n```mermaid\ngraph TD\n A[rail_string] --> B[rail_string_to_schema]\n B --> C[Schema 对象]\n C --> D[Guard._for_rail_schema]\n D --> E[Guard 实例]\n```\n\n资料来源：[guardrails/guard.py:80-100]()\n\n### 从 Pydantic 创建 Guard\n\n```python\nfrom guardrails import Guard\nfrom pydantic import BaseModel\n\nclass OutputModel(BaseModel):\n name: str\n age: int\n\nguard = Guard.for_pydantic(OutputModel)\n```\n\n支持的方法签名：\n\n| 方法 | 参数 | 返回类型 |\n|------|------|----------|\n| `for_rail` | `rail_string: str` | `Guard` |\n| `for_pydantic` | `output_class: ModelOrListOfModels` | `Guard` |\n\n资料来源：[guardrails/guard.py:100-140]()\n\n## 调用输入管理\n\n### CallInputs 数据结构\n\n`call_inputs.py` 定义了 LLM 调用时的输入参数：\n\n```python\nclass CallInputs(BaseModel):\n llm_api: Optional[Callable[[Any], Awaitable[Any]]] = None\n prompt: Optional[str] = Field(default=None, alias=\"prompt\")\n prompt_params: Optional[Dict[str, Any]] = Field(\n default=None,\n description=\"Parameters to be formatted into the messages.\",\n alias=\"promptParams\",\n )\n num_reasks: Optional[int] = Field(\n default=None,\n description=\"The total number of times the LLM can be called\",\n alias=\"numReasks\",\n )\n metadata: Optional[Dict[str, Any]] = Field(\n default=None,\n description=\"Additional data to be used by Validators\",\n )\n stream: Optional[bool] = Field(\n default=None, description=\"Whether to use streaming.\"\n )\n```\n\n| 字段 | 默认值 | 说明 |\n|------|--------|------|\n| `llm_api` | `None` | LLM API 回调函数 |\n| `prompt` | `None` | 提示词模板 |\n| `prompt_params` | `None` | 格式化参数 |\n| `num_reasks` | `None` | 最大重新请求次数 |\n| `metadata` | `None` | 元数据字典 |\n| `full_schema_reask` | `None` | 是否全量重新请求 |\n| `stream` | `None` | 是否启用流式输出 |\n\n资料来源：[guardrails/classes/history/call_inputs.py:20-50]()\n\n## Schema 处理流程\n\n### 完整验证流程\n\n```mermaid\ngraph TD\n A[输入数据] --> B[Guard.__call__]\n B --> C[Call 创建]\n C --> D[Schema 解析]\n D --> E[LLM 调用]\n E --> F[输出验证]\n \n F --> G{验证通过?}\n G -->|是| H[返回结果]\n G -->|否| I{num_reasks > 0?}\n \n I -->|是| J[num_reasks - 1]\n J --> E\n I -->|否| K[抛出异常]\n \n H --> L[Iteration 记录]\n K --> L\n```\n\n### 迭代追踪\n\n每次调用 `Guard.__call__`、`Guard.parse` 或 `Guard.validate` 都会创建一个 `Call` 实例，其中包含：\n\n- **初始验证轮次**：`Iteration` 栈\n- **重请求轮次**：每次重新请求都会产生新的 `Iteration`\n\n```python\n@computed_field\n@property\ndef id(self) -> str:\n \"\"\"唯一标识符，用于标识 Guard 的特定执行\"\"\"\n if not self._id:\n self._id = str(object_id(self))\n return self._id\n```\n\n资料来源：[guardrails/classes/history/call.py:30-45]()\n\n## 类型系统\n\n### 简单类型枚举\n\n| 类型名 | Python 类型 | 说明 |\n|--------|-------------|------|\n| `STRING` | `str` | 字符串 |\n| `INTEGER` | `int` | 整数 |\n| `FLOAT` | `float` | 浮点数 |\n| `BOOLEAN` | `bool` | 布尔值 |\n| `ARRAY` | `list` | 数组 |\n| `OBJECT` | `dict` | 对象 |\n| `NULL` | `None` | 空值 |\n\n### 特殊格式类型\n\n```python\n# 日期时间格式支持\nDATETIME: str # 支持 datetime-format 属性\nDATE: str # 支持 date-format 属性\nTIME: str # 支持 time-format 属性\nPERCENTAGE: str # 百分比字符串\nENUM: str # 枚举值列表\n```\n\n资料来源：[guardrails/schema/rail_schema.py:100-140]()\n\n## 配置与扩展\n\n### 自定义 Schema 处理器\n\n开发者可以通过继承基础类来扩展 Schema 功能：\n\n```python\nfrom guardrails.schema import BaseSchema\n\nclass CustomSchema(BaseSchema):\n def validate(self, value):\n # 自定义验证逻辑\n pass\n```\n\n### 验证器注册\n\n验证器通过 `ValidatorMap` 注册到 Schema 系统：\n\n```python\nvalidator_map: ValidatorMap # 全局验证器映射表\n```\n\n## 最佳实践\n\n1. **使用 Pydantic 模型定义复杂结构**：更声明式，类型安全\n2. **明确指定日期/时间格式**：避免歧义\n3. **合理设置 num_reasks**：平衡验证严格性和用户体验\n4. **利用 metadata 传递上下文**：验证器可访问运行时信息\n\n## 总结\n\nSchema 系统是 Guardrails 框架的基础架构层，提供了从多种模式定义格式到统一验证结构的转换能力。通过模块化的设计，支持 RAIL、Pydantic、JSON Schema 等多种输入方式，并提供灵活的验证器集成机制。该系统与 Guard 类紧密协作，实现了 LLM 输出的结构化和可验证性。\n\n---\n\n\n\n## 验证流程与 Runner\n\n### 相关页面\n\n相关主题：[Guard 类详解](#page-guard-class), [验证器基础](#page-validators)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [guardrails/run/runner.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/run/runner.py)\n- [guardrails/run/async_runner.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/run/async_runner.py)\n- [guardrails/run/stream_runner.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/run/stream_runner.py)\n- [guardrails/run/utils.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/run/utils.py)\n- [guardrails/classes/history/call.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call.py)\n- [guardrails/classes/history/iteration.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/iteration.py)\n \n\n# 验证流程与 Runner\n\n## 概述\n\nGuardrails 的验证流程是整个框架的核心执行机制，负责协调 LLM 响应与验证器之间的交互。当用户调用 `Guard.__call__`、`Guard.parse` 或 `Guard.validate` 方法时，框架会通过 Runner 组件来执行验证逻辑。\n\nRunner 系统采用模块化设计，支持同步、异步和流式三种执行模式。这种设计允许 Guardrails 适应不同的应用场景，从简单的批量验证到实时流式响应处理。\n\n## 核心架构组件\n\n### Call（调用）对象\n\n`Call` 类是 Guard 执行过程的顶层记录容器。每次调用 `Guard.__call__`、`Guard.parse` 或 `Guard.validate` 时，都会创建一个新的 `Call` 实例。\n\n```python\nclass Call:\n \"\"\"A Call represents a single execution of a Guard.\"\"\"\n \n _id: str | None = None\n iterations: Stack[Iteration] = Field(\n description=\"A stack of iterations for each step/reask that occurred.\",\n default_factory=Stack,\n )\n inputs: CallInputs = Field(\n description=\"The inputs as passed in to Guard.__call__ or Guard.parse\",\n default_factory=CallInputs,\n )\n exception: Optional[Exception] = Field(\n description=\"The exception that interrupted the run.\",\n default=None,\n )\n```\n\n`Call` 对象的核心属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `_id` | `str \\| None` | Call 的唯一标识符 |\n| `iterations` | `Stack[Iteration]` | 执行过程中的迭代栈 |\n| `inputs` | `CallInputs` | 传递给 Guard 的输入参数 |\n| `exception` | `Optional[Exception]` | 执行过程中捕获的异常 |\n\n`Call.id` 是一个计算属性，通过 `object_id(self)` 生成唯一标识符，可用于追踪特定的 Guard 执行：\n\n```python\n@computed_field\n@property\ndef id(self) -> str:\n \"\"\"The unique identifier for this Call.\"\"\"\n if not self._id:\n self._id = str(object_id(self))\n return self._id\n```\n\n资料来源：[guardrails/classes/history/call.py:16-45]()\n\n### Iteration（迭代）对象\n\n`Iteration` 代表验证过程中的单个迭代步骤。每次重新请求（reask）或验证循环都会创建一个新的 `Iteration` 实例，并压入 `Call.iterations` 栈中。\n\n迭代过程包含以下关键阶段：\n\n1. **初始验证轮次**：首次对 LLM 输出进行验证\n2. **Reask 阶段**：如果验证失败，触发重新请求机制\n3. **多轮迭代**：持续验证直到通过或达到最大重试次数\n\n资料来源：[guardrails/classes/history/iteration.py]()\n\n## Runner 执行模式\n\nGuardrails 提供了三种 Runner 实现，分别适用于不同的使用场景：\n\n### 同步 Runner\n\n`Runner` 是标准的同步执行器，适用于批量处理和非实时应用场景。它按顺序执行验证步骤，阻塞当前线程直到完成。\n\n```python\n# 典型使用方式\nfrom guardrails import Guard\n\nguard = Guard.from_pydantic(Pet)\nresult = guard(\n client,\n prompt_params={...}\n)\n```\n\n### 异步 Runner\n\n`AsyncRunner` 支持异步执行，利用 Python 的 `asyncio` 实现并发处理。这对于需要同时处理多个验证请求的高吞吐量应用至关重要。\n\n```python\n# 典型使用方式\nfrom guardrails import Guard\n\nguard = Guard.from_pydantic(Pet)\nresult = await guard.ainvoke(\n client,\n prompt_params={...}\n)\n```\n\n异步 Runner 保持了与同步 Runner 相同的验证逻辑，但通过 `async/await` 模式提升了资源利用率。\n\n### 流式 Runner\n\n`StreamRunner` 专门为流式 LLM 响应设计。当 LLM 支持流式输出时，Runner 可以边接收响应边进行验证，提供更好的实时性和更低的内存占用。\n\n```python\n# 典型使用方式\nfor token in guard.stream(\n client,\n prompt_params={...}\n):\n print(token, end=\"\", flush=True)\n```\n\n## 验证流程图\n\n```mermaid\ngraph TD\n A[Guard.__call__ / validate] --> B[创建 Call 实例]\n B --> C[创建 Iteration 栈]\n C --> D[调用 LLM]\n D --> E{解析 LLM 响应}\n E -->|成功解析| F{运行验证器}\n E -->|解析失败| G[触发 Reask]\n F -->|验证通过| H[返回验证结果]\n F -->|验证失败| G\n G -->|达到最大重试| I[抛出异常]\n G -->|未达最大重试| D\n H --> J[保存到 History]\n I --> J\n```\n\n## 验证执行流程详解\n\n### 第一阶段：输入处理\n\n在调用 Runner 之前，Guard 会准备以下输入数据：\n\n- **Prompt 模板**：包含 `${gr.complete_json_suffix_v2}` 等占位符的提示词\n- **Prompt 参数**：`prompt_params` 字典，用于填充模板变量\n- **LLM 客户端**：支持多种 LLM 提供商（OpenAI、Anthropic、LiteLLM 等）\n\n### 第二阶段：LLM 调用\n\nRunner 负责与 LLM 交互，获取原始响应。根据配置的调用方式，可能是：\n\n- **Function Calling**：使用 LLM 的函数调用能力获取结构化输出\n- **Prompt Optimization**：通过优化提示词引导 LLM 生成符合 schema 的 JSON\n\n### 第三阶段：验证循环\n\n验证循环是 Runner 的核心逻辑：\n\n```mermaid\ngraph LR\n A[获取 LLM 响应] --> B[解析响应]\n B --> C{解析成功?}\n C -->|否| D[记录异常]\n C -->|是| E[运行验证器]\n E --> F{所有验证通过?}\n F -->|是| G[返回结果]\n F -->|否| H[执行 Fix/Reask]\n H --> I{达到最大重试?}\n I -->|是| J[抛出异常]\n I -->|否| A\n```\n\n### 第四阶段：History 记录\n\n每个执行步骤都会记录到 History 中：\n\n- `Call.inputs`：保存原始输入\n- `Call.iterations`：保存每次迭代的详细记录\n- `Call.exception`：如果执行中断，保存异常信息\n\n```python\n@field_serializer(\"iterations\")\ndef serialize_iterations(\n self, iterations: Stack[Iteration] | None\n) -> list[dict[str, Any]] | None:\n if iterations is not None:\n return [\n # 序列化的迭代数据\n ]\n```\n\n## Runner 工具函数\n\n`guardrails/run/utils.py` 提供了 Runner 所需的核心工具函数：\n\n| 函数 | 功能 |\n|------|------|\n| `get_llm_response_text` | 从 LLM 响应中提取文本内容 |\n| `process_parsed_rail` | 处理解析后的 RAIL 规范 |\n| `validate_parsed_rail` | 验证 RAIL 规范的正确性 |\n| `extract_config_from_rail` | 从 RAIL 提取配置信息 |\n\n这些工具函数支持 Runner 在不同执行阶段进行数据转换和验证。\n\n## 执行状态管理\n\nRunner 通过 `TracerMixin` 提供执行追踪能力：\n\n```python\nclass TraceHandler(TracerMixin):\n \"\"\"TraceHandler wraps the internal _SQLiteTraceHandler to make it multi-\n thread safe.\"\"\"\n```\n\n追踪系统使用 SQLite 数据库记录每次执行的详细信息：\n\n- **日志文件位置**：可通过 `GUARDRAILS_LOG_FILE_PATH` 环境变量配置\n- **默认位置**：`tempfile.gettempdir() + \"/guardrails_calls.db\"`\n- **多线程安全**：通过单例模式和写前日志机制实现\n\n```python\nLOG_FILENAME = \"guardrails_calls.db\"\nLOGFILE_PATH = os.environ.get(\n \"GUARDRAILS_LOG_FILE_PATH\",\n os.path.join(tempfile.gettempdir(), LOG_FILENAME),\n)\n```\n\n## 与 LLM 提供商的集成\n\nRunner 通过 `llm_providers.py` 中的适配器类与不同 LLM 提供商集成：\n\n- **ManifestCallable**：支持使用 Manifest 库的 LLM\n- **LiteLLMCallable**：支持 LiteLLM 封装的多种 LLM\n- **PromptCallableBase**：所有提供商的基类\n\n```python\nclass LiteLLMCallable(PromptCallableBase):\n def _invoke_llm(\n self,\n text: Optional[str] = None,\n model: str = \"gpt-3.5-turbo\",\n messages: Optional[List[Dict]] = None,\n *args,\n **kwargs,\n ) -> LLMResponse:\n \"\"\"Wrapper for Lite LLM completions.\"\"\"\n```\n\n## 错误处理机制\n\n验证流程中的错误处理采用分层策略：\n\n1. **解析错误**：LLM 响应无法解析为预期格式\n2. **验证错误**：LLM 响应通过解析但不满足验证器条件\n3. **执行异常**：Runner 级别的异常（如 API 超时、网络错误）\n\n```python\ntry:\n guard.validate(\"1234-789-0000\") # 验证失败\nexcept Exception as e:\n print(e) # 输出: Validation failed for field with errors: Result must match...\n```\n\n## 配置选项\n\n创建 Guard 时可以通过多种方式配置验证流程：\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `output_class` | Pydantic 模型定义输出结构 | 必填 |\n| `messages` | LLM 消息列表 | None |\n| `reask_messages` | Reask 阶段使用的消息 | None |\n| `name` | Guard 实例名称 | `gr-` + 对象ID |\n| `output_formatter` | 输出格式化器 | None |\n\n## 总结\n\nRunner 系统是 Guardrails 验证流程的核心执行引擎，通过模块化的设计支持同步、异步和流式三种执行模式。`Call` 和 `Iteration` 类提供了完整的执行历史追踪能力，使调试和监控变得简单直观。理解 Runner 的工作原理对于深入掌握 Guardrails 框架、进行性能优化和故障排查至关重要。\n\n---\n\n\n\n## 验证器基础\n\n### 相关页面\n\n相关主题：[Guardrails Hub](#page-hub), [Schema 系统](#page-schema-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [guardrails/validator_base.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/validator_base.py)\n- [guardrails/classes/validation/validation_result.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/validation/validation_result.py)\n- [guardrails/classes/validation/validator_logs.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/validation/validator_logs.py)\n- [guardrails/actions/filter.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/actions/filter.py)\n- [guardrails/actions/refrain.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/actions/refrain.py)\n- [guardrails/actions/reask.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/actions/reask.py)\n- [guardrails/types/on_fail.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/types/on_fail.py)\n \n\n# 验证器基础\n\n## 概述\n\n验证器（Validator）是 Guardrails 框架的核心组件，用于对 LLM（大型语言模型）生成的输出进行质量检查和验证。验证器充当输出与预期规范之间的桥梁，确保 LLM 响应符合预定义的数据结构、格式要求和内容约束。\n\n### 核心职责\n\n- **格式验证**：检查输出是否符合指定的数据格式（如正则表达式、JSON Schema）\n- **内容验证**：检测敏感内容、不当语言或竞争对手提及\n- **结构验证**：确保输出符合 Pydantic 模型或 RAIL 规范定义的结构\n- **修复建议**：在验证失败时提供修正值或重新请求 LLM 生成\n\n### 验证器在 Guard 架构中的位置\n\n```mermaid\ngraph TD\n A[用户输入/提示词] --> B[Guard 实例]\n B --> C[验证器注册表 ValidatorMap]\n C --> D[验证器链 Validator Chain]\n D --> E{验证结果}\n E -->|通过| F[ValidationOutcome 有效输出]\n E -->|失败| G[OnFailAction 处理]\n G -->|REASK| H[重新请求 LLM]\n G -->|FILTER| I[过滤敏感内容]\n G -->|REFRAIN| J[返回空/默认值]\n G -->|EXCEPTION| K[抛出验证异常]\n H --> D\n```\n\n## 验证结果模型\n\n### ValidationOutcome\n\n`ValidationOutcome` 是验证过程的返回结果，封装了验证的完整状态信息。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `validated_output` | `OT` | 验证后的输出值 |\n| `reask_messages` | `List[Dict]` | 用于重新请求的消息列表 |\n| `error` | `Exception` | 验证过程中发生的错误（如果有） |\n| `validation_passed` | `bool` | 验证是否通过 |\n| `structure_generated` | `bool` | 是否生成了结构化输出 |\n\n资料来源：[guardrails/guard.py:420-450]()\n\n### 验证日志 ValidatorLogs\n\n每个验证步骤都会生成详细的日志记录，用于追踪和调试。\n\n| 属性 | 说明 |\n|------|------|\n| `validator_name` | 验证器的名称 |\n| `validator_value` | 当前验证的值 |\n| `validation_result` | 验证结果对象 |\n| `start_time` | 验证开始时间戳 |\n| `end_time` | 验证结束时间戳 |\n| `error` | 验证错误信息 |\n\n资料来源：[guardrails/classes/validation/validator_logs.py]()\n\n## 失败处理策略\n\n### OnFailAction 枚举\n\n当验证失败时，系统根据配置的 `OnFailAction` 决定如何处理。\n\n| 动作 | 说明 | 使用场景 |\n|------|------|----------|\n| `REASK` | 重新向 LLM 请求修正的输出 | 自动修正格式错误 |\n| `FILTER` | 过滤或替换敏感内容 | 内容安全检查 |\n| `REFRAIN` | 返回空值或默认值 | 避免生成不当内容 |\n| `EXCEPTION` | 抛出验证异常 | 严格模式下的错误处理 |\n| `FIX` | 使用预定义的修复值 | 已知错误模式的批量修正 |\n\n资料来源：[guardrails/types/on_fail.py]()\n\n### 各动作的处理流程\n\n#### 过滤动作 (Filter)\n\n过滤动作用于处理需要移除或替换的敏感内容：\n\n```python\n# 伪代码示例\nif validation_result.failed:\n if on_fail == OnFailAction.FILTER:\n return filtered_value\n```\n\n#### 克制动作 (Refrain)\n\n克制动作在检测到违规内容时返回空值或中性替代：\n\n```python\n# 克制动作返回空输出\nif validation_result.failed and on_fail == OnFailAction.REFRAIN:\n return None\n```\n\n资料来源：[guardrails/actions/filter.py]()\n资料来源：[guardrails/actions/refrain.py]()\n\n#### 重新请求动作 (Reask)\n\n重新请求是最常用的自动修正机制，会收集所有验证失败项并生成新的提示词：\n\n```mermaid\ngraph LR\n A[初始验证失败] --> B[gather_reasks 收集 ReAsk]\n B --> C[构建 reask_messages]\n C --> D[调用 LLM 重新生成]\n D --> E[再次验证]\n E -->|通过| F[返回修正结果]\n E -->|失败| G{达到最大次数?}\n G -->|否| C\n G -->|是| H[返回最终结果/错误]\n```\n\n资料来源：[guardrails/actions/reask.py]()\n\n## ReAsk 系统\n\n### ReAsk 数据结构\n\n当验证失败需要重新请求时，系统使用 `ReAsk` 对象记录失败信息：\n\n| 属性 | 说明 |\n|------|------|\n| `path` | 失败字段的 JSON 路径 |\n| `original_value` | 原始失败值 |\n| ` fail_results` | 失败验证结果列表 |\n| `expected_format` | 期望的格式描述 |\n\n### 递归收集机制\n\n`gather_reasks` 函数递归遍历验证输出，收集所有需要重新请求的字段：\n\n```python\ndef gather_reasks(validated_output):\n if isinstance(validated_output, ReAsk):\n return [validated_output], None\n if isinstance(validated_output, str):\n return [], validated_output\n # 递归处理字典和列表类型\n```\n\n资料来源：[guardrails/actions/reask.py:50-80]()\n\n## 验证器基类\n\n### Validator 抽象基类\n\n所有自定义验证器都继承自 `Validator` 基类，实现以下核心方法：\n\n| 方法 | 说明 |\n|------|------|\n| `validate(value, ...)` | 执行验证逻辑 |\n| `fix(...)` | 提供修复建议 |\n| `get_azure_function(...)` | Azure Functions 集成 |\n\n### 验证器调用追踪\n\n框架集成了 OpenTelemetry 追踪系统，记录每次验证的执行情况：\n\n```python\n# 验证器执行时会创建 span\nvalidator_span = tracer.start_span(f\"validator/{validator_name}\")\n# 记录输入值、初始化参数、执行结果\nadd_validator_attributes(\n validator_name=validator_name,\n result=resp,\n init_kwargs=init_kwargs,\n validation_session_id=validation_session_id,\n)\n```\n\n资料来源：[guardrails/telemetry/validator_tracing.py]()\n\n## 验证器在 Guard 中的使用\n\n### 注册验证器\n\n通过 `Guard.use()` 方法注册验证器：\n\n```python\nfrom guardrails import Guard, OnFailAction\nfrom guardrails.hub import RegexMatch, CompetitorCheck\n\nguard = Guard().use(\n RegexMatch(regex=r\"\\d{4}\", on_fail=OnFailAction.EXCEPTION),\n CompetitorCheck([\"Apple\", \"Google\"], on_fail=OnFailAction.FILTER)\n)\n```\n\n### 获取已注册的验证器\n\n```python\n# 获取 output 级别所有验证器\noutput_validators = guard.get_validators(on=\"output\")\n\n# 获取特定字段的验证器\nfield_validators = guard.get_validators(on=\"$.pet_type\")\n```\n\n### 验证流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant G as Guard\n participant V as ValidatorMap\n participant Val as Validator\n participant LLM as LLM API\n\n U->>G: guard.validate(llm_output)\n G->>V: 获取相关验证器\n V-->>G: 验证器列表\n loop 遍历每个验证器\n G->>Val: validate(value)\n Val-->>G: ValidationResult\n end\n G->>G: 处理失败结果\n alt 验证通过\n G-->>U: ValidationOutcome.validated_output\n else 验证失败\n G->>G: 根据 OnFailAction 处理\n alt REASK\n G->>LLM: 发送 reask_messages\n LLM-->>G: 修正后的输出\n G->>G: 递归验证\n else EXCEPTION\n G-->>U: 抛出 ValidationException\n end\n end\n```\n\n## 调用历史记录\n\n### Call 数据结构\n\n每次调用 Guard 都会生成 `Call` 对象，记录完整的执行历史：\n\n| 属性 | 说明 |\n|------|------|\n| `id` | 唯一标识符 |\n| `iterations` | 执行迭代栈（初始验证 + 每次 reask） |\n| `inputs` | 输入参数（prompt、llm_api 等） |\n| `exception` | 中断执行的异常（如果有） |\n\n### Iteration 数据结构\n\n单个迭代包含：\n\n- `validator_logs`：本次迭代中所有验证器的执行日志\n- `llm_response`：LLM 的原始响应\n- `parsed_output`：解析后的输出\n- `validation_response`：验证结果\n\n资料来源：[guardrails/classes/history/call.py]()\n\n## 验证器开发模板\n\n### 创建新验证器\n\n使用 CLI 命令创建验证器模板：\n\n```bash\nguardrails hub create-validator MyValidator ./my_validator.py\n```\n\n生成的模板包含：\n\n```python\nfrom guardrails import Validator\nfrom guardrails.validators import ValidationResult\n\nclass MyValidator(Validator):\n \"\"\"验证器描述\"\"\"\n \n def __init__(self, arg_1: str, on_fail: str = None):\n super().__init__(on_fail=on_fail)\n self.arg_1 = arg_1\n \n def validate(self, value, **kwargs) -> ValidationResult:\n # 验证逻辑\n if not self._is_valid(value):\n return ValidationResult(\n outcome=\"fail\",\n error_message=\"验证失败的原因\"\n )\n return ValidationResult(outcome=\"pass\")\n```\n\n资料来源：[guardrails/cli/hub/create_validator.py]()\n\n## 最佳实践\n\n### 1. 验证器组合策略\n\n| 场景 | 推荐验证器组合 |\n|------|----------------|\n| 数据提取 | `RegexMatch` + `ValidRange` |\n| 内容安全 | `CompetitorCheck` + `ToxicLanguage` |\n| 结构化输出 | Pydantic 模型 + 自定义字段验证器 |\n\n### 2. OnFailAction 选择指南\n\n- **严格模式**：使用 `EXCEPTION` 确保不返回无效数据\n- **容错模式**：使用 `REASK` 自动修正轻微格式错误\n- **安全模式**：使用 `FILTER` 或 `REFRAIN` 处理敏感内容\n\n### 3. 性能注意事项\n\n- 避免在验证器中执行阻塞 I/O 操作\n- 使用 `skip_reask_when_valid` 参数避免不必要的重新请求\n- 对于复杂验证逻辑，考虑异步实现\n\n## 相关资源\n\n- [Guardrails Hub](https://guardrailsai.com/hub/) - 官方验证器市场\n- [验证器模板仓库](https://github.com/guardrails-ai/validator-template) - 复杂验证器开发指南\n- [API 参考文档](https://docs.guardrailsai.com/) - 完整的 API 说明\n\n---\n\n\n\n## Guardrails Hub\n\n### 相关页面\n\n相关主题：[验证器基础](#page-validators), [CLI 命令行工具](#page-cli)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [guardrails/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)\n- [guardrails/cli/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/install.py)\n- [guardrails/cli/hub/create_validator.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/create_validator.py)\n- [README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)\n \n\n# Guardrails Hub\n\n## 概述\n\nGuardrails Hub 是 Guardrails 项目的验证器分发与共享平台，为用户提供了一个集中式的验证器市场，类似于 Python 生态中的 PyPI。Hub 的核心功能是允许用户从中央仓库安装、社区贡献者提交新的验证器，以及管理本地已安装的验证器模块。\n\n通过 Guardrails Hub，用户可以快速获取预构建的验证器（如正则匹配、竞争对手检查、有害内容检测等），无需从头编写验证逻辑。Hub 采用语义化版本控制，支持灵活的版本约束，确保项目的依赖稳定性。\n\n**核心特点：**\n\n- **即装即用**：通过 CLI 一键安装验证器\n- **版本管理**：支持语义化版本约束（如 `~=1.4`、`>=1.4,==1.*`）\n- **模块导出**：统一的导入接口 `from guardrails.hub import {ValidatorName}`\n- **本地模型支持**：部分验证器支持本地模型推理\n\n资料来源：[README.md:1-20](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n\n## 架构设计\n\n### 系统组件\n\nGuardrails Hub 由以下核心组件构成：\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| Hub CLI | `guardrails/cli/hub/` | 提供 hub 命令行接口（install、list、submit、uninstall、create-validator） |\n| 安装服务 | `guardrails/hub/install.py` | 处理验证器包的下载、安装、依赖解析 |\n| 包服务 | `validator_package_service.py` | 管理验证器清单、版本解析、包安装 |\n| 注册表 | `guardrails/hub/registry.py` | 维护已安装验证器的元数据注册 |\n\n### 安装流程\n\n```mermaid\ngraph TD\n A[用户执行 guardrails hub install] --> B[验证包 URI 和版本]\n B --> C{本地模型是否必需}\n C -->|是| D[确认安装本地模型]\n C -->|否| E[跳过]\n D --> F[获取 Manifest 清单]\n F --> G[下载依赖]\n G --> H[执行 Pip 安装]\n H --> I[加载模块]\n I --> J[返回已安装的验证器模块]\n```\n\n资料来源：[guardrails/hub/install.py:50-90](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)\n\n## URI 规范与版本控制\n\n### Hub URI 格式\n\nGuardrails Hub 使用统一的 URI 格式来标识验证器资源：\n\n```\nhub://guardrails/{validator_name}[~={version}]\n```\n\n**格式说明：**\n\n| 组成部分 | 说明 | 示例 |\n|----------|------|------|\n| `hub://` | 协议前缀，标识来自 Hub | - |\n| `guardrails` | 命名空间，通常为官方或用户名 | `guardrails` |\n| `validator_name` | 验证器名称（snake_case） | `regex_match` |\n| `~={version}` | 版本约束（可选） | `~=1.4`、`>=1.4,==1.*` |\n\n资料来源：[guardrails/hub/install.py:30-40](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)\n\n### 版本约束示例\n\n```python\n# 安装特定版本\ninstall(\"hub://guardrails/regex_match~=1.4\")\n\n# 安装兼容版本\ninstall(\"hub://guardrails/regex_match>=1.4,==1.*\")\n\n# 安装最新版本\ninstall(\"hub://guardrails/regex_match\")\n```\n\n资料来源：[guardrails/hub/install.py:25-35](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)\n\n## CLI 命令参考\n\nGuardrails Hub 通过 `guardrails hub` 子命令提供操作接口。\n\n### 安装验证器\n\n```bash\nguardrails hub install hub://guardrails/regex_match\nguardrails hub install hub://guardrails/competitor_check\n```\n\n**参数选项：**\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `package_uris` | List[str] | 必需 | 要安装的包 URI 列表 |\n| `--local-models` / `--local` | bool | False | 安装本地模型用于离线推理 |\n| `--quiet` / `-q` | bool | False | 静默模式，减少输出 |\n| `--upgrade` | bool | False | 升级到最新版本 |\n\n**本地模型安装确认：**\n\n当验证器需要本地模型时，系统会提示用户确认：\n\n```\nThis validator has a Guardrails AI inference endpoint available. \nWould you still like to install the local models for local inference?\n```\n\n资料来源：[guardrails/cli/hub/install.py:20-50](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/install.py)\n\n### 创建验证器模板\n\n```bash\nguardrails hub create-validator MyValidator\nguardrails hub create-validator CustomCheck --filepath ./validators/my_check.py\n```\n\n此命令生成验证器模板文件，包含基础结构和必要的方法占位符：\n\n```python\nclass MyValidator(Validator):\n \"\"\"FIXME: A brief description of what your validator does.\"\"\"\n \n def __init__(self, arg_1: str, ...):\n # FIXME: Replace with your custom init args\n pass\n \n def validate(self, value, ...):\n # FIXME: Implement validation logic\n pass\n```\n\n资料来源：[guardrails/cli/hub/create_validator.py:20-60](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/create_validator.py)\n\n### 其他 CLI 命令\n\n| 命令 | 说明 |\n|------|------|\n| `guardrails hub list` | 列出已安装的验证器 |\n| `guardrails hub submit` | 提交验证器到 Hub |\n| `guardrails hub uninstall` | 卸载已安装的验证器 |\n\n## 验证器使用方式\n\n### 基础导入与使用\n\n安装完成后，通过以下方式导入和使用验证器：\n\n```python\nfrom guardrails import Guard, OnFailAction\nfrom guardrails.hub import RegexMatch\n\n# 创建 Guard 实例\nguard = Guard().use(\n RegexMatch, \n regex=r\"\\(?\\d{3}\\)?-? *\\d{3}-? *-?\\d{4}\", \n on_fail=OnFailAction.EXCEPTION\n)\n\n# 验证通过\nguard.validate(\"123-456-7890\")\n\n# 验证失败（抛出异常）\ntry:\n guard.validate(\"1234-789-0000\")\nexcept Exception as e:\n print(e)\n```\n\n资料来源：[README.md:30-55](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n\n### 多个验证器组合\n\n可以链式使用多个验证器：\n\n```python\nfrom guardrails import Guard, OnFailAction\nfrom guardrails.hub import CompetitorCheck, ToxicLanguage\n\nguard = Guard().use(\n CompetitorCheck(\n [\"Apple\", \"Microsoft\", \"Google\"], \n on_fail=OnFailAction.EXCEPTION\n ),\n ToxicLanguage(\n threshold=0.5, \n validation_method=\"sentence\", \n on_fail=OnFailAction.EXCEPTION\n )\n)\n\n# 验证通过的场景\nguard.validate(\"An apple a day keeps a doctor away. This is good advice.\")\n```\n\n资料来源：[README.md:55-80](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n\n## 开发与贡献\n\n### 创建新验证器\n\n对于简单验证器，可使用 CLI 工具生成模板：\n\n```bash\nguardrails hub create-validator MyValidator\n```\n\n对于复杂验证器，建议使用官方模板仓库：\n\n> https://github.com/guardrails-ai/validator-template\n\n资料来源：[guardrails/cli/hub/create_validator.py:30-35](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/create_validator.py)\n\n### 提交到 Hub\n\n贡献者可以通过 `guardrails hub submit` 命令将自己开发的验证器提交到 Hub 进行审核。提交前请确保：\n\n1. 验证器包含完整的文档字符串\n2. 实现必要的 `__init__` 和 `validate` 方法\n3. 提供使用示例\n4. 所有测试通过\n\n资料来源：[CONTRIBUTING.md:1-30](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)\n\n### 开发环境设置\n\n```bash\n# 克隆仓库\ngit clone https://github.com/guardrails-ai/guardrails.git\ncd guardrails\n\n# 安装开发依赖\nmake dev\n\n# 安装 pre-commit 钩子\npre-commit install\n\n# 运行测试\nmake test\n\n# 代码格式化\nmake autoformat\n\n# 类型检查\nmake type\n```\n\n## 验证器清单示例\n\n| 验证器名称 | 功能描述 | 必需参数 |\n|-----------|----------|----------|\n| `RegexMatch` | 正则表达式匹配验证 | `regex` |\n| `CompetitorCheck` | 竞争对手名称检测 | `competitors: List[str]` |\n| `ToxicLanguage` | 有害内容检测 | `threshold`, `validation_method` |\n| `Summarizer` | 摘要生成（需本地模型） | - |\n| `Chatbot` | 对话机器人（需本地模型） | - |\n\n## 常见问题\n\n**Q: 安装失败怎么办？**\n\n检查网络连接和 pip 权限，确保已正确配置 PyPI 镜像源。\n\n**Q: 如何指定验证器版本？**\n\n在 URI 中添加版本约束：`hub://guardrails/regex_match~=1.4`\n\n**Q: 验证器需要本地模型时如何处理？**\n\n使用 `--local-models` 参数安装本地模型，或使用云端推理端点（默认行为）。\n\n---\n\n\n\n## CLI 命令行工具\n\n### 相关页面\n\n相关主题：[安装与配置](#page-installation), [Guardrails Hub](#page-hub), [Guardrails 服务器](#page-server)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [guardrails/cli/guardrails.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/guardrails.py)\n- [guardrails/cli/create.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/create.py)\n- [guardrails/cli/validate.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/validate.py)\n- [guardrails/cli/db/db.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/db/db.py)\n- [guardrails/cli/db/upgrade.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/db/upgrade.py)\n- [guardrails/cli/db/downgrade.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/db/downgrade.py)\n- [guardrails/cli/hub/__init__.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/__init__.py)\n \n\n# CLI 命令行工具\n\n## 概述\n\nGuardrails CLI 是 Guardrails 框架提供的命令行界面工具，为开发者提供了一系列便捷的终端操作命令。通过 CLI，用户可以快速创建验证器、管理 Hub 模块、执行数据验证、配置本地环境以及启动 API 服务。CLI 工具采用模块化架构设计，将不同功能封装为独立的子命令模块，包括 Guard 管理、RAIL 文件创建、数据验证、数据库迁移以及 Hub 模块安装等核心功能。\n\nCLI 基于 Typer 框架构建，充分利用了 Python 类型提示和命令补全功能，为用户提供流畅的命令行体验。所有的 CLI 命令都集成了日志系统，支持不同级别的日志输出，便于调试和监控操作状态。\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[\"guardrails CLI 入口\"] --> B[\"Typer 应用主框架\"]\n B --> C[\"guardrails 子命令\"]\n B --> D[\"hub 子命令\"]\n B --> E[\"create 子命令\"]\n B --> F[\"validate 子命令\"]\n B --> G[\"db 子命令\"]\n B --> H[\"start 子命令\"]\n \n C --> C1[\"Guard 状态管理\"]\n C --> C2[\"配置管理\"]\n \n D --> D1[\"install 安装命令\"]\n D --> D2[\"create-validator 创建验证器\"]\n D --> D3[\"search 搜索命令\"]\n \n E --> E1[\"RAIL 文件生成\"]\n E --> E2[\"Schema 模板\"]\n \n F --> F1[\"JSON 验证\"]\n F --> F2[\"输出校验\"]\n \n G --> G1[\"upgrade 升级\"]\n G --> G2[\"downgrade 降级\"]\n G --> G3[\"迁移管理\"]\n \n H --> H1[\"API 服务启动\"]\n H --> H2[\"环境配置\"]\n```\n\n### 目录结构\n\n```\nguardrails/cli/\n├── __init__.py # CLI 入口点\n├── guardrails.py # Guard 状态管理命令\n├── create.py # RAIL 文件创建命令\n├── validate.py # 数据验证命令\n├── hub/ # Hub 模块管理\n│ ├── __init__.py # Hub CLI 主模块\n│ ├── install.py # 安装验证器\n│ ├── create_validator.py # 创建验证器模板\n│ └── search.py # 搜索验证器\n├── db/ # 数据库迁移\n│ ├── db.py # 数据库配置\n│ ├── upgrade.py # 升级命令\n│ └── downgrade.py # 降级命令\n├── start.py # API 服务启动\n└── logger.py # 日志配置\n```\n\n## 核心模块详解\n\n### Hub 模块\n\nHub 模块是 Guardrails CLI 的核心组成部分，负责管理验证器模块的安装、创建和搜索功能。通过 Hub，用户可以访问 Guardrails 官方验证器库，并将其安装到本地环境中使用。\n\n#### 安装验证器\n\n`hub install` 命令用于从 Guardrails Hub 安装验证器模块。该命令支持多种安装方式，包括从官方 Hub 安装特定验证器以及从 git 仓库安装自定义模块。\n\n```mermaid\ngraph LR\n A[\"输入包URI\"] --> B[\"验证器ID解析\"]\n B --> C[\"获取模块清单\"]\n C --> D{\"是否安装本地模型\"}\n D -->|是| E[\"确认安装\"]\n D -->|否| F[\"跳过本地模型\"]\n E --> G[\"下载依赖\"]\n F --> G\n G --> H[\"pip 安装\"]\n H --> I[\"安装完成\"]\n```\n\n**主要参数：**\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `package_uris` | 列表/字符串 | 要安装的包URI列表 | 必需 |\n| `-l, --local-models` | 布尔值 | 是否安装本地模型 | False |\n| `-q, --quiet` | 布尔值 | 静默模式减少输出 | False |\n| `--upgrade` | 布尔值 | 升级到最新版本 | False |\n\n安装示例：\n\n```bash\n# 安装单个验证器\nguardrails hub install hub://guardrails/regex_match\n\n# 安装指定版本\nguardrails hub install hub://guardrails/regex_match~=1.4\n\n# 安装多个验证器\nguardrails hub install hub://guardrails/competitor_check hub://guardrails/toxic_language\n```\n\n资料来源：[guardrails/cli/hub/install.py:1-50]()\n\n#### 创建验证器\n\n`hub create-validator` 命令用于快速创建验证器模板文件。该命令会根据提供的名称自动生成符合 Guardrails 规范的验证器代码框架。\n\n```mermaid\ngraph TD\n A[\"输入验证器名称\"] --> B[\"名称格式转换\"]\n B --> C[\"snake_case 命名\"]\n B --> D[\"PascalCase 命名\"]\n C --> E[\"生成文件路径\"]\n D --> F[\"应用 Jinja2 模板\"]\n F --> G[\"写入 Python 文件\"]\n G --> H[\"创建完成\"]\n```\n\n**模板包含内容：**\n\n- 验证器类框架（继承自 `Validator` 基类）\n- 初始化参数定义区域\n- `validate` 方法骨架代码\n- 示例测试用例（docstring 中）\n- 文档注释模板\n\n```bash\n# 创建名为 MyValidator 的验证器\nguardrails hub create-validator MyValidator\n\n# 指定输出路径\nguardrails hub create-validator MyValidator --filepath ./custom/path/my_validator.py\n```\n\n资料来源：[guardrails/cli/hub/create_validator.py:1-80]()\n\n### 数据库迁移模块\n\n数据库迁移模块负责管理 Guardrails 内部数据库的版本控制，支持升级和降级操作。该模块使用 Alembic 作为迁移引擎，确保数据库结构的平滑演进。\n\n#### 数据库配置\n\n`db` 命令组提供数据库相关的管理功能，包括迁移状态查看和版本控制操作。\n\n资料来源：[guardrails/cli/db/db.py:1-30]()\n\n#### 升级操作\n\n`db upgrade` 命令将数据库迁移到指定版本或最新版本。迁移过程中会按顺序执行所有未应用的迁移文件。\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `revision` | 字符串 | 目标版本标识 | head（最新） |\n| `--sql` | 布尔值 | 仅生成 SQL 不执行 | False |\n| `-x, --xarg` | 字符串 | 扩展参数传递 | None |\n\n```bash\n# 升级到最新版本\nguardrails db upgrade head\n\n# 升级到指定版本\nguardrails db upgrade abc123\n\n# 查看生成的 SQL 而不执行\nguardrails db upgrade head --sql\n```\n\n资料来源：[guardrails/cli/db/upgrade.py:1-40]()\n\n#### 降级操作\n\n`db downgrade` 命令用于将数据库回滚到之前的版本。降级操作会按相反顺序撤销迁移。\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `revision` | 字符串 | 目标版本标识 | -1（上一个版本） |\n| `--sql` | 布尔值 | 仅生成 SQL 不执行 | False |\n| `-x, --xarg` | 字符串 | 扩展参数传递 | None |\n\n```bash\n# 降级一个版本\nguardrails db downgrade -1\n\n# 降级到初始状态\nguardrails db downgrade base\n\n# 查看生成的 SQL 而不执行\nguardrails db downgrade -1 --sql\n```\n\n资料来源：[guardrails/cli/db/downgrade.py:1-35]()\n\n### 创建模块\n\n`create` 命令用于从 Pydantic 模型或 JSON Schema 生成 RAIL 文件。RAIL（Reliable AI Application Language）是一种基于 XML 的规范语言，用于定义 LLM 输出的结构和验证规则。\n\n#### 输入格式支持\n\n| 输入类型 | 说明 | 支持参数 |\n|----------|------|----------|\n| Pydantic 模型 | Python 类继承 BaseModel | `output_class` |\n| JSON Schema | 标准 JSON Schema 格式 | `json_schema` |\n| Python 类 | 带有 Field 定义的类 | 自动推断 |\n\n```python\n# 从 Pydantic 模型创建 RAIL\nfrom guardrails.cli import create\n\nrail_xml = create.from_pydantic(MyModel)\nprint(rail_xml)\n```\n\n#### Schema 转换\n\ncreate 模块内部集成了 Schema 转换功能，能够将 JSON Schema 映射为 RAIL 格式的元素结构。转换过程支持以下类型映射：\n\n| JSON Schema 类型 | RAIL 元素 | 支持格式 |\n|------------------|-----------|----------|\n| string | string | date, time, datetime, percentage, enum |\n| number | float | - |\n| integer | integer | - |\n| boolean | bool | - |\n| array | list | - |\n| object | object | - |\n\n资料来源：[guardrails/schema/rail_schema.py:1-100]()\n\n### 验证模块\n\n`validate` 命令提供独立的验证功能，允许用户直接对输入数据进行验证而不需要通过 Python 代码调用 Guard 对象。\n\n```bash\n# 验证字符串是否符合正则表达式\nguardrails validate --validator regex_match --regex \"\\d{4}-\\d{2}-\\d{2}\" \"2024-01-15\"\n\n# 验证 JSON 格式\nguardrails validate --schema-path ./schema.json --input ./data.json\n```\n\n资料来源：[guardrails/cli/validate.py:1-50]()\n\n### 服务启动模块\n\n`start` 命令用于启动 Guardrails API 服务。该模块封装了 API 服务器的启动逻辑，提供端口配置、环境变量覆盖和热重载等功能。\n\n```mermaid\ngraph TD\n A[\"start 命令执行\"] --> B{\"检查 API 包安装\"}\n B -->|未安装| C[\"自动安装 guardrails-api\"]\n B -->|已安装| D[\"检查版本兼容性\"]\n C --> D\n D --> E[\"加载环境配置\"]\n E --> F{\"watch 模式\"}\n F -->|启用| G[\"开启热重载\"]\n F -->|禁用| H[\"标准启动\"]\n G --> I[\"启动 API 服务\"]\n H --> I\n```\n\n**主要参数：**\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `--port` | 整数 | 服务监听端口 | 8000 |\n| `--config` | 路径 | 配置文件路径 | None |\n| `--env` | 路径 | 环境变量文件 | None |\n| `--env-override` | 字典 | 环境变量覆盖 | None |\n| `--watch` | 布尔值 | 启用热重载 | False |\n\n```bash\n# 基础启动\nguardrails start\n\n# 指定端口\nguardrails start --port 9000\n\n# 加载环境配置\nguardrails start --env .env.production\n\n# 启用热重载开发模式\nguardrails start --watch\n```\n\n资料来源：[guardrails/cli/start.py:1-80]()\n\n## 日志系统\n\nGuardrails CLI 集成了统一的日志系统，支持多级别日志输出和彩色终端显示。\n\n```python\n# 可用的日志级别\nLEVELS = {\n \"SPAM\": 5, # 详细调试信息\n \"VERBOSE\": 15, # 详细操作信息\n \"NOTICE\": 25, # 重要提示\n \"SUCCESS\": 35, # 成功操作\n}\n```\n\n日志输出示例：\n\n```bash\n# 详细输出模式\nguardrails hub install hub://guardrails/regex_match --verbose\n\n# 静默模式\nguardrails hub install hub://guardrails/regex_match --quiet\n```\n\n资料来源：[guardrails/cli/logger.py:1-20]()\n\n## 使用流程示例\n\n### 完整工作流程\n\n```mermaid\ngraph LR\n A[\"安装 guardrails-ai\"] --> B[\"配置 CLI\"]\n B --> C[\"安装验证器\"]\n C --> D[\"创建/编写验证器\"]\n D --> E[\"创建 RAIL 文件\"]\n E --> F[\"编写 Python 代码\"]\n F --> G[\"运行验证\"]\n G --> H{\"验证结果\"}\n H -->|通过| I[\"流程结束\"]\n H -->|失败| J[\"重新调整输入\"]\n J --> G\n```\n\n### 典型使用场景\n\n#### 场景一：快速验证数据格式\n\n```bash\n# 1. 配置 CLI\nguardrails configure\n\n# 2. 安装验证器\nguardrails hub install hub://guardrails/regex_match\n\n# 3. 创建验证脚本\ncat > validate_phone.py << EOF\nfrom guardrails import Guard\nfrom guardrails.hub import RegexMatch\n\nguard = Guard().use(RegexMatch, regex=r\"\\d{3}-\\d{4}\")\n\nresult = guard.validate(\"123-4567\")\nprint(\"验证通过\" if result else \"验证失败\")\nEOF\n\n# 4. 执行验证\npython validate_phone.py\n```\n\n#### 场景二：从 Pydantic 模型生成 RAIL\n\n```bash\n# 1. 编写 Pydantic 模型\ncat > models.py << EOF\nfrom pydantic import BaseModel, Field\n\nclass User(BaseModel):\n name: str = Field(description=\"用户姓名\")\n email: str = Field(description=\"电子邮箱\")\n age: int = Field(description=\"年龄\", ge=0)\nEOF\n\n# 2. 生成 RAIL 文件\nguardrails create models.User --output user.rail\n```\n\n#### 场景三：构建和安装自定义验证器\n\n```bash\n# 1. 创建验证器模板\nguardrails hub create-validator competitor_check\n\n# 2. 编辑生成的 Python 文件\n# 编辑 competitor_check.py 实现具体验证逻辑\n\n# 3. 从本地路径安装\nguardrails hub install ./competitor_check.py\n\n# 4. 在代码中使用\npython << EOF\nfrom guardrails import Guard\nfrom guardrails.hub import CompetitorCheck\n\nguard = Guard().use(CompetitorCheck, competitors=[\"Apple\", \"Google\"])\nEOF\n```\n\n## 错误处理\n\nCLI 工具采用统一的错误处理机制，确保用户获得清晰的错误信息和建议。\n\n### 常见错误及解决方案\n\n| 错误类型 | 错误信息 | 解决方案 |\n|----------|----------|----------|\n| 包未找到 | `Package not found in hub` | 检查包名拼写，确认包已发布 |\n| 版本冲突 | `Version requirement failed` | 使用 `--upgrade` 参数升级 |\n| 权限不足 | `Permission denied` | 使用 `sudo` 或虚拟环境 |\n| 依赖缺失 | `Module not found` | 安装缺失的 Python 包 |\n\n### 调试模式\n\n```bash\n# 启用详细日志\nexport GUARDRAILS_LOG_LEVEL=VERBOSE\nguardrails hub install hub://guardrails/regex_match\n\n# 显示完整堆栈跟踪\nguardrails --traceback hub install hub://guardrails/regex_match\n```\n\n## 最佳实践\n\n1. **使用虚拟环境**：建议在虚拟环境中安装 Guardrails，避免依赖冲突\n2. **版本管理**：在项目中锁定 guardrails-ai 版本，确保复现性\n3. **本地模型**：仅在需要离线运行验证时安装本地模型\n4. **日志级别**：生产环境使用默认级别，开发环境使用详细日志\n5. **自动化测试**：使用 `validate` 命令集成到 CI/CD 流程\n\n## 总结\n\nGuardrails CLI 提供了一套完整且易用的命令行工具集，覆盖了从验证器管理、RAIL 文件创建、数据验证到 API 服务部署的全流程。通过模块化的命令设计，用户可以根据需要灵活组合使用各项功能，提高开发效率。CLI 工具的日志系统、错误处理和参数验证机制确保了操作的可靠性和用户体验的流畅性。\n\n---\n\n\n\n## Guardrails 服务器\n\n### 相关页面\n\n相关主题：[CLI 命令行工具](#page-cli), [框架集成](#page-integrations)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [guardrails/cli/start.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/start.py)\n- [guardrails/guard.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/guard.py)\n- [guardrails/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)\n- [guardrails/cli/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/install.py)\n- [README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n- [guardrails/classes/history/call.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call.py)\n \n\n# Guardrails 服务器\n\nGuardrails 服务器是 Guardrails 框架提供的一项可选服务，用于部署和管理 Guardrails 验证能力。通过服务器模式，用户可以将验证逻辑集中管理，并以 API 服务的方式对外提供验证功能。本文详细介绍 Guardrails 服务器的架构、启动方式、配置方法以及与客户端的交互方式。\n\n## 服务器概述\n\nGuardrails 服务器基于 `guardrails-api` 包构建，提供了一个轻量级的 REST API 服务，用于执行 LLM 输出验证任务。服务器接收原始文本或结构化数据，通过配置的验证器（Validators）进行验证，并返回验证结果。\n\n服务器的核心功能包括：\n\n- **集中化验证**：将验证逻辑部署在服务器端，客户端无需本地安装验证器\n- **API 服务**：提供 RESTful API 接口，支持远程验证调用\n- **多验证器编排**：支持同时运行多个验证器，实现复杂的验证场景\n- **历史记录追踪**：记录每次验证调用的详细信息，包括输入、输出和异常情况\n- **Watch 模式**：支持开发模式下的热重载功能\n\n## 系统架构\n\n```mermaid\ngraph TD\n A[客户端应用] -->|HTTP/REST API| B[Guardrails 服务器]\n B --> C[guardrails-api 核心服务]\n C --> D[验证器注册表]\n D --> E[RegexMatch]\n D --> F[CompetitorCheck]\n D --> G[ToxicLanguage]\n D --> H[其他验证器...]\n B --> I[历史记录存储]\n I --> J[Call 对象]\n J --> K[Iteration 堆栈]\n K --> L[验证步骤记录]\n```\n\n### 核心组件\n\n| 组件名称 | 文件位置 | 功能描述 |\n|---------|---------|---------|\n| guardrails-api | guardrails_api/ | 核心服务器实现 |\n| CLI 启动器 | guardrails/cli/start.py | 命令行启动入口 |\n| 配置管理 | settings | 服务器配置管理 |\n| 验证器服务 | guardrails/hub/ | 验证器安装与加载 |\n| Guard 类 | guardrails/guard.py | 验证逻辑封装 |\n\n## 启动服务器\n\n### 环境准备\n\n启动 Guardrails 服务器前，需要确保已安装 `guardrails-api` 包：\n\n```bash\npip install guardrails-api>=0.2.1\n```\n\n服务器启动时会检查 `guardrails-api` 是否已安装，若未安装则自动提示安装。资料来源：[guardrails/cli/start.py:12-18]()\n\n### 启动命令\n\n使用 `guardrails start` 命令启动服务器：\n\n```bash\nguardrails start [选项]\n```\n\n**常用选项：**\n\n| 选项 | 说明 | 默认值 |\n|-----|------|-------|\n| `--port` | 服务器监听端口 | 8000 |\n| `--env` | 环境变量文件路径 | None |\n| `--config` | 配置文件路径 | None |\n| `--env-override` | 环境变量覆盖 | None |\n| `--watch` | 启用 Watch 模式 | False |\n\n### Watch 模式\n\n启用 Watch 模式后，服务器会监视配置文件和验证器的变化，并自动重新加载：\n\n```bash\nguardrails start --watch\n```\n\nWatch 模式通过 `settings._watch_mode_enabled = True` 启用，适用于开发阶段。资料来源：[guardrails/cli/start.py:28-29]()\n\n## 服务器配置\n\n### 配置文件\n\nGuardrails 服务器支持通过配置文件进行定制化设置。配置文件采用 Python 格式，定义服务器的各项参数。\n\n### 环境变量覆盖\n\n对于敏感配置（如 API 密钥），建议使用环境变量进行配置。`--env-override` 参数允许指定环境变量文件：\n\n```bash\nguardrails start --env-override /path/to/.env\n```\n\n> 注意：`env_override` 功能仅在 `guardrails-api>=0.3.0` 版本中可用。资料来源：[guardrails/cli/start.py:36-42]()\n\n### 版本兼容性\n\n服务器启动时会检查版本兼容性：\n\n- **版本 < 0.3.0**：不支持 `env_override` 参数，调用 `start_api(env, config, port)`\n- **版本 >= 0.3.0**：支持所有参数，包括 `env_override`\n\n```python\nif major == \"0\" and int(minor) < 3:\n start_api(env, config, port)\nelse:\n start_api(env, config, port, env_override)\n```\n\n资料来源：[guardrails/cli/start.py:44-52]()\n\n## API 服务接口\n\n### 验证端点\n\n服务器提供标准的 REST API 端点供客户端调用：\n\n```python\nfrom guardrails import Guard, OnFailAction\n\n# 创建 Guard 实例\nguard = Guard().use(\n RegexMatch, regex=\"\\(?\\d{3}\\)?-? *\\d{3}-? *-?\\d{4}\", on_fail=OnFailAction.EXCEPTION\n)\n\n# 通过 API 调用验证\nresponse = guard.validate(\"123-456-7890\")\n```\n\n### 验证流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Server as Guardrails 服务器\n participant Guard as Guard 实例\n participant Validator as 验证器\n \n Client->>Server: POST /validate (待验证文本)\n Server->>Guard: 创建/获取 Guard 实例\n Guard->>Validator: 执行验证\n Validator-->>Guard: 验证结果\n Guard-->>Server: 验证响应\n Server-->>Client: JSON 响应\n```\n\n## 验证器管理\n\n### 安装验证器\n\n通过 CLI 安装验证器到服务器：\n\n```bash\nguardrails hub install hub://guardrails/regex_match\nguardrails hub install hub://guardrails/competitor_check\nguardrails hub install hub://guardrails/toxic_language\n```\n\n安装过程包括：\n\n1. **验证包 URI**：解析验证器标识符和版本\n2. **获取清单**：从 Hub 获取验证器元数据和依赖\n3. **安装依赖**：通过 pip 安装验证器及其依赖\n4. **加载模块**：将验证器模块加载到运行时\n\n资料来源：[guardrails/cli/hub/install.py:1-50]()\n\n### 验证器安装流程\n\n```mermaid\ngraph TD\n A[hub install 命令] --> B[ValidatorPackageService.get_validator_id]\n B --> C{验证器已安装?}\n C -->|是| D[返回已安装版本]\n C -->|否| E[ValidatorPackageService.get_manifest_and_site_packages]\n E --> F[下载依赖]\n F --> G[ValidatorPackageService.install_hub_module]\n G --> H[模块安装完成]\n```\n\n## 验证历史记录\n\n### Call 对象结构\n\n每次 API 调用都会生成一个 `Call` 对象，记录完整的执行历史：\n\n```python\nclass Call:\n iterations: Stack[Iteration] # 迭代堆栈\n inputs: CallInputs # 输入参数\n exception: Optional[Exception] # 异常信息\n```\n\n资料来源：[guardrails/classes/history/call.py:1-30]()\n\n### CallInputs 输入参数\n\n| 参数名 | 类型 | 说明 |\n|-------|------|------|\n| prompt | str | 输入提示词 |\n| prompt_params | Dict | 提示词参数 |\n| llm_api | Callable | LLM 调用函数 |\n| messages | List[Dict] | 消息历史 |\n| num_reasks | int | 最大重试次数 |\n| metadata | Dict | 附加元数据 |\n| full_schema_reask | bool | 全量重问标志 |\n| stream | bool | 流式响应标志 |\n| args | List | 额外位置参数 |\n| kwargs | Dict | 额外关键字参数 |\n\n资料来源：[guardrails/classes/history/call_inputs.py:1-60]()\n\n### 迭代记录\n\n```mermaid\ngraph LR\n A[初始调用] --> B[Iteration 1]\n B --> C{验证通过?}\n C -->|是| D[返回结果]\n C -->|否| E[Iteration 2]\n E --> F{验证通过?}\n F -->|否| G[Iteration N]\n G --> H{达到最大重试?}\n H -->|是| I[返回异常]\n H -->|否| E\n```\n\n## 客户端集成\n\n### Python 客户端\n\n使用 `guardrails-api` 客户端库连接服务器：\n\n```python\nfrom guardrails_api.client import GuardrailsClient\n\nclient = GuardrailsClient(\"http://localhost:8000\")\n\nresult = client.validate(\n text=\"需要验证的文本\",\n validators=[\"RegexMatch\"],\n config={\"regex\": r\"\\d+\"}\n)\n```\n\n### 配置验证器\n\n在服务器端预先配置验证器，客户端只需指定验证器名称：\n\n```python\nguard = Guard().use(\n CompetitorCheck(\n competitors=[\"Apple\", \"Microsoft\", \"Google\"],\n on_fail=OnFailAction.EXCEPTION\n ),\n ToxicLanguage(\n threshold=0.5,\n validation_method=\"sentence\",\n on_fail=OnFailAction.EXCEPTION\n )\n)\n```\n\n## 部署选项\n\n### Docker 部署\n\nGuardrails 服务器支持 Docker 容器化部署：\n\n```dockerfile\n# server_ci/Dockerfile\nFROM python:3.11-slim\n# ... 其他配置\n```\n\n### 生产环境建议\n\n| 配置项 | 建议值 | 说明 |\n|-------|-------|------|\n| 端口 | 8000+ | 避免使用低位端口 |\n| Watch 模式 | 禁用 | 生产环境禁用热重载 |\n| 日志级别 | INFO | 平衡日志量和调试能力 |\n| 超时设置 | 60s | LLM 调用超时时间 |\n| 重试次数 | 3 | 验证失败重试次数 |\n\n## 故障排查\n\n### 常见问题\n\n**服务器启动失败**\n- 检查 `guardrails-api` 是否正确安装：`pip show guardrails-api`\n- 验证端口是否被占用：`lsof -i :8000`\n- 查看日志输出获取详细错误信息\n\n**验证器加载失败**\n- 确认验证器已正确安装：`guardrails hub list`\n- 检查 Python 路径是否包含验证器目录\n\n**版本不兼容**\n- 升级 `guardrails-api`：`pip install --upgrade guardrails-api`\n- 检查版本兼容性矩阵\n\n## 相关资源\n\n- [Guardrails Hub](https://guardrailsai.com/hub/) - 验证器市场\n- [官方文档](https://docs.guardrailsai.com/) - 完整文档\n- [GitHub 仓库](https://github.com/guardrails-ai/guardrails) - 源代码\n- [Discord 社区](https://discord.gg/Jsey3mX98B) - 技术讨论\n\n---\n\n\n\n## 框架集成\n\n### 相关页面\n\n相关主题：[Guard 类详解](#page-guard-class), [验证流程与 Runner](#page-validation-flow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [guardrails/integrations/langchain/__init__.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/langchain/__init__.py)\n- [guardrails/integrations/langchain/guard_runnable.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/langchain/guard_runnable.py)\n- [guardrails/integrations/langchain/validator_runnable.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/langchain/validator_runnable.py)\n- [guardrails/integrations/langchain/base_runnable.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/langchain/base_runnable.py)\n- [guardrails/integrations/llama_index/__init__.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/llama_index/__init__.py)\n- [guardrails/integrations/llama_index/guardrails_chat_engine.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/llama_index/guardrails_chat_engine.py)\n- [guardrails/integrations/llama_index/guardrails_query_engine.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/llama_index/guardrails_query_engine.py)\n- [guardrails/integrations/databricks/__init__.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/databricks/__init__.py)\n- [guardrails/integrations/databricks/ml_flow_instrumentor.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/databricks/ml_flow_instrumentor.py)\n \n\n# 框架集成\n\nGuardrails 为主流 LLM 应用框架提供了官方集成支持，使开发者能够在不改变原有工作流的情况下，为 LLM 应用添加输出验证和结构化能力。框架集成的核心目标是将 Guardrails 的验证机制无缝嵌入到 LangChain、LlamaIndex 和 Databricks 等生态系统中，实现输入验证、输出校验、错误修正等功能的一体化支持。\n\n## 集成架构概述\n\nGuardrails 的框架集成采用模块化设计，每个框架都有独立的集成包，包含针对该框架特定接口的适配器。这种设计确保了集成代码的清晰性和可维护性，同时保持了各框架原生 API 的使用体验。\n\n```mermaid\ngraph TB\n subgraph \"Guardrails 集成层\"\n LC[\"LangChain 集成\"]\n LI[\"LlamaIndex 集成\"]\n DB[\"Databricks 集成\"]\n end\n \n subgraph \"Guardrails 核心\"\n G[\"Guard 类\"]\n V[\"Validator 系统\"]\n H[\"Hub 验证器\"]\n end\n \n LC --> G\n LI --> G\n DB --> G\n G --> V\n V --> H\n```\n\n## LangChain 集成\n\nLangChain 是目前最流行的 LLM 应用开发框架之一，Guardrails 提供了完整的 Runnable 接口实现，使 Guardrails 可以直接作为 LangChain 链式调用的一部分使用。\n\n### 核心组件\n\nLangChain 集成包含三个核心类，分别处理不同的验证场景：\n\n| 类名 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| `BaseRunnable` | `base_runnable.py` | 所有 Runnable 的基类，定义通用接口 |\n| `GuardRunnable` | `guard_runnable.py` | 将整个 Guard 实例包装为 Runnable |\n| `ValidatorRunnable` | `validator_runnable.py` | 将单个或多个 Validator 包装为 Runnable |\n\n资料来源：[guardrails/integrations/langchain/__init__.py]()\n\n### GuardRunnable\n\n`GuardRunnable` 是最常用的 LangChain 集成类，它将完整的 Guard 实例转换为 LangChain 的 Runnable 接口。这意味着开发者可以在 LangChain 表达式链中使用任何已定义的 Guard 配置。\n\n```python\nfrom guardrails import Guard\nfrom guardrails.integrations.langchain import GuardRunnable\n\n# 创建 Guard 实例\nguard = Guard().use(...)\n\n# 转换为 Runnable\nguard_runnable = GuardRunnable(guard=guard)\n\n# 在 LangChain 链中使用\nchain = prompt | model | guard_runnable\n```\n\n`GuardRunnable` 继承自 `BaseRunnable`，`BaseRunnable` 提供了与 LangChain Runnable 接口兼容的 `invoke`、`ainvoke`、`batch`、`abatch` 等方法。\n\n资料来源：[guardrails/integrations/langchain/guard_runnable.py]()\n资料来源：[guardrails/integrations/langchain/base_runnable.py]()\n\n### ValidatorRunnable\n\n当只需要使用特定验证器而不需要完整的 Guard 配置时，`ValidatorRunnable` 提供了更轻量级的选择。它允许开发者直接将 Validator 实例嵌入到 LangChain 链中。\n\n```python\nfrom guardrails.integrations.langchain import ValidatorRunnable\nfrom guardrails.hub import RegexMatch\n\n# 创建验证器 Runnable\nvalidator_runnable = ValidatorRunnable(validator=RegexMatch(...))\n\n# 单独使用或在链中使用\nresult = validator_runnable.invoke(\"待验证的文本\")\n```\n\n资料来源：[guardrails/integrations/langchain/validator_runnable.py]()\n\n### 集成工作流\n\n```mermaid\ngraph LR\n A[\"用户输入\"] --> B[\"LangChain Prompt\"]\n B --> C[\"LLM 模型\"]\n C --> D{\"GuardRunnable\"}\n D --> E{验证通过?}\n E -->|是| F[\"返回结果\"]\n E -->|否| G[\"错误处理\"]\n G --> H[\"重新生成或异常\"]\n```\n\n## LlamaIndex 集成\n\nLlamaIndex 是专注于知识增强检索的 LLM 框架，Guardrails 为其提供了 Query Engine 和 Chat Engine 的集成支持，使结构化输出验证可以直接应用于检索增强生成（RAG）场景。\n\n### 核心组件\n\n| 类名 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| `GuardrailsQueryEngine` | `guardrails_query_engine.py` | 为 LlamaIndex 查询引擎添加验证层 |\n| `GuardrailsChatEngine` | `guardrails_chat_engine.py` | 为 LlamaIndex 聊天引擎添加验证层 |\n\n资料来源：[guardrails/integrations/llama_index/__init__.py]()\n\n### GuardrailsQueryEngine\n\n`GuardrailsQueryEngine` 将验证层包装在现有的 LlamaIndex 查询引擎之上。当查询结果返回时，验证器会自动检查输出是否符合预期的格式和内容约束。\n\n```python\nfrom llama_index import VectorStoreIndex\nfrom guardrails import Guard\nfrom guardrails.integrations.llama_index import GuardrailsQueryEngine\n\n# 创建基础索引\nindex = VectorStoreIndex.from_documents(documents)\n\n# 创建带 Guardrails 的查询引擎\nguard = Guard().use(...)\nquery_engine = GuardrailsQueryEngine(\n query_engine=index.as_query_engine(),\n guard=guard\n)\n\n# 使用验证引擎查询\nresponse = query_engine.query(\"用户问题\")\n```\n\n资料来源：[guardrails/integrations/llama_index/guardrails_query_engine.py]()\n\n### GuardrailsChatEngine\n\n`GuardrailsChatEngine` 专门为聊天场景设计，适用于需要持续对话且对每次回复都需要验证的应用。它保持了 LlamaIndex 原有聊天引擎的状态管理能力，同时叠加了验证功能。\n\n```python\nfrom guardrails import Guard\nfrom guardrails.integrations.llama_index import GuardrailsChatEngine\n\nguard = Guard().use(...)\nchat_engine = GuardrailsChatEngine.from_defaults(\n chat_mode=\"condense_plus_context\",\n guard=guard\n)\n\n# 对话循环\nchat_engine.chat(\"用户的第一条消息\")\nchat_engine.chat(\"用户的第二条消息\")\n```\n\n资料来源：[guardrails/integrations/llama_index/guardrails_chat_engine.py]()\n\n## Databricks 集成\n\nDatabricks 集成为使用 Databricks 进行 LLM 应用的开发者提供了 MLflow 仪器化支持，允许在 Databricks 环境中追踪和监控 Guardrails 验证行为。\n\n### MLflow 仪器化器\n\nDatabricks 集成的核心是 `MLflowInstrumentor` 类，它扩展了 MLflow 的自动仪器化功能，使 Guardrails 验证可以自动记录到 MLflow 实验追踪系统中。\n\n```python\nfrom guardrails.integrations.databricks import MLflowInstrumentor\n\n# 初始化仪器化器\ninstrumentor = MLflowInstrumentor()\n\n# 启用自动追踪\ninstrumentor.instrument()\n```\n\n资料来源：[guardrails/integrations/databricks/__init__.py]()\n资料来源：[guardrails/integrations/databricks/ml_flow_instrumentor.py]()\n\n### 追踪能力\n\n通过 MLflow 集成，Guardrails 可以记录以下信息：\n\n- **验证执行次数**：记录每个 Guard 和 Validator 被调用的次数\n- **验证结果**：记录每次验证的通过/失败状态\n- **错误详情**：记录验证失败时的详细错误信息\n- **性能指标**：记录验证过程的执行时间\n\n## 集成配置选项\n\n### 通用配置\n\n| 配置项 | 适用框架 | 说明 |\n|--------|----------|------|\n| `guard` | LangChain, LlamaIndex | 核心 Guard 实例 |\n| `on_fail` | 所有框架 | 验证失败时的行为（EXCEPTION, FIX, FILTER 等） |\n| `strict` | 所有框架 | 是否启用严格模式 |\n\n### LangChain 特定配置\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `output_format` | `None` | 指定输出格式器 |\n| `messages` | `None` | 自定义消息列表 |\n| `reask_messages` | `None` | 重新生成时的消息 |\n\n### LlamaIndex 特定配置\n\n| 配置项 | 说明 |\n|--------|------|\n| `query_engine` | 底层查询引擎实例 |\n| `chat_mode` | 聊天模式选择 |\n\n## 最佳实践\n\n### 框架集成的性能考虑\n\n在生产环境中使用框架集成时，应注意以下性能优化点：\n\n1. **Guard 实例复用**：Guard 实例应该被创建一次并在多次调用中复用，避免重复初始化开销。\n2. **批量验证**：对于支持批量操作的框架（如 LangChain 的 `batch` 方法），应优先使用批量接口。\n3. **异步支持**：所有 Runnable 实现都支持异步操作，在高并发场景下应使用 `ainvoke` 或 `abatch`。\n\n### 错误处理策略\n\n| 策略 | 描述 | 适用场景 |\n|------|------|----------|\n| `EXCEPTION` | 抛出验证异常 | 开发调试阶段 |\n| `FIX` | 自动修正输出 | 自动化处理流程 |\n| `FILTER` | 过滤无效结果 | 需要干净输出的场景 |\n| `REASK` | 重新请求 LLM | 需要高可靠性的生产环境 |\n\n### 框架选择指南\n\n| 场景 | 推荐框架 | 集成类 |\n|------|----------|--------|\n| 链式 LLM 调用 | LangChain | `GuardRunnable` |\n| 检索增强生成 | LlamaIndex | `GuardrailsQueryEngine` |\n| 聊天机器人 | LlamaIndex | `GuardrailsChatEngine` |\n| Databricks 环境 | Databricks | `MLflowInstrumentor` |\n\n## 相关资源\n\n- [Guardrails 官方文档](https://docs.guardrailsai.com/)\n- [Guardrails Hub 验证器库](https://guardrailsai.com/hub/)\n- [LangChain 官方文档](https://python.langchain.com/)\n- [LlamaIndex 官方文档](https://docs.llamaindex.ai/)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：guardrails-ai/guardrails\n\n摘要：发现 23 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：安装坑 - 来源证据：FIX action silently mutates output - should there be a 'quarantine' tier between LOG and FIX?。\n\n## 1. 安装坑 · 来源证据：FIX action silently mutates output - should there be a 'quarantine' tier between LOG and FIX?\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：FIX action silently mutates output - should there be a 'quarantine' tier between LOG and FIX?\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_69600563346341a386aa86c6af5d1274 | https://github.com/guardrails-ai/guardrails/issues/1448 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：Portable evidence artifacts for validation outcomes\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Portable evidence artifacts for validation outcomes\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ef2970465bbe44c89b513edd115b682c | https://github.com/guardrails-ai/guardrails/issues/1457 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Proposal: PromptDefenseAudit Hub validator — static system prompt hardening check\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: PromptDefenseAudit Hub validator — static system prompt hardening check\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d7163e193eb54aab837d87b3ecd73991 | https://github.com/guardrails-ai/guardrails/issues/1453 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 能力坑 · 来源证据：[docs] Fix double logo display in pypi\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：[docs] Fix double logo display in pypi\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_084985c7cb4d4238a44e452b14b2eaf9 | https://github.com/guardrails-ai/guardrails/issues/1362 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安全/权限坑 · 来源证据：Integration proposal: Cryptographic audit trail validator with asqav\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Integration proposal: Cryptographic audit trail validator with asqav\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8db542ceccff4a71bc11c254ce3abfde | https://github.com/guardrails-ai/guardrails/issues/1446 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安全/权限坑 · 来源证据：Integration proposal: styxx hallucination validator (8-benchmark cross-validated)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Integration proposal: styxx hallucination validator (8-benchmark cross-validated)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_da275c0a112848ed920af00c76fd3e1b | https://github.com/guardrails-ai/guardrails/issues/1463 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：Proposal: Agent Threat Rules detection integration\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: Agent Threat Rules detection integration\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9d25561995774521a21051373d95b431 | https://github.com/guardrails-ai/guardrails/issues/1471 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：[bug] Guardrails CLI start command broken with guardrails-api 0.4.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] Guardrails CLI start command broken with guardrails-api 0.4.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f411132764b84c17b318b5cc7a32ef56 | https://github.com/guardrails-ai/guardrails/issues/1464 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：v0.7.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_95f33a7ff8014d78a13752aa7fd56d6e | https://github.com/guardrails-ai/guardrails/releases/tag/v0.7.3 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 10. 安装坑 · 来源证据：v0.8.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.8.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_559ad38ac0504cff91377804f004c57c | https://github.com/guardrails-ai/guardrails/releases/tag/v0.8.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 安装坑 · 来源证据：v0.9.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.2\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ae34ce00e8554a5199b5e78e3465942d | https://github.com/guardrails-ai/guardrails/releases/tag/v0.9.2 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 12. 安装坑 · 来源证据：v0.9.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f2b73a33cb2f47d3bba9b9f2dd07ed62 | https://github.com/guardrails-ai/guardrails/releases/tag/v0.9.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | README/documentation is current enough for a first validation pass.\n\n## 14. 维护坑 · 来源证据：v0.8.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.8.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_160840f6f00644f2bcd25339973d1d82 | https://github.com/guardrails-ai/guardrails/releases/tag/v0.8.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 维护坑 · 来源证据：v0.9.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.9.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_91ae72d0a0f74305b8b5b3f66d4048e4 | https://github.com/guardrails-ai/guardrails/releases/tag/v0.9.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | last_activity_observed missing\n\n## 17. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 19. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | no_demo; severity=medium\n\n## 20. 安全/权限坑 · 来源证据：MCP Server Compliance Scanning: OWASP MCP Top 10 guardrails\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：MCP Server Compliance Scanning: OWASP MCP Top 10 guardrails\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b6a63df899144908af33089886cfaf51 | https://github.com/guardrails-ai/guardrails/issues/1435 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 21. 安全/权限坑 · 来源证据：v0.8.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.8.1\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6721e28473844e92b61d6701c416d2fd | https://github.com/guardrails-ai/guardrails/releases/tag/v0.8.1 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 22. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | release_recency=unknown\n\n\n",
"markdown_key": "guardrails",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:594609262",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/guardrails-ai/guardrails"
},
{
"evidence_id": "art_bb3495c4c9b741779d972b7633462e32",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/guardrails-ai/guardrails#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "guardrails 说明书",
"toc": [
"https://github.com/guardrails-ai/guardrails 项目说明书",
"目录",
"Guardrails 简介",
"概述",
"核心概念",
"系统架构",
"Guard 类 API",
"LLM 集成",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "379ab72ff643d0d9b8dff4f74c956ce29eab341d",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"docs/pydocs/helpers.py",
"docs/pydocs/pydocs_markdown_impl.py",
"docs/pydocs/generate_pydocs.py",
"docs/pydocs/pydocs_to_md.py",
"docs/how_to_guides/rail.md",
"docs/how_to_guides/output.md",
"docs/api_reference/llm_interaction.md",
"docs/api_reference/history_and_logs.md",
"docs/api_reference/errors.md",
"docs/api_reference/guards.md",
"docs/api_reference/actions.md",
"docs/api_reference/validator.md",
"docs/api_reference/types.md",
"docs/api_reference/formatters.md",
"docs/api_reference/generics_and_base_classes.md",
"docs/examples/data/config.py",
"docs/pydocs/api_reference/llm_interaction.py",
"docs/pydocs/api_reference/generics_and_base_classes.py",
"docs/pydocs/api_reference/validation.py",
"docs/pydocs/api_reference/history.py",
"docs/pydocs/api_reference/guards.py",
"docs/pydocs/api_reference/formatters.py",
"docs/pydocs/api_reference/types.py",
"docs/pydocs/api_reference/actions.py",
"docs/pydocs/api_reference/errors.py"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# guardrails - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 guardrails 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **想在安装前理解开源项目价值和边界的用户**：当前证据主要来自项目文档。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install guardrails-ai` 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、本地环境或项目文件、环境变量 / API Key\n\n### 现在可以相信\n\n- **适合人群线索：想在安装前理解开源项目价值和边界的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `guardrails/api_client.py`, `guardrails/cli/hub/create_validator.py`, `guardrails/utils/openai_utils/v1.py` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0004` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：545\n- 重要文件覆盖：40/545\n- 证据索引条目：58\n- 角色 / Skill 条目：16\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 guardrails 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 guardrails 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 guardrails 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 16 个角色 / Skill / 项目文档条目。\n\n- **News and Updates**（project_doc）：! License https://img.shields.io/badge/License-Apache 2.0-blue.svg https://opensource.org/licenses/Apache-2.0 ! PyPI - Python Version https://img.shields.io/pypi/pyversions/guardrails-ai ! Downloads https://static.pepy.tech/badge/guardrails-ai/month https://pepy.tech/project/guardrails-ai ! CI https://github.com/guardrails-ai/guardrails/actions/workflows/ci.yml/badge.svg https://github.com/guardrails-ai/guardrails/a… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Contributing to Guardrails**（project_doc）：Welcome and thank you for your interest in contributing to Guardrails! We appreciate all contributions, big or small, from bug fixes to new features. Before diving in, let's go through some guidelines to make the process smoother for everyone. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **Actions**（project_doc）：- incorrect value Any - The value that failed validation. - fail results List FailResult - The results of the failed validations. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api_reference/actions.md`\n- **Errors**（project_doc）：This is thrown from the validation engine when a Validator has on fail=OnFailActions.EXCEPTION set and validation fails. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api_reference/errors.md`\n- **Formatters**（project_doc）：A Formatter takes an LLM Callable and wraps the method into an abstract callable. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api_reference/formatters.md`\n- **Generics And Base Classes**（project_doc）：Empty Pydantic model with a config that allows arbitrary types. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api_reference/generics_and_base_classes.md`\n- **Guards**（project_doc）：This class is the main entry point for using Guardrails. It can be initialized by one of the following patterns: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api_reference/guards.md`\n- **History and Logs**（project_doc）：A Call represents a single execution of a Guard. One Call is created each time the user invokes the Guard. call , Guard.parse , or Guard.validate method. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api_reference/history_and_logs.md`\n- **Helpers for LLM Interactions**（project_doc）：Class for representing a prompt entry. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api_reference/llm_interaction.md`\n- **Types**（project_doc）：OnFailAction is an Enum that represents the different actions that can be taken when a validation fails. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api_reference/types.md`\n- **Validation**（project_doc）：Do not override this function, instead implement validate . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api_reference/validator.md`\n- **Output Element**（project_doc）：The ... element of a RAIL spec is used to give precise specification of the expected output of the LLM. It specifies 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/how_to_guides/output.md`\n- **Use Guardrails via RAIL**（project_doc）：.RAIL is a dialect of XML. It stands for \" R eliable AI markup L anguage\", and it can be used to define: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/how_to_guides/rail.md`\n- **Bug report**（project_doc）：Describe the bug A clear and concise description of what the bug is. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/ISSUE_TEMPLATE/bug_report.md`\n- **Documentation issue**（project_doc）：Description Add a clear description of the documentation issue or improvement suggestion 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/ISSUE_TEMPLATE/documentation.md`\n- **Feature request**（project_doc）：Description Add a description of the feature 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/ISSUE_TEMPLATE/feature_request.md`\n\n## 证据索引\n\n- 共索引 58 条证据。\n\n- **News and Updates**（documentation）：! License https://img.shields.io/badge/License-Apache 2.0-blue.svg https://opensource.org/licenses/Apache-2.0 ! PyPI - Python Version https://img.shields.io/pypi/pyversions/guardrails-ai ! Downloads https://static.pepy.tech/badge/guardrails-ai/month https://pepy.tech/project/guardrails-ai ! CI https://github.com/guardrails-ai/guardrails/actions/workflows/ci.yml/badge.svg https://github.com/guardrails-ai/guardrails/actions/workflows/ci.yml ! codecov https://codecov.io/gh/guardrails-ai/guardrails/graph/badge.svg?token=CPkjw91Ngo https://codecov.io/gh/guardrails-ai/guardrails ! Checked with pyright https://microsoft.github.io/pyright/img/pyright badge.svg https://microsoft.github.io/pyright/ !… 证据：`README.md`\n- **Contributing to Guardrails**（documentation）：Welcome and thank you for your interest in contributing to Guardrails! We appreciate all contributions, big or small, from bug fixes to new features. Before diving in, let's go through some guidelines to make the process smoother for everyone. 证据：`CONTRIBUTING.md`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **Actions**（documentation）：- incorrect value Any - The value that failed validation. - fail results List FailResult - The results of the failed validations. 证据：`docs/api_reference/actions.md`\n- **Errors**（documentation）：This is thrown from the validation engine when a Validator has on fail=OnFailActions.EXCEPTION set and validation fails. 证据：`docs/api_reference/errors.md`\n- **Formatters**（documentation）：A Formatter takes an LLM Callable and wraps the method into an abstract callable. 证据：`docs/api_reference/formatters.md`\n- **Generics And Base Classes**（documentation）：Empty Pydantic model with a config that allows arbitrary types. 证据：`docs/api_reference/generics_and_base_classes.md`\n- **Guards**（documentation）：This class is the main entry point for using Guardrails. It can be initialized by one of the following patterns: 证据：`docs/api_reference/guards.md`\n- **History and Logs**（documentation）：A Call represents a single execution of a Guard. One Call is created each time the user invokes the Guard. call , Guard.parse , or Guard.validate method. 证据：`docs/api_reference/history_and_logs.md`\n- **Helpers for LLM Interactions**（documentation）：Class for representing a prompt entry. 证据：`docs/api_reference/llm_interaction.md`\n- **Types**（documentation）：OnFailAction is an Enum that represents the different actions that can be taken when a validation fails. 证据：`docs/api_reference/types.md`\n- **Validation**（documentation）：Do not override this function, instead implement validate . 证据：`docs/api_reference/validator.md`\n- **Output Element**（documentation）：The ... element of a RAIL spec is used to give precise specification of the expected output of the LLM. It specifies 证据：`docs/how_to_guides/output.md`\n- **Use Guardrails via RAIL**（documentation）：.RAIL is a dialect of XML. It stands for \" R eliable AI markup L anguage\", and it can be used to define: 证据：`docs/how_to_guides/rail.md`\n- **Bug Report**（documentation）：Describe the bug A clear and concise description of what the bug is. 证据：`.github/ISSUE_TEMPLATE/bug_report.md`\n- **Documentation**（documentation）：Description Add a clear description of the documentation issue or improvement suggestion 证据：`.github/ISSUE_TEMPLATE/documentation.md`\n- **Feature Request**（documentation）：Description Add a description of the feature 证据：`.github/ISSUE_TEMPLATE/feature_request.md`\n- **Pyrightconfig**（structured_config）：{ \"reportDeprecated\": true } 证据：`pyrightconfig.json`\n- **Guard Template**（structured_config）：{ \"name\": \"server-ci\", \"description\": \"basic guard template for oss server ci\", \"template version\": \"0.0.1\", \"namespace\": \"guardrails\", \"guards\": { \"id\": \"test-guard\", \"name\": \"test-guard\", \"validators\": { \"id\": \"guardrails/two words\", \"on\": \"$\", \"onFail\": \"fix\" } } } 证据：`server_ci/guard-template.json`\n- **Config**（structured_config）：{ \" name or path\": \"hf-internal-testing/tiny-random-gpt2\", \"activation function\": \"gelu new\", \"architectures\": \"GPT2LMHeadModel\" , \"attention probs dropout prob\": 0.1, \"attn pdrop\": 0.1, \"bos token id\": 98, \"embd pdrop\": 0.1, \"eos token id\": 98, \"gradient checkpointing\": false, \"hidden act\": \"gelu\", \"hidden dropout prob\": 0.1, \"initializer range\": 0.02, \"intermediate size\": 37, \"layer norm epsilon\": 1e-05, \"model type\": \"gpt2\", \"n ctx\": 512, \"n embd\": 32, \"n head\": 4, \"n inner\": null, \"n layer\": 5, \"n positions\": 512, \"pad token id\": 98, \"reorder and upcast attn\": false, \"resid pdrop\": 0.1, \"scale attn by inverse layer idx\": false, \"scale attn weights\": true, \"summary activation\": null, \"su… 证据：`tests/unit_tests/mocks/tiny-random-gpt2/config.json`\n- **Generation Config**（structured_config）：{ \" from model config\": true, \"bos token id\": 98, \"eos token id\": 98, \"pad token id\": 98, \"transformers version\": \"4.36.2\" } 证据：`tests/unit_tests/mocks/tiny-random-gpt2/generation_config.json`\n- **Special Tokens Map**（structured_config）：{ \"bos token\": { \"content\": \" \", \"lstrip\": false, \"normalized\": false, \"rstrip\": false, \"single word\": false }, \"eos token\": { \"content\": \" \", \"lstrip\": false, \"normalized\": false, \"rstrip\": false, \"single word\": false }, \"unk token\": { \"content\": \" \", \"lstrip\": false, \"normalized\": false, \"rstrip\": false, \"single word\": false } } 证据：`tests/unit_tests/mocks/tiny-random-gpt2/special_tokens_map.json`\n- **Tokenizer**（structured_config）：{ \"version\": \"1.0\", \"truncation\": null, \"padding\": null, \"added tokens\": { \"id\": 0, \"content\": \" \", \"single word\": false, \"lstrip\": false, \"rstrip\": false, \"normalized\": false, \"special\": true } , \"normalizer\": null, \"pre tokenizer\": { \"type\": \"ByteLevel\", \"add prefix space\": false, \"trim offsets\": true, \"use regex\": true }, \"post processor\": { \"type\": \"ByteLevel\", \"add prefix space\": true, \"trim offsets\": false, \"use regex\": true }, \"decoder\": { \"type\": \"ByteLevel\", \"add prefix space\": true, \"trim offsets\": true, \"use regex\": true }, \"model\": { \"type\": \"BPE\", \"dropout\": null, \"unk token\": null, \"continuing subword prefix\": \"\", \"end of word suffix\": \"\", \"fuse unk\": false, \"byte fallback\": f… 证据：`tests/unit_tests/mocks/tiny-random-gpt2/tokenizer.json`\n- **Tokenizer Config**（structured_config）：{ \"add prefix space\": false, \"added tokens decoder\": { \"0\": { \"content\": \" \", \"lstrip\": false, \"normalized\": false, \"rstrip\": false, \"single word\": false, \"special\": true } }, \"bos token\": \" \", \"clean up tokenization spaces\": true, \"eos token\": \" \", \"model max length\": 1024, \"tokenizer class\": \"GPT2Tokenizer\", \"unk token\": \" \" } 证据：`tests/unit_tests/mocks/tiny-random-gpt2/tokenizer_config.json`\n- **Vocab**（structured_config）：{\" \":0,\"!\":1,\"\\\"\":2,\" \":3,\"$\":4,\"%\":5,\"&\":6,\"'\":7,\" \":8,\" \":9,\" \":10,\"+\":11,\",\":12,\"-\":13,\".\":14,\"/\":15,\"0\":16,\"1\":17,\"2\":18,\"3\":19,\"4\":20,\"5\":21,\"6\":22,\"7\":23,\"8\":24,\"9\":25,\":\":26,\";\":27,\" \":30,\"?\":31,\"@\":32,\"A\":33,\"B\":34,\"C\":35,\"D\":36,\"E\":37,\"F\":38,\"G\":39,\"H\":40,\"I\":41,\"J\":42,\"K\":43,\"L\":44,\"M\":45,\"N\":46,\"O\":47,\"P\":48,\"Q\":49,\"R\":50,\"S\":51,\"T\":52,\"U\":53,\"V\":54,\"W\":55,\"X\":56,\"Y\":57,\"Z\":58,\" \":59,\"\\\\\":60,\" \":61,\"^\":62,\" \":63,\" \":64,\"a\":65,\"b\":66,\"c\":67,\"d\":68,\"e\":69,\"f\":70,\"g\":71,\"h\":72,\"i\":73,\"j\":74,\"k\":75,\"l\":76,\"m\":77,\"n\":78,\"o\":79,\"p\":80,\"q\":81,\"r\":82,\"s\":83,\"t\":84,\"u\":85,\"v\":86,\"w\":87,\"x\":88,\"y\":89,\"z\":90,\" \":91,\"}\":92,\"~\":93,\"¡\":94,\"¢\":95,\"£\":96,\"¤\":97,\"¥\":98,\"¦\":99,\"§\":100,\"¨\":101,\"©\":… 证据：`tests/unit_tests/mocks/tiny-random-gpt2/vocab.json`\n- **.dockerignore**（source_file）：pycache .pyc .pyo 证据：`.dockerignore`\n- **.gitignore**（source_file）：openai api key.txt pycache data/ .vscode/ .venv/ .DS Store .ipynb checkpoints/ .pyc .env .log .venv settings.json site/ guardrails.log guardrails ai.egg-info/ /build/ docs/build !docs/dist/ dist/ .rail output .idea/ .cache scratch/ scratch.py .coverage coverage.xml test.db test.index htmlcov node modules .docusaurus .vercel !docs/examples-toc.json .python-version static/docs docusaurus/static/docs /bin/ /etc/ /lib/ /lib64/ /include/ /share/ pyvenv.cfg mlruns mlartifacts /.guardrails .claude .idea .pytest cache .ruff cache .vscode docs/examples/.guardrails/hub registry.json 证据：`.gitignore`\n- **Performs ruff check with safe fixes**（source_file）：repos: - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.13.0 hooks: Performs ruff check with safe fixes - id: ruff name: ruff description: \"Run 'ruff' for linting\" args: \"--fix\" Performs ruff format - id: ruff-format name: ruff-format description: \"Run 'ruff format' for formatting\" 证据：`.pre-commit-config.yaml`\n- **pytest -x -q --no-summary**（source_file）：.PHONY: autoformat type lint test test-basic test-cov view-test-cov view-test-cov-file dev full install docs-gen self-install all precommit refresh update-lock 证据：`Makefile`\n- **Codecov**（source_file）：ignore: - \"guardrails/version.py\" - \"tests\" 证据：`codecov.yml`\n- **Set up init .py so that users can do from guardrails import Response, Schema, etc.**（source_file）：Set up init .py so that users can do from guardrails import Response, Schema, etc. 证据：`guardrails/__init__.py`\n- **Api Client**（source_file）：import json import os from typing import Any, AsyncIterator, Iterator, Optional 证据：`guardrails/api_client.py`\n- **check if validator requirements are fulfilled**（source_file）：from builtins import id as object id import contextvars import inspect from opentelemetry import context as otel context from typing import Any, AsyncIterator, Awaitable, Callable, Dict, Generic, List, Optional, Sequence, Union, cast, 证据：`guardrails/async_guard.py`\n- **Constants**（source_file）：Return a valid JSON object that respects this JSON Schema and extracts only the information requested in this document. Respect the types indicated in the JSON Schema -- the information you extract should be converted into the correct 'type'. Try to be as correct and concise as possible. Find all relevant information in the document. If you are unsure of the answer, enter 'None'. If you answer incorrectly, you will be asked again until you get it right which is expensive. 证据：`guardrails/constants.xml`\n- **Datatypes**（source_file）：from guardrails.types.simple import SimpleTypes from guardrails.types.rail import RailTypes 证据：`guardrails/datatypes.py`\n- **PageCoordinates is a datastructure that points to the location**（source_file）：import hashlib from abc import ABC, abstractmethod from collections import namedtuple from dataclasses import dataclass from typing import Any, Dict, List, Optional 证据：`guardrails/document_store.py`\n- **Detokenize the chunks**（source_file）：from abc import ABC, abstractmethod from functools import cached property from itertools import islice from typing import Callable, List, Optional 证据：`guardrails/embedding.py`\n- **Prevent duplicate declaration in the docs**（source_file）：import contextvars import json import os import uuid from builtins import id as object id from typing import Any, Callable, Dict, Generic, Iterator, List, Optional, Sequence, Union, cast, Iterable, import warnings from langchain core.runnables import Runnable 证据：`guardrails/guard.py`\n- **Llm Providers**（source_file）：import inspect from typing import Any, Awaitable, Callable, Dict, Iterator, List, Optional, Union, cast, 证据：`guardrails/llm_providers.py`\n- **from src.modules.otel logger import handler as otel handler**（source_file）：import logging import logging.config from logging import Handler, LogRecord from typing import Dict, List, Optional 证据：`guardrails/logger.py`\n- **TODO: Support a sink for logs so that they are not solely held in memory**（source_file）：from guardrails.logger import set config, set level 证据：`guardrails/logging_utils.py`\n- **SOURCE: https://github.com/spyder-ide/three-merge/blob/master/three merge/merge.py**（source_file）：SOURCE: https://github.com/spyder-ide/three-merge/blob/master/three merge/merge.py from typing import Optional from diff match patch import diff match patch 证据：`guardrails/merge.py`\n- **Settings**（source_file）：import threading from typing import Optional 证据：`guardrails/settings.py`\n- **TODO:**（source_file）：TODO: - Rename this to just validator.py 0.5.x - Maintain validator base.py for exports but deprecate them - Remove validator base.py in 0.6.x 证据：`guardrails/validator_base.py`\n- **Version**（source_file）：from importlib.metadata import version as importlib version 证据：`guardrails/version.py`\n- **TODO - drop this!**（source_file）：project name = \"guardrails-ai\" version = \"0.10.0\" description = \"Adding guardrails to large language models.\" authors = {name = \"Guardrails AI\", email = \"contact@guardrailsai.com\"} license = \"Apache License 2.0\" license-files = \"LICENSE\" homepage = \"https://www.guardrailsai.com/\" documentation = \"https://www.guardrailsai.com/guardrails/docs\" readme = \"README.md\" requires-python = \" =3.10,<4.0\" 证据：`pyproject.toml`\n- **server_ci/.dockerignore**（source_file）：.coverage .coverage.MacBook-Pro.local.75130.XUoRtLxx .dockerignore .docusaurus .git .github .gitignore .idea .pre-commit-config.yaml .pytest cache .python-version .ruff cache .venv .vscode build codecov.yml CONTRIBUTING.md docs docs-build docs/build docs-graveyard DOCS.md docusaurus htmlcov make.bat mlartifacts mlruns node modules package-lock.json package.json tests .venv 证据：`server_ci/.dockerignore`\n- **New LiteLLM version has a dependency on madoka which requires g++ to build the wheel**（source_file）：New LiteLLM version has a dependency on madoka which requires g++ to build the wheel FROM python:3.13 证据：`server_ci/Dockerfile`\n- **!/bin/bash**（source_file）：bash ./server ci/build.sh; bash ./server ci/run.sh; bash ./server ci/check.sh; bash ./server ci/test.sh; bash ./server ci/clean.sh; 证据：`server_ci/all.sh`\n- **!/bin/bash**（source_file）：docker buildx build \\ --platform linux/amd64 \\ -f \"./server ci/Dockerfile\" \\ -t \"guardrails:server-ci\" \\ --build-arg GUARDRAILS TOKEN=\"$GUARDRAILS TOKEN\" \\ --progress plain \\ --load . \\ exit 1 证据：`server_ci/build.sh`\n- **!/bin/bash**（source_file）：for i in {1..30}; do if docker exec guardrails-container curl -s http://localhost:8000/; then echo \"Server is up!\" break fi echo \"Waiting for server...\" sleep 5 done 证据：`server_ci/check.sh`\n- **!/bin/bash**（source_file）：!/bin/bash docker stop guardrails-container true docker rm guardrails-container true 证据：`server_ci/clean.sh`\n- **instantiate guards**（source_file）：import json import os from guardrails import Guard 证据：`server_ci/config.py`\n- **Fastapi Entry**（source_file）：uvicorn guardrails api.app:create app \\ --workers 3 \\ --host 0.0.0.0 \\ --port 8000 \\ --timeout-keep-alive 20 \\ --timeout-graceful-shutdown 60; 证据：`server_ci/fastapi-entry.sh`\n- **Requirements**（source_file）：pytest pytest-asyncio openai 证据：`server_ci/requirements.txt`\n- **!/bin/bash**（source_file）：docker stop guardrails-container true docker rm guardrails-container true docker run -d --name guardrails-container -p 8000:8000 -e OPENAI API KEY=$OPENAI API KEY guardrails:server-ci exit 1 证据：`server_ci/run.sh`\n- **Test Spec**（source_file）：Answer the question: What is 2+2? 证据：`test_spec.rail`\n- **Conftest**（source_file）：import os import pytest from unittest.mock import patch, MagicMock 证据：`tests/conftest.py`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `CONTRIBUTING.md`, `LICENSE`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `CONTRIBUTING.md`, `LICENSE`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Guardrails 简介**：importance `high`\n - source_paths: README.md, guardrails/__init__.py, guardrails/guard.py\n- **安装与配置**：importance `high`\n - source_paths: CONTRIBUTING.md, guardrails/cli/configure.py, Makefile\n- **Guard 类详解**：importance `high`\n - source_paths: guardrails/guard.py, guardrails/async_guard.py, guardrails/prompt/__init__.py, guardrails/prompt/prompt.py, guardrails/prompt/instructions.py\n- **Schema 系统**：importance `high`\n - source_paths: guardrails/schema/pydantic_schema.py, guardrails/schema/rail_schema.py, guardrails/schema/parser.py, guardrails/schema/primitive_schema.py, guardrails/schema/validator.py\n- **验证流程与 Runner**：importance `high`\n - source_paths: guardrails/run/runner.py, guardrails/run/async_runner.py, guardrails/run/stream_runner.py, guardrails/run/utils.py, guardrails/classes/history/call.py\n- **验证器基础**：importance `high`\n - source_paths: guardrails/validator_base.py, guardrails/classes/validation/validation_result.py, guardrails/classes/validation/validator_logs.py, guardrails/actions/filter.py, guardrails/actions/refrain.py\n- **Guardrails Hub**：importance `high`\n - source_paths: guardrails/hub/install.py, guardrails/hub/registry.py, guardrails/hub/validator_package_service.py, guardrails/cli/hub/install.py, guardrails/cli/hub/list.py\n- **CLI 命令行工具**：importance `medium`\n - source_paths: guardrails/cli/guardrails.py, guardrails/cli/create.py, guardrails/cli/validate.py, guardrails/cli/db/db.py, guardrails/cli/db/upgrade.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `379ab72ff643d0d9b8dff4f74c956ce29eab341d`\n- inspected_files: `pyproject.toml`, `README.md`, `docs/pydocs/helpers.py`, `docs/pydocs/pydocs_markdown_impl.py`, `docs/pydocs/generate_pydocs.py`, `docs/pydocs/pydocs_to_md.py`, `docs/how_to_guides/rail.md`, `docs/how_to_guides/output.md`, `docs/api_reference/llm_interaction.md`, `docs/api_reference/history_and_logs.md`, `docs/api_reference/errors.md`, `docs/api_reference/guards.md`, `docs/api_reference/actions.md`, `docs/api_reference/validator.md`, `docs/api_reference/types.md`, `docs/api_reference/formatters.md`, `docs/api_reference/generics_and_base_classes.md`, `docs/examples/data/config.py`, `docs/pydocs/api_reference/llm_interaction.py`, `docs/pydocs/api_reference/generics_and_base_classes.py`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：FIX action silently mutates output - should there be a 'quarantine' tier between LOG and FIX?\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：FIX action silently mutates output - should there be a 'quarantine' tier between LOG and FIX?\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_69600563346341a386aa86c6af5d1274 | https://github.com/guardrails-ai/guardrails/issues/1448 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Portable evidence artifacts for validation outcomes\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Portable evidence artifacts for validation outcomes\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ef2970465bbe44c89b513edd115b682c | https://github.com/guardrails-ai/guardrails/issues/1457 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Proposal: PromptDefenseAudit Hub validator — static system prompt hardening check\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: PromptDefenseAudit Hub validator — static system prompt hardening check\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_d7163e193eb54aab837d87b3ecd73991 | https://github.com/guardrails-ai/guardrails/issues/1453 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：[docs] Fix double logo display in pypi\n\n- Trigger: GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：[docs] Fix double logo display in pypi\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_084985c7cb4d4238a44e452b14b2eaf9 | https://github.com/guardrails-ai/guardrails/issues/1362 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：Integration proposal: Cryptographic audit trail validator with asqav\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Integration proposal: Cryptographic audit trail validator with asqav\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_8db542ceccff4a71bc11c254ce3abfde | https://github.com/guardrails-ai/guardrails/issues/1446 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：Integration proposal: styxx hallucination validator (8-benchmark cross-validated)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Integration proposal: styxx hallucination validator (8-benchmark cross-validated)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_da275c0a112848ed920af00c76fd3e1b | https://github.com/guardrails-ai/guardrails/issues/1463 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：Proposal: Agent Threat Rules detection integration\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: Agent Threat Rules detection integration\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_9d25561995774521a21051373d95b431 | https://github.com/guardrails-ai/guardrails/issues/1471 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：[bug] Guardrails CLI start command broken with guardrails-api 0.4.2\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] Guardrails CLI start command broken with guardrails-api 0.4.2\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_f411132764b84c17b318b5cc7a32ef56 | https://github.com/guardrails-ai/guardrails/issues/1464 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：v0.7.3\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.3\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_95f33a7ff8014d78a13752aa7fd56d6e | https://github.com/guardrails-ai/guardrails/releases/tag/v0.7.3 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：v0.8.2\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.8.2\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_559ad38ac0504cff91377804f004c57c | https://github.com/guardrails-ai/guardrails/releases/tag/v0.8.2 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：guardrails-ai/guardrails\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：chatgpt\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：FIX action silently mutates output - should there be a 'quarantine' tier between LOG and FIX?（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Portable evidence artifacts for validation outcomes（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Proposal: PromptDefenseAudit Hub validator — static system prompt hardening check（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[docs] Fix double logo display in pypi（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Integration proposal: Cryptographic audit trail validator with asqav（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/guardrails-ai/guardrails 项目说明书\n\n生成时间：2026-05-11 13:44:06 UTC\n\n## 目录\n\n- [Guardrails 简介](#page-introduction)\n- [安装与配置](#page-installation)\n- [Guard 类详解](#page-guard-class)\n- [Schema 系统](#page-schema-system)\n- [验证流程与 Runner](#page-validation-flow)\n- [验证器基础](#page-validators)\n- [Guardrails Hub](#page-hub)\n- [CLI 命令行工具](#page-cli)\n- [Guardrails 服务器](#page-server)\n- [框架集成](#page-integrations)\n\n\n\n## Guardrails 简介\n\n### 相关页面\n\n相关主题：[安装与配置](#page-installation), [Guard 类详解](#page-guard-class)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n- [guardrails/guard.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/guard.py)\n- [guardrails/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)\n- [guardrails/cli/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/install.py)\n- [guardrails/cli/hub/create_validator.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/create_validator.py)\n- [guardrails/llm_providers.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/llm_providers.py)\n- [guardrails/classes/history/call.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call.py)\n- [guardrails/classes/history/call_inputs.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call_inputs.py)\n \n\n# Guardrails 简介\n\n## 概述\n\nGuardrails 是一个用于验证和纠正大型语言模型（LLM）输出的 Python 库。它提供了输入/输出验证、格式约束和结构化数据生成等功能，帮助开发者确保 LLM 应用的可靠性和安全性。\n\nGuardrails 的核心设计理念是将验证逻辑与 LLM 调用解耦，使开发者能够以声明式的方式定义输出规范，然后自动验证和纠正 LLM 响应。\n\n资料来源：[README.md:1]()\n\n## 核心概念\n\n### Guard（守卫）\n\n`Guard` 是 Guardrails 框架的核心类，它包装 LLM 调用并自动执行验证和纠正流程。\n\n```python\nfrom guardrails import Guard, OnFailAction\n\nguard = Guard().use(\n RegexMatch, regex=\"\\(?\\d{3}\\)?-? *\\d{3}-? *-?\\d{4}\", on_fail=OnFailAction.EXCEPTION\n)\n\nguard.validate(\"123-456-7890\") # 验证通过\n```\n\n资料来源：[README.md:32](), [guardrails/guard.py:1]()\n\n### Validator（验证器）\n\n验证器是 Guardrails 的核心组件，用于定义具体的验证逻辑。验证器可以通过 Guardrails Hub 安装，也可以自定义创建。\n\n资料来源：[guardrails/cli/hub/create_validator.py:1]()\n\n### OnFailAction（失败动作）\n\n| 动作 | 描述 |\n|------|------|\n| `EXCEPTION` | 抛出异常 |\n| `REASK` | 重新请求 LLM 修正输出 |\n| `FIX` | 自动修复无效输出 |\n| `FILTER` | 过滤无效部分 |\n| `REFRAIN` | 返回空值 |\n\n资料来源：[README.md:35]()\n\n## 系统架构\n\n### 组件架构图\n\n```mermaid\ngraph TD\n A[用户代码] --> B[Guard]\n B --> C[LLM Provider]\n C --> D[LLM 响应]\n D --> E[Validators]\n E -->|通过| F[结构化输出]\n E -->|失败| G[纠正流程]\n G -->|重新请求| C\n G -->|抛出异常| H[Exception]\n \n I[Guardrails Hub] -->|安装验证器| B\n```\n\n### 调用流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant G as Guard\n participant L as LLM\n participant V as Validators\n participant H as History\n \n U->>G: 调用 Guard.__call__\n G->>L: 调用 LLM\n L-->>G: 返回响应\n G->>V: 验证响应\n V-->>G: 验证结果\n alt 验证通过\n G-->>U: 返回验证结果\n G->>H: 记录 Call\n else 验证失败\n G->>G: 重新请求\n G->>L: 重新调用 LLM\n end\n```\n\n## Guard 类 API\n\n### 创建 Guard 的方式\n\n| 方法 | 用途 |\n|------|------|\n| `Guard()` | 创建空 Guard |\n| `Guard.for_rail(rail_string)` | 从 RAIL 字符串创建 |\n| `Guard.for_pydantic(output_class)` | 从 Pydantic 模型创建 |\n\n资料来源：[guardrails/guard.py:1]()\n\n### for_pydantic 方法参数\n\n```python\n@classmethod\ndef for_pydantic(\n cls,\n output_class: ModelOrListOfModels,\n *,\n reask_messages: Optional[List[Dict]] = None,\n messages: Optional[List[Dict]] = None,\n name: Optional[str] = None,\n description: Optional[str] = None,\n output_formatter: Optional[Union[str, BaseFormatter]] = None,\n):\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `output_class` | `ModelOrListOfModels` | Pydantic 模型类 |\n| `reask_messages` | `Optional[List[Dict]]` | 重新请求时的消息 |\n| `messages` | `Optional[List[Dict]]` | 发送给 LLM 的消息 |\n| `name` | `Optional[str]` | Guard 实例名称 |\n| `description` | `Optional[str]` | Guard 实例描述 |\n| `output_formatter` | `Optional[Union[str, BaseFormatter]]` | 输出格式化器 |\n\n资料来源：[guardrails/guard.py:18]()\n\n## LLM 集成\n\nGuardrails 支持多种 LLM 提供商，包括 OpenAI、LiteLLM 和 Manifest。\n\n### LiteLLM 集成示例\n\n```python\nfrom litellm import completion\n\nraw_llm_response, validated_response = guard(\n completion,\n model=\"gpt-3.5-turbo\",\n prompt_params={...},\n temperature=...,\n)\n```\n\n资料来源：[guardrails/llm_providers.py:1]()\n\n### 支持的 LLM 提供商\n\n| 提供商 | 调用类 | 依赖包 |\n|--------|--------|--------|\n| OpenAI | `OpenAIClientCallable` | `openai` |\n| LiteLLM | `LiteLLMCallable` | `litellm` |\n| Manifest | `ManifestCallable` | `manifest-ml` |\n\n## 历史记录系统\n\nGuardrails 内置了调用历史记录功能，每次执行 `Guard.__call__`、`Guard.parse` 或 `Guard.validate` 都会创建一个 `Call` 对象。\n\n### Call 数据结构\n\n```python\nclass Call:\n _id: str | None = None\n iterations: Stack[Iteration] = Field(default_factory=Stack)\n inputs: CallInputs = Field(default_factory=CallInputs)\n exception: Optional[Exception] = None\n```\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `_id` | `str \\| None` | 唯一标识符 |\n| `iterations` | `Stack[Iteration]` | 迭代堆栈 |\n| `inputs` | `CallInputs` | 调用输入参数 |\n| `exception` | `Optional[Exception]` | 执行中的异常 |\n\n### CallInputs 参数\n\n| 字段 | 说明 |\n|------|------|\n| `llm_api` | LLM API 回调函数 |\n| `prompt_params` | 格式化到消息中的参数 |\n| `num_reasks` | 重新请求的最大次数 |\n| `metadata` | 验证器执行时使用的额外数据 |\n| `full_schema_reask` | 是否对整个 schema 执行重新请求 |\n| `stream` | 是否使用流式输出 |\n| `args` | LLM 的额外位置参数 |\n| `kwargs` | LLM 的额外关键字参数 |\n\n资料来源：[guardrails/classes/history/call.py:1](), [guardrails/classes/history/call_inputs.py:1]()\n\n## Guardrails Hub\n\nGuardrails Hub 是验证器的共享平台，开发者可以从中安装预构建的验证器。\n\n### 安装验证器\n\n```bash\npip install guardrails-ai\nguardrails configure\nguardrails hub install hub://guardrails/regex_match\n```\n\n资料来源：[README.md:10]()\n\n### 安装 API\n\n```python\nfrom guardrails.hub.install import install\n\nRegexMatch = install(\"hub://guardrails/regex_match\").RegexMatch\nRegexMatch = install(\"hub://guardrails/regex_match~=1.4\").RegexMatch\n```\n\n### Hub CLI 命令\n\n| 命令 | 说明 |\n|------|------|\n| `guardrails configure` | 配置 Guardrails Hub |\n| `guardrails hub install ` | 安装验证器 |\n| `guardrails hub create-validator ` | 创建验证器模板 |\n\n资料来源：[guardrails/hub/install.py:1](), [guardrails/cli/hub/install.py:1]()\n\n## 创建自定义验证器\n\n### 验证器模板\n\n使用 CLI 创建验证器模板：\n\n```bash\nguardrails hub create-validator MyValidator\n```\n\n这会生成一个模板文件 `my_validator.py`。\n\n资料来源：[guardrails/cli/hub/create_validator.py:1]()\n\n### 验证器基本结构\n\n```python\nclass MyValidator(Validator):\n \"\"\"验证器描述\"\"\"\n \n def __init__(self, ...):\n super().__init__(...)\n \n def validate(self, value, ...):\n # 验证逻辑\n pass\n```\n\n## 安装与配置\n\n### 环境要求\n\n| 要求 | 说明 |\n|------|------|\n| Python | >= 3.8 |\n| pip | 最新版本 |\n| LLM API Key | 对应提供商的密钥 |\n\n### 安装步骤\n\n1. 安装 guardrails-ai 包：\n\n```python\npip install guardrails-ai\n```\n\n2. 配置 Hub CLI：\n\n```bash\nguardrails configure\n```\n\n3. 安装验证器：\n\n```bash\nguardrails hub install hub://guardrails/competitor_check\nguardrails hub install hub://guardrails/toxic_language\n```\n\n资料来源：[README.md:10-20]()\n\n## 使用示例\n\n### 基本验证\n\n```python\nfrom guardrails import Guard, OnFailAction\nfrom guardrails.hub import RegexMatch\n\nguard = Guard().use(\n RegexMatch, regex=\"\\(?\\d{3}\\)?-? *\\d{3}-? *-?\\d{4}\", on_fail=OnFailAction.EXCEPTION\n)\n\nguard.validate(\"123-456-7890\") # 验证通过\n\ntry:\n guard.validate(\"1234-789-0000\") # 验证失败\nexcept Exception as e:\n print(e)\n```\n\n### 多验证器组合\n\n```python\nfrom guardrails import Guard, OnFailAction\nfrom guardrails.hub import CompetitorCheck, ToxicLanguage\n\nguard = Guard().use(\n CompetitorCheck([\"Apple\", \"Microsoft\", \"Google\"], on_fail=OnFailAction.EXCEPTION),\n ToxicLanguage(threshold=0.5, validation_method=\"sentence\", on_fail=OnFailAction.EXCEPTION)\n)\n\nguard.validate(\"An apple a day keeps a doctor away.\") # 两个验证器都通过\n```\n\n### 使用 Pydantic 模型生成结构化数据\n\n```python\nfrom pydantic import BaseModel, Field\nfrom guardrails import Guard\n\nclass Pet(BaseModel):\n pet_type: str = Field(description=\"宠物种类\")\n name: str = Field(description=\"宠物名字\")\n\nguard = Guard.for_pydantic(Pet)\n```\n\n资料来源：[README.md:32-80]()\n\n## 参与贡献\n\n### 开发环境设置\n\n1. 克隆仓库：`git clone https://github.com/guardrails-ai/guardrails.git`\n2. 安装开发依赖：`make dev`\n3. 安装 pre-commit：`pre-commit install`\n\n### 开发工作流\n\n| 步骤 | 命令 | 说明 |\n|------|------|------|\n| 运行测试 | `make test` | 确保所有测试通过 |\n| 代码格式化 | `make autoformat` | 格式化代码 |\n| 类型检查 | `make type` | 运行静态分析 |\n| 更新文档 | `make docs-gen` | 生成文档 |\n\n资料来源：[CONTRIBUTING.md:1]()\n\n## 相关资源\n\n- 官方文档：[Guardrails AI](https://guardrailsai.com/)\n- 验证器市场：[Guardrails Hub](https://guardrailsai.com/hub/)\n- Discord 社区：[加入讨论](https://discord.gg/Jsey3mX98B)\n- GitHub 仓库：[guardrails-ai/guardrails](https://github.com/guardrails-ai/guardrails)\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[Guardrails 简介](#page-introduction), [CLI 命令行工具](#page-cli)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)\n- [guardrails/cli/configure.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/configure.py)\n- [guardrails/cli/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/install.py)\n- [guardrails/cli/start.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/start.py)\n- [Makefile](https://github.com/guardrails-ai/guardrails/blob/main/Makefile)\n \n\n# 安装与配置\n\n## 概述\n\nGuardrails 是一个用于 LLM（大型语言模型）输出验证和结构化数据生成的 Python 库。本页面详细介绍 Guardrails 的安装方法、开发环境配置、CLI 工具设置以及 Hub 验证器的安装流程。\n\nGuardrails 支持两种主要的安装场景：\n\n- **生产环境安装**：仅安装核心库和必要的依赖\n- **开发环境安装**：安装所有开发依赖，支持本地测试、格式化、类型检查等\n\n资料来源：[CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)\n\n---\n\n## 基础安装\n\n### 使用 pip 安装\n\nGuardrails 可以通过 pip 包管理器快速安装：\n\n```bash\npip install guardrails-ai\n```\n\n此命令将安装 Guardrails 的核心功能，包括：\n\n- Guard 类和验证框架\n- 内置验证器支持\n- LLM 提供商集成\n- CLI 工具\n\n资料来源：[README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n\n### Python 版本要求\n\n| 要求 | 说明 |\n|------|------|\n| Python 版本 | 请参考 PyPI 上的版本要求 |\n| 包格式 | 支持 wheel 和 source distribution |\n\n资料来源：[README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n\n---\n\n## 开发环境配置\n\n### 克隆仓库\n\n首先从 GitHub 克隆 Guardrails 仓库：\n\n```bash\ngit clone https://github.com/guardrails-ai/guardrails.git\ncd guardrails\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)\n\n### 安装开发依赖\n\nGuardrails 提供了一个便捷的 `Makefile` 命令来配置完整的开发环境：\n\n```bash\nmake dev\n```\n\n此命令会：\n\n1. 以开发模式（editable mode）安装 guardrails 包\n2. 安装所有开发依赖\n3. 配置 pre-commit 钩子\n\n> **注意**：建议在虚拟环境中执行此操作，以隔离项目依赖。\n\n资料来源：[CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)\n\n### 开发工作流程命令\n\nGuardrails 项目定义了标准化的开发命令：\n\n| 命令 | 功能 |\n|------|------|\n| `make test` | 运行所有测试，确保代码正确性 |\n| `make autoformat` | 自动格式化代码 |\n| `make type` | 运行静态类型检查（pyright） |\n| `make docs-gen` | 生成项目文档 |\n\n```bash\n# 示例：开发过程中的完整流程\nmake test # 确保测试通过\nmake autoformat # 格式化代码\nmake type # 类型检查\nmake docs-gen # 更新文档\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)\n\n---\n\n## CLI 工具配置\n\n### Guardrails CLI 概述\n\nGuardrails 提供了命令行工具来管理验证器、启动服务等。CLI 工具支持多种命令：\n\n```bash\nguardrails configure # 配置 Guardrails\nguardrails hub install # 安装验证器\nguardrails start # 启动 Guardrails API 服务\n```\n\n资料来源：[guardrails/cli/configure.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/configure.py)\n\n### 配置命令\n\nGuardrails CLI 需要首次配置以初始化必要的设置：\n\n```bash\nguardrails configure\n```\n\n此命令会引导用户完成初始配置过程，包括：\n\n- 设置 API 端点（如需要）\n- 配置验证器缓存路径\n- 设置日志级别\n\n资料来源：[README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n\n### API 服务启动\n\nGuardrails 提供了一个可选的 API 服务，可通过 CLI 启动：\n\n```bash\nguardrails start [OPTIONS]\n```\n\n**可用选项：**\n\n| 参数 | 说明 |\n|------|------|\n| `--env` | 环境变量配置文件路径 |\n| `--config` | 服务配置文件路径 |\n| `--port` | 服务监听端口 |\n| `--env-override` | 运行时环境变量覆盖 |\n\n启动服务前会检查必要的依赖：\n\n```python\n# 伪代码：启动前检查\nif not api_is_installed():\n installer_process(\"install\", \"guardrails-api>=0.2.1\")\n```\n\n资料来源：[guardrails/cli/start.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/start.py)\n\n---\n\n## Pre-commit 钩子配置\n\n### 安装 Pre-commit\n\n安装项目提供的 pre-commit 钩子：\n\n```bash\npre-commit install\n```\n\n此步骤在执行 `make dev` 时会自动完成，但也可以手动单独执行。\n\n资料来源：[CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)\n\n### Pre-commit 钩子功能\n\nPre-commit 钩子会在每次提交前自动运行：\n\n- 代码格式检查\n- 语法验证\n- 基础测试\n\n> **好处**：减少代码审查中的格式问题，加快开发流程。\n\n资料来源：[CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)\n\n---\n\n## Hub 验证器安装\n\n### Hub CLI 安装流程\n\nGuardrails Hub 提供了丰富的预构建验证器。安装流程如下：\n\n1. **安装验证器包**\n\n```bash\nguardrails hub install hub://guardrails/regex_match\n```\n\n2. **在代码中使用**\n\n```python\nfrom guardrails import Guard, OnFailAction\nfrom guardrails.hub import RegexMatch\n\nguard = Guard().use(\n RegexMatch, \n regex=r\"\\(?\\d{3}\\)?-? *\\d{3}-? *-?\\d{4}\", \n on_fail=OnFailAction.EXCEPTION\n)\n\nguard.validate(\"123-456-7890\") # 通过验证\n```\n\n资料来源：[README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n\n### 安装多个验证器\n\n可以同时安装多个验证器：\n\n```bash\nguardrails hub install hub://guardrails/competitor_check\nguardrails hub install hub://guardrails/toxic_language\n```\n\n### 本地模型安装\n\n某些验证器支持本地推理。安装时可选择是否下载本地模型：\n\n```python\n# CLI 参数\nguardrails hub install hub://guardrails/ --local-models\n```\n\n验证器安装服务会：\n\n1. 验证包 URI 和版本\n2. 获取模块清单\n3. 下载依赖项\n4. 执行 pip 安装\n\n```python\n# 安装服务流程伪代码\ndef install_multiple(package_uris, install_local_models, quiet, upgrade):\n for package_uri in package_uris:\n validator_id, validator_version = ValidatorPackageService.get_validator_id(package_uri)\n module_manifest = ValidatorPackageService.get_manifest_and_site_packages(validator_id)\n ValidatorPackageService.install_hub_module(validator_id, validator_version=validator_version)\n```\n\n资料来源：[guardrails/cli/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/install.py)\n\n---\n\n## 项目结构概览\n\n```mermaid\ngraph TD\n A[guardrails-ai/guardrails] --> B[核心库]\n A --> C[CLI 工具]\n A --> D[Hub 验证器]\n A --> E[开发工具]\n \n B --> B1[guard.py - Guard 类]\n B --> B2[schema/ - 输出模式]\n B --> B3[validators/ - 验证器]\n \n C --> C1[configure.py - 配置命令]\n C --> C2[hub/install.py - Hub 安装]\n C --> C3[start.py - 服务启动]\n \n D --> D1[manifest.json - 验证器清单]\n D --> D2[本地/远程模型]\n \n E --> E1[Makefile - 开发命令]\n E --> E2[pre-commit - 钩子]\n```\n\n---\n\n## 常见问题排查\n\n| 问题 | 解决方案 |\n|------|----------|\n| `manifest` 包未安装 | 运行 `pip install manifest-ml` |\n| API 服务启动失败 | 确认 `guardrails-api>=0.2.1` 已安装 |\n| Hub 安装静默失败 | 使用 `--verbose` 参数查看详细日志 |\n| 类型检查失败 | 运行 `make autoformat` 后再执行 `make type` |\n\n---\n\n## 进阶配置\n\n### 环境变量配置\n\nGuardrails 支持通过环境变量进行高级配置：\n\n| 变量 | 说明 |\n|------|------|\n| `OPENAI_API_KEY` | OpenAI API 密钥 |\n| 自定义端点 | 通过 `--env` 参数指定 |\n\n资料来源：[guardrails/cli/start.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/start.py)\n\n### 自定义验证器开发\n\nGuardrails 支持开发自定义验证器：\n\n```bash\nguardrails create-validator \n```\n\n这会生成验证器模板文件，包含：\n\n- 验证逻辑框架\n- 单元测试模板\n- 文档注释结构\n\n资料来源：[guardrails/cli/hub/create_validator.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/create_validator.py)\n\n---\n\n## 总结\n\nGuardrails 提供了灵活的安装和配置选项，适应不同的使用场景：\n\n- **快速上手**：使用 `pip install guardrails-ai` 即可开始\n- **完整开发环境**：通过 `make dev` 配置一切\n- **生产部署**：使用 CLI 配置和 Hub 验证器管理\n\n建议按照本文档的步骤顺序进行配置，以确保所有依赖和工具链正确设置。\n\n---\n\n\n\n## Guard 类详解\n\n### 相关页面\n\n相关主题：[验证流程与 Runner](#page-validation-flow), [Schema 系统](#page-schema-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [guardrails/guard.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/guard.py)\n- [guardrails/classes/history/call.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call.py)\n- [guardrails/llm_providers.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/llm_providers.py)\n- [guardrails/api_client.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/api_client.py)\n- [guardrails/call_tracing/trace_handler.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/call_tracing/trace_handler.py)\n- [guardrails/schema/rail_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/rail_schema.py)\n \n\n# Guard 类详解\n\n## 概述\n\nGuard 是 Guardrails AI 框架的核心类，负责验证和约束大语言模型（LLM）的输入和输出。它提供了一个统一的接口，用于定义验证规则、调用 LLM、以及对输出进行结构化验证。\n\nGuard 类的设计目标包括：\n\n- **输出验证**：确保 LLM 生成的输出符合预定义的模式和约束\n- **结构化生成**：支持从 Pydantic 模型生成结构化数据\n- **多步骤验证**：支持重试机制（reask）和多次验证迭代\n- **历史追踪**：完整记录每次调用的输入、输出和验证结果\n\n资料来源：[guardrails/guard.py:1-100]()\n\n## 核心架构\n\n### 类层次结构\n\n```mermaid\ngraph TD\n A[Guard] --> B[for_rail]\n A --> C[for_pydantic]\n A --> D[__call__]\n A --> E[validate]\n A --> F[parse]\n \n G[PromptCallableBase] --> H[LiteLLMCallable]\n G --> I[ManifestCallable]\n \n J[Call] --> K[iterations]\n J --> L[inputs]\n J --> M[exception]\n \n K --> N[Iteration]\n N --> O[Stack]\n```\n\n### 执行流程\n\n```mermaid\nsequenceDiagram\n participant 用户\n participant Guard\n participant LLM\n participant Validator\n participant TraceHandler\n \n 用户->>Guard: __call__(prompt, model)\n Guard->>LLM: 调用模型生成响应\n LLM-->>Guard: 原始输出\n Guard->>Validator: 验证输出\n alt 验证失败 & 需要重试\n Guard->>Guard: 执行 reask\n Guard->>LLM: 重新调用\n end\n Guard->>TraceHandler: 记录调用历史\n Guard-->>用户: 返回验证后的结果\n```\n\n## Guard 类的创建方式\n\n### 从 RAIL 规范创建\n\nRAIL（Regression AI Language）是一种 XML 格式的规范，用于定义输出验证规则。\n\n```python\nguard = Guard.from_rail_string(rail_string)\n```\n\n资料来源：[guardrails/guard.py:100-120]()\n\n### 从 Pydantic 模型创建\n\n这是最常用的方式，直接使用 Pydantic BaseModel 定义输出结构：\n\n```python\nfrom pydantic import BaseModel, Field\nfrom guardrails import Guard\n\nclass Pet(BaseModel):\n pet_type: str = Field(description=\"宠物种类\")\n name: str = Field(description=\"宠物名称\")\n\nguard = Guard.for_pydantic(Pet)\n```\n\n资料来源：[guardrails/guard.py:150-180]()\n\n### for_pydantic 方法签名\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| output_class | ModelOrListOfModels | 是 | Pydantic 模型类或列表 |\n| reask_messages | Optional[List[Dict]] | 否 | 重试时的消息模板 |\n| messages | Optional[List[Dict]] | 否 | 发送给 LLM 的消息 |\n| name | Optional[str] | 否 | Guard 实例名称 |\n| description | Optional[str] | 否 | Guard 实例描述 |\n| output_formatter | Optional[Union[str, BaseFormatter]] | 否 | 输出格式化器 |\n\n## 验证机制\n\n### 验证流程\n\n```mermaid\ngraph TD\n A[接收 LLM 输出] --> B[解析输出]\n B --> C{是否需要结构化?}\n C -->|是| D[JSON 解析]\n C -->|否| E[保持原样]\n D --> F[应用验证器链]\n F --> G{所有验证器通过?}\n G -->|是| H[返回验证结果]\n G -->|否| I{on_fail 配置}\n I -->|EXCEPTION| J[抛出异常]\n I -->|FIX| K[尝试修复]\n I -->|REASK| L[重新请求 LLM]\n I -->|FILTER| M[过滤无效部分]\n I -->|CUSTOM| N[执行自定义处理]\n```\n\n### OnFailAction 枚举\n\n| 动作 | 说明 | 使用场景 |\n|------|------|----------|\n| EXCEPTION | 验证失败时抛出异常 | 需要严格验证的场景 |\n| FIX | 尝试自动修复输出 | 允许自动修正的场景 |\n| REASK | 重新请求 LLM 生成 | 需要模型重新生成 |\n| FILTER | 过滤掉无效部分 | 保留部分有效输出 |\n| CUSTOM | 执行自定义回调 | 自定义错误处理 |\n\n## 调用历史系统\n\n### Call 数据结构\n\n每次调用 Guard 时，系统会创建一个 Call 对象记录完整的执行历史。\n\n```mermaid\nclassDiagram\n class Call {\n +str id\n +Stack~Iteration~ iterations\n +CallInputs inputs\n +Optional~Exception~ exception\n +get_id() str\n }\n \n class Iteration {\n +Step[] steps\n +CallMetadata metadata\n }\n \n class CallInputs {\n +str prompt\n +str model\n +Dict kwargs\n }\n \n Call \"1\" *-- \"*\" Iteration : contains\n Iteration \"1\" *-- \"*\" Step : contains\n```\n\n资料来源：[guardrails/classes/history/call.py:1-80]()\n\n### Call 类的属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| _id | str \\| None | 唯一标识符 |\n| iterations | Stack[Iteration] | 迭代栈，包含每次重试的迭代 |\n| inputs | CallInputs | 调用输入参数 |\n| exception | Optional[Exception] | 执行过程中的异常 |\n\n资料来源：[guardrails/classes/history/call.py:20-50]()\n\n## LLM 集成\n\n### 支持的 LLM 提供者\n\nGuard 类支持与多种 LLM 提供者集成：\n\n```python\n# OpenAI\nfrom guardrails import Guard\nguard = Guard.for_pydantic(Pet)\nresult = guard(\n client=openai.ChatCompletion,\n prompt=\"生成一只宠物的信息\",\n model=\"gpt-4\"\n)\n\n# LiteLLM\nguard = Guard.for_pydantic(Pet)\nresult = guard(\n client=\"openai/gpt-3.5-turbo\",\n prompt=\"生成一只宠物的信息\"\n)\n\n# Manifest\nguard = Guard.for_pydantic(Pet)\nresult = guard(\n client=manifest_client,\n prompt=\"生成一只宠物的信息\"\n)\n```\n\n资料来源：[guardrails/llm_providers.py:1-100]()\n\n### PromptCallableBase 基类\n\n```mermaid\nclassDiagram\n class PromptCallableBase {\n +_invoke_llm() LLMResponse\n +_validate() ValidationResponse\n }\n \n class LiteLLMCallable {\n +_invoke_llm() LLMResponse\n }\n \n class ManifestCallable {\n +_invoke_llm() LLMResponse\n }\n \n PromptCallableBase <|-- LiteLLMCallable\n PromptCallableBase <|-- ManifestCallable\n```\n\n## API 客户端集成\n\nGuard 类可以与 Guardrails API 服务集成，实现远程存储和管理：\n\n```python\nfrom guardrails import Guard\nfrom guardrails.api_client import GuardrailsClient\n\nclient = GuardrailsClient(base_url=\"https://api.guardrails.ai\")\n\n# 上传 Guard 配置\nclient.upsert_guard(guard)\n\n# 获取已存储的 Guard\nremote_guard = client.fetch_guard(\"my-guard-name\")\n```\n\n### API 客户端方法\n\n| 方法 | 说明 | 异步版本 |\n|------|------|----------|\n| upsert_guard | 创建或更新 Guard | aupsert_guard |\n| fetch_guard | 获取指定名称的 Guard | afetch_guard |\n| list_guards | 列出所有 Guard | alist_guards |\n\n资料来源：[guardrails/api_client.py:1-150]()\n\n## 调用追踪系统\n\n### TraceHandler\n\nTraceHandler 是一个线程安全的追踪系统，用于记录 Guard 的调用历史：\n\n```python\nfrom guardrails.call_tracing.trace_handler import TraceHandler\n\n# 写入日志\nwriter = TraceHandler()\nwriter.log(\n \"my_guard\", # guard 名称\n 0.0, # 开始时间\n 1.0, # 结束时间\n \"原始输出\", # LLM 原始输出\n \"处理后输出\", # 验证后输出\n \"异常信息\" # 异常（如有）\n)\n\n# 读取日志\nreader = TraceHandler.get_reader()\nfor trace in reader.tail_logs():\n print(trace)\n```\n\n资料来源：[guardrails/call_tracing/trace_handler.py:1-80]()\n\n### 日志存储\n\n默认情况下，日志存储在临时目录中：\n\n```bash\n${TMPDIR}/guardrails_calls.db\n```\n\n可通过环境变量覆盖：\n\n```bash\nexport GUARDRAILS_LOG_FILE_PATH=\"/path/to/logs.db\"\n```\n\n## 使用示例\n\n### 基础验证示例\n\n```python\nfrom guardrails import Guard, OnFailAction\nfrom guardrails.hub import RegexMatch\n\n# 创建带验证规则的 Guard\nguard = Guard().use(\n RegexMatch,\n regex=r\"\\(?\\d{3}\\)?-? *\\d{3}-? *-?\\d{4}\",\n on_fail=OnFailAction.EXCEPTION\n)\n\n# 验证通过\nresult = guard.validate(\"123-456-7890\")\nprint(result) # Validation passed\n\n# 验证失败\ntry:\n guard.validate(\"1234-789-0000\")\nexcept Exception as e:\n print(e) # Result must match \\(?\\d{3}\\)?-? *\\d{3}-? *-?\\d{4}\n```\n\n### 结构化输出示例\n\n```python\nfrom pydantic import BaseModel, Field\nfrom guardrails import Guard\n\nclass Pet(BaseModel):\n pet_type: str = Field(description=\"宠物种类\")\n name: str = Field(description=\"宠物名称\")\n\nguard = Guard.for_pydantic(Pet)\n\n# 调用 LLM 并获取结构化输出\nresult = guard(\n client=openai.ChatCompletion,\n prompt=\"给我推荐一只宠物\",\n model=\"gpt-4\"\n)\n\nprint(result.validated_output)\n# 输出: Pet(pet_type=\"dog\", name=\"Max\")\n```\n\n### 多验证器组合示例\n\n```python\nfrom guardrails import Guard, OnFailAction\nfrom guardrails.hub import CompetitorCheck, ToxicLanguage\n\nguard = Guard().use(\n CompetitorCheck(\n competitors=[\"Apple\", \"Microsoft\", \"Google\"],\n on_fail=OnFailAction.EXCEPTION\n ),\n ToxicLanguage(\n threshold=0.5,\n validation_method=\"sentence\",\n on_fail=OnFailAction.EXCEPTION\n )\n)\n\n# 验证通过的场景\nguard.validate(\"An apple a day keeps a doctor away.\")\n\n# 验证失败的场景\ntry:\n guard.validate(\"Shut the hell up! Apple just released a new iPhone.\")\nexcept Exception as e:\n print(e)\n```\n\n## 最佳实践\n\n### 1. 合理的重试配置\n\n```python\n# 设置合理的重试次数和消息\nguard = Guard.for_pydantic(\n Pet,\n reask_messages=[\n {\"role\": \"user\", \"content\": \"请重新生成，必须包含 pet_type 和 name 字段\"}\n ]\n)\n```\n\n### 2. 使用适当的 on_fail 策略\n\n| 场景 | 推荐策略 |\n|------|----------|\n| 严格数据验证 | EXCEPTION |\n| 允许自动修正 | FIX |\n| 非关键字段 | FILTER |\n| 自定义处理 | CUSTOM |\n\n### 3. 调用历史记录\n\n```python\n# 获取最近一次调用的历史\ncall = guard.history[-1]\nprint(f\"调用 ID: {call.id}\")\nprint(f\"迭代次数: {len(call.iterations)}\")\nfor iteration in call.iterations:\n print(f\" - 步骤数: {len(iteration.steps)}\")\n```\n\n## 总结\n\nGuard 类是 Guardrails AI 框架的核心组件，它：\n\n- 提供了统一的接口来验证 LLM 输出\n- 支持多种创建方式（RAIL、Pydantic、自定义验证器）\n- 内置完整的调用历史追踪系统\n- 支持与多种 LLM 提供者无缝集成\n- 提供了灵活的错误处理机制\n\n通过合理使用 Guard 类，开发者可以确保 LLM 应用的输出质量和可靠性。\n\n---\n\n\n\n## Schema 系统\n\n### 相关页面\n\n相关主题：[Guard 类详解](#page-guard-class), [验证器基础](#page-validators)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [guardrails/schema/pydantic_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/pydantic_schema.py)\n- [guardrails/schema/rail_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/rail_schema.py)\n- [guardrails/schema/parser.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/parser.py)\n- [guardrails/schema/primitive_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/primitive_schema.py)\n- [guardrails/schema/validator.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/validator.py)\n- [guardrails/classes/schema/processed_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/schema/processed_schema.py)\n \n\n# Schema 系统\n\n## 概述\n\nSchema 系统是 Guardrails 框架的核心组件之一，负责定义和管理 LLM 输出的验证规范。该系统提供了从多种模式定义（RAIL、Pydantic、JSON Schema）到内部验证结构的转换能力，确保 LLM 生成的内容符合预定义的结构和约束条件。\n\nSchema 系统的主要职责包括：\n\n- **模式解析**：将用户定义的 RAIL 字符串、Pydantic 模型或 JSON Schema 解析为内部表示\n- **类型映射**：支持字符串、日期、时间、日期时间、百分比、枚举等多种数据类型的映射\n- **验证器集成**：将验证器（Validator）绑定到特定的 Schema 字段\n- **输出规范生成**：将 JSON Schema 反向转换为 RAIL 输出规范\n\n资料来源：[guardrails/schema/rail_schema.py:1-50]()\n\n## 架构设计\n\n### 核心组件\n\n```mermaid\ngraph TD\n A[用户定义 Schema] --> B{输入格式}\n B --> C[RAIL 字符串]\n B --> D[Pydantic 模型]\n B --> E[JSON Schema]\n \n C --> F[rail_schema.py]\n D --> G[pydantic_schema.py]\n E --> H[primitive_schema.py]\n \n F --> I[Schema Parser]\n G --> I\n H --> I\n \n I --> J[ProcessedSchema]\n J --> K[Guard 验证器]\n```\n\n### 目录结构\n\n```\nguardrails/schema/\n├── __init__.py # 模块初始化\n├── pydantic_schema.py # Pydantic 模型转换\n├── parser.py # 核心解析器\n├── primitive_schema.py # 基础类型处理\n├── rail_schema.py # RAIL 格式转换\n├── validator.py # 验证器绑定\n└── processed_schema.py # 处理后的模式类\n```\n\n## 核心模块详解\n\n### RailSchema 模块\n\n`rail_schema.py` 负责 RAIL（Rail Action Markup Language）格式与内部 Schema 之间的转换。\n\n#### 主要功能\n\n| 函数 | 功能描述 |\n|------|----------|\n| `build_element()` | 递归构建 XML 元素树 |\n| `build_string_element()` | 构建字符串类型元素 |\n| `json_schema_to_rail_output()` | JSON Schema 转 RAIL 输出规范 |\n\n#### 支持的数据类型\n\n| RailTypes | 说明 | 格式属性 |\n|-----------|------|----------|\n| `STRING` | 字符串类型 | 无 |\n| `DATE` | 日期类型 | `date-format` |\n| `TIME` | 时间类型 | `time-format` |\n| `DATETIME` | 日期时间类型 | `datetime-format` |\n| `PERCENTAGE` | 百分比类型 | 无 |\n| `ENUM` | 枚举类型 | `values` 属性 |\n| `FLOAT` | 浮点数 | 无 |\n| `INTEGER` | 整数 | 无 |\n| `BOOL` | 布尔值 | 无 |\n\n资料来源：[guardrails/schema/rail_schema.py:50-120]()\n\n#### 类型映射逻辑\n\n```python\ndef build_string_element(...):\n if format.internal_type == RailTypes.DATE:\n type = RailTypes.DATE\n date_format = format.internal_format_attr\n if date_format:\n attributes[\"date-format\"] = date_format\n elif format.internal_type == RailTypes.TIME:\n type = RailTypes.TIME\n # ...\n```\n\n资料来源：[guardrails/schema/rail_schema.py:80-95]()\n\n### JSON Schema 转换流程\n\n```mermaid\ngraph LR\n A[JSON Schema] --> B[jsonref.replace_refs]\n B --> C[解引用后的 Schema]\n C --> D[build_element]\n D --> E[XML Element 树]\n E --> F[canonicalize]\n F --> G[RAIL 输出字符串]\n```\n\n关键转换函数：\n\n```python\ndef json_schema_to_rail_output(\n json_schema: Dict[str, Any], \n validator_map: ValidatorMap\n) -> str:\n dereferenced_json_schema = jsonref.replace_refs(json_schema)\n output_element = build_element(\n dereferenced_json_schema,\n validator_map,\n json_path=\"$\",\n elem=Element,\n tag_override=\"output\",\n )\n return canonicalize(ET.tostring(output_element, pretty_print=True))\n```\n\n资料来源：[guardrails/schema/rail_schema.py:35-45]()\n\n### Pydantic Schema 模块\n\n`pydantic_schema.py` 提供了将 Pydantic `BaseModel` 转换为 Guardrails Schema 的能力。\n\n#### 创建 Guard 实例\n\n```python\nfrom guardrails import Guard\nfrom pydantic import BaseModel, Field\n\nclass Pet(BaseModel):\n pet_type: str = Field(description=\"Species of pet\")\n name: str = Field(description=\"a unique pet name\")\n\n# 从 Pydantic 模型创建 Guard\nguard = Guard.for_pydantic(Pet)\n```\n\n资料来源：[guardrails/guard.py:100-120]()\n\n### ProcessedSchema 类\n\n`processed_schema.py` 定义了处理后的 Schema 数据结构，包含以下关键属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `_id` | `str \\| None` | 唯一标识符 |\n| `iterations` | `Stack[Iteration]` | 执行迭代栈 |\n| `inputs` | `CallInputs` | 调用输入参数 |\n| `exception` | `Exception \\| None` | 异常信息 |\n\n```python\nclass Call:\n \"\"\"表示 Guard 的单次执行\"\"\"\n \n _id: str | None = None\n iterations: Stack[Iteration] = Field(\n description=\"迭代栈\",\n default_factory=Stack,\n )\n inputs: CallInputs = Field(\n description=\"调用输入\",\n default_factory=CallInputs,\n )\n exception: Optional[Exception] = Field(\n description=\"异常\",\n default=None,\n )\n```\n\n资料来源：[guardrails/classes/schema/processed_schema.py:20-45]()\n\n### Validator 模式绑定\n\n`validator.py` 负责将验证器与 Schema 字段进行绑定，支持以下配置选项：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `on_fail` | `OnFailAction` | 验证失败时的动作 |\n| `args` | `List[Any]` | 验证器位置参数 |\n| `kwargs` | `Dict[str, Any]` | 验证器关键字参数 |\n\n## Guard 与 Schema 的集成\n\n### 从 RAIL 创建 Guard\n\n```python\nfrom guardrails import Guard\n\nrail_string = \"\"\"\n\n \n\n\"\"\"\n\nguard = Guard.from_rail_string(rail_string)\n```\n\n内部调用流程：\n\n```mermaid\ngraph TD\n A[rail_string] --> B[rail_string_to_schema]\n B --> C[Schema 对象]\n C --> D[Guard._for_rail_schema]\n D --> E[Guard 实例]\n```\n\n资料来源：[guardrails/guard.py:80-100]()\n\n### 从 Pydantic 创建 Guard\n\n```python\nfrom guardrails import Guard\nfrom pydantic import BaseModel\n\nclass OutputModel(BaseModel):\n name: str\n age: int\n\nguard = Guard.for_pydantic(OutputModel)\n```\n\n支持的方法签名：\n\n| 方法 | 参数 | 返回类型 |\n|------|------|----------|\n| `for_rail` | `rail_string: str` | `Guard` |\n| `for_pydantic` | `output_class: ModelOrListOfModels` | `Guard` |\n\n资料来源：[guardrails/guard.py:100-140]()\n\n## 调用输入管理\n\n### CallInputs 数据结构\n\n`call_inputs.py` 定义了 LLM 调用时的输入参数：\n\n```python\nclass CallInputs(BaseModel):\n llm_api: Optional[Callable[[Any], Awaitable[Any]]] = None\n prompt: Optional[str] = Field(default=None, alias=\"prompt\")\n prompt_params: Optional[Dict[str, Any]] = Field(\n default=None,\n description=\"Parameters to be formatted into the messages.\",\n alias=\"promptParams\",\n )\n num_reasks: Optional[int] = Field(\n default=None,\n description=\"The total number of times the LLM can be called\",\n alias=\"numReasks\",\n )\n metadata: Optional[Dict[str, Any]] = Field(\n default=None,\n description=\"Additional data to be used by Validators\",\n )\n stream: Optional[bool] = Field(\n default=None, description=\"Whether to use streaming.\"\n )\n```\n\n| 字段 | 默认值 | 说明 |\n|------|--------|------|\n| `llm_api` | `None` | LLM API 回调函数 |\n| `prompt` | `None` | 提示词模板 |\n| `prompt_params` | `None` | 格式化参数 |\n| `num_reasks` | `None` | 最大重新请求次数 |\n| `metadata` | `None` | 元数据字典 |\n| `full_schema_reask` | `None` | 是否全量重新请求 |\n| `stream` | `None` | 是否启用流式输出 |\n\n资料来源：[guardrails/classes/history/call_inputs.py:20-50]()\n\n## Schema 处理流程\n\n### 完整验证流程\n\n```mermaid\ngraph TD\n A[输入数据] --> B[Guard.__call__]\n B --> C[Call 创建]\n C --> D[Schema 解析]\n D --> E[LLM 调用]\n E --> F[输出验证]\n \n F --> G{验证通过?}\n G -->|是| H[返回结果]\n G -->|否| I{num_reasks > 0?}\n \n I -->|是| J[num_reasks - 1]\n J --> E\n I -->|否| K[抛出异常]\n \n H --> L[Iteration 记录]\n K --> L\n```\n\n### 迭代追踪\n\n每次调用 `Guard.__call__`、`Guard.parse` 或 `Guard.validate` 都会创建一个 `Call` 实例，其中包含：\n\n- **初始验证轮次**：`Iteration` 栈\n- **重请求轮次**：每次重新请求都会产生新的 `Iteration`\n\n```python\n@computed_field\n@property\ndef id(self) -> str:\n \"\"\"唯一标识符，用于标识 Guard 的特定执行\"\"\"\n if not self._id:\n self._id = str(object_id(self))\n return self._id\n```\n\n资料来源：[guardrails/classes/history/call.py:30-45]()\n\n## 类型系统\n\n### 简单类型枚举\n\n| 类型名 | Python 类型 | 说明 |\n|--------|-------------|------|\n| `STRING` | `str` | 字符串 |\n| `INTEGER` | `int` | 整数 |\n| `FLOAT` | `float` | 浮点数 |\n| `BOOLEAN` | `bool` | 布尔值 |\n| `ARRAY` | `list` | 数组 |\n| `OBJECT` | `dict` | 对象 |\n| `NULL` | `None` | 空值 |\n\n### 特殊格式类型\n\n```python\n# 日期时间格式支持\nDATETIME: str # 支持 datetime-format 属性\nDATE: str # 支持 date-format 属性\nTIME: str # 支持 time-format 属性\nPERCENTAGE: str # 百分比字符串\nENUM: str # 枚举值列表\n```\n\n资料来源：[guardrails/schema/rail_schema.py:100-140]()\n\n## 配置与扩展\n\n### 自定义 Schema 处理器\n\n开发者可以通过继承基础类来扩展 Schema 功能：\n\n```python\nfrom guardrails.schema import BaseSchema\n\nclass CustomSchema(BaseSchema):\n def validate(self, value):\n # 自定义验证逻辑\n pass\n```\n\n### 验证器注册\n\n验证器通过 `ValidatorMap` 注册到 Schema 系统：\n\n```python\nvalidator_map: ValidatorMap # 全局验证器映射表\n```\n\n## 最佳实践\n\n1. **使用 Pydantic 模型定义复杂结构**：更声明式，类型安全\n2. **明确指定日期/时间格式**：避免歧义\n3. **合理设置 num_reasks**：平衡验证严格性和用户体验\n4. **利用 metadata 传递上下文**：验证器可访问运行时信息\n\n## 总结\n\nSchema 系统是 Guardrails 框架的基础架构层，提供了从多种模式定义格式到统一验证结构的转换能力。通过模块化的设计，支持 RAIL、Pydantic、JSON Schema 等多种输入方式，并提供灵活的验证器集成机制。该系统与 Guard 类紧密协作，实现了 LLM 输出的结构化和可验证性。\n\n---\n\n\n\n## 验证流程与 Runner\n\n### 相关页面\n\n相关主题：[Guard 类详解](#page-guard-class), [验证器基础](#page-validators)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [guardrails/run/runner.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/run/runner.py)\n- [guardrails/run/async_runner.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/run/async_runner.py)\n- [guardrails/run/stream_runner.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/run/stream_runner.py)\n- [guardrails/run/utils.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/run/utils.py)\n- [guardrails/classes/history/call.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call.py)\n- [guardrails/classes/history/iteration.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/iteration.py)\n \n\n# 验证流程与 Runner\n\n## 概述\n\nGuardrails 的验证流程是整个框架的核心执行机制，负责协调 LLM 响应与验证器之间的交互。当用户调用 `Guard.__call__`、`Guard.parse` 或 `Guard.validate` 方法时，框架会通过 Runner 组件来执行验证逻辑。\n\nRunner 系统采用模块化设计，支持同步、异步和流式三种执行模式。这种设计允许 Guardrails 适应不同的应用场景，从简单的批量验证到实时流式响应处理。\n\n## 核心架构组件\n\n### Call（调用）对象\n\n`Call` 类是 Guard 执行过程的顶层记录容器。每次调用 `Guard.__call__`、`Guard.parse` 或 `Guard.validate` 时，都会创建一个新的 `Call` 实例。\n\n```python\nclass Call:\n \"\"\"A Call represents a single execution of a Guard.\"\"\"\n \n _id: str | None = None\n iterations: Stack[Iteration] = Field(\n description=\"A stack of iterations for each step/reask that occurred.\",\n default_factory=Stack,\n )\n inputs: CallInputs = Field(\n description=\"The inputs as passed in to Guard.__call__ or Guard.parse\",\n default_factory=CallInputs,\n )\n exception: Optional[Exception] = Field(\n description=\"The exception that interrupted the run.\",\n default=None,\n )\n```\n\n`Call` 对象的核心属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `_id` | `str \\| None` | Call 的唯一标识符 |\n| `iterations` | `Stack[Iteration]` | 执行过程中的迭代栈 |\n| `inputs` | `CallInputs` | 传递给 Guard 的输入参数 |\n| `exception` | `Optional[Exception]` | 执行过程中捕获的异常 |\n\n`Call.id` 是一个计算属性，通过 `object_id(self)` 生成唯一标识符，可用于追踪特定的 Guard 执行：\n\n```python\n@computed_field\n@property\ndef id(self) -> str:\n \"\"\"The unique identifier for this Call.\"\"\"\n if not self._id:\n self._id = str(object_id(self))\n return self._id\n```\n\n资料来源：[guardrails/classes/history/call.py:16-45]()\n\n### Iteration（迭代）对象\n\n`Iteration` 代表验证过程中的单个迭代步骤。每次重新请求（reask）或验证循环都会创建一个新的 `Iteration` 实例，并压入 `Call.iterations` 栈中。\n\n迭代过程包含以下关键阶段：\n\n1. **初始验证轮次**：首次对 LLM 输出进行验证\n2. **Reask 阶段**：如果验证失败，触发重新请求机制\n3. **多轮迭代**：持续验证直到通过或达到最大重试次数\n\n资料来源：[guardrails/classes/history/iteration.py]()\n\n## Runner 执行模式\n\nGuardrails 提供了三种 Runner 实现，分别适用于不同的使用场景：\n\n### 同步 Runner\n\n`Runner` 是标准的同步执行器，适用于批量处理和非实时应用场景。它按顺序执行验证步骤，阻塞当前线程直到完成。\n\n```python\n# 典型使用方式\nfrom guardrails import Guard\n\nguard = Guard.from_pydantic(Pet)\nresult = guard(\n client,\n prompt_params={...}\n)\n```\n\n### 异步 Runner\n\n`AsyncRunner` 支持异步执行，利用 Python 的 `asyncio` 实现并发处理。这对于需要同时处理多个验证请求的高吞吐量应用至关重要。\n\n```python\n# 典型使用方式\nfrom guardrails import Guard\n\nguard = Guard.from_pydantic(Pet)\nresult = await guard.ainvoke(\n client,\n prompt_params={...}\n)\n```\n\n异步 Runner 保持了与同步 Runner 相同的验证逻辑，但通过 `async/await` 模式提升了资源利用率。\n\n### 流式 Runner\n\n`StreamRunner` 专门为流式 LLM 响应设计。当 LLM 支持流式输出时，Runner 可以边接收响应边进行验证，提供更好的实时性和更低的内存占用。\n\n```python\n# 典型使用方式\nfor token in guard.stream(\n client,\n prompt_params={...}\n):\n print(token, end=\"\", flush=True)\n```\n\n## 验证流程图\n\n```mermaid\ngraph TD\n A[Guard.__call__ / validate] --> B[创建 Call 实例]\n B --> C[创建 Iteration 栈]\n C --> D[调用 LLM]\n D --> E{解析 LLM 响应}\n E -->|成功解析| F{运行验证器}\n E -->|解析失败| G[触发 Reask]\n F -->|验证通过| H[返回验证结果]\n F -->|验证失败| G\n G -->|达到最大重试| I[抛出异常]\n G -->|未达最大重试| D\n H --> J[保存到 History]\n I --> J\n```\n\n## 验证执行流程详解\n\n### 第一阶段：输入处理\n\n在调用 Runner 之前，Guard 会准备以下输入数据：\n\n- **Prompt 模板**：包含 `${gr.complete_json_suffix_v2}` 等占位符的提示词\n- **Prompt 参数**：`prompt_params` 字典，用于填充模板变量\n- **LLM 客户端**：支持多种 LLM 提供商（OpenAI、Anthropic、LiteLLM 等）\n\n### 第二阶段：LLM 调用\n\nRunner 负责与 LLM 交互，获取原始响应。根据配置的调用方式，可能是：\n\n- **Function Calling**：使用 LLM 的函数调用能力获取结构化输出\n- **Prompt Optimization**：通过优化提示词引导 LLM 生成符合 schema 的 JSON\n\n### 第三阶段：验证循环\n\n验证循环是 Runner 的核心逻辑：\n\n```mermaid\ngraph LR\n A[获取 LLM 响应] --> B[解析响应]\n B --> C{解析成功?}\n C -->|否| D[记录异常]\n C -->|是| E[运行验证器]\n E --> F{所有验证通过?}\n F -->|是| G[返回结果]\n F -->|否| H[执行 Fix/Reask]\n H --> I{达到最大重试?}\n I -->|是| J[抛出异常]\n I -->|否| A\n```\n\n### 第四阶段：History 记录\n\n每个执行步骤都会记录到 History 中：\n\n- `Call.inputs`：保存原始输入\n- `Call.iterations`：保存每次迭代的详细记录\n- `Call.exception`：如果执行中断，保存异常信息\n\n```python\n@field_serializer(\"iterations\")\ndef serialize_iterations(\n self, iterations: Stack[Iteration] | None\n) -> list[dict[str, Any]] | None:\n if iterations is not None:\n return [\n # 序列化的迭代数据\n ]\n```\n\n## Runner 工具函数\n\n`guardrails/run/utils.py` 提供了 Runner 所需的核心工具函数：\n\n| 函数 | 功能 |\n|------|------|\n| `get_llm_response_text` | 从 LLM 响应中提取文本内容 |\n| `process_parsed_rail` | 处理解析后的 RAIL 规范 |\n| `validate_parsed_rail` | 验证 RAIL 规范的正确性 |\n| `extract_config_from_rail` | 从 RAIL 提取配置信息 |\n\n这些工具函数支持 Runner 在不同执行阶段进行数据转换和验证。\n\n## 执行状态管理\n\nRunner 通过 `TracerMixin` 提供执行追踪能力：\n\n```python\nclass TraceHandler(TracerMixin):\n \"\"\"TraceHandler wraps the internal _SQLiteTraceHandler to make it multi-\n thread safe.\"\"\"\n```\n\n追踪系统使用 SQLite 数据库记录每次执行的详细信息：\n\n- **日志文件位置**：可通过 `GUARDRAILS_LOG_FILE_PATH` 环境变量配置\n- **默认位置**：`tempfile.gettempdir() + \"/guardrails_calls.db\"`\n- **多线程安全**：通过单例模式和写前日志机制实现\n\n```python\nLOG_FILENAME = \"guardrails_calls.db\"\nLOGFILE_PATH = os.environ.get(\n \"GUARDRAILS_LOG_FILE_PATH\",\n os.path.join(tempfile.gettempdir(), LOG_FILENAME),\n)\n```\n\n## 与 LLM 提供商的集成\n\nRunner 通过 `llm_providers.py` 中的适配器类与不同 LLM 提供商集成：\n\n- **ManifestCallable**：支持使用 Manifest 库的 LLM\n- **LiteLLMCallable**：支持 LiteLLM 封装的多种 LLM\n- **PromptCallableBase**：所有提供商的基类\n\n```python\nclass LiteLLMCallable(PromptCallableBase):\n def _invoke_llm(\n self,\n text: Optional[str] = None,\n model: str = \"gpt-3.5-turbo\",\n messages: Optional[List[Dict]] = None,\n *args,\n **kwargs,\n ) -> LLMResponse:\n \"\"\"Wrapper for Lite LLM completions.\"\"\"\n```\n\n## 错误处理机制\n\n验证流程中的错误处理采用分层策略：\n\n1. **解析错误**：LLM 响应无法解析为预期格式\n2. **验证错误**：LLM 响应通过解析但不满足验证器条件\n3. **执行异常**：Runner 级别的异常（如 API 超时、网络错误）\n\n```python\ntry:\n guard.validate(\"1234-789-0000\") # 验证失败\nexcept Exception as e:\n print(e) # 输出: Validation failed for field with errors: Result must match...\n```\n\n## 配置选项\n\n创建 Guard 时可以通过多种方式配置验证流程：\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `output_class` | Pydantic 模型定义输出结构 | 必填 |\n| `messages` | LLM 消息列表 | None |\n| `reask_messages` | Reask 阶段使用的消息 | None |\n| `name` | Guard 实例名称 | `gr-` + 对象ID |\n| `output_formatter` | 输出格式化器 | None |\n\n## 总结\n\nRunner 系统是 Guardrails 验证流程的核心执行引擎，通过模块化的设计支持同步、异步和流式三种执行模式。`Call` 和 `Iteration` 类提供了完整的执行历史追踪能力，使调试和监控变得简单直观。理解 Runner 的工作原理对于深入掌握 Guardrails 框架、进行性能优化和故障排查至关重要。\n\n---\n\n\n\n## 验证器基础\n\n### 相关页面\n\n相关主题：[Guardrails Hub](#page-hub), [Schema 系统](#page-schema-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [guardrails/validator_base.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/validator_base.py)\n- [guardrails/classes/validation/validation_result.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/validation/validation_result.py)\n- [guardrails/classes/validation/validator_logs.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/validation/validator_logs.py)\n- [guardrails/actions/filter.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/actions/filter.py)\n- [guardrails/actions/refrain.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/actions/refrain.py)\n- [guardrails/actions/reask.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/actions/reask.py)\n- [guardrails/types/on_fail.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/types/on_fail.py)\n \n\n# 验证器基础\n\n## 概述\n\n验证器（Validator）是 Guardrails 框架的核心组件，用于对 LLM（大型语言模型）生成的输出进行质量检查和验证。验证器充当输出与预期规范之间的桥梁，确保 LLM 响应符合预定义的数据结构、格式要求和内容约束。\n\n### 核心职责\n\n- **格式验证**：检查输出是否符合指定的数据格式（如正则表达式、JSON Schema）\n- **内容验证**：检测敏感内容、不当语言或竞争对手提及\n- **结构验证**：确保输出符合 Pydantic 模型或 RAIL 规范定义的结构\n- **修复建议**：在验证失败时提供修正值或重新请求 LLM 生成\n\n### 验证器在 Guard 架构中的位置\n\n```mermaid\ngraph TD\n A[用户输入/提示词] --> B[Guard 实例]\n B --> C[验证器注册表 ValidatorMap]\n C --> D[验证器链 Validator Chain]\n D --> E{验证结果}\n E -->|通过| F[ValidationOutcome 有效输出]\n E -->|失败| G[OnFailAction 处理]\n G -->|REASK| H[重新请求 LLM]\n G -->|FILTER| I[过滤敏感内容]\n G -->|REFRAIN| J[返回空/默认值]\n G -->|EXCEPTION| K[抛出验证异常]\n H --> D\n```\n\n## 验证结果模型\n\n### ValidationOutcome\n\n`ValidationOutcome` 是验证过程的返回结果，封装了验证的完整状态信息。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `validated_output` | `OT` | 验证后的输出值 |\n| `reask_messages` | `List[Dict]` | 用于重新请求的消息列表 |\n| `error` | `Exception` | 验证过程中发生的错误（如果有） |\n| `validation_passed` | `bool` | 验证是否通过 |\n| `structure_generated` | `bool` | 是否生成了结构化输出 |\n\n资料来源：[guardrails/guard.py:420-450]()\n\n### 验证日志 ValidatorLogs\n\n每个验证步骤都会生成详细的日志记录，用于追踪和调试。\n\n| 属性 | 说明 |\n|------|------|\n| `validator_name` | 验证器的名称 |\n| `validator_value` | 当前验证的值 |\n| `validation_result` | 验证结果对象 |\n| `start_time` | 验证开始时间戳 |\n| `end_time` | 验证结束时间戳 |\n| `error` | 验证错误信息 |\n\n资料来源：[guardrails/classes/validation/validator_logs.py]()\n\n## 失败处理策略\n\n### OnFailAction 枚举\n\n当验证失败时，系统根据配置的 `OnFailAction` 决定如何处理。\n\n| 动作 | 说明 | 使用场景 |\n|------|------|----------|\n| `REASK` | 重新向 LLM 请求修正的输出 | 自动修正格式错误 |\n| `FILTER` | 过滤或替换敏感内容 | 内容安全检查 |\n| `REFRAIN` | 返回空值或默认值 | 避免生成不当内容 |\n| `EXCEPTION` | 抛出验证异常 | 严格模式下的错误处理 |\n| `FIX` | 使用预定义的修复值 | 已知错误模式的批量修正 |\n\n资料来源：[guardrails/types/on_fail.py]()\n\n### 各动作的处理流程\n\n#### 过滤动作 (Filter)\n\n过滤动作用于处理需要移除或替换的敏感内容：\n\n```python\n# 伪代码示例\nif validation_result.failed:\n if on_fail == OnFailAction.FILTER:\n return filtered_value\n```\n\n#### 克制动作 (Refrain)\n\n克制动作在检测到违规内容时返回空值或中性替代：\n\n```python\n# 克制动作返回空输出\nif validation_result.failed and on_fail == OnFailAction.REFRAIN:\n return None\n```\n\n资料来源：[guardrails/actions/filter.py]()\n资料来源：[guardrails/actions/refrain.py]()\n\n#### 重新请求动作 (Reask)\n\n重新请求是最常用的自动修正机制，会收集所有验证失败项并生成新的提示词：\n\n```mermaid\ngraph LR\n A[初始验证失败] --> B[gather_reasks 收集 ReAsk]\n B --> C[构建 reask_messages]\n C --> D[调用 LLM 重新生成]\n D --> E[再次验证]\n E -->|通过| F[返回修正结果]\n E -->|失败| G{达到最大次数?}\n G -->|否| C\n G -->|是| H[返回最终结果/错误]\n```\n\n资料来源：[guardrails/actions/reask.py]()\n\n## ReAsk 系统\n\n### ReAsk 数据结构\n\n当验证失败需要重新请求时，系统使用 `ReAsk` 对象记录失败信息：\n\n| 属性 | 说明 |\n|------|------|\n| `path` | 失败字段的 JSON 路径 |\n| `original_value` | 原始失败值 |\n| ` fail_results` | 失败验证结果列表 |\n| `expected_format` | 期望的格式描述 |\n\n### 递归收集机制\n\n`gather_reasks` 函数递归遍历验证输出，收集所有需要重新请求的字段：\n\n```python\ndef gather_reasks(validated_output):\n if isinstance(validated_output, ReAsk):\n return [validated_output], None\n if isinstance(validated_output, str):\n return [], validated_output\n # 递归处理字典和列表类型\n```\n\n资料来源：[guardrails/actions/reask.py:50-80]()\n\n## 验证器基类\n\n### Validator 抽象基类\n\n所有自定义验证器都继承自 `Validator` 基类，实现以下核心方法：\n\n| 方法 | 说明 |\n|------|------|\n| `validate(value, ...)` | 执行验证逻辑 |\n| `fix(...)` | 提供修复建议 |\n| `get_azure_function(...)` | Azure Functions 集成 |\n\n### 验证器调用追踪\n\n框架集成了 OpenTelemetry 追踪系统，记录每次验证的执行情况：\n\n```python\n# 验证器执行时会创建 span\nvalidator_span = tracer.start_span(f\"validator/{validator_name}\")\n# 记录输入值、初始化参数、执行结果\nadd_validator_attributes(\n validator_name=validator_name,\n result=resp,\n init_kwargs=init_kwargs,\n validation_session_id=validation_session_id,\n)\n```\n\n资料来源：[guardrails/telemetry/validator_tracing.py]()\n\n## 验证器在 Guard 中的使用\n\n### 注册验证器\n\n通过 `Guard.use()` 方法注册验证器：\n\n```python\nfrom guardrails import Guard, OnFailAction\nfrom guardrails.hub import RegexMatch, CompetitorCheck\n\nguard = Guard().use(\n RegexMatch(regex=r\"\\d{4}\", on_fail=OnFailAction.EXCEPTION),\n CompetitorCheck([\"Apple\", \"Google\"], on_fail=OnFailAction.FILTER)\n)\n```\n\n### 获取已注册的验证器\n\n```python\n# 获取 output 级别所有验证器\noutput_validators = guard.get_validators(on=\"output\")\n\n# 获取特定字段的验证器\nfield_validators = guard.get_validators(on=\"$.pet_type\")\n```\n\n### 验证流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant G as Guard\n participant V as ValidatorMap\n participant Val as Validator\n participant LLM as LLM API\n\n U->>G: guard.validate(llm_output)\n G->>V: 获取相关验证器\n V-->>G: 验证器列表\n loop 遍历每个验证器\n G->>Val: validate(value)\n Val-->>G: ValidationResult\n end\n G->>G: 处理失败结果\n alt 验证通过\n G-->>U: ValidationOutcome.validated_output\n else 验证失败\n G->>G: 根据 OnFailAction 处理\n alt REASK\n G->>LLM: 发送 reask_messages\n LLM-->>G: 修正后的输出\n G->>G: 递归验证\n else EXCEPTION\n G-->>U: 抛出 ValidationException\n end\n end\n```\n\n## 调用历史记录\n\n### Call 数据结构\n\n每次调用 Guard 都会生成 `Call` 对象，记录完整的执行历史：\n\n| 属性 | 说明 |\n|------|------|\n| `id` | 唯一标识符 |\n| `iterations` | 执行迭代栈（初始验证 + 每次 reask） |\n| `inputs` | 输入参数（prompt、llm_api 等） |\n| `exception` | 中断执行的异常（如果有） |\n\n### Iteration 数据结构\n\n单个迭代包含：\n\n- `validator_logs`：本次迭代中所有验证器的执行日志\n- `llm_response`：LLM 的原始响应\n- `parsed_output`：解析后的输出\n- `validation_response`：验证结果\n\n资料来源：[guardrails/classes/history/call.py]()\n\n## 验证器开发模板\n\n### 创建新验证器\n\n使用 CLI 命令创建验证器模板：\n\n```bash\nguardrails hub create-validator MyValidator ./my_validator.py\n```\n\n生成的模板包含：\n\n```python\nfrom guardrails import Validator\nfrom guardrails.validators import ValidationResult\n\nclass MyValidator(Validator):\n \"\"\"验证器描述\"\"\"\n \n def __init__(self, arg_1: str, on_fail: str = None):\n super().__init__(on_fail=on_fail)\n self.arg_1 = arg_1\n \n def validate(self, value, **kwargs) -> ValidationResult:\n # 验证逻辑\n if not self._is_valid(value):\n return ValidationResult(\n outcome=\"fail\",\n error_message=\"验证失败的原因\"\n )\n return ValidationResult(outcome=\"pass\")\n```\n\n资料来源：[guardrails/cli/hub/create_validator.py]()\n\n## 最佳实践\n\n### 1. 验证器组合策略\n\n| 场景 | 推荐验证器组合 |\n|------|----------------|\n| 数据提取 | `RegexMatch` + `ValidRange` |\n| 内容安全 | `CompetitorCheck` + `ToxicLanguage` |\n| 结构化输出 | Pydantic 模型 + 自定义字段验证器 |\n\n### 2. OnFailAction 选择指南\n\n- **严格模式**：使用 `EXCEPTION` 确保不返回无效数据\n- **容错模式**：使用 `REASK` 自动修正轻微格式错误\n- **安全模式**：使用 `FILTER` 或 `REFRAIN` 处理敏感内容\n\n### 3. 性能注意事项\n\n- 避免在验证器中执行阻塞 I/O 操作\n- 使用 `skip_reask_when_valid` 参数避免不必要的重新请求\n- 对于复杂验证逻辑，考虑异步实现\n\n## 相关资源\n\n- [Guardrails Hub](https://guardrailsai.com/hub/) - 官方验证器市场\n- [验证器模板仓库](https://github.com/guardrails-ai/validator-template) - 复杂验证器开发指南\n- [API 参考文档](https://docs.guardrailsai.com/) - 完整的 API 说明\n\n---\n\n\n\n## Guardrails Hub\n\n### 相关页面\n\n相关主题：[验证器基础](#page-validators), [CLI 命令行工具](#page-cli)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [guardrails/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)\n- [guardrails/cli/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/install.py)\n- [guardrails/cli/hub/create_validator.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/create_validator.py)\n- [README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)\n \n\n# Guardrails Hub\n\n## 概述\n\nGuardrails Hub 是 Guardrails 项目的验证器分发与共享平台，为用户提供了一个集中式的验证器市场，类似于 Python 生态中的 PyPI。Hub 的核心功能是允许用户从中央仓库安装、社区贡献者提交新的验证器，以及管理本地已安装的验证器模块。\n\n通过 Guardrails Hub，用户可以快速获取预构建的验证器（如正则匹配、竞争对手检查、有害内容检测等），无需从头编写验证逻辑。Hub 采用语义化版本控制，支持灵活的版本约束，确保项目的依赖稳定性。\n\n**核心特点：**\n\n- **即装即用**：通过 CLI 一键安装验证器\n- **版本管理**：支持语义化版本约束（如 `~=1.4`、`>=1.4,==1.*`）\n- **模块导出**：统一的导入接口 `from guardrails.hub import {ValidatorName}`\n- **本地模型支持**：部分验证器支持本地模型推理\n\n资料来源：[README.md:1-20](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n\n## 架构设计\n\n### 系统组件\n\nGuardrails Hub 由以下核心组件构成：\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| Hub CLI | `guardrails/cli/hub/` | 提供 hub 命令行接口（install、list、submit、uninstall、create-validator） |\n| 安装服务 | `guardrails/hub/install.py` | 处理验证器包的下载、安装、依赖解析 |\n| 包服务 | `validator_package_service.py` | 管理验证器清单、版本解析、包安装 |\n| 注册表 | `guardrails/hub/registry.py` | 维护已安装验证器的元数据注册 |\n\n### 安装流程\n\n```mermaid\ngraph TD\n A[用户执行 guardrails hub install] --> B[验证包 URI 和版本]\n B --> C{本地模型是否必需}\n C -->|是| D[确认安装本地模型]\n C -->|否| E[跳过]\n D --> F[获取 Manifest 清单]\n F --> G[下载依赖]\n G --> H[执行 Pip 安装]\n H --> I[加载模块]\n I --> J[返回已安装的验证器模块]\n```\n\n资料来源：[guardrails/hub/install.py:50-90](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)\n\n## URI 规范与版本控制\n\n### Hub URI 格式\n\nGuardrails Hub 使用统一的 URI 格式来标识验证器资源：\n\n```\nhub://guardrails/{validator_name}[~={version}]\n```\n\n**格式说明：**\n\n| 组成部分 | 说明 | 示例 |\n|----------|------|------|\n| `hub://` | 协议前缀，标识来自 Hub | - |\n| `guardrails` | 命名空间，通常为官方或用户名 | `guardrails` |\n| `validator_name` | 验证器名称（snake_case） | `regex_match` |\n| `~={version}` | 版本约束（可选） | `~=1.4`、`>=1.4,==1.*` |\n\n资料来源：[guardrails/hub/install.py:30-40](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)\n\n### 版本约束示例\n\n```python\n# 安装特定版本\ninstall(\"hub://guardrails/regex_match~=1.4\")\n\n# 安装兼容版本\ninstall(\"hub://guardrails/regex_match>=1.4,==1.*\")\n\n# 安装最新版本\ninstall(\"hub://guardrails/regex_match\")\n```\n\n资料来源：[guardrails/hub/install.py:25-35](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)\n\n## CLI 命令参考\n\nGuardrails Hub 通过 `guardrails hub` 子命令提供操作接口。\n\n### 安装验证器\n\n```bash\nguardrails hub install hub://guardrails/regex_match\nguardrails hub install hub://guardrails/competitor_check\n```\n\n**参数选项：**\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `package_uris` | List[str] | 必需 | 要安装的包 URI 列表 |\n| `--local-models` / `--local` | bool | False | 安装本地模型用于离线推理 |\n| `--quiet` / `-q` | bool | False | 静默模式，减少输出 |\n| `--upgrade` | bool | False | 升级到最新版本 |\n\n**本地模型安装确认：**\n\n当验证器需要本地模型时，系统会提示用户确认：\n\n```\nThis validator has a Guardrails AI inference endpoint available. \nWould you still like to install the local models for local inference?\n```\n\n资料来源：[guardrails/cli/hub/install.py:20-50](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/install.py)\n\n### 创建验证器模板\n\n```bash\nguardrails hub create-validator MyValidator\nguardrails hub create-validator CustomCheck --filepath ./validators/my_check.py\n```\n\n此命令生成验证器模板文件，包含基础结构和必要的方法占位符：\n\n```python\nclass MyValidator(Validator):\n \"\"\"FIXME: A brief description of what your validator does.\"\"\"\n \n def __init__(self, arg_1: str, ...):\n # FIXME: Replace with your custom init args\n pass\n \n def validate(self, value, ...):\n # FIXME: Implement validation logic\n pass\n```\n\n资料来源：[guardrails/cli/hub/create_validator.py:20-60](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/create_validator.py)\n\n### 其他 CLI 命令\n\n| 命令 | 说明 |\n|------|------|\n| `guardrails hub list` | 列出已安装的验证器 |\n| `guardrails hub submit` | 提交验证器到 Hub |\n| `guardrails hub uninstall` | 卸载已安装的验证器 |\n\n## 验证器使用方式\n\n### 基础导入与使用\n\n安装完成后，通过以下方式导入和使用验证器：\n\n```python\nfrom guardrails import Guard, OnFailAction\nfrom guardrails.hub import RegexMatch\n\n# 创建 Guard 实例\nguard = Guard().use(\n RegexMatch, \n regex=r\"\\(?\\d{3}\\)?-? *\\d{3}-? *-?\\d{4}\", \n on_fail=OnFailAction.EXCEPTION\n)\n\n# 验证通过\nguard.validate(\"123-456-7890\")\n\n# 验证失败（抛出异常）\ntry:\n guard.validate(\"1234-789-0000\")\nexcept Exception as e:\n print(e)\n```\n\n资料来源：[README.md:30-55](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n\n### 多个验证器组合\n\n可以链式使用多个验证器：\n\n```python\nfrom guardrails import Guard, OnFailAction\nfrom guardrails.hub import CompetitorCheck, ToxicLanguage\n\nguard = Guard().use(\n CompetitorCheck(\n [\"Apple\", \"Microsoft\", \"Google\"], \n on_fail=OnFailAction.EXCEPTION\n ),\n ToxicLanguage(\n threshold=0.5, \n validation_method=\"sentence\", \n on_fail=OnFailAction.EXCEPTION\n )\n)\n\n# 验证通过的场景\nguard.validate(\"An apple a day keeps a doctor away. This is good advice.\")\n```\n\n资料来源：[README.md:55-80](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n\n## 开发与贡献\n\n### 创建新验证器\n\n对于简单验证器，可使用 CLI 工具生成模板：\n\n```bash\nguardrails hub create-validator MyValidator\n```\n\n对于复杂验证器，建议使用官方模板仓库：\n\n> https://github.com/guardrails-ai/validator-template\n\n资料来源：[guardrails/cli/hub/create_validator.py:30-35](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/create_validator.py)\n\n### 提交到 Hub\n\n贡献者可以通过 `guardrails hub submit` 命令将自己开发的验证器提交到 Hub 进行审核。提交前请确保：\n\n1. 验证器包含完整的文档字符串\n2. 实现必要的 `__init__` 和 `validate` 方法\n3. 提供使用示例\n4. 所有测试通过\n\n资料来源：[CONTRIBUTING.md:1-30](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)\n\n### 开发环境设置\n\n```bash\n# 克隆仓库\ngit clone https://github.com/guardrails-ai/guardrails.git\ncd guardrails\n\n# 安装开发依赖\nmake dev\n\n# 安装 pre-commit 钩子\npre-commit install\n\n# 运行测试\nmake test\n\n# 代码格式化\nmake autoformat\n\n# 类型检查\nmake type\n```\n\n## 验证器清单示例\n\n| 验证器名称 | 功能描述 | 必需参数 |\n|-----------|----------|----------|\n| `RegexMatch` | 正则表达式匹配验证 | `regex` |\n| `CompetitorCheck` | 竞争对手名称检测 | `competitors: List[str]` |\n| `ToxicLanguage` | 有害内容检测 | `threshold`, `validation_method` |\n| `Summarizer` | 摘要生成（需本地模型） | - |\n| `Chatbot` | 对话机器人（需本地模型） | - |\n\n## 常见问题\n\n**Q: 安装失败怎么办？**\n\n检查网络连接和 pip 权限，确保已正确配置 PyPI 镜像源。\n\n**Q: 如何指定验证器版本？**\n\n在 URI 中添加版本约束：`hub://guardrails/regex_match~=1.4`\n\n**Q: 验证器需要本地模型时如何处理？**\n\n使用 `--local-models` 参数安装本地模型，或使用云端推理端点（默认行为）。\n\n---\n\n\n\n## CLI 命令行工具\n\n### 相关页面\n\n相关主题：[安装与配置](#page-installation), [Guardrails Hub](#page-hub), [Guardrails 服务器](#page-server)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [guardrails/cli/guardrails.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/guardrails.py)\n- [guardrails/cli/create.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/create.py)\n- [guardrails/cli/validate.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/validate.py)\n- [guardrails/cli/db/db.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/db/db.py)\n- [guardrails/cli/db/upgrade.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/db/upgrade.py)\n- [guardrails/cli/db/downgrade.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/db/downgrade.py)\n- [guardrails/cli/hub/__init__.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/__init__.py)\n \n\n# CLI 命令行工具\n\n## 概述\n\nGuardrails CLI 是 Guardrails 框架提供的命令行界面工具，为开发者提供了一系列便捷的终端操作命令。通过 CLI，用户可以快速创建验证器、管理 Hub 模块、执行数据验证、配置本地环境以及启动 API 服务。CLI 工具采用模块化架构设计，将不同功能封装为独立的子命令模块，包括 Guard 管理、RAIL 文件创建、数据验证、数据库迁移以及 Hub 模块安装等核心功能。\n\nCLI 基于 Typer 框架构建，充分利用了 Python 类型提示和命令补全功能，为用户提供流畅的命令行体验。所有的 CLI 命令都集成了日志系统，支持不同级别的日志输出，便于调试和监控操作状态。\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[\"guardrails CLI 入口\"] --> B[\"Typer 应用主框架\"]\n B --> C[\"guardrails 子命令\"]\n B --> D[\"hub 子命令\"]\n B --> E[\"create 子命令\"]\n B --> F[\"validate 子命令\"]\n B --> G[\"db 子命令\"]\n B --> H[\"start 子命令\"]\n \n C --> C1[\"Guard 状态管理\"]\n C --> C2[\"配置管理\"]\n \n D --> D1[\"install 安装命令\"]\n D --> D2[\"create-validator 创建验证器\"]\n D --> D3[\"search 搜索命令\"]\n \n E --> E1[\"RAIL 文件生成\"]\n E --> E2[\"Schema 模板\"]\n \n F --> F1[\"JSON 验证\"]\n F --> F2[\"输出校验\"]\n \n G --> G1[\"upgrade 升级\"]\n G --> G2[\"downgrade 降级\"]\n G --> G3[\"迁移管理\"]\n \n H --> H1[\"API 服务启动\"]\n H --> H2[\"环境配置\"]\n```\n\n### 目录结构\n\n```\nguardrails/cli/\n├── __init__.py # CLI 入口点\n├── guardrails.py # Guard 状态管理命令\n├── create.py # RAIL 文件创建命令\n├── validate.py # 数据验证命令\n├── hub/ # Hub 模块管理\n│ ├── __init__.py # Hub CLI 主模块\n│ ├── install.py # 安装验证器\n│ ├── create_validator.py # 创建验证器模板\n│ └── search.py # 搜索验证器\n├── db/ # 数据库迁移\n│ ├── db.py # 数据库配置\n│ ├── upgrade.py # 升级命令\n│ └── downgrade.py # 降级命令\n├── start.py # API 服务启动\n└── logger.py # 日志配置\n```\n\n## 核心模块详解\n\n### Hub 模块\n\nHub 模块是 Guardrails CLI 的核心组成部分，负责管理验证器模块的安装、创建和搜索功能。通过 Hub，用户可以访问 Guardrails 官方验证器库，并将其安装到本地环境中使用。\n\n#### 安装验证器\n\n`hub install` 命令用于从 Guardrails Hub 安装验证器模块。该命令支持多种安装方式，包括从官方 Hub 安装特定验证器以及从 git 仓库安装自定义模块。\n\n```mermaid\ngraph LR\n A[\"输入包URI\"] --> B[\"验证器ID解析\"]\n B --> C[\"获取模块清单\"]\n C --> D{\"是否安装本地模型\"}\n D -->|是| E[\"确认安装\"]\n D -->|否| F[\"跳过本地模型\"]\n E --> G[\"下载依赖\"]\n F --> G\n G --> H[\"pip 安装\"]\n H --> I[\"安装完成\"]\n```\n\n**主要参数：**\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `package_uris` | 列表/字符串 | 要安装的包URI列表 | 必需 |\n| `-l, --local-models` | 布尔值 | 是否安装本地模型 | False |\n| `-q, --quiet` | 布尔值 | 静默模式减少输出 | False |\n| `--upgrade` | 布尔值 | 升级到最新版本 | False |\n\n安装示例：\n\n```bash\n# 安装单个验证器\nguardrails hub install hub://guardrails/regex_match\n\n# 安装指定版本\nguardrails hub install hub://guardrails/regex_match~=1.4\n\n# 安装多个验证器\nguardrails hub install hub://guardrails/competitor_check hub://guardrails/toxic_language\n```\n\n资料来源：[guardrails/cli/hub/install.py:1-50]()\n\n#### 创建验证器\n\n`hub create-validator` 命令用于快速创建验证器模板文件。该命令会根据提供的名称自动生成符合 Guardrails 规范的验证器代码框架。\n\n```mermaid\ngraph TD\n A[\"输入验证器名称\"] --> B[\"名称格式转换\"]\n B --> C[\"snake_case 命名\"]\n B --> D[\"PascalCase 命名\"]\n C --> E[\"生成文件路径\"]\n D --> F[\"应用 Jinja2 模板\"]\n F --> G[\"写入 Python 文件\"]\n G --> H[\"创建完成\"]\n```\n\n**模板包含内容：**\n\n- 验证器类框架（继承自 `Validator` 基类）\n- 初始化参数定义区域\n- `validate` 方法骨架代码\n- 示例测试用例（docstring 中）\n- 文档注释模板\n\n```bash\n# 创建名为 MyValidator 的验证器\nguardrails hub create-validator MyValidator\n\n# 指定输出路径\nguardrails hub create-validator MyValidator --filepath ./custom/path/my_validator.py\n```\n\n资料来源：[guardrails/cli/hub/create_validator.py:1-80]()\n\n### 数据库迁移模块\n\n数据库迁移模块负责管理 Guardrails 内部数据库的版本控制，支持升级和降级操作。该模块使用 Alembic 作为迁移引擎，确保数据库结构的平滑演进。\n\n#### 数据库配置\n\n`db` 命令组提供数据库相关的管理功能，包括迁移状态查看和版本控制操作。\n\n资料来源：[guardrails/cli/db/db.py:1-30]()\n\n#### 升级操作\n\n`db upgrade` 命令将数据库迁移到指定版本或最新版本。迁移过程中会按顺序执行所有未应用的迁移文件。\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `revision` | 字符串 | 目标版本标识 | head（最新） |\n| `--sql` | 布尔值 | 仅生成 SQL 不执行 | False |\n| `-x, --xarg` | 字符串 | 扩展参数传递 | None |\n\n```bash\n# 升级到最新版本\nguardrails db upgrade head\n\n# 升级到指定版本\nguardrails db upgrade abc123\n\n# 查看生成的 SQL 而不执行\nguardrails db upgrade head --sql\n```\n\n资料来源：[guardrails/cli/db/upgrade.py:1-40]()\n\n#### 降级操作\n\n`db downgrade` 命令用于将数据库回滚到之前的版本。降级操作会按相反顺序撤销迁移。\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `revision` | 字符串 | 目标版本标识 | -1（上一个版本） |\n| `--sql` | 布尔值 | 仅生成 SQL 不执行 | False |\n| `-x, --xarg` | 字符串 | 扩展参数传递 | None |\n\n```bash\n# 降级一个版本\nguardrails db downgrade -1\n\n# 降级到初始状态\nguardrails db downgrade base\n\n# 查看生成的 SQL 而不执行\nguardrails db downgrade -1 --sql\n```\n\n资料来源：[guardrails/cli/db/downgrade.py:1-35]()\n\n### 创建模块\n\n`create` 命令用于从 Pydantic 模型或 JSON Schema 生成 RAIL 文件。RAIL（Reliable AI Application Language）是一种基于 XML 的规范语言，用于定义 LLM 输出的结构和验证规则。\n\n#### 输入格式支持\n\n| 输入类型 | 说明 | 支持参数 |\n|----------|------|----------|\n| Pydantic 模型 | Python 类继承 BaseModel | `output_class` |\n| JSON Schema | 标准 JSON Schema 格式 | `json_schema` |\n| Python 类 | 带有 Field 定义的类 | 自动推断 |\n\n```python\n# 从 Pydantic 模型创建 RAIL\nfrom guardrails.cli import create\n\nrail_xml = create.from_pydantic(MyModel)\nprint(rail_xml)\n```\n\n#### Schema 转换\n\ncreate 模块内部集成了 Schema 转换功能，能够将 JSON Schema 映射为 RAIL 格式的元素结构。转换过程支持以下类型映射：\n\n| JSON Schema 类型 | RAIL 元素 | 支持格式 |\n|------------------|-----------|----------|\n| string | string | date, time, datetime, percentage, enum |\n| number | float | - |\n| integer | integer | - |\n| boolean | bool | - |\n| array | list | - |\n| object | object | - |\n\n资料来源：[guardrails/schema/rail_schema.py:1-100]()\n\n### 验证模块\n\n`validate` 命令提供独立的验证功能，允许用户直接对输入数据进行验证而不需要通过 Python 代码调用 Guard 对象。\n\n```bash\n# 验证字符串是否符合正则表达式\nguardrails validate --validator regex_match --regex \"\\d{4}-\\d{2}-\\d{2}\" \"2024-01-15\"\n\n# 验证 JSON 格式\nguardrails validate --schema-path ./schema.json --input ./data.json\n```\n\n资料来源：[guardrails/cli/validate.py:1-50]()\n\n### 服务启动模块\n\n`start` 命令用于启动 Guardrails API 服务。该模块封装了 API 服务器的启动逻辑，提供端口配置、环境变量覆盖和热重载等功能。\n\n```mermaid\ngraph TD\n A[\"start 命令执行\"] --> B{\"检查 API 包安装\"}\n B -->|未安装| C[\"自动安装 guardrails-api\"]\n B -->|已安装| D[\"检查版本兼容性\"]\n C --> D\n D --> E[\"加载环境配置\"]\n E --> F{\"watch 模式\"}\n F -->|启用| G[\"开启热重载\"]\n F -->|禁用| H[\"标准启动\"]\n G --> I[\"启动 API 服务\"]\n H --> I\n```\n\n**主要参数：**\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `--port` | 整数 | 服务监听端口 | 8000 |\n| `--config` | 路径 | 配置文件路径 | None |\n| `--env` | 路径 | 环境变量文件 | None |\n| `--env-override` | 字典 | 环境变量覆盖 | None |\n| `--watch` | 布尔值 | 启用热重载 | False |\n\n```bash\n# 基础启动\nguardrails start\n\n# 指定端口\nguardrails start --port 9000\n\n# 加载环境配置\nguardrails start --env .env.production\n\n# 启用热重载开发模式\nguardrails start --watch\n```\n\n资料来源：[guardrails/cli/start.py:1-80]()\n\n## 日志系统\n\nGuardrails CLI 集成了统一的日志系统，支持多级别日志输出和彩色终端显示。\n\n```python\n# 可用的日志级别\nLEVELS = {\n \"SPAM\": 5, # 详细调试信息\n \"VERBOSE\": 15, # 详细操作信息\n \"NOTICE\": 25, # 重要提示\n \"SUCCESS\": 35, # 成功操作\n}\n```\n\n日志输出示例：\n\n```bash\n# 详细输出模式\nguardrails hub install hub://guardrails/regex_match --verbose\n\n# 静默模式\nguardrails hub install hub://guardrails/regex_match --quiet\n```\n\n资料来源：[guardrails/cli/logger.py:1-20]()\n\n## 使用流程示例\n\n### 完整工作流程\n\n```mermaid\ngraph LR\n A[\"安装 guardrails-ai\"] --> B[\"配置 CLI\"]\n B --> C[\"安装验证器\"]\n C --> D[\"创建/编写验证器\"]\n D --> E[\"创建 RAIL 文件\"]\n E --> F[\"编写 Python 代码\"]\n F --> G[\"运行验证\"]\n G --> H{\"验证结果\"}\n H -->|通过| I[\"流程结束\"]\n H -->|失败| J[\"重新调整输入\"]\n J --> G\n```\n\n### 典型使用场景\n\n#### 场景一：快速验证数据格式\n\n```bash\n# 1. 配置 CLI\nguardrails configure\n\n# 2. 安装验证器\nguardrails hub install hub://guardrails/regex_match\n\n# 3. 创建验证脚本\ncat > validate_phone.py << EOF\nfrom guardrails import Guard\nfrom guardrails.hub import RegexMatch\n\nguard = Guard().use(RegexMatch, regex=r\"\\d{3}-\\d{4}\")\n\nresult = guard.validate(\"123-4567\")\nprint(\"验证通过\" if result else \"验证失败\")\nEOF\n\n# 4. 执行验证\npython validate_phone.py\n```\n\n#### 场景二：从 Pydantic 模型生成 RAIL\n\n```bash\n# 1. 编写 Pydantic 模型\ncat > models.py << EOF\nfrom pydantic import BaseModel, Field\n\nclass User(BaseModel):\n name: str = Field(description=\"用户姓名\")\n email: str = Field(description=\"电子邮箱\")\n age: int = Field(description=\"年龄\", ge=0)\nEOF\n\n# 2. 生成 RAIL 文件\nguardrails create models.User --output user.rail\n```\n\n#### 场景三：构建和安装自定义验证器\n\n```bash\n# 1. 创建验证器模板\nguardrails hub create-validator competitor_check\n\n# 2. 编辑生成的 Python 文件\n# 编辑 competitor_check.py 实现具体验证逻辑\n\n# 3. 从本地路径安装\nguardrails hub install ./competitor_check.py\n\n# 4. 在代码中使用\npython << EOF\nfrom guardrails import Guard\nfrom guardrails.hub import CompetitorCheck\n\nguard = Guard().use(CompetitorCheck, competitors=[\"Apple\", \"Google\"])\nEOF\n```\n\n## 错误处理\n\nCLI 工具采用统一的错误处理机制，确保用户获得清晰的错误信息和建议。\n\n### 常见错误及解决方案\n\n| 错误类型 | 错误信息 | 解决方案 |\n|----------|----------|----------|\n| 包未找到 | `Package not found in hub` | 检查包名拼写，确认包已发布 |\n| 版本冲突 | `Version requirement failed` | 使用 `--upgrade` 参数升级 |\n| 权限不足 | `Permission denied` | 使用 `sudo` 或虚拟环境 |\n| 依赖缺失 | `Module not found` | 安装缺失的 Python 包 |\n\n### 调试模式\n\n```bash\n# 启用详细日志\nexport GUARDRAILS_LOG_LEVEL=VERBOSE\nguardrails hub install hub://guardrails/regex_match\n\n# 显示完整堆栈跟踪\nguardrails --traceback hub install hub://guardrails/regex_match\n```\n\n## 最佳实践\n\n1. **使用虚拟环境**：建议在虚拟环境中安装 Guardrails，避免依赖冲突\n2. **版本管理**：在项目中锁定 guardrails-ai 版本，确保复现性\n3. **本地模型**：仅在需要离线运行验证时安装本地模型\n4. **日志级别**：生产环境使用默认级别，开发环境使用详细日志\n5. **自动化测试**：使用 `validate` 命令集成到 CI/CD 流程\n\n## 总结\n\nGuardrails CLI 提供了一套完整且易用的命令行工具集，覆盖了从验证器管理、RAIL 文件创建、数据验证到 API 服务部署的全流程。通过模块化的命令设计，用户可以根据需要灵活组合使用各项功能，提高开发效率。CLI 工具的日志系统、错误处理和参数验证机制确保了操作的可靠性和用户体验的流畅性。\n\n---\n\n\n\n## Guardrails 服务器\n\n### 相关页面\n\n相关主题：[CLI 命令行工具](#page-cli), [框架集成](#page-integrations)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [guardrails/cli/start.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/start.py)\n- [guardrails/guard.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/guard.py)\n- [guardrails/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)\n- [guardrails/cli/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/install.py)\n- [README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)\n- [guardrails/classes/history/call.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call.py)\n \n\n# Guardrails 服务器\n\nGuardrails 服务器是 Guardrails 框架提供的一项可选服务，用于部署和管理 Guardrails 验证能力。通过服务器模式，用户可以将验证逻辑集中管理，并以 API 服务的方式对外提供验证功能。本文详细介绍 Guardrails 服务器的架构、启动方式、配置方法以及与客户端的交互方式。\n\n## 服务器概述\n\nGuardrails 服务器基于 `guardrails-api` 包构建，提供了一个轻量级的 REST API 服务，用于执行 LLM 输出验证任务。服务器接收原始文本或结构化数据，通过配置的验证器（Validators）进行验证，并返回验证结果。\n\n服务器的核心功能包括：\n\n- **集中化验证**：将验证逻辑部署在服务器端，客户端无需本地安装验证器\n- **API 服务**：提供 RESTful API 接口，支持远程验证调用\n- **多验证器编排**：支持同时运行多个验证器，实现复杂的验证场景\n- **历史记录追踪**：记录每次验证调用的详细信息，包括输入、输出和异常情况\n- **Watch 模式**：支持开发模式下的热重载功能\n\n## 系统架构\n\n```mermaid\ngraph TD\n A[客户端应用] -->|HTTP/REST API| B[Guardrails 服务器]\n B --> C[guardrails-api 核心服务]\n C --> D[验证器注册表]\n D --> E[RegexMatch]\n D --> F[CompetitorCheck]\n D --> G[ToxicLanguage]\n D --> H[其他验证器...]\n B --> I[历史记录存储]\n I --> J[Call 对象]\n J --> K[Iteration 堆栈]\n K --> L[验证步骤记录]\n```\n\n### 核心组件\n\n| 组件名称 | 文件位置 | 功能描述 |\n|---------|---------|---------|\n| guardrails-api | guardrails_api/ | 核心服务器实现 |\n| CLI 启动器 | guardrails/cli/start.py | 命令行启动入口 |\n| 配置管理 | settings | 服务器配置管理 |\n| 验证器服务 | guardrails/hub/ | 验证器安装与加载 |\n| Guard 类 | guardrails/guard.py | 验证逻辑封装 |\n\n## 启动服务器\n\n### 环境准备\n\n启动 Guardrails 服务器前，需要确保已安装 `guardrails-api` 包：\n\n```bash\npip install guardrails-api>=0.2.1\n```\n\n服务器启动时会检查 `guardrails-api` 是否已安装，若未安装则自动提示安装。资料来源：[guardrails/cli/start.py:12-18]()\n\n### 启动命令\n\n使用 `guardrails start` 命令启动服务器：\n\n```bash\nguardrails start [选项]\n```\n\n**常用选项：**\n\n| 选项 | 说明 | 默认值 |\n|-----|------|-------|\n| `--port` | 服务器监听端口 | 8000 |\n| `--env` | 环境变量文件路径 | None |\n| `--config` | 配置文件路径 | None |\n| `--env-override` | 环境变量覆盖 | None |\n| `--watch` | 启用 Watch 模式 | False |\n\n### Watch 模式\n\n启用 Watch 模式后，服务器会监视配置文件和验证器的变化，并自动重新加载：\n\n```bash\nguardrails start --watch\n```\n\nWatch 模式通过 `settings._watch_mode_enabled = True` 启用，适用于开发阶段。资料来源：[guardrails/cli/start.py:28-29]()\n\n## 服务器配置\n\n### 配置文件\n\nGuardrails 服务器支持通过配置文件进行定制化设置。配置文件采用 Python 格式，定义服务器的各项参数。\n\n### 环境变量覆盖\n\n对于敏感配置（如 API 密钥），建议使用环境变量进行配置。`--env-override` 参数允许指定环境变量文件：\n\n```bash\nguardrails start --env-override /path/to/.env\n```\n\n> 注意：`env_override` 功能仅在 `guardrails-api>=0.3.0` 版本中可用。资料来源：[guardrails/cli/start.py:36-42]()\n\n### 版本兼容性\n\n服务器启动时会检查版本兼容性：\n\n- **版本 < 0.3.0**：不支持 `env_override` 参数，调用 `start_api(env, config, port)`\n- **版本 >= 0.3.0**：支持所有参数，包括 `env_override`\n\n```python\nif major == \"0\" and int(minor) < 3:\n start_api(env, config, port)\nelse:\n start_api(env, config, port, env_override)\n```\n\n资料来源：[guardrails/cli/start.py:44-52]()\n\n## API 服务接口\n\n### 验证端点\n\n服务器提供标准的 REST API 端点供客户端调用：\n\n```python\nfrom guardrails import Guard, OnFailAction\n\n# 创建 Guard 实例\nguard = Guard().use(\n RegexMatch, regex=\"\\(?\\d{3}\\)?-? *\\d{3}-? *-?\\d{4}\", on_fail=OnFailAction.EXCEPTION\n)\n\n# 通过 API 调用验证\nresponse = guard.validate(\"123-456-7890\")\n```\n\n### 验证流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Server as Guardrails 服务器\n participant Guard as Guard 实例\n participant Validator as 验证器\n \n Client->>Server: POST /validate (待验证文本)\n Server->>Guard: 创建/获取 Guard 实例\n Guard->>Validator: 执行验证\n Validator-->>Guard: 验证结果\n Guard-->>Server: 验证响应\n Server-->>Client: JSON 响应\n```\n\n## 验证器管理\n\n### 安装验证器\n\n通过 CLI 安装验证器到服务器：\n\n```bash\nguardrails hub install hub://guardrails/regex_match\nguardrails hub install hub://guardrails/competitor_check\nguardrails hub install hub://guardrails/toxic_language\n```\n\n安装过程包括：\n\n1. **验证包 URI**：解析验证器标识符和版本\n2. **获取清单**：从 Hub 获取验证器元数据和依赖\n3. **安装依赖**：通过 pip 安装验证器及其依赖\n4. **加载模块**：将验证器模块加载到运行时\n\n资料来源：[guardrails/cli/hub/install.py:1-50]()\n\n### 验证器安装流程\n\n```mermaid\ngraph TD\n A[hub install 命令] --> B[ValidatorPackageService.get_validator_id]\n B --> C{验证器已安装?}\n C -->|是| D[返回已安装版本]\n C -->|否| E[ValidatorPackageService.get_manifest_and_site_packages]\n E --> F[下载依赖]\n F --> G[ValidatorPackageService.install_hub_module]\n G --> H[模块安装完成]\n```\n\n## 验证历史记录\n\n### Call 对象结构\n\n每次 API 调用都会生成一个 `Call` 对象，记录完整的执行历史：\n\n```python\nclass Call:\n iterations: Stack[Iteration] # 迭代堆栈\n inputs: CallInputs # 输入参数\n exception: Optional[Exception] # 异常信息\n```\n\n资料来源：[guardrails/classes/history/call.py:1-30]()\n\n### CallInputs 输入参数\n\n| 参数名 | 类型 | 说明 |\n|-------|------|------|\n| prompt | str | 输入提示词 |\n| prompt_params | Dict | 提示词参数 |\n| llm_api | Callable | LLM 调用函数 |\n| messages | List[Dict] | 消息历史 |\n| num_reasks | int | 最大重试次数 |\n| metadata | Dict | 附加元数据 |\n| full_schema_reask | bool | 全量重问标志 |\n| stream | bool | 流式响应标志 |\n| args | List | 额外位置参数 |\n| kwargs | Dict | 额外关键字参数 |\n\n资料来源：[guardrails/classes/history/call_inputs.py:1-60]()\n\n### 迭代记录\n\n```mermaid\ngraph LR\n A[初始调用] --> B[Iteration 1]\n B --> C{验证通过?}\n C -->|是| D[返回结果]\n C -->|否| E[Iteration 2]\n E --> F{验证通过?}\n F -->|否| G[Iteration N]\n G --> H{达到最大重试?}\n H -->|是| I[返回异常]\n H -->|否| E\n```\n\n## 客户端集成\n\n### Python 客户端\n\n使用 `guardrails-api` 客户端库连接服务器：\n\n```python\nfrom guardrails_api.client import GuardrailsClient\n\nclient = GuardrailsClient(\"http://localhost:8000\")\n\nresult = client.validate(\n text=\"需要验证的文本\",\n validators=[\"RegexMatch\"],\n config={\"regex\": r\"\\d+\"}\n)\n```\n\n### 配置验证器\n\n在服务器端预先配置验证器，客户端只需指定验证器名称：\n\n```python\nguard = Guard().use(\n CompetitorCheck(\n competitors=[\"Apple\", \"Microsoft\", \"Google\"],\n on_fail=OnFailAction.EXCEPTION\n ),\n ToxicLanguage(\n threshold=0.5,\n validation_method=\"sentence\",\n on_fail=OnFailAction.EXCEPTION\n )\n)\n```\n\n## 部署选项\n\n### Docker 部署\n\nGuardrails 服务器支持 Docker 容器化部署：\n\n```dockerfile\n# server_ci/Dockerfile\nFROM python:3.11-slim\n# ... 其他配置\n```\n\n### 生产环境建议\n\n| 配置项 | 建议值 | 说明 |\n|-------|-------|------|\n| 端口 | 8000+ | 避免使用低位端口 |\n| Watch 模式 | 禁用 | 生产环境禁用热重载 |\n| 日志级别 | INFO | 平衡日志量和调试能力 |\n| 超时设置 | 60s | LLM 调用超时时间 |\n| 重试次数 | 3 | 验证失败重试次数 |\n\n## 故障排查\n\n### 常见问题\n\n**服务器启动失败**\n- 检查 `guardrails-api` 是否正确安装：`pip show guardrails-api`\n- 验证端口是否被占用：`lsof -i :8000`\n- 查看日志输出获取详细错误信息\n\n**验证器加载失败**\n- 确认验证器已正确安装：`guardrails hub list`\n- 检查 Python 路径是否包含验证器目录\n\n**版本不兼容**\n- 升级 `guardrails-api`：`pip install --upgrade guardrails-api`\n- 检查版本兼容性矩阵\n\n## 相关资源\n\n- [Guardrails Hub](https://guardrailsai.com/hub/) - 验证器市场\n- [官方文档](https://docs.guardrailsai.com/) - 完整文档\n- [GitHub 仓库](https://github.com/guardrails-ai/guardrails) - 源代码\n- [Discord 社区](https://discord.gg/Jsey3mX98B) - 技术讨论\n\n---\n\n\n\n## 框架集成\n\n### 相关页面\n\n相关主题：[Guard 类详解](#page-guard-class), [验证流程与 Runner](#page-validation-flow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [guardrails/integrations/langchain/__init__.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/langchain/__init__.py)\n- [guardrails/integrations/langchain/guard_runnable.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/langchain/guard_runnable.py)\n- [guardrails/integrations/langchain/validator_runnable.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/langchain/validator_runnable.py)\n- [guardrails/integrations/langchain/base_runnable.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/langchain/base_runnable.py)\n- [guardrails/integrations/llama_index/__init__.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/llama_index/__init__.py)\n- [guardrails/integrations/llama_index/guardrails_chat_engine.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/llama_index/guardrails_chat_engine.py)\n- [guardrails/integrations/llama_index/guardrails_query_engine.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/llama_index/guardrails_query_engine.py)\n- [guardrails/integrations/databricks/__init__.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/databricks/__init__.py)\n- [guardrails/integrations/databricks/ml_flow_instrumentor.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/databricks/ml_flow_instrumentor.py)\n \n\n# 框架集成\n\nGuardrails 为主流 LLM 应用框架提供了官方集成支持，使开发者能够在不改变原有工作流的情况下，为 LLM 应用添加输出验证和结构化能力。框架集成的核心目标是将 Guardrails 的验证机制无缝嵌入到 LangChain、LlamaIndex 和 Databricks 等生态系统中，实现输入验证、输出校验、错误修正等功能的一体化支持。\n\n## 集成架构概述\n\nGuardrails 的框架集成采用模块化设计，每个框架都有独立的集成包，包含针对该框架特定接口的适配器。这种设计确保了集成代码的清晰性和可维护性，同时保持了各框架原生 API 的使用体验。\n\n```mermaid\ngraph TB\n subgraph \"Guardrails 集成层\"\n LC[\"LangChain 集成\"]\n LI[\"LlamaIndex 集成\"]\n DB[\"Databricks 集成\"]\n end\n \n subgraph \"Guardrails 核心\"\n G[\"Guard 类\"]\n V[\"Validator 系统\"]\n H[\"Hub 验证器\"]\n end\n \n LC --> G\n LI --> G\n DB --> G\n G --> V\n V --> H\n```\n\n## LangChain 集成\n\nLangChain 是目前最流行的 LLM 应用开发框架之一，Guardrails 提供了完整的 Runnable 接口实现，使 Guardrails 可以直接作为 LangChain 链式调用的一部分使用。\n\n### 核心组件\n\nLangChain 集成包含三个核心类，分别处理不同的验证场景：\n\n| 类名 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| `BaseRunnable` | `base_runnable.py` | 所有 Runnable 的基类，定义通用接口 |\n| `GuardRunnable` | `guard_runnable.py` | 将整个 Guard 实例包装为 Runnable |\n| `ValidatorRunnable` | `validator_runnable.py` | 将单个或多个 Validator 包装为 Runnable |\n\n资料来源：[guardrails/integrations/langchain/__init__.py]()\n\n### GuardRunnable\n\n`GuardRunnable` 是最常用的 LangChain 集成类，它将完整的 Guard 实例转换为 LangChain 的 Runnable 接口。这意味着开发者可以在 LangChain 表达式链中使用任何已定义的 Guard 配置。\n\n```python\nfrom guardrails import Guard\nfrom guardrails.integrations.langchain import GuardRunnable\n\n# 创建 Guard 实例\nguard = Guard().use(...)\n\n# 转换为 Runnable\nguard_runnable = GuardRunnable(guard=guard)\n\n# 在 LangChain 链中使用\nchain = prompt | model | guard_runnable\n```\n\n`GuardRunnable` 继承自 `BaseRunnable`，`BaseRunnable` 提供了与 LangChain Runnable 接口兼容的 `invoke`、`ainvoke`、`batch`、`abatch` 等方法。\n\n资料来源：[guardrails/integrations/langchain/guard_runnable.py]()\n资料来源：[guardrails/integrations/langchain/base_runnable.py]()\n\n### ValidatorRunnable\n\n当只需要使用特定验证器而不需要完整的 Guard 配置时，`ValidatorRunnable` 提供了更轻量级的选择。它允许开发者直接将 Validator 实例嵌入到 LangChain 链中。\n\n```python\nfrom guardrails.integrations.langchain import ValidatorRunnable\nfrom guardrails.hub import RegexMatch\n\n# 创建验证器 Runnable\nvalidator_runnable = ValidatorRunnable(validator=RegexMatch(...))\n\n# 单独使用或在链中使用\nresult = validator_runnable.invoke(\"待验证的文本\")\n```\n\n资料来源：[guardrails/integrations/langchain/validator_runnable.py]()\n\n### 集成工作流\n\n```mermaid\ngraph LR\n A[\"用户输入\"] --> B[\"LangChain Prompt\"]\n B --> C[\"LLM 模型\"]\n C --> D{\"GuardRunnable\"}\n D --> E{验证通过?}\n E -->|是| F[\"返回结果\"]\n E -->|否| G[\"错误处理\"]\n G --> H[\"重新生成或异常\"]\n```\n\n## LlamaIndex 集成\n\nLlamaIndex 是专注于知识增强检索的 LLM 框架，Guardrails 为其提供了 Query Engine 和 Chat Engine 的集成支持，使结构化输出验证可以直接应用于检索增强生成（RAG）场景。\n\n### 核心组件\n\n| 类名 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| `GuardrailsQueryEngine` | `guardrails_query_engine.py` | 为 LlamaIndex 查询引擎添加验证层 |\n| `GuardrailsChatEngine` | `guardrails_chat_engine.py` | 为 LlamaIndex 聊天引擎添加验证层 |\n\n资料来源：[guardrails/integrations/llama_index/__init__.py]()\n\n### GuardrailsQueryEngine\n\n`GuardrailsQueryEngine` 将验证层包装在现有的 LlamaIndex 查询引擎之上。当查询结果返回时，验证器会自动检查输出是否符合预期的格式和内容约束。\n\n```python\nfrom llama_index import VectorStoreIndex\nfrom guardrails import Guard\nfrom guardrails.integrations.llama_index import GuardrailsQueryEngine\n\n# 创建基础索引\nindex = VectorStoreIndex.from_documents(documents)\n\n# 创建带 Guardrails 的查询引擎\nguard = Guard().use(...)\nquery_engine = GuardrailsQueryEngine(\n query_engine=index.as_query_engine(),\n guard=guard\n)\n\n# 使用验证引擎查询\nresponse = query_engine.query(\"用户问题\")\n```\n\n资料来源：[guardrails/integrations/llama_index/guardrails_query_engine.py]()\n\n### GuardrailsChatEngine\n\n`GuardrailsChatEngine` 专门为聊天场景设计，适用于需要持续对话且对每次回复都需要验证的应用。它保持了 LlamaIndex 原有聊天引擎的状态管理能力，同时叠加了验证功能。\n\n```python\nfrom guardrails import Guard\nfrom guardrails.integrations.llama_index import GuardrailsChatEngine\n\nguard = Guard().use(...)\nchat_engine = GuardrailsChatEngine.from_defaults(\n chat_mode=\"condense_plus_context\",\n guard=guard\n)\n\n# 对话循环\nchat_engine.chat(\"用户的第一条消息\")\nchat_engine.chat(\"用户的第二条消息\")\n```\n\n资料来源：[guardrails/integrations/llama_index/guardrails_chat_engine.py]()\n\n## Databricks 集成\n\nDatabricks 集成为使用 Databricks 进行 LLM 应用的开发者提供了 MLflow 仪器化支持，允许在 Databricks 环境中追踪和监控 Guardrails 验证行为。\n\n### MLflow 仪器化器\n\nDatabricks 集成的核心是 `MLflowInstrumentor` 类，它扩展了 MLflow 的自动仪器化功能，使 Guardrails 验证可以自动记录到 MLflow 实验追踪系统中。\n\n```python\nfrom guardrails.integrations.databricks import MLflowInstrumentor\n\n# 初始化仪器化器\ninstrumentor = MLflowInstrumentor()\n\n# 启用自动追踪\ninstrumentor.instrument()\n```\n\n资料来源：[guardrails/integrations/databricks/__init__.py]()\n资料来源：[guardrails/integrations/databricks/ml_flow_instrumentor.py]()\n\n### 追踪能力\n\n通过 MLflow 集成，Guardrails 可以记录以下信息：\n\n- **验证执行次数**：记录每个 Guard 和 Validator 被调用的次数\n- **验证结果**：记录每次验证的通过/失败状态\n- **错误详情**：记录验证失败时的详细错误信息\n- **性能指标**：记录验证过程的执行时间\n\n## 集成配置选项\n\n### 通用配置\n\n| 配置项 | 适用框架 | 说明 |\n|--------|----------|------|\n| `guard` | LangChain, LlamaIndex | 核心 Guard 实例 |\n| `on_fail` | 所有框架 | 验证失败时的行为（EXCEPTION, FIX, FILTER 等） |\n| `strict` | 所有框架 | 是否启用严格模式 |\n\n### LangChain 特定配置\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `output_format` | `None` | 指定输出格式器 |\n| `messages` | `None` | 自定义消息列表 |\n| `reask_messages` | `None` | 重新生成时的消息 |\n\n### LlamaIndex 特定配置\n\n| 配置项 | 说明 |\n|--------|------|\n| `query_engine` | 底层查询引擎实例 |\n| `chat_mode` | 聊天模式选择 |\n\n## 最佳实践\n\n### 框架集成的性能考虑\n\n在生产环境中使用框架集成时，应注意以下性能优化点：\n\n1. **Guard 实例复用**：Guard 实例应该被创建一次并在多次调用中复用，避免重复初始化开销。\n2. **批量验证**：对于支持批量操作的框架（如 LangChain 的 `batch` 方法），应优先使用批量接口。\n3. **异步支持**：所有 Runnable 实现都支持异步操作，在高并发场景下应使用 `ainvoke` 或 `abatch`。\n\n### 错误处理策略\n\n| 策略 | 描述 | 适用场景 |\n|------|------|----------|\n| `EXCEPTION` | 抛出验证异常 | 开发调试阶段 |\n| `FIX` | 自动修正输出 | 自动化处理流程 |\n| `FILTER` | 过滤无效结果 | 需要干净输出的场景 |\n| `REASK` | 重新请求 LLM | 需要高可靠性的生产环境 |\n\n### 框架选择指南\n\n| 场景 | 推荐框架 | 集成类 |\n|------|----------|--------|\n| 链式 LLM 调用 | LangChain | `GuardRunnable` |\n| 检索增强生成 | LlamaIndex | `GuardrailsQueryEngine` |\n| 聊天机器人 | LlamaIndex | `GuardrailsChatEngine` |\n| Databricks 环境 | Databricks | `MLflowInstrumentor` |\n\n## 相关资源\n\n- [Guardrails 官方文档](https://docs.guardrailsai.com/)\n- [Guardrails Hub 验证器库](https://guardrailsai.com/hub/)\n- [LangChain 官方文档](https://python.langchain.com/)\n- [LlamaIndex 官方文档](https://docs.llamaindex.ai/)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：guardrails-ai/guardrails\n\n摘要：发现 23 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：安装坑 - 来源证据：FIX action silently mutates output - should there be a 'quarantine' tier between LOG and FIX?。\n\n## 1. 安装坑 · 来源证据：FIX action silently mutates output - should there be a 'quarantine' tier between LOG and FIX?\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：FIX action silently mutates output - should there be a 'quarantine' tier between LOG and FIX?\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_69600563346341a386aa86c6af5d1274 | https://github.com/guardrails-ai/guardrails/issues/1448 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：Portable evidence artifacts for validation outcomes\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Portable evidence artifacts for validation outcomes\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ef2970465bbe44c89b513edd115b682c | https://github.com/guardrails-ai/guardrails/issues/1457 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Proposal: PromptDefenseAudit Hub validator — static system prompt hardening check\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: PromptDefenseAudit Hub validator — static system prompt hardening check\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d7163e193eb54aab837d87b3ecd73991 | https://github.com/guardrails-ai/guardrails/issues/1453 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 能力坑 · 来源证据：[docs] Fix double logo display in pypi\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：[docs] Fix double logo display in pypi\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_084985c7cb4d4238a44e452b14b2eaf9 | https://github.com/guardrails-ai/guardrails/issues/1362 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安全/权限坑 · 来源证据：Integration proposal: Cryptographic audit trail validator with asqav\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Integration proposal: Cryptographic audit trail validator with asqav\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8db542ceccff4a71bc11c254ce3abfde | https://github.com/guardrails-ai/guardrails/issues/1446 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安全/权限坑 · 来源证据：Integration proposal: styxx hallucination validator (8-benchmark cross-validated)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Integration proposal: styxx hallucination validator (8-benchmark cross-validated)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_da275c0a112848ed920af00c76fd3e1b | https://github.com/guardrails-ai/guardrails/issues/1463 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：Proposal: Agent Threat Rules detection integration\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: Agent Threat Rules detection integration\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9d25561995774521a21051373d95b431 | https://github.com/guardrails-ai/guardrails/issues/1471 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：[bug] Guardrails CLI start command broken with guardrails-api 0.4.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] Guardrails CLI start command broken with guardrails-api 0.4.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f411132764b84c17b318b5cc7a32ef56 | https://github.com/guardrails-ai/guardrails/issues/1464 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：v0.7.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_95f33a7ff8014d78a13752aa7fd56d6e | https://github.com/guardrails-ai/guardrails/releases/tag/v0.7.3 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 10. 安装坑 · 来源证据：v0.8.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.8.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_559ad38ac0504cff91377804f004c57c | https://github.com/guardrails-ai/guardrails/releases/tag/v0.8.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 安装坑 · 来源证据：v0.9.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.2\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ae34ce00e8554a5199b5e78e3465942d | https://github.com/guardrails-ai/guardrails/releases/tag/v0.9.2 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 12. 安装坑 · 来源证据：v0.9.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f2b73a33cb2f47d3bba9b9f2dd07ed62 | https://github.com/guardrails-ai/guardrails/releases/tag/v0.9.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | README/documentation is current enough for a first validation pass.\n\n## 14. 维护坑 · 来源证据：v0.8.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.8.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_160840f6f00644f2bcd25339973d1d82 | https://github.com/guardrails-ai/guardrails/releases/tag/v0.8.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 维护坑 · 来源证据：v0.9.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.9.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_91ae72d0a0f74305b8b5b3f66d4048e4 | https://github.com/guardrails-ai/guardrails/releases/tag/v0.9.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | last_activity_observed missing\n\n## 17. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 19. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | no_demo; severity=medium\n\n## 20. 安全/权限坑 · 来源证据：MCP Server Compliance Scanning: OWASP MCP Top 10 guardrails\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：MCP Server Compliance Scanning: OWASP MCP Top 10 guardrails\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b6a63df899144908af33089886cfaf51 | https://github.com/guardrails-ai/guardrails/issues/1435 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 21. 安全/权限坑 · 来源证据：v0.8.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.8.1\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6721e28473844e92b61d6701c416d2fd | https://github.com/guardrails-ai/guardrails/releases/tag/v0.8.1 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 22. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：guardrails-ai/guardrails\n\n摘要：发现 23 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：安装坑 - 来源证据：FIX action silently mutates output - should there be a 'quarantine' tier between LOG and FIX?。\n\n## 1. 安装坑 · 来源证据：FIX action silently mutates output - should there be a 'quarantine' tier between LOG and FIX?\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：FIX action silently mutates output - should there be a 'quarantine' tier between LOG and FIX?\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_69600563346341a386aa86c6af5d1274 | https://github.com/guardrails-ai/guardrails/issues/1448 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：Portable evidence artifacts for validation outcomes\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Portable evidence artifacts for validation outcomes\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ef2970465bbe44c89b513edd115b682c | https://github.com/guardrails-ai/guardrails/issues/1457 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Proposal: PromptDefenseAudit Hub validator — static system prompt hardening check\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: PromptDefenseAudit Hub validator — static system prompt hardening check\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d7163e193eb54aab837d87b3ecd73991 | https://github.com/guardrails-ai/guardrails/issues/1453 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 能力坑 · 来源证据：[docs] Fix double logo display in pypi\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：[docs] Fix double logo display in pypi\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_084985c7cb4d4238a44e452b14b2eaf9 | https://github.com/guardrails-ai/guardrails/issues/1362 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安全/权限坑 · 来源证据：Integration proposal: Cryptographic audit trail validator with asqav\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Integration proposal: Cryptographic audit trail validator with asqav\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8db542ceccff4a71bc11c254ce3abfde | https://github.com/guardrails-ai/guardrails/issues/1446 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安全/权限坑 · 来源证据：Integration proposal: styxx hallucination validator (8-benchmark cross-validated)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Integration proposal: styxx hallucination validator (8-benchmark cross-validated)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_da275c0a112848ed920af00c76fd3e1b | https://github.com/guardrails-ai/guardrails/issues/1463 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：Proposal: Agent Threat Rules detection integration\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: Agent Threat Rules detection integration\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9d25561995774521a21051373d95b431 | https://github.com/guardrails-ai/guardrails/issues/1471 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：[bug] Guardrails CLI start command broken with guardrails-api 0.4.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] Guardrails CLI start command broken with guardrails-api 0.4.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f411132764b84c17b318b5cc7a32ef56 | https://github.com/guardrails-ai/guardrails/issues/1464 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：v0.7.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_95f33a7ff8014d78a13752aa7fd56d6e | https://github.com/guardrails-ai/guardrails/releases/tag/v0.7.3 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 10. 安装坑 · 来源证据：v0.8.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.8.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_559ad38ac0504cff91377804f004c57c | https://github.com/guardrails-ai/guardrails/releases/tag/v0.8.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 安装坑 · 来源证据：v0.9.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.2\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ae34ce00e8554a5199b5e78e3465942d | https://github.com/guardrails-ai/guardrails/releases/tag/v0.9.2 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 12. 安装坑 · 来源证据：v0.9.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f2b73a33cb2f47d3bba9b9f2dd07ed62 | https://github.com/guardrails-ai/guardrails/releases/tag/v0.9.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | README/documentation is current enough for a first validation pass.\n\n## 14. 维护坑 · 来源证据：v0.8.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.8.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_160840f6f00644f2bcd25339973d1d82 | https://github.com/guardrails-ai/guardrails/releases/tag/v0.8.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 维护坑 · 来源证据：v0.9.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.9.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_91ae72d0a0f74305b8b5b3f66d4048e4 | https://github.com/guardrails-ai/guardrails/releases/tag/v0.9.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | last_activity_observed missing\n\n## 17. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 19. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | no_demo; severity=medium\n\n## 20. 安全/权限坑 · 来源证据：MCP Server Compliance Scanning: OWASP MCP Top 10 guardrails\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：MCP Server Compliance Scanning: OWASP MCP Top 10 guardrails\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b6a63df899144908af33089886cfaf51 | https://github.com/guardrails-ai/guardrails/issues/1435 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 21. 安全/权限坑 · 来源证据：v0.8.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.8.1\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6721e28473844e92b61d6701c416d2fd | https://github.com/guardrails-ai/guardrails/releases/tag/v0.8.1 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 22. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# guardrails - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 guardrails 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Adding guardrails to large language models. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：Guardrails 简介。围绕“Guardrails 简介”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装与配置。围绕“安装与配置”模拟一次用户任务，不展示安装或运行结果。\n3. page-guard-class：Guard 类详解。围绕“Guard 类详解”模拟一次用户任务，不展示安装或运行结果。\n4. page-schema-system：Schema 系统。围绕“Schema 系统”模拟一次用户任务，不展示安装或运行结果。\n5. page-validation-flow：验证流程与 Runner。围绕“验证流程与 Runner”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“Guardrails 简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装与配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-guard-class\n输入：用户提供的“Guard 类详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-schema-system\n输入：用户提供的“Schema 系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-validation-flow\n输入：用户提供的“验证流程与 Runner”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“Guardrails 简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装与配置”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-guard-class：Step 3 必须围绕“Guard 类详解”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-schema-system：Step 4 必须围绕“Schema 系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-validation-flow：Step 5 必须围绕“验证流程与 Runner”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/guardrails-ai/guardrails\n- https://github.com/guardrails-ai/guardrails#readme\n- README.md\n- guardrails/__init__.py\n- guardrails/guard.py\n- CONTRIBUTING.md\n- guardrails/cli/configure.py\n- Makefile\n- guardrails/async_guard.py\n- guardrails/prompt/__init__.py\n- guardrails/prompt/prompt.py\n- guardrails/prompt/instructions.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 guardrails 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：guardrails-ai/guardrails\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install guardrails-ai\n```\n\n来源：https://github.com/guardrails-ai/guardrails#readme\n\n## 来源\n\n- repo: https://github.com/guardrails-ai/guardrails\n- docs: https://github.com/guardrails-ai/guardrails#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_4e8dcba9fe0c48c2ac835e2e5a64cd86"
}