有关更详细的说明，请参阅[安装指南](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!"}]
)

`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
│   ├── ...

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**，这是一种专为设计灵活且可控的对话流程而创建的建模语言。Colang 具有类似 Python 的语法，并且设计得简单直观，尤其适合开发者使用。```{note}
Two versions of Colang, 1.0 and 2.0, are supported and Colang 1.0 is the default.

该库包含用于 LLM 自我检查的护栏（输入/输出审核、事实核查、幻觉检测）、NVIDIA 安全模型（内容安全、主题安全）、越狱和注入检测，以及与社区模型和第三方 API 的集成。完整列表请参阅 [Guardrails 库文档](https://docs.nvidia.com/nemo/guardrails/user-guides/guardrails-library.html)。

## CLI

NeMo Guardrails 库还附带一个内置 CLI。```bash
$ nemoguardrails --help

Usage: nemoguardrails [OPTIONS] COMMAND [ARGS]...

actions-server    Start a NeMo Guardrails actions server.
chat              Start an interactive chat session.
evaluate          Run an evaluation task.
server            Start a NeMo Guardrails server.

例如，要为 `sample` 配置获取聊天补全，你可以使用 `/v1/chat/completions` 端点：```
POST /v1/chat/completions

# 基本用法
scanner -u https://example.com

# 使用自定义请求头
scanner -u https://example.com -H "Authorization: Bearer token"

# 使用代理和自定义超时时间
scanner -u https://example.com --proxy http://127.0.0.1:8080 --timeout 30

# 将结果保存为 JSON 格式
scanner -u https://example.com --output results.json --format json

# 使用配置文件
scanner --config config.yaml

target: https://example.com
threads: 10
timeout: 30
proxy: http://127.0.0.1:8080
headers:
  User-Agent: "Mozilla/5.0"
  Authorization: "Bearer token"
cookies:
  session: "abc123"
follow_redirects: true
verify_ssl: false
rate_limit: 100
output: results.json
format: json
verbose: true

[+] 目标：https://example.com
[+] 状态：200 OK
[+] 服务器：nginx/1.18.0
[+] 检测到的技术：Nginx、PHP、jQuery
[+] 发现的漏洞：2
    - CVE-2021-1234（严重）
    - CVE-2021-5678（高危）

{
  "target": "https://example.com",
  "status": 200,
  "server": "nginx/1.18.0",
  "technologies": ["Nginx", "PHP", "jQuery"],
  "vulnerabilities": [
    {
      "id": "CVE-2021-1234",
      "severity": "critical",
      "description": "远程代码执行漏洞"
    },
    {
      "id": "CVE-2021-5678",
      "severity": "high",
      "description": "SQL 注入漏洞"
    }
  ]
}

target,status,server,technologies,vulnerabilities
https://example.com,200,nginx/1.18.0,"Nginx;PHP;jQuery","CVE-2021-1234;CVE-2021-5678"

docker run -it --rm scanner -u https://example.com

# .github/workflows/scan.yml
name: Security Scan
on: [push]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run scanner
        run: |
          docker run -it --rm scanner -u https://example.com --output results.json --format json
      - name: Upload results
        uses: actions/upload-artifact@v2
        with:
          name: scan-results
          path: results.json

chmod +x scanner

scanner -u https://example.com --timeout 60

scanner -u https://example.com --verify-ssl false

scanner -u https://example.com --threads 5

# 使用 Go
go install github.com/example/scanner@latest

# 使用 Homebrew
brew upgrade scanner

# 使用 Docker
docker pull scanner:latest

scanner -f targets.txt

示例输出：```json
{"role": "assistant", "content": "Hi! How can I help you?"}

在 NVIDIA NeMo Guardrails 库启动之前设置退出选项。在遥测已启动后更改环境变量或创建 `do_not_track` 不会停止已在运行的心跳线程。

有关完整架构和逐字段说明，请参阅 [docs/telemetry.md](https://docs.nvidia.com/nemo/guardrails/latest/telemetry.html)。

您可以随时退出遥测数据收集。退出仅适用于 NVIDIA NeMo Guardrails 库本身的数据收集。

第三方端点有单独的条款和隐私惯例。NVIDIA NeMo Guardrails 库可以使用诸如 NVIDIA Build（`build.nvidia.com`）之类的推理端点。如果您使用 NVIDIA Build 或其他第三方端点，该端点的服务条款和隐私惯例将独立于本库适用。NVIDIA NeMo Guardrails 库中的任何遥测退出均不延伸至您所选择的端点。NVIDIA Build 仅供评估和测试使用，不得用于生产环境。使用 NVIDIA Build 时，请勿提交机密信息或个人数据。

## 邀请社区贡献

仓库中现有的示例护栏是极好的起点。我们热忱邀请社区贡献力量，让可信、安全且可靠的 LLM 能力惠及所有人。有关设置开发环境以及如何为 NeMo Guardrails 库贡献的指导，请参阅[贡献指南](https://github.com/nvidia-nemo/guardrails/blob/develop/CONTRIBUTING.md)。

## 许可证

NeMo Guardrails 库根据 [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0) 许可。

## 如何引用

如果您使用 NeMo Guardrails 库，请引用介绍该库的 [EMNLP 2023 论文](https://aclanthology.org/2023.emnlp-demo.40)。```bibtex
@inproceedings{rebedea-etal-2023-nemo,
    title = "{N}e{M}o Guardrails: A Toolkit for Controllable and Safe {LLM} Applications with Programmable Rails",
    author = "Rebedea, Traian  and
      Dinu, Razvan  and
      Sreedhar, Makesh Narsimhan  and
      Parisien, Christopher  and
      Cohen, Jonathan",
    editor = "Feng, Yansong  and
      Lefever, Els",
    booktitle = "Proceedings of the 2023 Conference on Empirical Methods in Natural Language Processing: System Demonstrations",
    month = dec,
    year = "2023",
    address = "Singapore",
    publisher = "Association for Computational Linguistics",
    url = "https://aclanthology.org/2023.emnlp-demo.40",
    doi = "10.18653/v1/2023.emnlp-demo.40",
    pages = "431--445",
}