生成选项#

NeMo Guardrails 公开了一组**生成选项**，使您可以精细地控制 LLM 生成的执行方式（例如，启用哪些 rails，应传递给 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": {
      ...
    }
}

输出变量#

某些 rails 可以在上下文变量中存储其他信息。您可以通过将 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：包括有关生成期间激活的 rails 的详细信息。
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**：添加有关返回数据的更多详细信息。

禁用 Rails#

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

res = rails.generate(messages=messages)

等效于

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

仅输入 Rails#

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

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

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

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

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

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

如果输入被阻止，您将获得预定义的响应 bot refuse to respond（默认情况下为 “I’m sorry, I can’t respond to that”）。

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

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

仅输入和输出 Rails#

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

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

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

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

仅输出 Rails#

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

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

限制#

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