# https://github.com/guardrails-ai/guardrails 项目说明书
生成时间：2026-05-11 13:44:06 UTC
## 目录
- [Guardrails 简介](#page-introduction)
- [安装与配置](#page-installation)
- [Guard 类详解](#page-guard-class)
- [Schema 系统](#page-schema-system)
- [验证流程与 Runner](#page-validation-flow)
- [验证器基础](#page-validators)
- [Guardrails Hub](#page-hub)
- [CLI 命令行工具](#page-cli)
- [Guardrails 服务器](#page-server)
- [框架集成](#page-integrations)
## Guardrails 简介
### 相关页面
相关主题：[安装与配置](#page-installation), [Guard 类详解](#page-guard-class)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)
- [guardrails/guard.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/guard.py)
- [guardrails/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)
- [guardrails/cli/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/install.py)
- [guardrails/cli/hub/create_validator.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/create_validator.py)
- [guardrails/llm_providers.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/llm_providers.py)
- [guardrails/classes/history/call.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call.py)
- [guardrails/classes/history/call_inputs.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call_inputs.py)
# Guardrails 简介
## 概述
Guardrails 是一个用于验证和纠正大型语言模型（LLM）输出的 Python 库。它提供了输入/输出验证、格式约束和结构化数据生成等功能，帮助开发者确保 LLM 应用的可靠性和安全性。
Guardrails 的核心设计理念是将验证逻辑与 LLM 调用解耦，使开发者能够以声明式的方式定义输出规范，然后自动验证和纠正 LLM 响应。
资料来源：[README.md:1]()
## 核心概念
### Guard（守卫）
`Guard` 是 Guardrails 框架的核心类，它包装 LLM 调用并自动执行验证和纠正流程。
```python
from guardrails import Guard, OnFailAction
guard = Guard().use(
RegexMatch, regex="\(?\d{3}\)?-? *\d{3}-? *-?\d{4}", on_fail=OnFailAction.EXCEPTION
)
guard.validate("123-456-7890") # 验证通过
```
资料来源：[README.md:32](), [guardrails/guard.py:1]()
### Validator（验证器）
验证器是 Guardrails 的核心组件，用于定义具体的验证逻辑。验证器可以通过 Guardrails Hub 安装，也可以自定义创建。
资料来源：[guardrails/cli/hub/create_validator.py:1]()
### OnFailAction（失败动作）
| 动作 | 描述 |
|------|------|
| `EXCEPTION` | 抛出异常 |
| `REASK` | 重新请求 LLM 修正输出 |
| `FIX` | 自动修复无效输出 |
| `FILTER` | 过滤无效部分 |
| `REFRAIN` | 返回空值 |
资料来源：[README.md:35]()
## 系统架构
### 组件架构图
```mermaid
graph TD
A[用户代码] --> B[Guard]
B --> C[LLM Provider]
C --> D[LLM 响应]
D --> E[Validators]
E -->|通过| F[结构化输出]
E -->|失败| G[纠正流程]
G -->|重新请求| C
G -->|抛出异常| H[Exception]
I[Guardrails Hub] -->|安装验证器| B
```
### 调用流程
```mermaid
sequenceDiagram
participant U as 用户
participant G as Guard
participant L as LLM
participant V as Validators
participant H as History
U->>G: 调用 Guard.__call__
G->>L: 调用 LLM
L-->>G: 返回响应
G->>V: 验证响应
V-->>G: 验证结果
alt 验证通过
G-->>U: 返回验证结果
G->>H: 记录 Call
else 验证失败
G->>G: 重新请求
G->>L: 重新调用 LLM
end
```
## Guard 类 API
### 创建 Guard 的方式
| 方法 | 用途 |
|------|------|
| `Guard()` | 创建空 Guard |
| `Guard.for_rail(rail_string)` | 从 RAIL 字符串创建 |
| `Guard.for_pydantic(output_class)` | 从 Pydantic 模型创建 |
资料来源：[guardrails/guard.py:1]()
### for_pydantic 方法参数
```python
@classmethod
def for_pydantic(
cls,
output_class: ModelOrListOfModels,
*,
reask_messages: Optional[List[Dict]] = None,
messages: Optional[List[Dict]] = None,
name: Optional[str] = None,
description: Optional[str] = None,
output_formatter: Optional[Union[str, BaseFormatter]] = None,
):
```
| 参数 | 类型 | 说明 |
|------|------|------|
| `output_class` | `ModelOrListOfModels` | Pydantic 模型类 |
| `reask_messages` | `Optional[List[Dict]]` | 重新请求时的消息 |
| `messages` | `Optional[List[Dict]]` | 发送给 LLM 的消息 |
| `name` | `Optional[str]` | Guard 实例名称 |
| `description` | `Optional[str]` | Guard 实例描述 |
| `output_formatter` | `Optional[Union[str, BaseFormatter]]` | 输出格式化器 |
资料来源：[guardrails/guard.py:18]()
## LLM 集成
Guardrails 支持多种 LLM 提供商，包括 OpenAI、LiteLLM 和 Manifest。
### LiteLLM 集成示例
```python
from litellm import completion
raw_llm_response, validated_response = guard(
completion,
model="gpt-3.5-turbo",
prompt_params={...},
temperature=...,
)
```
资料来源：[guardrails/llm_providers.py:1]()
### 支持的 LLM 提供商
| 提供商 | 调用类 | 依赖包 |
|--------|--------|--------|
| OpenAI | `OpenAIClientCallable` | `openai` |
| LiteLLM | `LiteLLMCallable` | `litellm` |
| Manifest | `ManifestCallable` | `manifest-ml` |
## 历史记录系统
Guardrails 内置了调用历史记录功能，每次执行 `Guard.__call__`、`Guard.parse` 或 `Guard.validate` 都会创建一个 `Call` 对象。
### Call 数据结构
```python
class Call:
_id: str | None = None
iterations: Stack[Iteration] = Field(default_factory=Stack)
inputs: CallInputs = Field(default_factory=CallInputs)
exception: Optional[Exception] = None
```
| 属性 | 类型 | 说明 |
|------|------|------|
| `_id` | `str \| None` | 唯一标识符 |
| `iterations` | `Stack[Iteration]` | 迭代堆栈 |
| `inputs` | `CallInputs` | 调用输入参数 |
| `exception` | `Optional[Exception]` | 执行中的异常 |
### CallInputs 参数
| 字段 | 说明 |
|------|------|
| `llm_api` | LLM API 回调函数 |
| `prompt_params` | 格式化到消息中的参数 |
| `num_reasks` | 重新请求的最大次数 |
| `metadata` | 验证器执行时使用的额外数据 |
| `full_schema_reask` | 是否对整个 schema 执行重新请求 |
| `stream` | 是否使用流式输出 |
| `args` | LLM 的额外位置参数 |
| `kwargs` | LLM 的额外关键字参数 |
资料来源：[guardrails/classes/history/call.py:1](), [guardrails/classes/history/call_inputs.py:1]()
## Guardrails Hub
Guardrails Hub 是验证器的共享平台，开发者可以从中安装预构建的验证器。
### 安装验证器
```bash
pip install guardrails-ai
guardrails configure
guardrails hub install hub://guardrails/regex_match
```
资料来源：[README.md:10]()
### 安装 API
```python
from guardrails.hub.install import install
RegexMatch = install("hub://guardrails/regex_match").RegexMatch
RegexMatch = install("hub://guardrails/regex_match~=1.4").RegexMatch
```
### Hub CLI 命令
| 命令 | 说明 |
|------|------|
| `guardrails configure` | 配置 Guardrails Hub |
| `guardrails hub install ` | 安装验证器 |
| `guardrails hub create-validator ` | 创建验证器模板 |
资料来源：[guardrails/hub/install.py:1](), [guardrails/cli/hub/install.py:1]()
## 创建自定义验证器
### 验证器模板
使用 CLI 创建验证器模板：
```bash
guardrails hub create-validator MyValidator
```
这会生成一个模板文件 `my_validator.py`。
资料来源：[guardrails/cli/hub/create_validator.py:1]()
### 验证器基本结构
```python
class MyValidator(Validator):
"""验证器描述"""
def __init__(self, ...):
super().__init__(...)
def validate(self, value, ...):
# 验证逻辑
pass
```
## 安装与配置
### 环境要求
| 要求 | 说明 |
|------|------|
| Python | >= 3.8 |
| pip | 最新版本 |
| LLM API Key | 对应提供商的密钥 |
### 安装步骤
1. 安装 guardrails-ai 包：
```python
pip install guardrails-ai
```
2. 配置 Hub CLI：
```bash
guardrails configure
```
3. 安装验证器：
```bash
guardrails hub install hub://guardrails/competitor_check
guardrails hub install hub://guardrails/toxic_language
```
资料来源：[README.md:10-20]()
## 使用示例
### 基本验证
```python
from guardrails import Guard, OnFailAction
from guardrails.hub import RegexMatch
guard = Guard().use(
RegexMatch, regex="\(?\d{3}\)?-? *\d{3}-? *-?\d{4}", on_fail=OnFailAction.EXCEPTION
)
guard.validate("123-456-7890") # 验证通过
try:
guard.validate("1234-789-0000") # 验证失败
except Exception as e:
print(e)
```
### 多验证器组合
```python
from guardrails import Guard, OnFailAction
from guardrails.hub import CompetitorCheck, ToxicLanguage
guard = Guard().use(
CompetitorCheck(["Apple", "Microsoft", "Google"], on_fail=OnFailAction.EXCEPTION),
ToxicLanguage(threshold=0.5, validation_method="sentence", on_fail=OnFailAction.EXCEPTION)
)
guard.validate("An apple a day keeps a doctor away.") # 两个验证器都通过
```
### 使用 Pydantic 模型生成结构化数据
```python
from pydantic import BaseModel, Field
from guardrails import Guard
class Pet(BaseModel):
pet_type: str = Field(description="宠物种类")
name: str = Field(description="宠物名字")
guard = Guard.for_pydantic(Pet)
```
资料来源：[README.md:32-80]()
## 参与贡献
### 开发环境设置
1. 克隆仓库：`git clone https://github.com/guardrails-ai/guardrails.git`
2. 安装开发依赖：`make dev`
3. 安装 pre-commit：`pre-commit install`
### 开发工作流
| 步骤 | 命令 | 说明 |
|------|------|------|
| 运行测试 | `make test` | 确保所有测试通过 |
| 代码格式化 | `make autoformat` | 格式化代码 |
| 类型检查 | `make type` | 运行静态分析 |
| 更新文档 | `make docs-gen` | 生成文档 |
资料来源：[CONTRIBUTING.md:1]()
## 相关资源
- 官方文档：[Guardrails AI](https://guardrailsai.com/)
- 验证器市场：[Guardrails Hub](https://guardrailsai.com/hub/)
- Discord 社区：[加入讨论](https://discord.gg/Jsey3mX98B)
- GitHub 仓库：[guardrails-ai/guardrails](https://github.com/guardrails-ai/guardrails)
---
## 安装与配置
### 相关页面
相关主题：[Guardrails 简介](#page-introduction), [CLI 命令行工具](#page-cli)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)
- [guardrails/cli/configure.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/configure.py)
- [guardrails/cli/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/install.py)
- [guardrails/cli/start.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/start.py)
- [Makefile](https://github.com/guardrails-ai/guardrails/blob/main/Makefile)
# 安装与配置
## 概述
Guardrails 是一个用于 LLM（大型语言模型）输出验证和结构化数据生成的 Python 库。本页面详细介绍 Guardrails 的安装方法、开发环境配置、CLI 工具设置以及 Hub 验证器的安装流程。
Guardrails 支持两种主要的安装场景：
- **生产环境安装**：仅安装核心库和必要的依赖
- **开发环境安装**：安装所有开发依赖，支持本地测试、格式化、类型检查等
资料来源：[CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)
---
## 基础安装
### 使用 pip 安装
Guardrails 可以通过 pip 包管理器快速安装：
```bash
pip install guardrails-ai
```
此命令将安装 Guardrails 的核心功能，包括：
- Guard 类和验证框架
- 内置验证器支持
- LLM 提供商集成
- CLI 工具
资料来源：[README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)
### Python 版本要求
| 要求 | 说明 |
|------|------|
| Python 版本 | 请参考 PyPI 上的版本要求 |
| 包格式 | 支持 wheel 和 source distribution |
资料来源：[README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)
---
## 开发环境配置
### 克隆仓库
首先从 GitHub 克隆 Guardrails 仓库：
```bash
git clone https://github.com/guardrails-ai/guardrails.git
cd guardrails
```
资料来源：[CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)
### 安装开发依赖
Guardrails 提供了一个便捷的 `Makefile` 命令来配置完整的开发环境：
```bash
make dev
```
此命令会：
1. 以开发模式（editable mode）安装 guardrails 包
2. 安装所有开发依赖
3. 配置 pre-commit 钩子
> **注意**：建议在虚拟环境中执行此操作，以隔离项目依赖。
资料来源：[CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)
### 开发工作流程命令
Guardrails 项目定义了标准化的开发命令：
| 命令 | 功能 |
|------|------|
| `make test` | 运行所有测试，确保代码正确性 |
| `make autoformat` | 自动格式化代码 |
| `make type` | 运行静态类型检查（pyright） |
| `make docs-gen` | 生成项目文档 |
```bash
# 示例：开发过程中的完整流程
make test # 确保测试通过
make autoformat # 格式化代码
make type # 类型检查
make docs-gen # 更新文档
```
资料来源：[CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)
---
## CLI 工具配置
### Guardrails CLI 概述
Guardrails 提供了命令行工具来管理验证器、启动服务等。CLI 工具支持多种命令：
```bash
guardrails configure # 配置 Guardrails
guardrails hub install # 安装验证器
guardrails start # 启动 Guardrails API 服务
```
资料来源：[guardrails/cli/configure.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/configure.py)
### 配置命令
Guardrails CLI 需要首次配置以初始化必要的设置：
```bash
guardrails configure
```
此命令会引导用户完成初始配置过程，包括：
- 设置 API 端点（如需要）
- 配置验证器缓存路径
- 设置日志级别
资料来源：[README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)
### API 服务启动
Guardrails 提供了一个可选的 API 服务，可通过 CLI 启动：
```bash
guardrails start [OPTIONS]
```
**可用选项：**
| 参数 | 说明 |
|------|------|
| `--env` | 环境变量配置文件路径 |
| `--config` | 服务配置文件路径 |
| `--port` | 服务监听端口 |
| `--env-override` | 运行时环境变量覆盖 |
启动服务前会检查必要的依赖：
```python
# 伪代码：启动前检查
if not api_is_installed():
installer_process("install", "guardrails-api>=0.2.1")
```
资料来源：[guardrails/cli/start.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/start.py)
---
## Pre-commit 钩子配置
### 安装 Pre-commit
安装项目提供的 pre-commit 钩子：
```bash
pre-commit install
```
此步骤在执行 `make dev` 时会自动完成，但也可以手动单独执行。
资料来源：[CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)
### Pre-commit 钩子功能
Pre-commit 钩子会在每次提交前自动运行：
- 代码格式检查
- 语法验证
- 基础测试
> **好处**：减少代码审查中的格式问题，加快开发流程。
资料来源：[CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)
---
## Hub 验证器安装
### Hub CLI 安装流程
Guardrails Hub 提供了丰富的预构建验证器。安装流程如下：
1. **安装验证器包**
```bash
guardrails hub install hub://guardrails/regex_match
```
2. **在代码中使用**
```python
from guardrails import Guard, OnFailAction
from guardrails.hub import RegexMatch
guard = Guard().use(
RegexMatch,
regex=r"\(?\d{3}\)?-? *\d{3}-? *-?\d{4}",
on_fail=OnFailAction.EXCEPTION
)
guard.validate("123-456-7890") # 通过验证
```
资料来源：[README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)
### 安装多个验证器
可以同时安装多个验证器：
```bash
guardrails hub install hub://guardrails/competitor_check
guardrails hub install hub://guardrails/toxic_language
```
### 本地模型安装
某些验证器支持本地推理。安装时可选择是否下载本地模型：
```python
# CLI 参数
guardrails hub install hub://guardrails/ --local-models
```
验证器安装服务会：
1. 验证包 URI 和版本
2. 获取模块清单
3. 下载依赖项
4. 执行 pip 安装
```python
# 安装服务流程伪代码
def install_multiple(package_uris, install_local_models, quiet, upgrade):
for package_uri in package_uris:
validator_id, validator_version = ValidatorPackageService.get_validator_id(package_uri)
module_manifest = ValidatorPackageService.get_manifest_and_site_packages(validator_id)
ValidatorPackageService.install_hub_module(validator_id, validator_version=validator_version)
```
资料来源：[guardrails/cli/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/install.py)
---
## 项目结构概览
```mermaid
graph TD
A[guardrails-ai/guardrails] --> B[核心库]
A --> C[CLI 工具]
A --> D[Hub 验证器]
A --> E[开发工具]
B --> B1[guard.py - Guard 类]
B --> B2[schema/ - 输出模式]
B --> B3[validators/ - 验证器]
C --> C1[configure.py - 配置命令]
C --> C2[hub/install.py - Hub 安装]
C --> C3[start.py - 服务启动]
D --> D1[manifest.json - 验证器清单]
D --> D2[本地/远程模型]
E --> E1[Makefile - 开发命令]
E --> E2[pre-commit - 钩子]
```
---
## 常见问题排查
| 问题 | 解决方案 |
|------|----------|
| `manifest` 包未安装 | 运行 `pip install manifest-ml` |
| API 服务启动失败 | 确认 `guardrails-api>=0.2.1` 已安装 |
| Hub 安装静默失败 | 使用 `--verbose` 参数查看详细日志 |
| 类型检查失败 | 运行 `make autoformat` 后再执行 `make type` |
---
## 进阶配置
### 环境变量配置
Guardrails 支持通过环境变量进行高级配置：
| 变量 | 说明 |
|------|------|
| `OPENAI_API_KEY` | OpenAI API 密钥 |
| 自定义端点 | 通过 `--env` 参数指定 |
资料来源：[guardrails/cli/start.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/start.py)
### 自定义验证器开发
Guardrails 支持开发自定义验证器：
```bash
guardrails create-validator
```
这会生成验证器模板文件，包含：
- 验证逻辑框架
- 单元测试模板
- 文档注释结构
资料来源：[guardrails/cli/hub/create_validator.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/create_validator.py)
---
## 总结
Guardrails 提供了灵活的安装和配置选项，适应不同的使用场景：
- **快速上手**：使用 `pip install guardrails-ai` 即可开始
- **完整开发环境**：通过 `make dev` 配置一切
- **生产部署**：使用 CLI 配置和 Hub 验证器管理
建议按照本文档的步骤顺序进行配置，以确保所有依赖和工具链正确设置。
---
## Guard 类详解
### 相关页面
相关主题：[验证流程与 Runner](#page-validation-flow), [Schema 系统](#page-schema-system)
相关源码文件
以下源码文件用于生成本页说明：
- [guardrails/guard.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/guard.py)
- [guardrails/classes/history/call.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call.py)
- [guardrails/llm_providers.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/llm_providers.py)
- [guardrails/api_client.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/api_client.py)
- [guardrails/call_tracing/trace_handler.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/call_tracing/trace_handler.py)
- [guardrails/schema/rail_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/rail_schema.py)
# Guard 类详解
## 概述
Guard 是 Guardrails AI 框架的核心类，负责验证和约束大语言模型（LLM）的输入和输出。它提供了一个统一的接口，用于定义验证规则、调用 LLM、以及对输出进行结构化验证。
Guard 类的设计目标包括：
- **输出验证**：确保 LLM 生成的输出符合预定义的模式和约束
- **结构化生成**：支持从 Pydantic 模型生成结构化数据
- **多步骤验证**：支持重试机制（reask）和多次验证迭代
- **历史追踪**：完整记录每次调用的输入、输出和验证结果
资料来源：[guardrails/guard.py:1-100]()
## 核心架构
### 类层次结构
```mermaid
graph TD
A[Guard] --> B[for_rail]
A --> C[for_pydantic]
A --> D[__call__]
A --> E[validate]
A --> F[parse]
G[PromptCallableBase] --> H[LiteLLMCallable]
G --> I[ManifestCallable]
J[Call] --> K[iterations]
J --> L[inputs]
J --> M[exception]
K --> N[Iteration]
N --> O[Stack]
```
### 执行流程
```mermaid
sequenceDiagram
participant 用户
participant Guard
participant LLM
participant Validator
participant TraceHandler
用户->>Guard: __call__(prompt, model)
Guard->>LLM: 调用模型生成响应
LLM-->>Guard: 原始输出
Guard->>Validator: 验证输出
alt 验证失败 & 需要重试
Guard->>Guard: 执行 reask
Guard->>LLM: 重新调用
end
Guard->>TraceHandler: 记录调用历史
Guard-->>用户: 返回验证后的结果
```
## Guard 类的创建方式
### 从 RAIL 规范创建
RAIL（Regression AI Language）是一种 XML 格式的规范，用于定义输出验证规则。
```python
guard = Guard.from_rail_string(rail_string)
```
资料来源：[guardrails/guard.py:100-120]()
### 从 Pydantic 模型创建
这是最常用的方式，直接使用 Pydantic BaseModel 定义输出结构：
```python
from pydantic import BaseModel, Field
from guardrails import Guard
class Pet(BaseModel):
pet_type: str = Field(description="宠物种类")
name: str = Field(description="宠物名称")
guard = Guard.for_pydantic(Pet)
```
资料来源：[guardrails/guard.py:150-180]()
### for_pydantic 方法签名
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| output_class | ModelOrListOfModels | 是 | Pydantic 模型类或列表 |
| reask_messages | Optional[List[Dict]] | 否 | 重试时的消息模板 |
| messages | Optional[List[Dict]] | 否 | 发送给 LLM 的消息 |
| name | Optional[str] | 否 | Guard 实例名称 |
| description | Optional[str] | 否 | Guard 实例描述 |
| output_formatter | Optional[Union[str, BaseFormatter]] | 否 | 输出格式化器 |
## 验证机制
### 验证流程
```mermaid
graph TD
A[接收 LLM 输出] --> B[解析输出]
B --> C{是否需要结构化?}
C -->|是| D[JSON 解析]
C -->|否| E[保持原样]
D --> F[应用验证器链]
F --> G{所有验证器通过?}
G -->|是| H[返回验证结果]
G -->|否| I{on_fail 配置}
I -->|EXCEPTION| J[抛出异常]
I -->|FIX| K[尝试修复]
I -->|REASK| L[重新请求 LLM]
I -->|FILTER| M[过滤无效部分]
I -->|CUSTOM| N[执行自定义处理]
```
### OnFailAction 枚举
| 动作 | 说明 | 使用场景 |
|------|------|----------|
| EXCEPTION | 验证失败时抛出异常 | 需要严格验证的场景 |
| FIX | 尝试自动修复输出 | 允许自动修正的场景 |
| REASK | 重新请求 LLM 生成 | 需要模型重新生成 |
| FILTER | 过滤掉无效部分 | 保留部分有效输出 |
| CUSTOM | 执行自定义回调 | 自定义错误处理 |
## 调用历史系统
### Call 数据结构
每次调用 Guard 时，系统会创建一个 Call 对象记录完整的执行历史。
```mermaid
classDiagram
class Call {
+str id
+Stack~Iteration~ iterations
+CallInputs inputs
+Optional~Exception~ exception
+get_id() str
}
class Iteration {
+Step[] steps
+CallMetadata metadata
}
class CallInputs {
+str prompt
+str model
+Dict kwargs
}
Call "1" *-- "*" Iteration : contains
Iteration "1" *-- "*" Step : contains
```
资料来源：[guardrails/classes/history/call.py:1-80]()
### Call 类的属性
| 属性 | 类型 | 说明 |
|------|------|------|
| _id | str \| None | 唯一标识符 |
| iterations | Stack[Iteration] | 迭代栈，包含每次重试的迭代 |
| inputs | CallInputs | 调用输入参数 |
| exception | Optional[Exception] | 执行过程中的异常 |
资料来源：[guardrails/classes/history/call.py:20-50]()
## LLM 集成
### 支持的 LLM 提供者
Guard 类支持与多种 LLM 提供者集成：
```python
# OpenAI
from guardrails import Guard
guard = Guard.for_pydantic(Pet)
result = guard(
client=openai.ChatCompletion,
prompt="生成一只宠物的信息",
model="gpt-4"
)
# LiteLLM
guard = Guard.for_pydantic(Pet)
result = guard(
client="openai/gpt-3.5-turbo",
prompt="生成一只宠物的信息"
)
# Manifest
guard = Guard.for_pydantic(Pet)
result = guard(
client=manifest_client,
prompt="生成一只宠物的信息"
)
```
资料来源：[guardrails/llm_providers.py:1-100]()
### PromptCallableBase 基类
```mermaid
classDiagram
class PromptCallableBase {
+_invoke_llm() LLMResponse
+_validate() ValidationResponse
}
class LiteLLMCallable {
+_invoke_llm() LLMResponse
}
class ManifestCallable {
+_invoke_llm() LLMResponse
}
PromptCallableBase <|-- LiteLLMCallable
PromptCallableBase <|-- ManifestCallable
```
## API 客户端集成
Guard 类可以与 Guardrails API 服务集成，实现远程存储和管理：
```python
from guardrails import Guard
from guardrails.api_client import GuardrailsClient
client = GuardrailsClient(base_url="https://api.guardrails.ai")
# 上传 Guard 配置
client.upsert_guard(guard)
# 获取已存储的 Guard
remote_guard = client.fetch_guard("my-guard-name")
```
### API 客户端方法
| 方法 | 说明 | 异步版本 |
|------|------|----------|
| upsert_guard | 创建或更新 Guard | aupsert_guard |
| fetch_guard | 获取指定名称的 Guard | afetch_guard |
| list_guards | 列出所有 Guard | alist_guards |
资料来源：[guardrails/api_client.py:1-150]()
## 调用追踪系统
### TraceHandler
TraceHandler 是一个线程安全的追踪系统，用于记录 Guard 的调用历史：
```python
from guardrails.call_tracing.trace_handler import TraceHandler
# 写入日志
writer = TraceHandler()
writer.log(
"my_guard", # guard 名称
0.0, # 开始时间
1.0, # 结束时间
"原始输出", # LLM 原始输出
"处理后输出", # 验证后输出
"异常信息" # 异常（如有）
)
# 读取日志
reader = TraceHandler.get_reader()
for trace in reader.tail_logs():
print(trace)
```
资料来源：[guardrails/call_tracing/trace_handler.py:1-80]()
### 日志存储
默认情况下，日志存储在临时目录中：
```bash
${TMPDIR}/guardrails_calls.db
```
可通过环境变量覆盖：
```bash
export GUARDRAILS_LOG_FILE_PATH="/path/to/logs.db"
```
## 使用示例
### 基础验证示例
```python
from guardrails import Guard, OnFailAction
from guardrails.hub import RegexMatch
# 创建带验证规则的 Guard
guard = Guard().use(
RegexMatch,
regex=r"\(?\d{3}\)?-? *\d{3}-? *-?\d{4}",
on_fail=OnFailAction.EXCEPTION
)
# 验证通过
result = guard.validate("123-456-7890")
print(result) # Validation passed
# 验证失败
try:
guard.validate("1234-789-0000")
except Exception as e:
print(e) # Result must match \(?\d{3}\)?-? *\d{3}-? *-?\d{4}
```
### 结构化输出示例
```python
from pydantic import BaseModel, Field
from guardrails import Guard
class Pet(BaseModel):
pet_type: str = Field(description="宠物种类")
name: str = Field(description="宠物名称")
guard = Guard.for_pydantic(Pet)
# 调用 LLM 并获取结构化输出
result = guard(
client=openai.ChatCompletion,
prompt="给我推荐一只宠物",
model="gpt-4"
)
print(result.validated_output)
# 输出: Pet(pet_type="dog", name="Max")
```
### 多验证器组合示例
```python
from guardrails import Guard, OnFailAction
from guardrails.hub import CompetitorCheck, ToxicLanguage
guard = Guard().use(
CompetitorCheck(
competitors=["Apple", "Microsoft", "Google"],
on_fail=OnFailAction.EXCEPTION
),
ToxicLanguage(
threshold=0.5,
validation_method="sentence",
on_fail=OnFailAction.EXCEPTION
)
)
# 验证通过的场景
guard.validate("An apple a day keeps a doctor away.")
# 验证失败的场景
try:
guard.validate("Shut the hell up! Apple just released a new iPhone.")
except Exception as e:
print(e)
```
## 最佳实践
### 1. 合理的重试配置
```python
# 设置合理的重试次数和消息
guard = Guard.for_pydantic(
Pet,
reask_messages=[
{"role": "user", "content": "请重新生成，必须包含 pet_type 和 name 字段"}
]
)
```
### 2. 使用适当的 on_fail 策略
| 场景 | 推荐策略 |
|------|----------|
| 严格数据验证 | EXCEPTION |
| 允许自动修正 | FIX |
| 非关键字段 | FILTER |
| 自定义处理 | CUSTOM |
### 3. 调用历史记录
```python
# 获取最近一次调用的历史
call = guard.history[-1]
print(f"调用 ID: {call.id}")
print(f"迭代次数: {len(call.iterations)}")
for iteration in call.iterations:
print(f" - 步骤数: {len(iteration.steps)}")
```
## 总结
Guard 类是 Guardrails AI 框架的核心组件，它：
- 提供了统一的接口来验证 LLM 输出
- 支持多种创建方式（RAIL、Pydantic、自定义验证器）
- 内置完整的调用历史追踪系统
- 支持与多种 LLM 提供者无缝集成
- 提供了灵活的错误处理机制
通过合理使用 Guard 类，开发者可以确保 LLM 应用的输出质量和可靠性。
---
## Schema 系统
### 相关页面
相关主题：[Guard 类详解](#page-guard-class), [验证器基础](#page-validators)
相关源码文件
以下源码文件用于生成本页说明：
- [guardrails/schema/pydantic_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/pydantic_schema.py)
- [guardrails/schema/rail_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/rail_schema.py)
- [guardrails/schema/parser.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/parser.py)
- [guardrails/schema/primitive_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/primitive_schema.py)
- [guardrails/schema/validator.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/schema/validator.py)
- [guardrails/classes/schema/processed_schema.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/schema/processed_schema.py)
# Schema 系统
## 概述
Schema 系统是 Guardrails 框架的核心组件之一，负责定义和管理 LLM 输出的验证规范。该系统提供了从多种模式定义（RAIL、Pydantic、JSON Schema）到内部验证结构的转换能力，确保 LLM 生成的内容符合预定义的结构和约束条件。
Schema 系统的主要职责包括：
- **模式解析**：将用户定义的 RAIL 字符串、Pydantic 模型或 JSON Schema 解析为内部表示
- **类型映射**：支持字符串、日期、时间、日期时间、百分比、枚举等多种数据类型的映射
- **验证器集成**：将验证器（Validator）绑定到特定的 Schema 字段
- **输出规范生成**：将 JSON Schema 反向转换为 RAIL 输出规范
资料来源：[guardrails/schema/rail_schema.py:1-50]()
## 架构设计
### 核心组件
```mermaid
graph TD
A[用户定义 Schema] --> B{输入格式}
B --> C[RAIL 字符串]
B --> D[Pydantic 模型]
B --> E[JSON Schema]
C --> F[rail_schema.py]
D --> G[pydantic_schema.py]
E --> H[primitive_schema.py]
F --> I[Schema Parser]
G --> I
H --> I
I --> J[ProcessedSchema]
J --> K[Guard 验证器]
```
### 目录结构
```
guardrails/schema/
├── __init__.py # 模块初始化
├── pydantic_schema.py # Pydantic 模型转换
├── parser.py # 核心解析器
├── primitive_schema.py # 基础类型处理
├── rail_schema.py # RAIL 格式转换
├── validator.py # 验证器绑定
└── processed_schema.py # 处理后的模式类
```
## 核心模块详解
### RailSchema 模块
`rail_schema.py` 负责 RAIL（Rail Action Markup Language）格式与内部 Schema 之间的转换。
#### 主要功能
| 函数 | 功能描述 |
|------|----------|
| `build_element()` | 递归构建 XML 元素树 |
| `build_string_element()` | 构建字符串类型元素 |
| `json_schema_to_rail_output()` | JSON Schema 转 RAIL 输出规范 |
#### 支持的数据类型
| RailTypes | 说明 | 格式属性 |
|-----------|------|----------|
| `STRING` | 字符串类型 | 无 |
| `DATE` | 日期类型 | `date-format` |
| `TIME` | 时间类型 | `time-format` |
| `DATETIME` | 日期时间类型 | `datetime-format` |
| `PERCENTAGE` | 百分比类型 | 无 |
| `ENUM` | 枚举类型 | `values` 属性 |
| `FLOAT` | 浮点数 | 无 |
| `INTEGER` | 整数 | 无 |
| `BOOL` | 布尔值 | 无 |
资料来源：[guardrails/schema/rail_schema.py:50-120]()
#### 类型映射逻辑
```python
def build_string_element(...):
if format.internal_type == RailTypes.DATE:
type = RailTypes.DATE
date_format = format.internal_format_attr
if date_format:
attributes["date-format"] = date_format
elif format.internal_type == RailTypes.TIME:
type = RailTypes.TIME
# ...
```
资料来源：[guardrails/schema/rail_schema.py:80-95]()
### JSON Schema 转换流程
```mermaid
graph LR
A[JSON Schema] --> B[jsonref.replace_refs]
B --> C[解引用后的 Schema]
C --> D[build_element]
D --> E[XML Element 树]
E --> F[canonicalize]
F --> G[RAIL 输出字符串]
```
关键转换函数：
```python
def json_schema_to_rail_output(
json_schema: Dict[str, Any],
validator_map: ValidatorMap
) -> str:
dereferenced_json_schema = jsonref.replace_refs(json_schema)
output_element = build_element(
dereferenced_json_schema,
validator_map,
json_path="$",
elem=Element,
tag_override="output",
)
return canonicalize(ET.tostring(output_element, pretty_print=True))
```
资料来源：[guardrails/schema/rail_schema.py:35-45]()
### Pydantic Schema 模块
`pydantic_schema.py` 提供了将 Pydantic `BaseModel` 转换为 Guardrails Schema 的能力。
#### 创建 Guard 实例
```python
from guardrails import Guard
from pydantic import BaseModel, Field
class Pet(BaseModel):
pet_type: str = Field(description="Species of pet")
name: str = Field(description="a unique pet name")
# 从 Pydantic 模型创建 Guard
guard = Guard.for_pydantic(Pet)
```
资料来源：[guardrails/guard.py:100-120]()
### ProcessedSchema 类
`processed_schema.py` 定义了处理后的 Schema 数据结构，包含以下关键属性：
| 属性 | 类型 | 说明 |
|------|------|------|
| `_id` | `str \| None` | 唯一标识符 |
| `iterations` | `Stack[Iteration]` | 执行迭代栈 |
| `inputs` | `CallInputs` | 调用输入参数 |
| `exception` | `Exception \| None` | 异常信息 |
```python
class Call:
"""表示 Guard 的单次执行"""
_id: str | None = None
iterations: Stack[Iteration] = Field(
description="迭代栈",
default_factory=Stack,
)
inputs: CallInputs = Field(
description="调用输入",
default_factory=CallInputs,
)
exception: Optional[Exception] = Field(
description="异常",
default=None,
)
```
资料来源：[guardrails/classes/schema/processed_schema.py:20-45]()
### Validator 模式绑定
`validator.py` 负责将验证器与 Schema 字段进行绑定，支持以下配置选项：
| 参数 | 类型 | 说明 |
|------|------|------|
| `on_fail` | `OnFailAction` | 验证失败时的动作 |
| `args` | `List[Any]` | 验证器位置参数 |
| `kwargs` | `Dict[str, Any]` | 验证器关键字参数 |
## Guard 与 Schema 的集成
### 从 RAIL 创建 Guard
```python
from guardrails import Guard
rail_string = """
"""
guard = Guard.from_rail_string(rail_string)
```
内部调用流程：
```mermaid
graph TD
A[rail_string] --> B[rail_string_to_schema]
B --> C[Schema 对象]
C --> D[Guard._for_rail_schema]
D --> E[Guard 实例]
```
资料来源：[guardrails/guard.py:80-100]()
### 从 Pydantic 创建 Guard
```python
from guardrails import Guard
from pydantic import BaseModel
class OutputModel(BaseModel):
name: str
age: int
guard = Guard.for_pydantic(OutputModel)
```
支持的方法签名：
| 方法 | 参数 | 返回类型 |
|------|------|----------|
| `for_rail` | `rail_string: str` | `Guard` |
| `for_pydantic` | `output_class: ModelOrListOfModels` | `Guard` |
资料来源：[guardrails/guard.py:100-140]()
## 调用输入管理
### CallInputs 数据结构
`call_inputs.py` 定义了 LLM 调用时的输入参数：
```python
class CallInputs(BaseModel):
llm_api: Optional[Callable[[Any], Awaitable[Any]]] = None
prompt: Optional[str] = Field(default=None, alias="prompt")
prompt_params: Optional[Dict[str, Any]] = Field(
default=None,
description="Parameters to be formatted into the messages.",
alias="promptParams",
)
num_reasks: Optional[int] = Field(
default=None,
description="The total number of times the LLM can be called",
alias="numReasks",
)
metadata: Optional[Dict[str, Any]] = Field(
default=None,
description="Additional data to be used by Validators",
)
stream: Optional[bool] = Field(
default=None, description="Whether to use streaming."
)
```
| 字段 | 默认值 | 说明 |
|------|--------|------|
| `llm_api` | `None` | LLM API 回调函数 |
| `prompt` | `None` | 提示词模板 |
| `prompt_params` | `None` | 格式化参数 |
| `num_reasks` | `None` | 最大重新请求次数 |
| `metadata` | `None` | 元数据字典 |
| `full_schema_reask` | `None` | 是否全量重新请求 |
| `stream` | `None` | 是否启用流式输出 |
资料来源：[guardrails/classes/history/call_inputs.py:20-50]()
## Schema 处理流程
### 完整验证流程
```mermaid
graph TD
A[输入数据] --> B[Guard.__call__]
B --> C[Call 创建]
C --> D[Schema 解析]
D --> E[LLM 调用]
E --> F[输出验证]
F --> G{验证通过?}
G -->|是| H[返回结果]
G -->|否| I{num_reasks > 0?}
I -->|是| J[num_reasks - 1]
J --> E
I -->|否| K[抛出异常]
H --> L[Iteration 记录]
K --> L
```
### 迭代追踪
每次调用 `Guard.__call__`、`Guard.parse` 或 `Guard.validate` 都会创建一个 `Call` 实例，其中包含：
- **初始验证轮次**：`Iteration` 栈
- **重请求轮次**：每次重新请求都会产生新的 `Iteration`
```python
@computed_field
@property
def id(self) -> str:
"""唯一标识符，用于标识 Guard 的特定执行"""
if not self._id:
self._id = str(object_id(self))
return self._id
```
资料来源：[guardrails/classes/history/call.py:30-45]()
## 类型系统
### 简单类型枚举
| 类型名 | Python 类型 | 说明 |
|--------|-------------|------|
| `STRING` | `str` | 字符串 |
| `INTEGER` | `int` | 整数 |
| `FLOAT` | `float` | 浮点数 |
| `BOOLEAN` | `bool` | 布尔值 |
| `ARRAY` | `list` | 数组 |
| `OBJECT` | `dict` | 对象 |
| `NULL` | `None` | 空值 |
### 特殊格式类型
```python
# 日期时间格式支持
DATETIME: str # 支持 datetime-format 属性
DATE: str # 支持 date-format 属性
TIME: str # 支持 time-format 属性
PERCENTAGE: str # 百分比字符串
ENUM: str # 枚举值列表
```
资料来源：[guardrails/schema/rail_schema.py:100-140]()
## 配置与扩展
### 自定义 Schema 处理器
开发者可以通过继承基础类来扩展 Schema 功能：
```python
from guardrails.schema import BaseSchema
class CustomSchema(BaseSchema):
def validate(self, value):
# 自定义验证逻辑
pass
```
### 验证器注册
验证器通过 `ValidatorMap` 注册到 Schema 系统：
```python
validator_map: ValidatorMap # 全局验证器映射表
```
## 最佳实践
1. **使用 Pydantic 模型定义复杂结构**：更声明式，类型安全
2. **明确指定日期/时间格式**：避免歧义
3. **合理设置 num_reasks**：平衡验证严格性和用户体验
4. **利用 metadata 传递上下文**：验证器可访问运行时信息
## 总结
Schema 系统是 Guardrails 框架的基础架构层，提供了从多种模式定义格式到统一验证结构的转换能力。通过模块化的设计，支持 RAIL、Pydantic、JSON Schema 等多种输入方式，并提供灵活的验证器集成机制。该系统与 Guard 类紧密协作，实现了 LLM 输出的结构化和可验证性。
---
## 验证流程与 Runner
### 相关页面
相关主题：[Guard 类详解](#page-guard-class), [验证器基础](#page-validators)
相关源码文件
以下源码文件用于生成本页说明：
- [guardrails/run/runner.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/run/runner.py)
- [guardrails/run/async_runner.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/run/async_runner.py)
- [guardrails/run/stream_runner.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/run/stream_runner.py)
- [guardrails/run/utils.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/run/utils.py)
- [guardrails/classes/history/call.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call.py)
- [guardrails/classes/history/iteration.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/iteration.py)
# 验证流程与 Runner
## 概述
Guardrails 的验证流程是整个框架的核心执行机制，负责协调 LLM 响应与验证器之间的交互。当用户调用 `Guard.__call__`、`Guard.parse` 或 `Guard.validate` 方法时，框架会通过 Runner 组件来执行验证逻辑。
Runner 系统采用模块化设计，支持同步、异步和流式三种执行模式。这种设计允许 Guardrails 适应不同的应用场景，从简单的批量验证到实时流式响应处理。
## 核心架构组件
### Call（调用）对象
`Call` 类是 Guard 执行过程的顶层记录容器。每次调用 `Guard.__call__`、`Guard.parse` 或 `Guard.validate` 时，都会创建一个新的 `Call` 实例。
```python
class Call:
"""A Call represents a single execution of a Guard."""
_id: str | None = None
iterations: Stack[Iteration] = Field(
description="A stack of iterations for each step/reask that occurred.",
default_factory=Stack,
)
inputs: CallInputs = Field(
description="The inputs as passed in to Guard.__call__ or Guard.parse",
default_factory=CallInputs,
)
exception: Optional[Exception] = Field(
description="The exception that interrupted the run.",
default=None,
)
```
`Call` 对象的核心属性：
| 属性 | 类型 | 说明 |
|------|------|------|
| `_id` | `str \| None` | Call 的唯一标识符 |
| `iterations` | `Stack[Iteration]` | 执行过程中的迭代栈 |
| `inputs` | `CallInputs` | 传递给 Guard 的输入参数 |
| `exception` | `Optional[Exception]` | 执行过程中捕获的异常 |
`Call.id` 是一个计算属性，通过 `object_id(self)` 生成唯一标识符，可用于追踪特定的 Guard 执行：
```python
@computed_field
@property
def id(self) -> str:
"""The unique identifier for this Call."""
if not self._id:
self._id = str(object_id(self))
return self._id
```
资料来源：[guardrails/classes/history/call.py:16-45]()
### Iteration（迭代）对象
`Iteration` 代表验证过程中的单个迭代步骤。每次重新请求（reask）或验证循环都会创建一个新的 `Iteration` 实例，并压入 `Call.iterations` 栈中。
迭代过程包含以下关键阶段：
1. **初始验证轮次**：首次对 LLM 输出进行验证
2. **Reask 阶段**：如果验证失败，触发重新请求机制
3. **多轮迭代**：持续验证直到通过或达到最大重试次数
资料来源：[guardrails/classes/history/iteration.py]()
## Runner 执行模式
Guardrails 提供了三种 Runner 实现，分别适用于不同的使用场景：
### 同步 Runner
`Runner` 是标准的同步执行器，适用于批量处理和非实时应用场景。它按顺序执行验证步骤，阻塞当前线程直到完成。
```python
# 典型使用方式
from guardrails import Guard
guard = Guard.from_pydantic(Pet)
result = guard(
client,
prompt_params={...}
)
```
### 异步 Runner
`AsyncRunner` 支持异步执行，利用 Python 的 `asyncio` 实现并发处理。这对于需要同时处理多个验证请求的高吞吐量应用至关重要。
```python
# 典型使用方式
from guardrails import Guard
guard = Guard.from_pydantic(Pet)
result = await guard.ainvoke(
client,
prompt_params={...}
)
```
异步 Runner 保持了与同步 Runner 相同的验证逻辑，但通过 `async/await` 模式提升了资源利用率。
### 流式 Runner
`StreamRunner` 专门为流式 LLM 响应设计。当 LLM 支持流式输出时，Runner 可以边接收响应边进行验证，提供更好的实时性和更低的内存占用。
```python
# 典型使用方式
for token in guard.stream(
client,
prompt_params={...}
):
print(token, end="", flush=True)
```
## 验证流程图
```mermaid
graph TD
A[Guard.__call__ / validate] --> B[创建 Call 实例]
B --> C[创建 Iteration 栈]
C --> D[调用 LLM]
D --> E{解析 LLM 响应}
E -->|成功解析| F{运行验证器}
E -->|解析失败| G[触发 Reask]
F -->|验证通过| H[返回验证结果]
F -->|验证失败| G
G -->|达到最大重试| I[抛出异常]
G -->|未达最大重试| D
H --> J[保存到 History]
I --> J
```
## 验证执行流程详解
### 第一阶段：输入处理
在调用 Runner 之前，Guard 会准备以下输入数据：
- **Prompt 模板**：包含 `${gr.complete_json_suffix_v2}` 等占位符的提示词
- **Prompt 参数**：`prompt_params` 字典，用于填充模板变量
- **LLM 客户端**：支持多种 LLM 提供商（OpenAI、Anthropic、LiteLLM 等）
### 第二阶段：LLM 调用
Runner 负责与 LLM 交互，获取原始响应。根据配置的调用方式，可能是：
- **Function Calling**：使用 LLM 的函数调用能力获取结构化输出
- **Prompt Optimization**：通过优化提示词引导 LLM 生成符合 schema 的 JSON
### 第三阶段：验证循环
验证循环是 Runner 的核心逻辑：
```mermaid
graph LR
A[获取 LLM 响应] --> B[解析响应]
B --> C{解析成功?}
C -->|否| D[记录异常]
C -->|是| E[运行验证器]
E --> F{所有验证通过?}
F -->|是| G[返回结果]
F -->|否| H[执行 Fix/Reask]
H --> I{达到最大重试?}
I -->|是| J[抛出异常]
I -->|否| A
```
### 第四阶段：History 记录
每个执行步骤都会记录到 History 中：
- `Call.inputs`：保存原始输入
- `Call.iterations`：保存每次迭代的详细记录
- `Call.exception`：如果执行中断，保存异常信息
```python
@field_serializer("iterations")
def serialize_iterations(
self, iterations: Stack[Iteration] | None
) -> list[dict[str, Any]] | None:
if iterations is not None:
return [
# 序列化的迭代数据
]
```
## Runner 工具函数
`guardrails/run/utils.py` 提供了 Runner 所需的核心工具函数：
| 函数 | 功能 |
|------|------|
| `get_llm_response_text` | 从 LLM 响应中提取文本内容 |
| `process_parsed_rail` | 处理解析后的 RAIL 规范 |
| `validate_parsed_rail` | 验证 RAIL 规范的正确性 |
| `extract_config_from_rail` | 从 RAIL 提取配置信息 |
这些工具函数支持 Runner 在不同执行阶段进行数据转换和验证。
## 执行状态管理
Runner 通过 `TracerMixin` 提供执行追踪能力：
```python
class TraceHandler(TracerMixin):
"""TraceHandler wraps the internal _SQLiteTraceHandler to make it multi-
thread safe."""
```
追踪系统使用 SQLite 数据库记录每次执行的详细信息：
- **日志文件位置**：可通过 `GUARDRAILS_LOG_FILE_PATH` 环境变量配置
- **默认位置**：`tempfile.gettempdir() + "/guardrails_calls.db"`
- **多线程安全**：通过单例模式和写前日志机制实现
```python
LOG_FILENAME = "guardrails_calls.db"
LOGFILE_PATH = os.environ.get(
"GUARDRAILS_LOG_FILE_PATH",
os.path.join(tempfile.gettempdir(), LOG_FILENAME),
)
```
## 与 LLM 提供商的集成
Runner 通过 `llm_providers.py` 中的适配器类与不同 LLM 提供商集成：
- **ManifestCallable**：支持使用 Manifest 库的 LLM
- **LiteLLMCallable**：支持 LiteLLM 封装的多种 LLM
- **PromptCallableBase**：所有提供商的基类
```python
class LiteLLMCallable(PromptCallableBase):
def _invoke_llm(
self,
text: Optional[str] = None,
model: str = "gpt-3.5-turbo",
messages: Optional[List[Dict]] = None,
*args,
**kwargs,
) -> LLMResponse:
"""Wrapper for Lite LLM completions."""
```
## 错误处理机制
验证流程中的错误处理采用分层策略：
1. **解析错误**：LLM 响应无法解析为预期格式
2. **验证错误**：LLM 响应通过解析但不满足验证器条件
3. **执行异常**：Runner 级别的异常（如 API 超时、网络错误）
```python
try:
guard.validate("1234-789-0000") # 验证失败
except Exception as e:
print(e) # 输出: Validation failed for field with errors: Result must match...
```
## 配置选项
创建 Guard 时可以通过多种方式配置验证流程：
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `output_class` | Pydantic 模型定义输出结构 | 必填 |
| `messages` | LLM 消息列表 | None |
| `reask_messages` | Reask 阶段使用的消息 | None |
| `name` | Guard 实例名称 | `gr-` + 对象ID |
| `output_formatter` | 输出格式化器 | None |
## 总结
Runner 系统是 Guardrails 验证流程的核心执行引擎，通过模块化的设计支持同步、异步和流式三种执行模式。`Call` 和 `Iteration` 类提供了完整的执行历史追踪能力，使调试和监控变得简单直观。理解 Runner 的工作原理对于深入掌握 Guardrails 框架、进行性能优化和故障排查至关重要。
---
## 验证器基础
### 相关页面
相关主题：[Guardrails Hub](#page-hub), [Schema 系统](#page-schema-system)
相关源码文件
以下源码文件用于生成本页说明：
- [guardrails/validator_base.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/validator_base.py)
- [guardrails/classes/validation/validation_result.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/validation/validation_result.py)
- [guardrails/classes/validation/validator_logs.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/validation/validator_logs.py)
- [guardrails/actions/filter.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/actions/filter.py)
- [guardrails/actions/refrain.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/actions/refrain.py)
- [guardrails/actions/reask.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/actions/reask.py)
- [guardrails/types/on_fail.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/types/on_fail.py)
# 验证器基础
## 概述
验证器（Validator）是 Guardrails 框架的核心组件，用于对 LLM（大型语言模型）生成的输出进行质量检查和验证。验证器充当输出与预期规范之间的桥梁，确保 LLM 响应符合预定义的数据结构、格式要求和内容约束。
### 核心职责
- **格式验证**：检查输出是否符合指定的数据格式（如正则表达式、JSON Schema）
- **内容验证**：检测敏感内容、不当语言或竞争对手提及
- **结构验证**：确保输出符合 Pydantic 模型或 RAIL 规范定义的结构
- **修复建议**：在验证失败时提供修正值或重新请求 LLM 生成
### 验证器在 Guard 架构中的位置
```mermaid
graph TD
A[用户输入/提示词] --> B[Guard 实例]
B --> C[验证器注册表 ValidatorMap]
C --> D[验证器链 Validator Chain]
D --> E{验证结果}
E -->|通过| F[ValidationOutcome 有效输出]
E -->|失败| G[OnFailAction 处理]
G -->|REASK| H[重新请求 LLM]
G -->|FILTER| I[过滤敏感内容]
G -->|REFRAIN| J[返回空/默认值]
G -->|EXCEPTION| K[抛出验证异常]
H --> D
```
## 验证结果模型
### ValidationOutcome
`ValidationOutcome` 是验证过程的返回结果，封装了验证的完整状态信息。
| 属性 | 类型 | 说明 |
|------|------|------|
| `validated_output` | `OT` | 验证后的输出值 |
| `reask_messages` | `List[Dict]` | 用于重新请求的消息列表 |
| `error` | `Exception` | 验证过程中发生的错误（如果有） |
| `validation_passed` | `bool` | 验证是否通过 |
| `structure_generated` | `bool` | 是否生成了结构化输出 |
资料来源：[guardrails/guard.py:420-450]()
### 验证日志 ValidatorLogs
每个验证步骤都会生成详细的日志记录，用于追踪和调试。
| 属性 | 说明 |
|------|------|
| `validator_name` | 验证器的名称 |
| `validator_value` | 当前验证的值 |
| `validation_result` | 验证结果对象 |
| `start_time` | 验证开始时间戳 |
| `end_time` | 验证结束时间戳 |
| `error` | 验证错误信息 |
资料来源：[guardrails/classes/validation/validator_logs.py]()
## 失败处理策略
### OnFailAction 枚举
当验证失败时，系统根据配置的 `OnFailAction` 决定如何处理。
| 动作 | 说明 | 使用场景 |
|------|------|----------|
| `REASK` | 重新向 LLM 请求修正的输出 | 自动修正格式错误 |
| `FILTER` | 过滤或替换敏感内容 | 内容安全检查 |
| `REFRAIN` | 返回空值或默认值 | 避免生成不当内容 |
| `EXCEPTION` | 抛出验证异常 | 严格模式下的错误处理 |
| `FIX` | 使用预定义的修复值 | 已知错误模式的批量修正 |
资料来源：[guardrails/types/on_fail.py]()
### 各动作的处理流程
#### 过滤动作 (Filter)
过滤动作用于处理需要移除或替换的敏感内容：
```python
# 伪代码示例
if validation_result.failed:
if on_fail == OnFailAction.FILTER:
return filtered_value
```
#### 克制动作 (Refrain)
克制动作在检测到违规内容时返回空值或中性替代：
```python
# 克制动作返回空输出
if validation_result.failed and on_fail == OnFailAction.REFRAIN:
return None
```
资料来源：[guardrails/actions/filter.py]()
资料来源：[guardrails/actions/refrain.py]()
#### 重新请求动作 (Reask)
重新请求是最常用的自动修正机制，会收集所有验证失败项并生成新的提示词：
```mermaid
graph LR
A[初始验证失败] --> B[gather_reasks 收集 ReAsk]
B --> C[构建 reask_messages]
C --> D[调用 LLM 重新生成]
D --> E[再次验证]
E -->|通过| F[返回修正结果]
E -->|失败| G{达到最大次数?}
G -->|否| C
G -->|是| H[返回最终结果/错误]
```
资料来源：[guardrails/actions/reask.py]()
## ReAsk 系统
### ReAsk 数据结构
当验证失败需要重新请求时，系统使用 `ReAsk` 对象记录失败信息：
| 属性 | 说明 |
|------|------|
| `path` | 失败字段的 JSON 路径 |
| `original_value` | 原始失败值 |
| ` fail_results` | 失败验证结果列表 |
| `expected_format` | 期望的格式描述 |
### 递归收集机制
`gather_reasks` 函数递归遍历验证输出，收集所有需要重新请求的字段：
```python
def gather_reasks(validated_output):
if isinstance(validated_output, ReAsk):
return [validated_output], None
if isinstance(validated_output, str):
return [], validated_output
# 递归处理字典和列表类型
```
资料来源：[guardrails/actions/reask.py:50-80]()
## 验证器基类
### Validator 抽象基类
所有自定义验证器都继承自 `Validator` 基类，实现以下核心方法：
| 方法 | 说明 |
|------|------|
| `validate(value, ...)` | 执行验证逻辑 |
| `fix(...)` | 提供修复建议 |
| `get_azure_function(...)` | Azure Functions 集成 |
### 验证器调用追踪
框架集成了 OpenTelemetry 追踪系统，记录每次验证的执行情况：
```python
# 验证器执行时会创建 span
validator_span = tracer.start_span(f"validator/{validator_name}")
# 记录输入值、初始化参数、执行结果
add_validator_attributes(
validator_name=validator_name,
result=resp,
init_kwargs=init_kwargs,
validation_session_id=validation_session_id,
)
```
资料来源：[guardrails/telemetry/validator_tracing.py]()
## 验证器在 Guard 中的使用
### 注册验证器
通过 `Guard.use()` 方法注册验证器：
```python
from guardrails import Guard, OnFailAction
from guardrails.hub import RegexMatch, CompetitorCheck
guard = Guard().use(
RegexMatch(regex=r"\d{4}", on_fail=OnFailAction.EXCEPTION),
CompetitorCheck(["Apple", "Google"], on_fail=OnFailAction.FILTER)
)
```
### 获取已注册的验证器
```python
# 获取 output 级别所有验证器
output_validators = guard.get_validators(on="output")
# 获取特定字段的验证器
field_validators = guard.get_validators(on="$.pet_type")
```
### 验证流程
```mermaid
sequenceDiagram
participant U as 用户
participant G as Guard
participant V as ValidatorMap
participant Val as Validator
participant LLM as LLM API
U->>G: guard.validate(llm_output)
G->>V: 获取相关验证器
V-->>G: 验证器列表
loop 遍历每个验证器
G->>Val: validate(value)
Val-->>G: ValidationResult
end
G->>G: 处理失败结果
alt 验证通过
G-->>U: ValidationOutcome.validated_output
else 验证失败
G->>G: 根据 OnFailAction 处理
alt REASK
G->>LLM: 发送 reask_messages
LLM-->>G: 修正后的输出
G->>G: 递归验证
else EXCEPTION
G-->>U: 抛出 ValidationException
end
end
```
## 调用历史记录
### Call 数据结构
每次调用 Guard 都会生成 `Call` 对象，记录完整的执行历史：
| 属性 | 说明 |
|------|------|
| `id` | 唯一标识符 |
| `iterations` | 执行迭代栈（初始验证 + 每次 reask） |
| `inputs` | 输入参数（prompt、llm_api 等） |
| `exception` | 中断执行的异常（如果有） |
### Iteration 数据结构
单个迭代包含：
- `validator_logs`：本次迭代中所有验证器的执行日志
- `llm_response`：LLM 的原始响应
- `parsed_output`：解析后的输出
- `validation_response`：验证结果
资料来源：[guardrails/classes/history/call.py]()
## 验证器开发模板
### 创建新验证器
使用 CLI 命令创建验证器模板：
```bash
guardrails hub create-validator MyValidator ./my_validator.py
```
生成的模板包含：
```python
from guardrails import Validator
from guardrails.validators import ValidationResult
class MyValidator(Validator):
"""验证器描述"""
def __init__(self, arg_1: str, on_fail: str = None):
super().__init__(on_fail=on_fail)
self.arg_1 = arg_1
def validate(self, value, **kwargs) -> ValidationResult:
# 验证逻辑
if not self._is_valid(value):
return ValidationResult(
outcome="fail",
error_message="验证失败的原因"
)
return ValidationResult(outcome="pass")
```
资料来源：[guardrails/cli/hub/create_validator.py]()
## 最佳实践
### 1. 验证器组合策略
| 场景 | 推荐验证器组合 |
|------|----------------|
| 数据提取 | `RegexMatch` + `ValidRange` |
| 内容安全 | `CompetitorCheck` + `ToxicLanguage` |
| 结构化输出 | Pydantic 模型 + 自定义字段验证器 |
### 2. OnFailAction 选择指南
- **严格模式**：使用 `EXCEPTION` 确保不返回无效数据
- **容错模式**：使用 `REASK` 自动修正轻微格式错误
- **安全模式**：使用 `FILTER` 或 `REFRAIN` 处理敏感内容
### 3. 性能注意事项
- 避免在验证器中执行阻塞 I/O 操作
- 使用 `skip_reask_when_valid` 参数避免不必要的重新请求
- 对于复杂验证逻辑，考虑异步实现
## 相关资源
- [Guardrails Hub](https://guardrailsai.com/hub/) - 官方验证器市场
- [验证器模板仓库](https://github.com/guardrails-ai/validator-template) - 复杂验证器开发指南
- [API 参考文档](https://docs.guardrailsai.com/) - 完整的 API 说明
---
## Guardrails Hub
### 相关页面
相关主题：[验证器基础](#page-validators), [CLI 命令行工具](#page-cli)
相关源码文件
以下源码文件用于生成本页说明：
- [guardrails/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)
- [guardrails/cli/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/install.py)
- [guardrails/cli/hub/create_validator.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/create_validator.py)
- [README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)
# Guardrails Hub
## 概述
Guardrails Hub 是 Guardrails 项目的验证器分发与共享平台，为用户提供了一个集中式的验证器市场，类似于 Python 生态中的 PyPI。Hub 的核心功能是允许用户从中央仓库安装、社区贡献者提交新的验证器，以及管理本地已安装的验证器模块。
通过 Guardrails Hub，用户可以快速获取预构建的验证器（如正则匹配、竞争对手检查、有害内容检测等），无需从头编写验证逻辑。Hub 采用语义化版本控制，支持灵活的版本约束，确保项目的依赖稳定性。
**核心特点：**
- **即装即用**：通过 CLI 一键安装验证器
- **版本管理**：支持语义化版本约束（如 `~=1.4`、`>=1.4,==1.*`）
- **模块导出**：统一的导入接口 `from guardrails.hub import {ValidatorName}`
- **本地模型支持**：部分验证器支持本地模型推理
资料来源：[README.md:1-20](https://github.com/guardrails-ai/guardrails/blob/main/README.md)
## 架构设计
### 系统组件
Guardrails Hub 由以下核心组件构成：
| 组件 | 文件位置 | 职责 |
|------|----------|------|
| Hub CLI | `guardrails/cli/hub/` | 提供 hub 命令行接口（install、list、submit、uninstall、create-validator） |
| 安装服务 | `guardrails/hub/install.py` | 处理验证器包的下载、安装、依赖解析 |
| 包服务 | `validator_package_service.py` | 管理验证器清单、版本解析、包安装 |
| 注册表 | `guardrails/hub/registry.py` | 维护已安装验证器的元数据注册 |
### 安装流程
```mermaid
graph TD
A[用户执行 guardrails hub install] --> B[验证包 URI 和版本]
B --> C{本地模型是否必需}
C -->|是| D[确认安装本地模型]
C -->|否| E[跳过]
D --> F[获取 Manifest 清单]
F --> G[下载依赖]
G --> H[执行 Pip 安装]
H --> I[加载模块]
I --> J[返回已安装的验证器模块]
```
资料来源：[guardrails/hub/install.py:50-90](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)
## URI 规范与版本控制
### Hub URI 格式
Guardrails Hub 使用统一的 URI 格式来标识验证器资源：
```
hub://guardrails/{validator_name}[~={version}]
```
**格式说明：**
| 组成部分 | 说明 | 示例 |
|----------|------|------|
| `hub://` | 协议前缀，标识来自 Hub | - |
| `guardrails` | 命名空间，通常为官方或用户名 | `guardrails` |
| `validator_name` | 验证器名称（snake_case） | `regex_match` |
| `~={version}` | 版本约束（可选） | `~=1.4`、`>=1.4,==1.*` |
资料来源：[guardrails/hub/install.py:30-40](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)
### 版本约束示例
```python
# 安装特定版本
install("hub://guardrails/regex_match~=1.4")
# 安装兼容版本
install("hub://guardrails/regex_match>=1.4,==1.*")
# 安装最新版本
install("hub://guardrails/regex_match")
```
资料来源：[guardrails/hub/install.py:25-35](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)
## CLI 命令参考
Guardrails Hub 通过 `guardrails hub` 子命令提供操作接口。
### 安装验证器
```bash
guardrails hub install hub://guardrails/regex_match
guardrails hub install hub://guardrails/competitor_check
```
**参数选项：**
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `package_uris` | List[str] | 必需 | 要安装的包 URI 列表 |
| `--local-models` / `--local` | bool | False | 安装本地模型用于离线推理 |
| `--quiet` / `-q` | bool | False | 静默模式，减少输出 |
| `--upgrade` | bool | False | 升级到最新版本 |
**本地模型安装确认：**
当验证器需要本地模型时，系统会提示用户确认：
```
This validator has a Guardrails AI inference endpoint available.
Would you still like to install the local models for local inference?
```
资料来源：[guardrails/cli/hub/install.py:20-50](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/install.py)
### 创建验证器模板
```bash
guardrails hub create-validator MyValidator
guardrails hub create-validator CustomCheck --filepath ./validators/my_check.py
```
此命令生成验证器模板文件，包含基础结构和必要的方法占位符：
```python
class MyValidator(Validator):
"""FIXME: A brief description of what your validator does."""
def __init__(self, arg_1: str, ...):
# FIXME: Replace with your custom init args
pass
def validate(self, value, ...):
# FIXME: Implement validation logic
pass
```
资料来源：[guardrails/cli/hub/create_validator.py:20-60](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/create_validator.py)
### 其他 CLI 命令
| 命令 | 说明 |
|------|------|
| `guardrails hub list` | 列出已安装的验证器 |
| `guardrails hub submit` | 提交验证器到 Hub |
| `guardrails hub uninstall` | 卸载已安装的验证器 |
## 验证器使用方式
### 基础导入与使用
安装完成后，通过以下方式导入和使用验证器：
```python
from guardrails import Guard, OnFailAction
from guardrails.hub import RegexMatch
# 创建 Guard 实例
guard = Guard().use(
RegexMatch,
regex=r"\(?\d{3}\)?-? *\d{3}-? *-?\d{4}",
on_fail=OnFailAction.EXCEPTION
)
# 验证通过
guard.validate("123-456-7890")
# 验证失败（抛出异常）
try:
guard.validate("1234-789-0000")
except Exception as e:
print(e)
```
资料来源：[README.md:30-55](https://github.com/guardrails-ai/guardrails/blob/main/README.md)
### 多个验证器组合
可以链式使用多个验证器：
```python
from guardrails import Guard, OnFailAction
from guardrails.hub import CompetitorCheck, ToxicLanguage
guard = Guard().use(
CompetitorCheck(
["Apple", "Microsoft", "Google"],
on_fail=OnFailAction.EXCEPTION
),
ToxicLanguage(
threshold=0.5,
validation_method="sentence",
on_fail=OnFailAction.EXCEPTION
)
)
# 验证通过的场景
guard.validate("An apple a day keeps a doctor away. This is good advice.")
```
资料来源：[README.md:55-80](https://github.com/guardrails-ai/guardrails/blob/main/README.md)
## 开发与贡献
### 创建新验证器
对于简单验证器，可使用 CLI 工具生成模板：
```bash
guardrails hub create-validator MyValidator
```
对于复杂验证器，建议使用官方模板仓库：
> https://github.com/guardrails-ai/validator-template
资料来源：[guardrails/cli/hub/create_validator.py:30-35](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/create_validator.py)
### 提交到 Hub
贡献者可以通过 `guardrails hub submit` 命令将自己开发的验证器提交到 Hub 进行审核。提交前请确保：
1. 验证器包含完整的文档字符串
2. 实现必要的 `__init__` 和 `validate` 方法
3. 提供使用示例
4. 所有测试通过
资料来源：[CONTRIBUTING.md:1-30](https://github.com/guardrails-ai/guardrails/blob/main/CONTRIBUTING.md)
### 开发环境设置
```bash
# 克隆仓库
git clone https://github.com/guardrails-ai/guardrails.git
cd guardrails
# 安装开发依赖
make dev
# 安装 pre-commit 钩子
pre-commit install
# 运行测试
make test
# 代码格式化
make autoformat
# 类型检查
make type
```
## 验证器清单示例
| 验证器名称 | 功能描述 | 必需参数 |
|-----------|----------|----------|
| `RegexMatch` | 正则表达式匹配验证 | `regex` |
| `CompetitorCheck` | 竞争对手名称检测 | `competitors: List[str]` |
| `ToxicLanguage` | 有害内容检测 | `threshold`, `validation_method` |
| `Summarizer` | 摘要生成（需本地模型） | - |
| `Chatbot` | 对话机器人（需本地模型） | - |
## 常见问题
**Q: 安装失败怎么办？**
检查网络连接和 pip 权限，确保已正确配置 PyPI 镜像源。
**Q: 如何指定验证器版本？**
在 URI 中添加版本约束：`hub://guardrails/regex_match~=1.4`
**Q: 验证器需要本地模型时如何处理？**
使用 `--local-models` 参数安装本地模型，或使用云端推理端点（默认行为）。
---
## CLI 命令行工具
### 相关页面
相关主题：[安装与配置](#page-installation), [Guardrails Hub](#page-hub), [Guardrails 服务器](#page-server)
相关源码文件
以下源码文件用于生成本页说明：
- [guardrails/cli/guardrails.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/guardrails.py)
- [guardrails/cli/create.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/create.py)
- [guardrails/cli/validate.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/validate.py)
- [guardrails/cli/db/db.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/db/db.py)
- [guardrails/cli/db/upgrade.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/db/upgrade.py)
- [guardrails/cli/db/downgrade.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/db/downgrade.py)
- [guardrails/cli/hub/__init__.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/__init__.py)
# CLI 命令行工具
## 概述
Guardrails CLI 是 Guardrails 框架提供的命令行界面工具，为开发者提供了一系列便捷的终端操作命令。通过 CLI，用户可以快速创建验证器、管理 Hub 模块、执行数据验证、配置本地环境以及启动 API 服务。CLI 工具采用模块化架构设计，将不同功能封装为独立的子命令模块，包括 Guard 管理、RAIL 文件创建、数据验证、数据库迁移以及 Hub 模块安装等核心功能。
CLI 基于 Typer 框架构建，充分利用了 Python 类型提示和命令补全功能，为用户提供流畅的命令行体验。所有的 CLI 命令都集成了日志系统，支持不同级别的日志输出，便于调试和监控操作状态。
## 架构设计
### 整体架构
```mermaid
graph TD
A["guardrails CLI 入口"] --> B["Typer 应用主框架"]
B --> C["guardrails 子命令"]
B --> D["hub 子命令"]
B --> E["create 子命令"]
B --> F["validate 子命令"]
B --> G["db 子命令"]
B --> H["start 子命令"]
C --> C1["Guard 状态管理"]
C --> C2["配置管理"]
D --> D1["install 安装命令"]
D --> D2["create-validator 创建验证器"]
D --> D3["search 搜索命令"]
E --> E1["RAIL 文件生成"]
E --> E2["Schema 模板"]
F --> F1["JSON 验证"]
F --> F2["输出校验"]
G --> G1["upgrade 升级"]
G --> G2["downgrade 降级"]
G --> G3["迁移管理"]
H --> H1["API 服务启动"]
H --> H2["环境配置"]
```
### 目录结构
```
guardrails/cli/
├── __init__.py # CLI 入口点
├── guardrails.py # Guard 状态管理命令
├── create.py # RAIL 文件创建命令
├── validate.py # 数据验证命令
├── hub/ # Hub 模块管理
│ ├── __init__.py # Hub CLI 主模块
│ ├── install.py # 安装验证器
│ ├── create_validator.py # 创建验证器模板
│ └── search.py # 搜索验证器
├── db/ # 数据库迁移
│ ├── db.py # 数据库配置
│ ├── upgrade.py # 升级命令
│ └── downgrade.py # 降级命令
├── start.py # API 服务启动
└── logger.py # 日志配置
```
## 核心模块详解
### Hub 模块
Hub 模块是 Guardrails CLI 的核心组成部分，负责管理验证器模块的安装、创建和搜索功能。通过 Hub，用户可以访问 Guardrails 官方验证器库，并将其安装到本地环境中使用。
#### 安装验证器
`hub install` 命令用于从 Guardrails Hub 安装验证器模块。该命令支持多种安装方式，包括从官方 Hub 安装特定验证器以及从 git 仓库安装自定义模块。
```mermaid
graph LR
A["输入包URI"] --> B["验证器ID解析"]
B --> C["获取模块清单"]
C --> D{"是否安装本地模型"}
D -->|是| E["确认安装"]
D -->|否| F["跳过本地模型"]
E --> G["下载依赖"]
F --> G
G --> H["pip 安装"]
H --> I["安装完成"]
```
**主要参数：**
| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `package_uris` | 列表/字符串 | 要安装的包URI列表 | 必需 |
| `-l, --local-models` | 布尔值 | 是否安装本地模型 | False |
| `-q, --quiet` | 布尔值 | 静默模式减少输出 | False |
| `--upgrade` | 布尔值 | 升级到最新版本 | False |
安装示例：
```bash
# 安装单个验证器
guardrails hub install hub://guardrails/regex_match
# 安装指定版本
guardrails hub install hub://guardrails/regex_match~=1.4
# 安装多个验证器
guardrails hub install hub://guardrails/competitor_check hub://guardrails/toxic_language
```
资料来源：[guardrails/cli/hub/install.py:1-50]()
#### 创建验证器
`hub create-validator` 命令用于快速创建验证器模板文件。该命令会根据提供的名称自动生成符合 Guardrails 规范的验证器代码框架。
```mermaid
graph TD
A["输入验证器名称"] --> B["名称格式转换"]
B --> C["snake_case 命名"]
B --> D["PascalCase 命名"]
C --> E["生成文件路径"]
D --> F["应用 Jinja2 模板"]
F --> G["写入 Python 文件"]
G --> H["创建完成"]
```
**模板包含内容：**
- 验证器类框架（继承自 `Validator` 基类）
- 初始化参数定义区域
- `validate` 方法骨架代码
- 示例测试用例（docstring 中）
- 文档注释模板
```bash
# 创建名为 MyValidator 的验证器
guardrails hub create-validator MyValidator
# 指定输出路径
guardrails hub create-validator MyValidator --filepath ./custom/path/my_validator.py
```
资料来源：[guardrails/cli/hub/create_validator.py:1-80]()
### 数据库迁移模块
数据库迁移模块负责管理 Guardrails 内部数据库的版本控制，支持升级和降级操作。该模块使用 Alembic 作为迁移引擎，确保数据库结构的平滑演进。
#### 数据库配置
`db` 命令组提供数据库相关的管理功能，包括迁移状态查看和版本控制操作。
资料来源：[guardrails/cli/db/db.py:1-30]()
#### 升级操作
`db upgrade` 命令将数据库迁移到指定版本或最新版本。迁移过程中会按顺序执行所有未应用的迁移文件。
| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `revision` | 字符串 | 目标版本标识 | head（最新） |
| `--sql` | 布尔值 | 仅生成 SQL 不执行 | False |
| `-x, --xarg` | 字符串 | 扩展参数传递 | None |
```bash
# 升级到最新版本
guardrails db upgrade head
# 升级到指定版本
guardrails db upgrade abc123
# 查看生成的 SQL 而不执行
guardrails db upgrade head --sql
```
资料来源：[guardrails/cli/db/upgrade.py:1-40]()
#### 降级操作
`db downgrade` 命令用于将数据库回滚到之前的版本。降级操作会按相反顺序撤销迁移。
| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `revision` | 字符串 | 目标版本标识 | -1（上一个版本） |
| `--sql` | 布尔值 | 仅生成 SQL 不执行 | False |
| `-x, --xarg` | 字符串 | 扩展参数传递 | None |
```bash
# 降级一个版本
guardrails db downgrade -1
# 降级到初始状态
guardrails db downgrade base
# 查看生成的 SQL 而不执行
guardrails db downgrade -1 --sql
```
资料来源：[guardrails/cli/db/downgrade.py:1-35]()
### 创建模块
`create` 命令用于从 Pydantic 模型或 JSON Schema 生成 RAIL 文件。RAIL（Reliable AI Application Language）是一种基于 XML 的规范语言，用于定义 LLM 输出的结构和验证规则。
#### 输入格式支持
| 输入类型 | 说明 | 支持参数 |
|----------|------|----------|
| Pydantic 模型 | Python 类继承 BaseModel | `output_class` |
| JSON Schema | 标准 JSON Schema 格式 | `json_schema` |
| Python 类 | 带有 Field 定义的类 | 自动推断 |
```python
# 从 Pydantic 模型创建 RAIL
from guardrails.cli import create
rail_xml = create.from_pydantic(MyModel)
print(rail_xml)
```
#### Schema 转换
create 模块内部集成了 Schema 转换功能，能够将 JSON Schema 映射为 RAIL 格式的元素结构。转换过程支持以下类型映射：
| JSON Schema 类型 | RAIL 元素 | 支持格式 |
|------------------|-----------|----------|
| string | string | date, time, datetime, percentage, enum |
| number | float | - |
| integer | integer | - |
| boolean | bool | - |
| array | list | - |
| object | object | - |
资料来源：[guardrails/schema/rail_schema.py:1-100]()
### 验证模块
`validate` 命令提供独立的验证功能，允许用户直接对输入数据进行验证而不需要通过 Python 代码调用 Guard 对象。
```bash
# 验证字符串是否符合正则表达式
guardrails validate --validator regex_match --regex "\d{4}-\d{2}-\d{2}" "2024-01-15"
# 验证 JSON 格式
guardrails validate --schema-path ./schema.json --input ./data.json
```
资料来源：[guardrails/cli/validate.py:1-50]()
### 服务启动模块
`start` 命令用于启动 Guardrails API 服务。该模块封装了 API 服务器的启动逻辑，提供端口配置、环境变量覆盖和热重载等功能。
```mermaid
graph TD
A["start 命令执行"] --> B{"检查 API 包安装"}
B -->|未安装| C["自动安装 guardrails-api"]
B -->|已安装| D["检查版本兼容性"]
C --> D
D --> E["加载环境配置"]
E --> F{"watch 模式"}
F -->|启用| G["开启热重载"]
F -->|禁用| H["标准启动"]
G --> I["启动 API 服务"]
H --> I
```
**主要参数：**
| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `--port` | 整数 | 服务监听端口 | 8000 |
| `--config` | 路径 | 配置文件路径 | None |
| `--env` | 路径 | 环境变量文件 | None |
| `--env-override` | 字典 | 环境变量覆盖 | None |
| `--watch` | 布尔值 | 启用热重载 | False |
```bash
# 基础启动
guardrails start
# 指定端口
guardrails start --port 9000
# 加载环境配置
guardrails start --env .env.production
# 启用热重载开发模式
guardrails start --watch
```
资料来源：[guardrails/cli/start.py:1-80]()
## 日志系统
Guardrails CLI 集成了统一的日志系统，支持多级别日志输出和彩色终端显示。
```python
# 可用的日志级别
LEVELS = {
"SPAM": 5, # 详细调试信息
"VERBOSE": 15, # 详细操作信息
"NOTICE": 25, # 重要提示
"SUCCESS": 35, # 成功操作
}
```
日志输出示例：
```bash
# 详细输出模式
guardrails hub install hub://guardrails/regex_match --verbose
# 静默模式
guardrails hub install hub://guardrails/regex_match --quiet
```
资料来源：[guardrails/cli/logger.py:1-20]()
## 使用流程示例
### 完整工作流程
```mermaid
graph LR
A["安装 guardrails-ai"] --> B["配置 CLI"]
B --> C["安装验证器"]
C --> D["创建/编写验证器"]
D --> E["创建 RAIL 文件"]
E --> F["编写 Python 代码"]
F --> G["运行验证"]
G --> H{"验证结果"}
H -->|通过| I["流程结束"]
H -->|失败| J["重新调整输入"]
J --> G
```
### 典型使用场景
#### 场景一：快速验证数据格式
```bash
# 1. 配置 CLI
guardrails configure
# 2. 安装验证器
guardrails hub install hub://guardrails/regex_match
# 3. 创建验证脚本
cat > validate_phone.py << EOF
from guardrails import Guard
from guardrails.hub import RegexMatch
guard = Guard().use(RegexMatch, regex=r"\d{3}-\d{4}")
result = guard.validate("123-4567")
print("验证通过" if result else "验证失败")
EOF
# 4. 执行验证
python validate_phone.py
```
#### 场景二：从 Pydantic 模型生成 RAIL
```bash
# 1. 编写 Pydantic 模型
cat > models.py << EOF
from pydantic import BaseModel, Field
class User(BaseModel):
name: str = Field(description="用户姓名")
email: str = Field(description="电子邮箱")
age: int = Field(description="年龄", ge=0)
EOF
# 2. 生成 RAIL 文件
guardrails create models.User --output user.rail
```
#### 场景三：构建和安装自定义验证器
```bash
# 1. 创建验证器模板
guardrails hub create-validator competitor_check
# 2. 编辑生成的 Python 文件
# 编辑 competitor_check.py 实现具体验证逻辑
# 3. 从本地路径安装
guardrails hub install ./competitor_check.py
# 4. 在代码中使用
python << EOF
from guardrails import Guard
from guardrails.hub import CompetitorCheck
guard = Guard().use(CompetitorCheck, competitors=["Apple", "Google"])
EOF
```
## 错误处理
CLI 工具采用统一的错误处理机制，确保用户获得清晰的错误信息和建议。
### 常见错误及解决方案
| 错误类型 | 错误信息 | 解决方案 |
|----------|----------|----------|
| 包未找到 | `Package not found in hub` | 检查包名拼写，确认包已发布 |
| 版本冲突 | `Version requirement failed` | 使用 `--upgrade` 参数升级 |
| 权限不足 | `Permission denied` | 使用 `sudo` 或虚拟环境 |
| 依赖缺失 | `Module not found` | 安装缺失的 Python 包 |
### 调试模式
```bash
# 启用详细日志
export GUARDRAILS_LOG_LEVEL=VERBOSE
guardrails hub install hub://guardrails/regex_match
# 显示完整堆栈跟踪
guardrails --traceback hub install hub://guardrails/regex_match
```
## 最佳实践
1. **使用虚拟环境**：建议在虚拟环境中安装 Guardrails，避免依赖冲突
2. **版本管理**：在项目中锁定 guardrails-ai 版本，确保复现性
3. **本地模型**：仅在需要离线运行验证时安装本地模型
4. **日志级别**：生产环境使用默认级别，开发环境使用详细日志
5. **自动化测试**：使用 `validate` 命令集成到 CI/CD 流程
## 总结
Guardrails CLI 提供了一套完整且易用的命令行工具集，覆盖了从验证器管理、RAIL 文件创建、数据验证到 API 服务部署的全流程。通过模块化的命令设计，用户可以根据需要灵活组合使用各项功能，提高开发效率。CLI 工具的日志系统、错误处理和参数验证机制确保了操作的可靠性和用户体验的流畅性。
---
## Guardrails 服务器
### 相关页面
相关主题：[CLI 命令行工具](#page-cli), [框架集成](#page-integrations)
相关源码文件
以下源码文件用于生成本页说明：
- [guardrails/cli/start.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/start.py)
- [guardrails/guard.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/guard.py)
- [guardrails/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/hub/install.py)
- [guardrails/cli/hub/install.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/cli/hub/install.py)
- [README.md](https://github.com/guardrails-ai/guardrails/blob/main/README.md)
- [guardrails/classes/history/call.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/classes/history/call.py)
# Guardrails 服务器
Guardrails 服务器是 Guardrails 框架提供的一项可选服务，用于部署和管理 Guardrails 验证能力。通过服务器模式，用户可以将验证逻辑集中管理，并以 API 服务的方式对外提供验证功能。本文详细介绍 Guardrails 服务器的架构、启动方式、配置方法以及与客户端的交互方式。
## 服务器概述
Guardrails 服务器基于 `guardrails-api` 包构建，提供了一个轻量级的 REST API 服务，用于执行 LLM 输出验证任务。服务器接收原始文本或结构化数据，通过配置的验证器（Validators）进行验证，并返回验证结果。
服务器的核心功能包括：
- **集中化验证**：将验证逻辑部署在服务器端，客户端无需本地安装验证器
- **API 服务**：提供 RESTful API 接口，支持远程验证调用
- **多验证器编排**：支持同时运行多个验证器，实现复杂的验证场景
- **历史记录追踪**：记录每次验证调用的详细信息，包括输入、输出和异常情况
- **Watch 模式**：支持开发模式下的热重载功能
## 系统架构
```mermaid
graph TD
A[客户端应用] -->|HTTP/REST API| B[Guardrails 服务器]
B --> C[guardrails-api 核心服务]
C --> D[验证器注册表]
D --> E[RegexMatch]
D --> F[CompetitorCheck]
D --> G[ToxicLanguage]
D --> H[其他验证器...]
B --> I[历史记录存储]
I --> J[Call 对象]
J --> K[Iteration 堆栈]
K --> L[验证步骤记录]
```
### 核心组件
| 组件名称 | 文件位置 | 功能描述 |
|---------|---------|---------|
| guardrails-api | guardrails_api/ | 核心服务器实现 |
| CLI 启动器 | guardrails/cli/start.py | 命令行启动入口 |
| 配置管理 | settings | 服务器配置管理 |
| 验证器服务 | guardrails/hub/ | 验证器安装与加载 |
| Guard 类 | guardrails/guard.py | 验证逻辑封装 |
## 启动服务器
### 环境准备
启动 Guardrails 服务器前，需要确保已安装 `guardrails-api` 包：
```bash
pip install guardrails-api>=0.2.1
```
服务器启动时会检查 `guardrails-api` 是否已安装，若未安装则自动提示安装。资料来源：[guardrails/cli/start.py:12-18]()
### 启动命令
使用 `guardrails start` 命令启动服务器：
```bash
guardrails start [选项]
```
**常用选项：**
| 选项 | 说明 | 默认值 |
|-----|------|-------|
| `--port` | 服务器监听端口 | 8000 |
| `--env` | 环境变量文件路径 | None |
| `--config` | 配置文件路径 | None |
| `--env-override` | 环境变量覆盖 | None |
| `--watch` | 启用 Watch 模式 | False |
### Watch 模式
启用 Watch 模式后，服务器会监视配置文件和验证器的变化，并自动重新加载：
```bash
guardrails start --watch
```
Watch 模式通过 `settings._watch_mode_enabled = True` 启用，适用于开发阶段。资料来源：[guardrails/cli/start.py:28-29]()
## 服务器配置
### 配置文件
Guardrails 服务器支持通过配置文件进行定制化设置。配置文件采用 Python 格式，定义服务器的各项参数。
### 环境变量覆盖
对于敏感配置（如 API 密钥），建议使用环境变量进行配置。`--env-override` 参数允许指定环境变量文件：
```bash
guardrails start --env-override /path/to/.env
```
> 注意：`env_override` 功能仅在 `guardrails-api>=0.3.0` 版本中可用。资料来源：[guardrails/cli/start.py:36-42]()
### 版本兼容性
服务器启动时会检查版本兼容性：
- **版本 < 0.3.0**：不支持 `env_override` 参数，调用 `start_api(env, config, port)`
- **版本 >= 0.3.0**：支持所有参数，包括 `env_override`
```python
if major == "0" and int(minor) < 3:
start_api(env, config, port)
else:
start_api(env, config, port, env_override)
```
资料来源：[guardrails/cli/start.py:44-52]()
## API 服务接口
### 验证端点
服务器提供标准的 REST API 端点供客户端调用：
```python
from guardrails import Guard, OnFailAction
# 创建 Guard 实例
guard = Guard().use(
RegexMatch, regex="\(?\d{3}\)?-? *\d{3}-? *-?\d{4}", on_fail=OnFailAction.EXCEPTION
)
# 通过 API 调用验证
response = guard.validate("123-456-7890")
```
### 验证流程
```mermaid
sequenceDiagram
participant Client as 客户端
participant Server as Guardrails 服务器
participant Guard as Guard 实例
participant Validator as 验证器
Client->>Server: POST /validate (待验证文本)
Server->>Guard: 创建/获取 Guard 实例
Guard->>Validator: 执行验证
Validator-->>Guard: 验证结果
Guard-->>Server: 验证响应
Server-->>Client: JSON 响应
```
## 验证器管理
### 安装验证器
通过 CLI 安装验证器到服务器：
```bash
guardrails hub install hub://guardrails/regex_match
guardrails hub install hub://guardrails/competitor_check
guardrails hub install hub://guardrails/toxic_language
```
安装过程包括：
1. **验证包 URI**：解析验证器标识符和版本
2. **获取清单**：从 Hub 获取验证器元数据和依赖
3. **安装依赖**：通过 pip 安装验证器及其依赖
4. **加载模块**：将验证器模块加载到运行时
资料来源：[guardrails/cli/hub/install.py:1-50]()
### 验证器安装流程
```mermaid
graph TD
A[hub install 命令] --> B[ValidatorPackageService.get_validator_id]
B --> C{验证器已安装?}
C -->|是| D[返回已安装版本]
C -->|否| E[ValidatorPackageService.get_manifest_and_site_packages]
E --> F[下载依赖]
F --> G[ValidatorPackageService.install_hub_module]
G --> H[模块安装完成]
```
## 验证历史记录
### Call 对象结构
每次 API 调用都会生成一个 `Call` 对象，记录完整的执行历史：
```python
class Call:
iterations: Stack[Iteration] # 迭代堆栈
inputs: CallInputs # 输入参数
exception: Optional[Exception] # 异常信息
```
资料来源：[guardrails/classes/history/call.py:1-30]()
### CallInputs 输入参数
| 参数名 | 类型 | 说明 |
|-------|------|------|
| prompt | str | 输入提示词 |
| prompt_params | Dict | 提示词参数 |
| llm_api | Callable | LLM 调用函数 |
| messages | List[Dict] | 消息历史 |
| num_reasks | int | 最大重试次数 |
| metadata | Dict | 附加元数据 |
| full_schema_reask | bool | 全量重问标志 |
| stream | bool | 流式响应标志 |
| args | List | 额外位置参数 |
| kwargs | Dict | 额外关键字参数 |
资料来源：[guardrails/classes/history/call_inputs.py:1-60]()
### 迭代记录
```mermaid
graph LR
A[初始调用] --> B[Iteration 1]
B --> C{验证通过?}
C -->|是| D[返回结果]
C -->|否| E[Iteration 2]
E --> F{验证通过?}
F -->|否| G[Iteration N]
G --> H{达到最大重试?}
H -->|是| I[返回异常]
H -->|否| E
```
## 客户端集成
### Python 客户端
使用 `guardrails-api` 客户端库连接服务器：
```python
from guardrails_api.client import GuardrailsClient
client = GuardrailsClient("http://localhost:8000")
result = client.validate(
text="需要验证的文本",
validators=["RegexMatch"],
config={"regex": r"\d+"}
)
```
### 配置验证器
在服务器端预先配置验证器，客户端只需指定验证器名称：
```python
guard = Guard().use(
CompetitorCheck(
competitors=["Apple", "Microsoft", "Google"],
on_fail=OnFailAction.EXCEPTION
),
ToxicLanguage(
threshold=0.5,
validation_method="sentence",
on_fail=OnFailAction.EXCEPTION
)
)
```
## 部署选项
### Docker 部署
Guardrails 服务器支持 Docker 容器化部署：
```dockerfile
# server_ci/Dockerfile
FROM python:3.11-slim
# ... 其他配置
```
### 生产环境建议
| 配置项 | 建议值 | 说明 |
|-------|-------|------|
| 端口 | 8000+ | 避免使用低位端口 |
| Watch 模式 | 禁用 | 生产环境禁用热重载 |
| 日志级别 | INFO | 平衡日志量和调试能力 |
| 超时设置 | 60s | LLM 调用超时时间 |
| 重试次数 | 3 | 验证失败重试次数 |
## 故障排查
### 常见问题
**服务器启动失败**
- 检查 `guardrails-api` 是否正确安装：`pip show guardrails-api`
- 验证端口是否被占用：`lsof -i :8000`
- 查看日志输出获取详细错误信息
**验证器加载失败**
- 确认验证器已正确安装：`guardrails hub list`
- 检查 Python 路径是否包含验证器目录
**版本不兼容**
- 升级 `guardrails-api`：`pip install --upgrade guardrails-api`
- 检查版本兼容性矩阵
## 相关资源
- [Guardrails Hub](https://guardrailsai.com/hub/) - 验证器市场
- [官方文档](https://docs.guardrailsai.com/) - 完整文档
- [GitHub 仓库](https://github.com/guardrails-ai/guardrails) - 源代码
- [Discord 社区](https://discord.gg/Jsey3mX98B) - 技术讨论
---
## 框架集成
### 相关页面
相关主题：[Guard 类详解](#page-guard-class), [验证流程与 Runner](#page-validation-flow)
相关源码文件
以下源码文件用于生成本页说明：
- [guardrails/integrations/langchain/__init__.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/langchain/__init__.py)
- [guardrails/integrations/langchain/guard_runnable.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/langchain/guard_runnable.py)
- [guardrails/integrations/langchain/validator_runnable.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/langchain/validator_runnable.py)
- [guardrails/integrations/langchain/base_runnable.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/langchain/base_runnable.py)
- [guardrails/integrations/llama_index/__init__.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/llama_index/__init__.py)
- [guardrails/integrations/llama_index/guardrails_chat_engine.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/llama_index/guardrails_chat_engine.py)
- [guardrails/integrations/llama_index/guardrails_query_engine.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/llama_index/guardrails_query_engine.py)
- [guardrails/integrations/databricks/__init__.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/databricks/__init__.py)
- [guardrails/integrations/databricks/ml_flow_instrumentor.py](https://github.com/guardrails-ai/guardrails/blob/main/guardrails/integrations/databricks/ml_flow_instrumentor.py)
# 框架集成
Guardrails 为主流 LLM 应用框架提供了官方集成支持，使开发者能够在不改变原有工作流的情况下，为 LLM 应用添加输出验证和结构化能力。框架集成的核心目标是将 Guardrails 的验证机制无缝嵌入到 LangChain、LlamaIndex 和 Databricks 等生态系统中，实现输入验证、输出校验、错误修正等功能的一体化支持。
## 集成架构概述
Guardrails 的框架集成采用模块化设计，每个框架都有独立的集成包，包含针对该框架特定接口的适配器。这种设计确保了集成代码的清晰性和可维护性，同时保持了各框架原生 API 的使用体验。
```mermaid
graph TB
subgraph "Guardrails 集成层"
LC["LangChain 集成"]
LI["LlamaIndex 集成"]
DB["Databricks 集成"]
end
subgraph "Guardrails 核心"
G["Guard 类"]
V["Validator 系统"]
H["Hub 验证器"]
end
LC --> G
LI --> G
DB --> G
G --> V
V --> H
```
## LangChain 集成
LangChain 是目前最流行的 LLM 应用开发框架之一，Guardrails 提供了完整的 Runnable 接口实现，使 Guardrails 可以直接作为 LangChain 链式调用的一部分使用。
### 核心组件
LangChain 集成包含三个核心类，分别处理不同的验证场景：
| 类名 | 文件路径 | 功能描述 |
|------|----------|----------|
| `BaseRunnable` | `base_runnable.py` | 所有 Runnable 的基类，定义通用接口 |
| `GuardRunnable` | `guard_runnable.py` | 将整个 Guard 实例包装为 Runnable |
| `ValidatorRunnable` | `validator_runnable.py` | 将单个或多个 Validator 包装为 Runnable |
资料来源：[guardrails/integrations/langchain/__init__.py]()
### GuardRunnable
`GuardRunnable` 是最常用的 LangChain 集成类，它将完整的 Guard 实例转换为 LangChain 的 Runnable 接口。这意味着开发者可以在 LangChain 表达式链中使用任何已定义的 Guard 配置。
```python
from guardrails import Guard
from guardrails.integrations.langchain import GuardRunnable
# 创建 Guard 实例
guard = Guard().use(...)
# 转换为 Runnable
guard_runnable = GuardRunnable(guard=guard)
# 在 LangChain 链中使用
chain = prompt | model | guard_runnable
```
`GuardRunnable` 继承自 `BaseRunnable`，`BaseRunnable` 提供了与 LangChain Runnable 接口兼容的 `invoke`、`ainvoke`、`batch`、`abatch` 等方法。
资料来源：[guardrails/integrations/langchain/guard_runnable.py]()
资料来源：[guardrails/integrations/langchain/base_runnable.py]()
### ValidatorRunnable
当只需要使用特定验证器而不需要完整的 Guard 配置时，`ValidatorRunnable` 提供了更轻量级的选择。它允许开发者直接将 Validator 实例嵌入到 LangChain 链中。
```python
from guardrails.integrations.langchain import ValidatorRunnable
from guardrails.hub import RegexMatch
# 创建验证器 Runnable
validator_runnable = ValidatorRunnable(validator=RegexMatch(...))
# 单独使用或在链中使用
result = validator_runnable.invoke("待验证的文本")
```
资料来源：[guardrails/integrations/langchain/validator_runnable.py]()
### 集成工作流
```mermaid
graph LR
A["用户输入"] --> B["LangChain Prompt"]
B --> C["LLM 模型"]
C --> D{"GuardRunnable"}
D --> E{验证通过?}
E -->|是| F["返回结果"]
E -->|否| G["错误处理"]
G --> H["重新生成或异常"]
```
## LlamaIndex 集成
LlamaIndex 是专注于知识增强检索的 LLM 框架，Guardrails 为其提供了 Query Engine 和 Chat Engine 的集成支持，使结构化输出验证可以直接应用于检索增强生成（RAG）场景。
### 核心组件
| 类名 | 文件路径 | 功能描述 |
|------|----------|----------|
| `GuardrailsQueryEngine` | `guardrails_query_engine.py` | 为 LlamaIndex 查询引擎添加验证层 |
| `GuardrailsChatEngine` | `guardrails_chat_engine.py` | 为 LlamaIndex 聊天引擎添加验证层 |
资料来源：[guardrails/integrations/llama_index/__init__.py]()
### GuardrailsQueryEngine
`GuardrailsQueryEngine` 将验证层包装在现有的 LlamaIndex 查询引擎之上。当查询结果返回时，验证器会自动检查输出是否符合预期的格式和内容约束。
```python
from llama_index import VectorStoreIndex
from guardrails import Guard
from guardrails.integrations.llama_index import GuardrailsQueryEngine
# 创建基础索引
index = VectorStoreIndex.from_documents(documents)
# 创建带 Guardrails 的查询引擎
guard = Guard().use(...)
query_engine = GuardrailsQueryEngine(
query_engine=index.as_query_engine(),
guard=guard
)
# 使用验证引擎查询
response = query_engine.query("用户问题")
```
资料来源：[guardrails/integrations/llama_index/guardrails_query_engine.py]()
### GuardrailsChatEngine
`GuardrailsChatEngine` 专门为聊天场景设计，适用于需要持续对话且对每次回复都需要验证的应用。它保持了 LlamaIndex 原有聊天引擎的状态管理能力，同时叠加了验证功能。
```python
from guardrails import Guard
from guardrails.integrations.llama_index import GuardrailsChatEngine
guard = Guard().use(...)
chat_engine = GuardrailsChatEngine.from_defaults(
chat_mode="condense_plus_context",
guard=guard
)
# 对话循环
chat_engine.chat("用户的第一条消息")
chat_engine.chat("用户的第二条消息")
```
资料来源：[guardrails/integrations/llama_index/guardrails_chat_engine.py]()
## Databricks 集成
Databricks 集成为使用 Databricks 进行 LLM 应用的开发者提供了 MLflow 仪器化支持，允许在 Databricks 环境中追踪和监控 Guardrails 验证行为。
### MLflow 仪器化器
Databricks 集成的核心是 `MLflowInstrumentor` 类，它扩展了 MLflow 的自动仪器化功能，使 Guardrails 验证可以自动记录到 MLflow 实验追踪系统中。
```python
from guardrails.integrations.databricks import MLflowInstrumentor
# 初始化仪器化器
instrumentor = MLflowInstrumentor()
# 启用自动追踪
instrumentor.instrument()
```
资料来源：[guardrails/integrations/databricks/__init__.py]()
资料来源：[guardrails/integrations/databricks/ml_flow_instrumentor.py]()
### 追踪能力
通过 MLflow 集成，Guardrails 可以记录以下信息：
- **验证执行次数**：记录每个 Guard 和 Validator 被调用的次数
- **验证结果**：记录每次验证的通过/失败状态
- **错误详情**：记录验证失败时的详细错误信息
- **性能指标**：记录验证过程的执行时间
## 集成配置选项
### 通用配置
| 配置项 | 适用框架 | 说明 |
|--------|----------|------|
| `guard` | LangChain, LlamaIndex | 核心 Guard 实例 |
| `on_fail` | 所有框架 | 验证失败时的行为（EXCEPTION, FIX, FILTER 等） |
| `strict` | 所有框架 | 是否启用严格模式 |
### LangChain 特定配置
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `output_format` | `None` | 指定输出格式器 |
| `messages` | `None` | 自定义消息列表 |
| `reask_messages` | `None` | 重新生成时的消息 |
### LlamaIndex 特定配置
| 配置项 | 说明 |
|--------|------|
| `query_engine` | 底层查询引擎实例 |
| `chat_mode` | 聊天模式选择 |
## 最佳实践
### 框架集成的性能考虑
在生产环境中使用框架集成时，应注意以下性能优化点：
1. **Guard 实例复用**：Guard 实例应该被创建一次并在多次调用中复用，避免重复初始化开销。
2. **批量验证**：对于支持批量操作的框架（如 LangChain 的 `batch` 方法），应优先使用批量接口。
3. **异步支持**：所有 Runnable 实现都支持异步操作，在高并发场景下应使用 `ainvoke` 或 `abatch`。
### 错误处理策略
| 策略 | 描述 | 适用场景 |
|------|------|----------|
| `EXCEPTION` | 抛出验证异常 | 开发调试阶段 |
| `FIX` | 自动修正输出 | 自动化处理流程 |
| `FILTER` | 过滤无效结果 | 需要干净输出的场景 |
| `REASK` | 重新请求 LLM | 需要高可靠性的生产环境 |
### 框架选择指南
| 场景 | 推荐框架 | 集成类 |
|------|----------|--------|
| 链式 LLM 调用 | LangChain | `GuardRunnable` |
| 检索增强生成 | LlamaIndex | `GuardrailsQueryEngine` |
| 聊天机器人 | LlamaIndex | `GuardrailsChatEngine` |
| Databricks 环境 | Databricks | `MLflowInstrumentor` |
## 相关资源
- [Guardrails 官方文档](https://docs.guardrailsai.com/)
- [Guardrails Hub 验证器库](https://guardrailsai.com/hub/)
- [LangChain 官方文档](https://python.langchain.com/)
- [LlamaIndex 官方文档](https://docs.llamaindex.ai/)
---
---
## Doramagic 踩坑日志
项目：guardrails-ai/guardrails
摘要：发现 23 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：安装坑 - 来源证据：FIX action silently mutates output - should there be a 'quarantine' tier between LOG and FIX?。
## 1. 安装坑 · 来源证据：FIX action silently mutates output - should there be a 'quarantine' tier between LOG and FIX?
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：FIX action silently mutates output - should there be a 'quarantine' tier between LOG and FIX?
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_69600563346341a386aa86c6af5d1274 | https://github.com/guardrails-ai/guardrails/issues/1448 | 来源类型 github_issue 暴露的待验证使用条件。
## 2. 安装坑 · 来源证据：Portable evidence artifacts for validation outcomes
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Portable evidence artifacts for validation outcomes
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ef2970465bbe44c89b513edd115b682c | https://github.com/guardrails-ai/guardrails/issues/1457 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 3. 安装坑 · 来源证据：Proposal: PromptDefenseAudit Hub validator — static system prompt hardening check
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: PromptDefenseAudit Hub validator — static system prompt hardening check
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_d7163e193eb54aab837d87b3ecd73991 | https://github.com/guardrails-ai/guardrails/issues/1453 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 4. 能力坑 · 来源证据：[docs] Fix double logo display in pypi
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：[docs] Fix double logo display in pypi
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_084985c7cb4d4238a44e452b14b2eaf9 | https://github.com/guardrails-ai/guardrails/issues/1362 | 来源类型 github_issue 暴露的待验证使用条件。
## 5. 安全/权限坑 · 来源证据：Integration proposal: Cryptographic audit trail validator with asqav
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Integration proposal: Cryptographic audit trail validator with asqav
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_8db542ceccff4a71bc11c254ce3abfde | https://github.com/guardrails-ai/guardrails/issues/1446 | 来源类型 github_issue 暴露的待验证使用条件。
## 6. 安全/权限坑 · 来源证据：Integration proposal: styxx hallucination validator (8-benchmark cross-validated)
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Integration proposal: styxx hallucination validator (8-benchmark cross-validated)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_da275c0a112848ed920af00c76fd3e1b | https://github.com/guardrails-ai/guardrails/issues/1463 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 7. 安装坑 · 来源证据：Proposal: Agent Threat Rules detection integration
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: Agent Threat Rules detection integration
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9d25561995774521a21051373d95b431 | https://github.com/guardrails-ai/guardrails/issues/1471 | 来源类型 github_issue 暴露的待验证使用条件。
## 8. 安装坑 · 来源证据：[bug] Guardrails CLI start command broken with guardrails-api 0.4.2
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] Guardrails CLI start command broken with guardrails-api 0.4.2
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_f411132764b84c17b318b5cc7a32ef56 | https://github.com/guardrails-ai/guardrails/issues/1464 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 9. 安装坑 · 来源证据：v0.7.3
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.3
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_95f33a7ff8014d78a13752aa7fd56d6e | https://github.com/guardrails-ai/guardrails/releases/tag/v0.7.3 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 10. 安装坑 · 来源证据：v0.8.2
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.8.2
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_559ad38ac0504cff91377804f004c57c | https://github.com/guardrails-ai/guardrails/releases/tag/v0.8.2 | 来源类型 github_release 暴露的待验证使用条件。
## 11. 安装坑 · 来源证据：v0.9.2
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.2
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ae34ce00e8554a5199b5e78e3465942d | https://github.com/guardrails-ai/guardrails/releases/tag/v0.9.2 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 12. 安装坑 · 来源证据：v0.9.3
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.9.3
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_f2b73a33cb2f47d3bba9b9f2dd07ed62 | https://github.com/guardrails-ai/guardrails/releases/tag/v0.9.3 | 来源类型 github_release 暴露的待验证使用条件。
## 13. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | README/documentation is current enough for a first validation pass.
## 14. 维护坑 · 来源证据：v0.8.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.8.0
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_160840f6f00644f2bcd25339973d1d82 | https://github.com/guardrails-ai/guardrails/releases/tag/v0.8.0 | 来源类型 github_release 暴露的待验证使用条件。
## 15. 维护坑 · 来源证据：v0.9.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.9.0
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_91ae72d0a0f74305b8b5b3f66d4048e4 | https://github.com/guardrails-ai/guardrails/releases/tag/v0.9.0 | 来源类型 github_release 暴露的待验证使用条件。
## 16. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | last_activity_observed missing
## 17. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | no_demo; severity=medium
## 18. 安全/权限坑 · 存在安全注意事项
- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 建议检查：转成明确权限清单和安全审查提示。
- 防护动作：安全注意事项必须面向用户前置展示。
- 证据：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.
## 19. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | no_demo; severity=medium
## 20. 安全/权限坑 · 来源证据：MCP Server Compliance Scanning: OWASP MCP Top 10 guardrails
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：MCP Server Compliance Scanning: OWASP MCP Top 10 guardrails
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_b6a63df899144908af33089886cfaf51 | https://github.com/guardrails-ai/guardrails/issues/1435 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 21. 安全/权限坑 · 来源证据：v0.8.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.8.1
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_6721e28473844e92b61d6701c416d2fd | https://github.com/guardrails-ai/guardrails/releases/tag/v0.8.1 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 22. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | issue_or_pr_quality=unknown
## 23. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:594609262 | https://github.com/guardrails-ai/guardrails | release_recency=unknown