NeMo Guardrails：给大模型戴上安全护栏的可编程对话守卫

开篇：这篇教程带你完成什么

读完并跟着操作，你会在本地跑起来一个带 NeMo Guardrails 的对话服务：用户输入“把大象放进冰箱”，护栏会拦截这个无法执行的操作，并返回一条安全提示，而不是让背后的语言模型硬答。

前置条件

• Python 3.10 或 3.11（3.12 部分依赖尚未完全兼容）
• pip 23.0+，用于安装 Python 包
• OpenAI API Key 或本地兼容接口（如 vLLM、Ollama），NeMo Guardrails 默认调用 OpenAI 格式接口
• 建议 8GB 内存以上，本教程不涉及本地大模型推理
• Linux / macOS / WSL2 均可，Windows 原生环境不保证命令一致

安装部署

第 1 步：创建虚拟环境并安装

python3 -m venv nemo-env
source nemo-env/bin/activate
pip install --upgrade pip
pip install nemoguardrails

安装完成后验证版本：

python -c "import nemoguardrails; print(nemoguardrails.__version__)"

第 2 步：初始化项目结构

mkdir rails-demo && cd rails-demo
mkdir -p config/rails
touch config/config.yml
touch config/rails/action_calls.yml

NeMo Guardrails 使用 config/rails 目录存放护栏规则文件，这是它的默认约定。

第 3 步：启动最小服务

先别急着跑，我们要在配置文件里指定大模型后端。

cat > config/config.yml << 'EOF'
models:
  - type: main
    engine: openai
    model: gpt-3.5-turbo

rails:
  config:
    core:
      verbose: true
EOF

配置完成后，用 Python 交互式验证启动：

python << 'EOF'
from nemoguardrails import RailsConfig
from nemoguardrails import LLMRails

config = RailsConfig.from_path("config")
rails = LLMRails(config)
print("Rails 加载成功，等待请求...")
EOF

预期输出：Rails 加载成功，等待请求...，且没有报错。

第一个 Demo：拦截“指令型”危险操作

这一步要做什么

定义一条“用户说把大象放进冰箱”的护栏规则。护栏收到这条消息后，不去调用 LLM，而是直接返回固定安全回复。

第 1 步：编写护栏规则

cat > config/rails/action_calls.yml << 'EOF'
rails:
  user_action:
    - user said "把大象放进冰箱"
      or user said "帮我杀死进程"
      -> respond "抱歉，这个操作我不能执行。"
EOF

第 2 步：启动 Demo 脚本

cat > demo.py << 'EOF'
from nemoguardrails import LLMRails, RailsConfig

config = RailsConfig.from_path("config")
rails = LLMRails(config)

messages = [{"role": "user", "content": "把大象放进冰箱"}]
response = rails.generate(messages=messages)
print("护栏回复：", response["content"])

messages2 = [{"role": "user", "content": "帮我写一首关于星星的诗"}]
response2 = rails.generate(messages=messages2)
print("正常请求回复：", response2["content"])
EOF
python demo.py

预期输出

护栏回复： 抱歉，这个操作我不能执行。
正常请求回复： （这里会调用 GPT，输出一首关于星星的诗）

如果第二条消息也返回“抱歉”，请检查是否已正确设置 OPENAI_API_KEY 环境变量，或确认网络能访问 OpenAI 接口。

配置与调优

1. 修改嵌入模型模型

NeMo Guardrails 默认使用 text-embedding-ada-002 做意图匹配，可以换成更轻量的本地嵌入模型：

models:
  - type: main
    engine: openai
    model: gpt-3.5-turbo
  - type: embeddings
    engine: openai
    model: text-embedding-3-small

2. 调整护栏的容错范围

用 similarity_threshold 控制用户输入跟护栏规则之间的匹配度，数值越低越容易命中：

rails:
  config:
    core:
      similar_tasks_threshold: 0.35  # 默认 0.5，如果发现该拦的没拦住就调低

3. 开启详细日志，调试时必开

export LOGLEVEL=DEBUG
python demo.py

这能让你看到每一条用户消息被哪些护栏规则扫描了，方便定位为什么某条输入没被拦截。

常见坑与排错

下一步

• 自己定义 bot_action 护栏，拦截模型输出中的敏感内容，而不仅限制用户输入
• 集成 Colang 对话流，实现多轮上下文下的动态护栏：例如先反问用户确认，再决定是否执行
• 把护栏接入 FastAPI，封装成 HTTP 接口，接入你现有的应用后端