新闻与更新

• [2025年2月12日] 我们刚刚推出了 Guardrails Index——首个同类基准，用于比较 24 种护栏工具在 6 大常见类别中的性能和延迟！请访问 index.guardrailsai.com 查看该指数。

什么是 Guardrails？

Guardrails 是一个 Python 框架，通过执行两项关键功能来帮助构建可靠的 AI 应用程序：

1. Guardrails 在您的应用程序中运行输入/输出护栏，以检测、量化并缓解特定类型的风险。要查看完整的风险列表，请访问 Guardrails Hub。
2. Guardrails 帮助您从 LLM 中生成结构化数据。

Guardrails Hub

Guardrails Hub 是一系列预构建的特定类型风险度量（称为“验证器”）。多个验证器可以组合成输入和输出护栏，拦截 LLM 的输入和输出。访问 Guardrails Hub 查看完整的验证器列表及其文档。

安装

pip install guardrails-ai

入门指南

创建用于 LLM 验证的输入和输出护栏

1. 下载并配置 Guardrails Hub CLI。

   pip install guardrails-ai
   guardrails configure
   

2. 从 Guardrails Hub 安装一个护栏。

   guardrails hub install hub://guardrails/regex_match
   

3. 从已安装的护栏创建一个护栏。

   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)
   

   输出：

   字段验证失败，错误如下：结果必须匹配 \(?\d{3}\)?-? *\d{3}-? *-?\d{4}
   

4. 在一个护栏中运行多个护栏。 首先，从 Guardrails Hub 安装必要的护栏。

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

   然后，从已安装的护栏创建一个护栏。

   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 for keeping your health."""
   )  # 两个护栏都通过
   
   try:
       guard.validate(
           """Shut the hell up! Apple just released a new iPhone."""
       )  # 两个护栏都失败
   except Exception as e:
       print(e)
   

   输出：

   字段验证失败，错误如下：发现了以下竞争对手：[['Apple']]。请下次避免提及这些竞争对手；您的回复中包含以下有毒语句：
   
   - Shut the hell up!
   

使用 Guardrails 从 LLM 中生成结构化数据

让我们通过一个例子来说明如何让 LLM 生成虚构的宠物名字。为此，我们将创建一个 Pydantic BaseModel，它代表我们期望的输出结构。

from pydantic import BaseModel, Field

class Pet(BaseModel):
    pet_type: str = Field(description="宠物种类")
    name: str = Field(description="独特的宠物名字")

现在，从 Pet 类创建一个护栏。该护栏可用于调用 LLM，使输出格式化为 Pet 类。其底层实现方式有两种：

1. 函数调用：对于支持函数调用的 LLM，我们使用函数调用语法生成结构化数据。
2. 提示优化：对于不支持函数调用的 LLM，我们将预期输出的模式添加到提示中，以便 LLM 能够生成结构化数据。

from guardrails import Guard
import openai

prompt = """
    我应该养什么类型的宠物，又该给它取个什么名字呢？

    ${gr.complete_json_suffix_v2}
"""
guard = Guard.for_pydantic(output_class=Pet, prompt=prompt)

raw_output, validated_output, *rest = guard(
    llm_api=openai.completions.create,
    engine="gpt-3.5-turbo-instruct"
)

print(validated_output)

这将打印出：

{
    "pet_type": "dog",
    "name": "Buddy
}

Guardrails 服务器

Guardrails 可以通过 guardrails start 命令以 Flask 提供的独立服务形式部署，从而允许您通过 REST API 与其交互。这种方法简化了基于 Guardrails 的应用程序的开发和部署。

1. 安装：pip install "guardrails-ai"
2. 配置：guardrails configure
3. 创建配置：guardrails create --validators=hub://guardrails/two_words --guard-name=two-word-guard
4. 启动开发服务器：guardrails start --config=./config.py
5. 使用以下代码片段与开发服务器交互：

# 使用 guardrails 客户端
import guardrails as gr

gr.settings.use_server = True
guard = gr.Guard(name='two-word-guard')
guard.validate('this is more than two words')

# 或者使用 OpenAI SDK
import openai
openai.base_url = "http://localhost:8000/guards/two-word-guard/openai/v1/"
os.environ["OPENAI_API_KEY"] = "youropenaikey"

messages = [
        {
            "role": "user",
            "content": "用恰好三个词告诉我关于苹果的事情",
        },
    ]

completion = openai.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,
)

对于生产环境部署，我们建议使用 Docker 并搭配 Gunicorn 作为 WSGI 服务器，以提升性能和可扩展性。

常见问题解答

我在使用 Guardrails 时遇到了问题，可以在哪里寻求帮助？

您可以通过 Discord 或 Twitter 联系我们。

我可以将 Guardrails 与任何大模型一起使用吗？

是的，Guardrails 可以与专有和开源的大模型一起使用。请参阅这篇关于如何将 Guardrails 与任何大模型结合使用的指南。

我可以创建自己的验证器吗？

当然可以！您可以创建自己的验证器，并将其贡献到 Guardrails Hub。请参阅这篇关于如何创建自定义验证器的指南。

Guardrails 是否支持其他语言？

目前，Guardrails 支持 Python 和 JavaScript。您可以查阅文档，了解如何从 JavaScript 中使用 Guardrails。我们正在努力增加对其他语言的支持。如果您希望为 Guardrails 做出贡献，请通过 Discord 或 Twitter 联系我们。

贡献

我们欢迎所有对 Guardrails 的贡献！

您可以从浏览 GitHub 上的问题开始，并查看贡献指南。欢迎您随时提出新问题，或在希望参与项目时与我们联系！

Guardrails AI 快速上手指南

Guardrails 是一个 Python 框架，旨在通过执行输入/输出防护（Guards）来检测、量化和缓解特定类型的风险，并帮助从大语言模型（LLM）生成结构化数据，从而构建可靠的 AI 应用。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：3.8 - 3.12
• 前置依赖：
  • pip (Python 包管理工具)
  • 已配置的 LLM API Key（如 OpenAI，用于结构化数据生成示例）

提示：国内开发者若遇到下载速度慢的问题，建议在安装命令中指定国内镜像源（如清华源或阿里源）。

安装步骤

1. 安装核心库

   pip install guardrails-ai -i https://pypi.tuna.tsinghua.edu.cn/simple
   

2. 配置 Guardrails Hub CLI 安装完成后，运行以下命令进行初始化配置（按提示操作即可）：

   guardrails configure
   

基本使用

场景一：为 LLM 创建输入/输出验证器 (Input/Output Guards)

此功能用于拦截并验证文本内容，例如检查格式、敏感词或竞争对手提及。

1. 安装所需的验证器 (Validators) 从 Guardrails Hub 安装预定义的验证规则（例如正则匹配、竞争对手检查、有毒语言检测）：

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

2. 编写验证代码 以下示例展示了如何组合多个验证规则并对文本进行校验：

from guardrails import Guard, OnFailAction
from guardrails.hub import CompetitorCheck, ToxicLanguage

# 创建一个 Guard，组合多个验证器
guard = Guard().use(
    # 检查是否包含特定竞争对手名称
    CompetitorCheck(["Apple", "Microsoft", "Google"], on_fail=OnFailAction.EXCEPTION),
    # 检查是否包含有毒/侮辱性语言
    ToxicLanguage(threshold=0.5, validation_method="sentence", on_fail=OnFailAction.EXCEPTION)
)

# 测试用例 1：正常内容，验证通过
guard.validate(
    """An apple a day keeps a doctor away.
    This is good advice for keeping your health."""
)

# 测试用例 2：包含违规内容，验证失败并抛出异常
try:
    guard.validate(
        """Shut the hell up! Apple just released a new iPhone."""
    )
except Exception as e:
    print(e)

预期输出（失败时）：

Validation failed for field with errors: Found the following competitors: [['Apple']]. Please avoid naming those competitors next time, The following sentences in your response were found to be toxic:

- Shut the hell up!

---

场景二：利用 Guardrails 生成结构化数据

此功能强制 LLM 按照指定的 Pydantic 模型格式输出数据（如 JSON），适用于需要固定格式输出的场景。

1. 定义数据结构 使用 Pydantic 定义你期望的输出格式：

from pydantic import BaseModel, Field

class Pet(BaseModel):
    pet_type: str = Field(description="Species of pet")
    name: str = Field(description="a unique pet name")

2. 调用 LLM 获取结构化结果 Guardrails 会自动处理 Prompt 优化或使用 Function Calling，确保输出符合 Pet 模型：

from guardrails import Guard
import openai

# 定义 Prompt，${gr.complete_json_suffix_v2} 是 Guardrails 的特殊标记
prompt = """
    What kind of pet should I get and what should I name it?

    ${gr.complete_json_suffix_v2}
"""

# 创建针对 Pydantic 模型的 Guard
guard = Guard.for_pydantic(output_class=Pet, prompt=prompt)

# 调用 LLM (需配置好 openai API Key)
raw_output, validated_output, *rest = guard(
    llm_api=openai.completions.create,
    engine="gpt-3.5-turbo-instruct"
)

print(validated_output)

预期输出：

{
    "pet_type": "dog",
    "name": "Buddy"
}