✨✨✨
📌 NeMo Guardrails 库的官方文档位于 docs.nvidia.com/nemo/guardrails。
✨✨✨
NVIDIA NeMo Guardrails 库是一个开源工具包，可轻松为基于 LLM 的对话应用添加可编程护栏。护栏（或简称 "rails"）是控制大型语言模型输出的特定方式，例如不谈论政治、以特定方式回应特定用户请求、遵循预定义的对话路径、使用特定的语言风格、提取结构化数据等。
这篇论文介绍了 NeMo Guardrails 库，并包含该系统的技术概述和当前评估。
Python 3.10、3.11、3.12 或 3.13。
使用 pip 安装：```bash
pip install nemoguardrails
有关更详细的说明，请参阅[安装指南](https://docs.nvidia.com/nemo/guardrails/get-started/installation-guide)。
## 概述
<!-- start-documentation-reuse -->
NeMo Guardrails 库使构建基于 LLM 应用程序的开发者能够在应用程序代码和 LLM 之间添加**可编程护栏**。
<div align="center">
<img src="https://raw.githubusercontent.com/NVIDIA-NeMo/Guardrails/develop/docs/_static/images/programmable_guardrails.png" width="75%" alt="Programmable Guardrails">
</div>
添加*可编程护栏*的主要优势包括：
- **构建可信、安全且可靠的基于 LLM 的应用程序：** 您可以定义护栏来引导和保护对话；您可以选择针对特定主题定义基于 LLM 的应用程序的行为，并防止其参与不受欢迎的话题讨论。
- **安全地连接模型、链和其他服务：** 您可以将 LLM 与其他服务（即工具）无缝且安全地连接。
- **可控对话**：您可以引导 LLM 遵循预定义的对话路径，从而按照对话设计最佳实践来设计交互，并执行标准操作流程（例如身份验证、支持）。
<!-- end-documentation-reuse -->
### 防范 LLM 漏洞
NeMo Guardrails 库提供了多种机制，用于保护由 LLM 驱动的聊天应用程序免受常见 LLM 漏洞的影响，例如越狱和提示注入。以下是本仓库中包含的示例 [ABC Bot](https://github.com/nvidia-nemo/guardrails/blob/develop/examples/bots/abc) 在不同护栏配置下所提供的保护的示例概览。有关更多详细信息，请参阅 [LLM 漏洞扫描](https://docs.nvidia.com/nemo/guardrails/evaluation/llm-vulnerability-scanning.html)页面。
<div align="center">
<img src="https://raw.githubusercontent.com/NVIDIA-NeMo/Guardrails/develop/docs/_static/images/abc-llm-vulnerability-scan-results.png" width="500">
</div>
### 使用场景
您可以在不同类型的用例中使用可编程护栏：
1. **基于一组文档的问答**（即检索增强生成）：强制执行事实核查和输出审核。
2. **特定领域的助手**（即聊天机器人）：确保助手不偏离主题并遵循设计好的对话流程。
3. **LLM 端点**：为您的自定义 LLM 添加护栏，以实现更安全的客户交互。
4. **LangChain 链**（可选）：如果您在任何用例中使用 LangChain，可以在链周围添加护栏层。要启用此集成，请设置 `NEMOGUARDRAILS_LLM_FRAMEWORK=langchain` 环境变量或调用 `set_default_framework("langchain")`。
### 用法
要为您的应用程序添加可编程护栏，您可以使用 Python API 或护栏服务器（有关更多详细信息，请参阅[服务器指南](https://docs.nvidia.com/nemo/guardrails/get-started/integrate-into-application)）。使用 Python API 与直接使用 LLM 类似。调用护栏层而不是 LLM 只需对代码库进行最小改动，并且涉及两个简单步骤：
1. 加载护栏配置并创建 `LLMRails` 实例。
2. 使用 `generate`/`generate_async` 方法调用 LLM。```python
from nemoguardrails import LLMRails, RailsConfig
# Load a guardrails configuration from the specified path.
config = RailsConfig.from_path("PATH/TO/CONFIG")
rails = LLMRails(config)
completion = rails.generate(
messages=[{"role": "user", "content": "Hello world!"}]
)
示例输出：```json {"role": "assistant", "content": "Hi! How can I help you?"}
`generate` 方法的输入和输出格式与 OpenAI 的 [Chat Completions API](https://platform.openai.com/docs/guides/gpt/chat-completions-api) 类似。
#### 异步 API
NeMo Guardrails 库是一个异步优先的工具包，因为其核心机制是使用 Python 异步模型实现的。公共方法同时提供同步和异步版本。例如：`LLMRails.generate` 和 `LLMRails.generate_async`。
### 支持的 LLM
你可以将 NeMo Guardrails 与多个 LLM 一起使用，例如 OpenAI GPT-3.5、GPT-4、LLaMa-2、Falcon、Vicuna 或 Mosaic。有关更多详细信息，请查看配置指南中的[支持的 LLM 模型](https://docs.nvidia.com/nemo/guardrails/about-nemo-guardrails-library/supported-llms)部分。
### 护栏类型
NeMo Guardrails 库支持五种主要类型的护栏：
<div align="center">
<img src="https://raw.githubusercontent.com/NVIDIA-NeMo/Guardrails/develop/docs/_static/images/programmable_guardrails_flow.png" width="75%" alt="Programmable Guardrails Flow">
</div>
1. **输入护栏**：应用于来自用户的输入；输入护栏可以拒绝输入，停止任何进一步处理，或修改输入（例如，屏蔽潜在敏感数据、改写）。
2. **对话护栏**：影响 LLM 的提示方式；对话护栏作用于规范形式消息（有关详细信息，请参阅 [Colang 指南](https://docs.nvidia.com/nemo/guardrails/configure-guardrails/colang)），并决定是否应执行某个操作、是否应调用 LLM 生成下一步或响应、是否应改用预定义响应等。
3. **检索护栏**：在 RAG（检索增强生成）场景中应用于检索到的块；检索护栏可以拒绝某个块，阻止其被用于提示 LLM，或修改相关块（例如，屏蔽潜在敏感数据）。
4. **执行护栏**：应用于需要由 LLM 调用的自定义操作（又称工具）的输入/输出。
5. **输出护栏**：应用于 LLM 生成的输出；输出护栏可以拒绝输出，阻止其返回给用户，或修改输出（例如，移除敏感数据）。
### 护栏配置
护栏配置定义了要使用的 **LLM** 以及**一个或多个护栏**。护栏配置可以包含任意数量的输入/对话/输出/检索/执行护栏。未配置任何护栏的配置本质上会将请求转发给 LLM。
护栏配置文件夹的标准结构如下所示：```
.
├── config
│ ├── actions.py
│ ├── config.py
│ ├── config.yml
│ ├── rails.co
│ ├── ...
config.yml 包含所有通用配置选项，例如 LLM 模型、启用的护栏以及自定义配置数据。config.py 文件包含任何自定义初始化代码，actions.py 包含任何自定义 Python 操作。有关完整概述，请参阅配置指南。
以下是一个 config.yml 示例：```yaml
models:
rails:
input: flows: - check jailbreak - mask sensitive data on input
output: flows: - self check facts - self check hallucination - activefence moderation on input
config: # Configure the types of entities that should be masked on user input. sensitive_data_detection: input: entities: - PERSON - EMAIL_ADDRESS
guardrails 配置中包含的 `.co` 文件含有 Colang 定义（关于 Colang 的简要概述见下一节），这些定义用于定义各种类型的护栏。下面是一个示例 `greeting.co` 文件，它定义了用于向用户问候的对话护栏。```colang
define user express greeting
"Hello!"
"Good afternoon!"
define flow
user express greeting
bot express greeting
bot offer to help
define bot express greeting
"Hello there!"
define bot offer to help
"How can I help you today?"
以下是一个针对侮辱性言论的对话护栏的 Colang 定义附加示例：```colang define user express insult "You are stupid"
define flow user express insult bot express calmly willingness to help
### Colang
为了配置和实现各种类型的护栏，本工具包引入了 **Colang**，这是一种专为设计灵活且可控的对话流程而创建的建模语言。Colang 具有类似 Python 的语法，并且设计得简单直观，尤其适合开发者使用。```{note}
Two versions of Colang, 1.0 and 2.0, are supported and Colang 1.0 is the default.
关于 Colang 1.0 语法的简要介绍，请参阅 Colang 1.0 语言语法指南。
要开始使用 Colang 2.0，请参阅 Colang 2.0 文档。