生成选项

NeMo Guardrails 公开了一组生成选项，使您可以细粒度地控制 LLM 生成的执行方式（例如，启用哪些 rail、应传递给 LLM 的其他参数、应返回哪些上下文数据、应返回哪些日志记录信息）。

生成选项可以在 Python API 和服务器 API 中使用。

要通过 Python API 使用生成选项，您必须提供 options 关键字参数

messages = [{
    "role": "user",
    "content": "..."
}]
rails.generate(messages=messages, options={...})

要通过服务器 API 使用生成选项，您必须将 options 作为请求正文的一部分提供

POST /v1/chat/completions

{
    "config_id": "...",
    "messages": [{
      "role":"user",
      "content":"..."
    }],
    "options": {
      ...
    }
}

输出变量

一些 rail 可以将其他信息存储在上下文变量中。您可以通过将 output_vars 生成选项设置为您感兴趣的所有变量的名称列表来返回这些变量的内容。如果您想返回完整上下文（这也将包括一些预定义的变量），您可以将 output_vars 设置为 True。

rails.generate(messages=messages, options={
    "output_vars": ["some_input_rail_score", "some_output_rail_score"]
})

返回的数据将包含在响应的 output_data 键中

{
  "response": [...],
  "output_data": {
    "some_input_rail_score": 0.7,
    "some_output_rail_score": 0.8
  }
}

其他 LLM 参数

您可以使用 llm_params 生成选项将其他参数传递给用于生成最终消息的 LLM 调用。例如，要使用比默认温度更低的温度

rails.generate(messages=messages, options={
    "llm_params": {
        "temperature": 0.2
    }
})

支持的参数取决于底层 LLM 引擎。NeMo Guardrails “按原样”传递它们。

其他 LLM 输出

您可以使用 llm_output 生成选项从 LLM 生成接收其他输出。

rails.generate(messages=messages, options={
    "llm_output": True
})

注意：返回的数据高度依赖于 LLM 提供商的 LangChain 连接器的底层实现。例如，对于 OpenAI，它仅返回 token_usage 和 model_name。

详细日志信息

您可以通过设置 log 生成选项来获取有关生成过程中幕后发生情况的详细信息。此选项有四个不同的内部选项

activated_rails：包含有关生成期间激活的 rail 的详细信息。
llm_calls：包含有关所有 LLM 调用的信息。这包括：提示、完成、令牌使用情况、原始响应等。
internal_events：包含内部生成的事件数组。
colang_history：包含 Colang 格式的对话历史记录。

res = rails.generate(messages=messages, options={
    "log": {
        "activated_rails": True,
        "llm_calls": True,
        "internal_events": True,
        "colang_history": True
    }
})

{
  "response": [...],
  "log": {
    "activated_rails": {
      ...
    },
    "stats": {...},
    "llm_calls": [...],
    "internal_events": [...],
    "colang_history": "..."
  }
}

使用 Python API 时，log 是一个对象，它也具有 print_summary 方法。调用时，它将打印日志信息的简化版本。以下是示例输出。

res.log.print_summary()

# General stats

- Total time: 2.85s
  - [0.56s][19.64%]: INPUT Rails
  - [1.40s][49.02%]: DIALOG Rails
  - [0.58s][20.22%]: GENERATION Rails
  - [0.31s][10.98%]: OUTPUT Rails
- 5 LLM calls, 2.74s total duration, 1641 total prompt tokens, 103 total completion tokens, 1744 total tokens.

# Detailed stats

- [0.56s] INPUT (self check input): 1 actions (self_check_input), 1 llm calls [0.56s]
- [0.43s] DIALOG (generate user intent): 1 actions (generate_user_intent), 1 llm calls [0.43s]
- [0.96s] DIALOG (generate next step): 1 actions (generate_next_step), 1 llm calls [0.95s]
- [0.58s] GENERATION (generate bot message): 2 actions (retrieve_relevant_chunks, generate_bot_message), 1 llm calls [0.49s]
- [0.31s] OUTPUT (self check output): 1 actions (self_check_output), 1 llm calls [0.31s]

TODO：添加有关返回数据的更多详细信息。

禁用 Rail

您可以使用 rails 生成选项选择要应用的 rail 类别。支持的四个类别是：input、dialog、retrieval 和 output。默认情况下，所有类别都已启用。

res = rails.generate(messages=messages)

等效于

res = rails.generate(messages=messages, options={
    "rails": ["input", "dialog", "retrieval", "output"]
})

仅输入 Rail

如果您只想通过运行来自 guardrails 配置的输入 rail 来检查用户输入，则必须禁用所有其他 rail

res = rails.generate(messages=[{
    "role": "user",
    "content": "Some user input."
}], options={
    "rails": ["input"]
})

如果输入“按原样”被允许，则响应将是相同的字符串

{
  "role": "assistant",
  "content": "Some user input."
}

如果某些 rail 更改了输入，例如，为了屏蔽敏感信息，则返回的值是更改后的输入。

{
  "role": "assistant",
  "content": "Some altered user input."
}

如果输入被阻止，您将收到预定义的响应 bot refuse to respond（默认情况下为“抱歉，我无法回应”）。

{
  "role": "assistant",
  "content": "I'm sorry, I can't respond to that."
}

有关触发了哪些 rail 的更多详细信息，请使用 log.activated_rails 生成选项。

仅输入和输出 Rail

如果您想同时检查用户输入和在 guardrails 配置之外生成的输出，则必须禁用对话 rail 和检索 rail，并在调用时提供 bot 消息

res = rails.generate(messages=[{
    "role": "user",
    "content": "Some user input."
}, {
    "role": "bot",
    "content": "Some bot output."
}], options={
    "rails": ["input", "output"]
})

如果允许，响应将是提供的确切 bot 消息；如果输出 rail 决定更改它，例如，删除敏感信息，则响应将是更改后的版本；如果消息被阻止，则响应将是 bot refuse to respond 的预定义消息。

有关触发了哪些 rail 的更多详细信息，请使用 log.activated_rails 生成选项。

仅输出 Rail

如果您只想将输出 rail 应用于 LLM 输出，则必须禁用输入 rail 并提供空输入。

res = rails.generate(messages=[{
    "role": "user",
    "content": ""
}, {
    "role": "bot",
    "content": "Some bot output."
}], options={
    "rails": ["output"]
})

局限性

仅支持 generate/generate_async 方法（不适用于 generate_events/generate_events_async）。
尚不支持指定要激活的特定类型的各个 rail。