概述

Guardrails 是一个用于验证和纠正大型语言模型（LLM）输出的 Python 库。它提供了输入/输出验证、格式约束和结构化数据生成等功能，帮助开发者确保 LLM 应用的可靠性和安全性。

Guardrails 的核心设计理念是将验证逻辑与 LLM 调用解耦，使开发者能够以声明式的方式定义输出规范，然后自动验证和纠正 LLM 响应。

资料来源：README.md:1

核心概念

Guard（守卫）

Guard 是 Guardrails 框架的核心类，它包装 LLM 调用并自动执行验证和纠正流程。

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（失败动作）

资料来源：README.md:35

系统架构

组件架构图

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

调用流程

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 的方式

资料来源：guardrails/guard.py:1

for_pydantic 方法参数

@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,
):

资料来源：guardrails/guard.py:18

LLM 集成

Guardrails 支持多种 LLM 提供商，包括 OpenAI、LiteLLM 和 Manifest。

LiteLLM 集成示例

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 提供商

历史记录系统

Guardrails 内置了调用历史记录功能，每次执行 Guard.__call__、Guard.parse 或 Guard.validate 都会创建一个 Call 对象。

Call 数据结构

class Call:
    _id: str | None = None
    iterations: Stack[Iteration] = Field(default_factory=Stack)
    inputs: CallInputs = Field(default_factory=CallInputs)
    exception: Optional[Exception] = None

CallInputs 参数

资料来源：guardrails/classes/history/call.py:1, guardrails/classes/history/call_inputs.py:1

Guardrails Hub

Guardrails Hub 是验证器的共享平台，开发者可以从中安装预构建的验证器。

安装验证器

pip install guardrails-ai
guardrails configure
guardrails hub install hub://guardrails/regex_match

资料来源：README.md:10

安装 API

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/hub/install.py:1, guardrails/cli/hub/install.py:1

创建自定义验证器

验证器模板

使用 CLI 创建验证器模板：

guardrails hub create-validator MyValidator

这会生成一个模板文件 my_validator.py。

资料来源：guardrails/cli/hub/create_validator.py:1

验证器基本结构

class MyValidator(Validator):
    """验证器描述"""
    
    def __init__(self, ...):
        super().__init__(...)
        
    def validate(self, value, ...):
        # 验证逻辑
        pass

安装与配置

环境要求

安装步骤

1. 安装 guardrails-ai 包：

pip install guardrails-ai

1. 配置 Hub CLI：

guardrails configure

1. 安装验证器：

guardrails hub install hub://guardrails/competitor_check
guardrails hub install hub://guardrails/toxic_language

资料来源：README.md:10-20

使用示例

基本验证

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)

多验证器组合

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 模型生成结构化数据

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

开发工作流

资料来源：CONTRIBUTING.md:1

相关资源

• 官方文档：Guardrails AI
• 验证器市场：Guardrails Hub
• Discord 社区：加入讨论
• GitHub 仓库：guardrails-ai/guardrails

概述

Guardrails 是一个用于 LLM（大型语言模型）输出验证和结构化数据生成的 Python 库。本页面详细介绍 Guardrails 的安装方法、开发环境配置、CLI 工具设置以及 Hub 验证器的安装流程。

Guardrails 支持两种主要的安装场景：

• 生产环境安装：仅安装核心库和必要的依赖
• 开发环境安装：安装所有开发依赖，支持本地测试、格式化、类型检查等

资料来源：CONTRIBUTING.md

概述

Guard 是 Guardrails AI 框架的核心类，负责验证和约束大语言模型（LLM）的输入和输出。它提供了一个统一的接口，用于定义验证规则、调用 LLM、以及对输出进行结构化验证。

Guard 类的设计目标包括：

• 输出验证：确保 LLM 生成的输出符合预定义的模式和约束
• 结构化生成：支持从 Pydantic 模型生成结构化数据
• 多步骤验证：支持重试机制（reask）和多次验证迭代
• 历史追踪：完整记录每次调用的输入、输出和验证结果

资料来源：guardrails/guard.py:1-100

核心架构

类层次结构

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]

执行流程

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 格式的规范，用于定义输出验证规则。

guard = Guard.from_rail_string(rail_string)

资料来源：guardrails/guard.py:100-120

从 Pydantic 模型创建

这是最常用的方式，直接使用 Pydantic BaseModel 定义输出结构：

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 方法签名

验证机制

验证流程

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 枚举

调用历史系统

Call 数据结构

每次调用 Guard 时，系统会创建一个 Call 对象记录完整的执行历史。

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 类的属性

资料来源：guardrails/classes/history/call.py:20-50

LLM 集成

支持的 LLM 提供者

Guard 类支持与多种 LLM 提供者集成：

# 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 基类

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 服务集成，实现远程存储和管理：

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 客户端方法

资料来源：guardrails/api_client.py:1-150

调用追踪系统

TraceHandler

TraceHandler 是一个线程安全的追踪系统，用于记录 Guard 的调用历史：

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

日志存储

默认情况下，日志存储在临时目录中：

${TMPDIR}/guardrails_calls.db

可通过环境变量覆盖：

export GUARDRAILS_LOG_FILE_PATH="/path/to/logs.db"

使用示例

基础验证示例

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}

结构化输出示例

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")

多验证器组合示例

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. 合理的重试配置

# 设置合理的重试次数和消息
guard = Guard.for_pydantic(
    Pet,
    reask_messages=[
        {"role": "user", "content": "请重新生成，必须包含 pet_type 和 name 字段"}
    ]
)

2. 使用适当的 on_fail 策略

3. 调用历史记录

# 获取最近一次调用的历史
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 系统是 Guardrails 框架的核心组件之一，负责定义和管理 LLM 输出的验证规范。该系统提供了从多种模式定义（RAIL、Pydantic、JSON Schema）到内部验证结构的转换能力，确保 LLM 生成的内容符合预定义的结构和约束条件。

Schema 系统的主要职责包括：

• 模式解析：将用户定义的 RAIL 字符串、Pydantic 模型或 JSON Schema 解析为内部表示
• 类型映射：支持字符串、日期、时间、日期时间、百分比、枚举等多种数据类型的映射
• 验证器集成：将验证器（Validator）绑定到特定的 Schema 字段
• 输出规范生成：将 JSON Schema 反向转换为 RAIL 输出规范

资料来源：guardrails/schema/rail_schema.py:1-50

架构设计

核心组件

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 之间的转换。

#### 主要功能

#### 支持的数据类型

资料来源：guardrails/schema/rail_schema.py:50-120

#### 类型映射逻辑

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 转换流程

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 输出字符串]

关键转换函数：

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 实例

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 数据结构，包含以下关键属性：

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 字段进行绑定，支持以下配置选项：

Guard 与 Schema 的集成

从 RAIL 创建 Guard

from guardrails import Guard

rail_string = """
<rail version="1.0">
    <output>
        <string name="result" />
    </output>
</rail>
"""

guard = Guard.from_rail_string(rail_string)

内部调用流程：

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

from guardrails import Guard
from pydantic import BaseModel

class OutputModel(BaseModel):
    name: str
    age: int

guard = Guard.for_pydantic(OutputModel)

支持的方法签名：

资料来源：guardrails/guard.py:100-140

调用输入管理

CallInputs 数据结构

call_inputs.py 定义了 LLM 调用时的输入参数：

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."
    )

资料来源：guardrails/classes/history/call_inputs.py:20-50

Schema 处理流程

完整验证流程

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

@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

类型系统

简单类型枚举

特殊格式类型

# 日期时间格式支持
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 功能：

from guardrails.schema import BaseSchema

class CustomSchema(BaseSchema):
    def validate(self, value):
        # 自定义验证逻辑
        pass

验证器注册

验证器通过 ValidatorMap 注册到 Schema 系统：

validator_map: ValidatorMap  # 全局验证器映射表

最佳实践

1. 使用 Pydantic 模型定义复杂结构：更声明式，类型安全
2. 明确指定日期/时间格式：避免歧义
3. 合理设置 num_reasks：平衡验证严格性和用户体验
4. 利用 metadata 传递上下文：验证器可访问运行时信息

总结

Schema 系统是 Guardrails 框架的基础架构层，提供了从多种模式定义格式到统一验证结构的转换能力。通过模块化的设计，支持 RAIL、Pydantic、JSON Schema 等多种输入方式，并提供灵活的验证器集成机制。该系统与 Guard 类紧密协作，实现了 LLM 输出的结构化和可验证性。

概述

Guardrails 的验证流程是整个框架的核心执行机制，负责协调 LLM 响应与验证器之间的交互。当用户调用 Guard.__call__、Guard.parse 或 Guard.validate 方法时，框架会通过 Runner 组件来执行验证逻辑。

Runner 系统采用模块化设计，支持同步、异步和流式三种执行模式。这种设计允许 Guardrails 适应不同的应用场景，从简单的批量验证到实时流式响应处理。

核心架构组件

Call（调用）对象

Call 类是 Guard 执行过程的顶层记录容器。每次调用 Guard.__call__、Guard.parse 或 Guard.validate 时，都会创建一个新的 Call 实例。

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 对象的核心属性：

Call.id 是一个计算属性，通过 object_id(self) 生成唯一标识符，可用于追踪特定的 Guard 执行：

@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 是标准的同步执行器，适用于批量处理和非实时应用场景。它按顺序执行验证步骤，阻塞当前线程直到完成。

# 典型使用方式
from guardrails import Guard

guard = Guard.from_pydantic(Pet)
result = guard(
    client,
    prompt_params={...}
)

异步 Runner

AsyncRunner 支持异步执行，利用 Python 的 asyncio 实现并发处理。这对于需要同时处理多个验证请求的高吞吐量应用至关重要。

# 典型使用方式
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 可以边接收响应边进行验证，提供更好的实时性和更低的内存占用。

# 典型使用方式
for token in guard.stream(
    client,
    prompt_params={...}
):
    print(token, end="", flush=True)

验证流程图

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 的核心逻辑：

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：如果执行中断，保存异常信息

@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 所需的核心工具函数：

这些工具函数支持 Runner 在不同执行阶段进行数据转换和验证。

执行状态管理

Runner 通过 TracerMixin 提供执行追踪能力：

class TraceHandler(TracerMixin):
    """TraceHandler wraps the internal _SQLiteTraceHandler to make it multi-
    thread safe."""

追踪系统使用 SQLite 数据库记录每次执行的详细信息：

• 日志文件位置：可通过 GUARDRAILS_LOG_FILE_PATH 环境变量配置
• 默认位置：tempfile.gettempdir() + "/guardrails_calls.db"
• 多线程安全：通过单例模式和写前日志机制实现

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：所有提供商的基类

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 超时、网络错误）

try:
    guard.validate("1234-789-0000")  # 验证失败
except Exception as e:
    print(e)  # 输出: Validation failed for field with errors: Result must match...

配置选项

创建 Guard 时可以通过多种方式配置验证流程：

总结

Runner 系统是 Guardrails 验证流程的核心执行引擎，通过模块化的设计支持同步、异步和流式三种执行模式。Call 和 Iteration 类提供了完整的执行历史追踪能力，使调试和监控变得简单直观。理解 Runner 的工作原理对于深入掌握 Guardrails 框架、进行性能优化和故障排查至关重要。

概述

验证器（Validator）是 Guardrails 框架的核心组件，用于对 LLM（大型语言模型）生成的输出进行质量检查和验证。验证器充当输出与预期规范之间的桥梁，确保 LLM 响应符合预定义的数据结构、格式要求和内容约束。

核心职责

• 格式验证：检查输出是否符合指定的数据格式（如正则表达式、JSON Schema）
• 内容验证：检测敏感内容、不当语言或竞争对手提及
• 结构验证：确保输出符合 Pydantic 模型或 RAIL 规范定义的结构
• 修复建议：在验证失败时提供修正值或重新请求 LLM 生成

验证器在 Guard 架构中的位置

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 是验证过程的返回结果，封装了验证的完整状态信息。

资料来源：guardrails/guard.py:420-450

验证日志 ValidatorLogs

每个验证步骤都会生成详细的日志记录，用于追踪和调试。

资料来源：guardrails/classes/validation/validator_logs.py

失败处理策略

OnFailAction 枚举

当验证失败时，系统根据配置的 OnFailAction 决定如何处理。

资料来源：guardrails/types/on_fail.py

各动作的处理流程

#### 过滤动作 (Filter)

过滤动作用于处理需要移除或替换的敏感内容：

# 伪代码示例
if validation_result.failed:
    if on_fail == OnFailAction.FILTER:
        return filtered_value

#### 克制动作 (Refrain)

克制动作在检测到违规内容时返回空值或中性替代：

# 克制动作返回空输出
if validation_result.failed and on_fail == OnFailAction.REFRAIN:
    return None

资料来源：guardrails/actions/filter.py 资料来源：guardrails/actions/refrain.py

#### 重新请求动作 (Reask)

重新请求是最常用的自动修正机制，会收集所有验证失败项并生成新的提示词：

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 对象记录失败信息：

递归收集机制

gather_reasks 函数递归遍历验证输出，收集所有需要重新请求的字段：

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 基类，实现以下核心方法：

验证器调用追踪

框架集成了 OpenTelemetry 追踪系统，记录每次验证的执行情况：

# 验证器执行时会创建 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() 方法注册验证器：

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)
)

获取已注册的验证器

# 获取 output 级别所有验证器
output_validators = guard.get_validators(on="output")

# 获取特定字段的验证器
field_validators = guard.get_validators(on="$.pet_type")

验证流程

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 对象，记录完整的执行历史：

Iteration 数据结构

单个迭代包含：

• validator_logs：本次迭代中所有验证器的执行日志
• llm_response：LLM 的原始响应
• parsed_output：解析后的输出
• validation_response：验证结果

资料来源：guardrails/classes/history/call.py

验证器开发模板

创建新验证器

使用 CLI 命令创建验证器模板：

guardrails hub create-validator MyValidator ./my_validator.py

生成的模板包含：

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. 验证器组合策略

2. OnFailAction 选择指南

• 严格模式：使用 EXCEPTION 确保不返回无效数据
• 容错模式：使用 REASK 自动修正轻微格式错误
• 安全模式：使用 FILTER 或 REFRAIN 处理敏感内容

3. 性能注意事项

• 避免在验证器中执行阻塞 I/O 操作
• 使用 skip_reask_when_valid 参数避免不必要的重新请求
• 对于复杂验证逻辑，考虑异步实现

相关资源

• Guardrails Hub - 官方验证器市场
• 验证器模板仓库 - 复杂验证器开发指南
• API 参考文档 - 完整的 API 说明

概述

Guardrails Hub 是 Guardrails 项目的验证器分发与共享平台，为用户提供了一个集中式的验证器市场，类似于 Python 生态中的 PyPI。Hub 的核心功能是允许用户从中央仓库安装、社区贡献者提交新的验证器，以及管理本地已安装的验证器模块。

通过 Guardrails Hub，用户可以快速获取预构建的验证器（如正则匹配、竞争对手检查、有害内容检测等），无需从头编写验证逻辑。Hub 采用语义化版本控制，支持灵活的版本约束，确保项目的依赖稳定性。

核心特点：

• 即装即用：通过 CLI 一键安装验证器
• 版本管理：支持语义化版本约束（如 ~=1.4、>=1.4,==1.*）
• 模块导出：统一的导入接口 from guardrails.hub import {ValidatorName}
• 本地模型支持：部分验证器支持本地模型推理

资料来源：README.md:1-20

架构设计

系统组件

Guardrails Hub 由以下核心组件构成：

安装流程

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

URI 规范与版本控制

Hub URI 格式

Guardrails Hub 使用统一的 URI 格式来标识验证器资源：

hub://guardrails/{validator_name}[~={version}]

格式说明：

资料来源：guardrails/hub/install.py:30-40

版本约束示例

# 安装特定版本
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

CLI 命令参考

Guardrails Hub 通过 guardrails hub 子命令提供操作接口。

安装验证器

guardrails hub install hub://guardrails/regex_match
guardrails hub install hub://guardrails/competitor_check

参数选项：

本地模型安装确认：

当验证器需要本地模型时，系统会提示用户确认：

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

创建验证器模板

guardrails hub create-validator MyValidator
guardrails hub create-validator CustomCheck --filepath ./validators/my_check.py

此命令生成验证器模板文件，包含基础结构和必要的方法占位符：

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

其他 CLI 命令

验证器使用方式

基础导入与使用

安装完成后，通过以下方式导入和使用验证器：

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

多个验证器组合

可以链式使用多个验证器：

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

开发与贡献

创建新验证器

对于简单验证器，可使用 CLI 工具生成模板：

guardrails hub create-validator MyValidator

对于复杂验证器，建议使用官方模板仓库：

https://github.com/guardrails-ai/validator-template

资料来源：guardrails/cli/hub/create_validator.py:30-35

提交到 Hub

贡献者可以通过 guardrails hub submit 命令将自己开发的验证器提交到 Hub 进行审核。提交前请确保：

1. 验证器包含完整的文档字符串
2. 实现必要的 __init__ 和 validate 方法
3. 提供使用示例
4. 所有测试通过

资料来源：CONTRIBUTING.md:1-30

开发环境设置

# 克隆仓库
git clone https://github.com/guardrails-ai/guardrails.git
cd guardrails

# 安装开发依赖
make dev

# 安装 pre-commit 钩子
pre-commit install

# 运行测试
make test

# 代码格式化
make autoformat

# 类型检查
make type

验证器清单示例

常见问题

Q: 安装失败怎么办？

检查网络连接和 pip 权限，确保已正确配置 PyPI 镜像源。

Q: 如何指定验证器版本？

在 URI 中添加版本约束：hub://guardrails/regex_match~=1.4

Q: 验证器需要本地模型时如何处理？

使用 --local-models 参数安装本地模型，或使用云端推理端点（默认行为）。

概述

Guardrails CLI 是 Guardrails 框架提供的命令行界面工具，为开发者提供了一系列便捷的终端操作命令。通过 CLI，用户可以快速创建验证器、管理 Hub 模块、执行数据验证、配置本地环境以及启动 API 服务。CLI 工具采用模块化架构设计，将不同功能封装为独立的子命令模块，包括 Guard 管理、RAIL 文件创建、数据验证、数据库迁移以及 Hub 模块安装等核心功能。

CLI 基于 Typer 框架构建，充分利用了 Python 类型提示和命令补全功能，为用户提供流畅的命令行体验。所有的 CLI 命令都集成了日志系统，支持不同级别的日志输出，便于调试和监控操作状态。

架构设计

整体架构

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 仓库安装自定义模块。

graph LR
    A["输入包URI"] --> B["验证器ID解析"]
    B --> C["获取模块清单"]
    C --> D{"是否安装本地模型"}
    D -->|是| E["确认安装"]
    D -->|否| F["跳过本地模型"]
    E --> G["下载依赖"]
    F --> G
    G --> H["pip 安装"]
    H --> I["安装完成"]

主要参数：

安装示例：

# 安装单个验证器
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 规范的验证器代码框架。

graph TD
    A["输入验证器名称"] --> B["名称格式转换"]
    B --> C["snake_case 命名"]
    B --> D["PascalCase 命名"]
    C --> E["生成文件路径"]
    D --> F["应用 Jinja2 模板"]
    F --> G["写入 Python 文件"]
    G --> H["创建完成"]

模板包含内容：

• 验证器类框架（继承自 Validator 基类）
• 初始化参数定义区域
• validate 方法骨架代码
• 示例测试用例（docstring 中）
• 文档注释模板

# 创建名为 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 命令将数据库迁移到指定版本或最新版本。迁移过程中会按顺序执行所有未应用的迁移文件。

# 升级到最新版本
guardrails db upgrade head

# 升级到指定版本
guardrails db upgrade abc123

# 查看生成的 SQL 而不执行
guardrails db upgrade head --sql

资料来源：guardrails/cli/db/upgrade.py:1-40

#### 降级操作

db downgrade 命令用于将数据库回滚到之前的版本。降级操作会按相反顺序撤销迁移。

# 降级一个版本
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 模型创建 RAIL
from guardrails.cli import create

rail_xml = create.from_pydantic(MyModel)
print(rail_xml)

#### Schema 转换

create 模块内部集成了 Schema 转换功能，能够将 JSON Schema 映射为 RAIL 格式的元素结构。转换过程支持以下类型映射：

资料来源：guardrails/schema/rail_schema.py:1-100

验证模块

validate 命令提供独立的验证功能，允许用户直接对输入数据进行验证而不需要通过 Python 代码调用 Guard 对象。

# 验证字符串是否符合正则表达式
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 服务器的启动逻辑，提供端口配置、环境变量覆盖和热重载等功能。

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

主要参数：

# 基础启动
guardrails start

# 指定端口
guardrails start --port 9000

# 加载环境配置
guardrails start --env .env.production

# 启用热重载开发模式
guardrails start --watch

资料来源：guardrails/cli/start.py:1-80

日志系统

Guardrails CLI 集成了统一的日志系统，支持多级别日志输出和彩色终端显示。

# 可用的日志级别
LEVELS = {
    "SPAM": 5,      # 详细调试信息
    "VERBOSE": 15,  # 详细操作信息
    "NOTICE": 25,   # 重要提示
    "SUCCESS": 35,  # 成功操作
}

日志输出示例：

# 详细输出模式
guardrails hub install hub://guardrails/regex_match --verbose

# 静默模式
guardrails hub install hub://guardrails/regex_match --quiet

资料来源：guardrails/cli/logger.py:1-20

使用流程示例

完整工作流程

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

典型使用场景

#### 场景一：快速验证数据格式

# 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

# 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

#### 场景三：构建和安装自定义验证器

# 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 工具采用统一的错误处理机制，确保用户获得清晰的错误信息和建议。

常见错误及解决方案

调试模式

# 启用详细日志
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 服务器基于 guardrails-api 包构建，提供了一个轻量级的 REST API 服务，用于执行 LLM 输出验证任务。服务器接收原始文本或结构化数据，通过配置的验证器（Validators）进行验证，并返回验证结果。

服务器的核心功能包括：

• 集中化验证：将验证逻辑部署在服务器端，客户端无需本地安装验证器
• API 服务：提供 RESTful API 接口，支持远程验证调用
• 多验证器编排：支持同时运行多个验证器，实现复杂的验证场景
• 历史记录追踪：记录每次验证调用的详细信息，包括输入、输出和异常情况
• Watch 模式：支持开发模式下的热重载功能

系统架构

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 服务器前，需要确保已安装 guardrails-api 包：

pip install guardrails-api>=0.2.1

服务器启动时会检查 guardrails-api 是否已安装，若未安装则自动提示安装。资料来源：guardrails/cli/start.py:12-18

启动命令

使用 guardrails start 命令启动服务器：

guardrails start [选项]

常用选项：

Watch 模式

启用 Watch 模式后，服务器会监视配置文件和验证器的变化，并自动重新加载：

guardrails start --watch

Watch 模式通过 settings._watch_mode_enabled = True 启用，适用于开发阶段。资料来源：guardrails/cli/start.py:28-29

服务器配置

配置文件

Guardrails 服务器支持通过配置文件进行定制化设置。配置文件采用 Python 格式，定义服务器的各项参数。

环境变量覆盖

对于敏感配置（如 API 密钥），建议使用环境变量进行配置。--env-override 参数允许指定环境变量文件：

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

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 端点供客户端调用：

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")

验证流程

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 安装验证器到服务器：

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

验证器安装流程

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 对象，记录完整的执行历史：

class Call:
    iterations: Stack[Iteration]  # 迭代堆栈
    inputs: CallInputs           # 输入参数
    exception: Optional[Exception]  # 异常信息

资料来源：guardrails/classes/history/call.py:1-30

CallInputs 输入参数

资料来源：guardrails/classes/history/call_inputs.py:1-60

迭代记录

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 客户端库连接服务器：

from guardrails_api.client import GuardrailsClient

client = GuardrailsClient("http://localhost:8000")

result = client.validate(
    text="需要验证的文本",
    validators=["RegexMatch"],
    config={"regex": r"\d+"}
)

配置验证器

在服务器端预先配置验证器，客户端只需指定验证器名称：

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 容器化部署：

# server_ci/Dockerfile
FROM python:3.11-slim
# ... 其他配置

生产环境建议

故障排查

常见问题

服务器启动失败

• 检查 guardrails-api 是否正确安装：pip show guardrails-api
• 验证端口是否被占用：lsof -i :8000
• 查看日志输出获取详细错误信息

验证器加载失败

• 确认验证器已正确安装：guardrails hub list
• 检查 Python 路径是否包含验证器目录

版本不兼容

• 升级 guardrails-api：pip install --upgrade guardrails-api
• 检查版本兼容性矩阵

相关资源

• Guardrails Hub - 验证器市场
• 官方文档 - 完整文档
• GitHub 仓库 - 源代码
• Discord 社区 - 技术讨论

集成架构概述

Guardrails 的框架集成采用模块化设计，每个框架都有独立的集成包，包含针对该框架特定接口的适配器。这种设计确保了集成代码的清晰性和可维护性，同时保持了各框架原生 API 的使用体验。

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 集成包含三个核心类，分别处理不同的验证场景：

资料来源：guardrails/integrations/langchain/__init__.py

GuardRunnable

GuardRunnable 是最常用的 LangChain 集成类，它将完整的 Guard 实例转换为 LangChain 的 Runnable 接口。这意味着开发者可以在 LangChain 表达式链中使用任何已定义的 Guard 配置。

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 链中。

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

集成工作流

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）场景。

核心组件

资料来源：guardrails/integrations/llama_index/__init__.py

GuardrailsQueryEngine

GuardrailsQueryEngine 将验证层包装在现有的 LlamaIndex 查询引擎之上。当查询结果返回时，验证器会自动检查输出是否符合预期的格式和内容约束。

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 原有聊天引擎的状态管理能力，同时叠加了验证功能。

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 实验追踪系统中。

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 被调用的次数
• 验证结果：记录每次验证的通过/失败状态
• 错误详情：记录验证失败时的详细错误信息
• 性能指标：记录验证过程的执行时间

集成配置选项

通用配置

LangChain 特定配置

LlamaIndex 特定配置

最佳实践

框架集成的性能考虑

在生产环境中使用框架集成时，应注意以下性能优化点：

1. Guard 实例复用：Guard 实例应该被创建一次并在多次调用中复用，避免重复初始化开销。
2. 批量验证：对于支持批量操作的框架（如 LangChain 的 batch 方法），应优先使用批量接口。
3. 异步支持：所有 Runnable 实现都支持异步操作，在高并发场景下应使用 ainvoke 或 abatch。

错误处理策略

框架选择指南

相关资源

• Guardrails 官方文档
• Guardrails Hub 验证器库
• LangChain 官方文档
• LlamaIndex 官方文档

Pitfall Log / 踩坑日志

项目：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