Python API

在您的项目中使用 guardrails 的主要方式是

创建一个 RailsConfig 对象。
创建一个 LLMRails 实例，该实例提供了一个自动应用配置 guardrails 的 LLM 接口。
使用 LLMRails.generate(...) 或 LLMRails.generate_async(...) 方法生成 LLM 响应。

基本用法

from nemoguardrails import LLMRails, RailsConfig

config = RailsConfig.from_path("path/to/config")

app = LLMRails(config)
new_message = app.generate(messages=[{
    "role": "user",
    "content": "Hello! What can you do for me?"
}])

RailsConfig

RailsConfig 类包含用于配置 guardrails 的关键信息位

models: rails 配置使用的模型列表。
user_messages: 应该用于 rails 的用户消息列表。
bot_messages: 应该用于 rails 的机器人消息列表。
flows: 应该用于 rails 的流程列表。
instructions: 自然语言的指令列表（目前，仅支持通用指令）。
docs: 知识库中包含的文档列表。
sample_conversation: 在提示中使用的示例对话。
actions_server_url: 要使用的动作服务器。如果指定，动作将通过动作服务器执行。

消息生成

要使用 guardrails 配置，您可以调用 LLMRails.generate 或 LLMRails.generate_async 方法。

LLMRails.generate 方法接受 prompt 或 messages 数组作为输入。当提供 prompt 时，guardrails 应用于单轮对话中。消息的结构如下

properties:
  role:
    type: "string"
    enum: ["user", "assistant", "context"]
  content:
    oneOf:
      - type: "string"
      - type: "object"

对话历史的示例如下

[
  {
    "role": "user",
    "content": "Hello!"
  },
  {
    "role": "assistant",
    "content": "Hello! How can I help you?"
  },
  {
    "role": "user",
    "content": "I want to know if my insurance covers certain expenses."
  }
]

也设置了初始上下文的示例如下

[
  {
    "role": "context",
    "content": {
      "user_name": "John",
      "access_level": "admin"
    }
  },
  {
    "role": "user",
    "content": "Hello!"
  },
  {
    "role": "assistant",
    "content": "Hello! How can I help you?"
  },
  {
    "role": "user",
    "content": "I want to know if my insurance covers certain expenses."
  }
]

动作

动作是 Guardrails 工具包的关键组件。动作使得在 guardrails 内部执行 python 代码成为可能。

默认动作

以下是工具包中包含的默认动作

核心动作

generate_user_intent: 生成用户所说内容的规范形式。
generate_next_step: 生成当前对话流程中的下一步。
generate_bot_message: 基于期望的机器人意图生成机器人消息。
retrieve_relevant_chunks: 从知识库中检索相关块并将它们添加到上下文中。

Guardrail 特定动作

self_check_facts: 检查最后一次机器人响应的事实，参考从知识库中提取的相关块。
self_check_input: 检查是否应该允许用户输入。
self_check_output: 检查是否应该允许机器人响应。
self_check_hallucination: 检查最后一次机器人响应是否是幻觉。

为了方便起见，此工具包还包括一些 LangChain 工具，包装为动作

apify: Apify 是一个网络抓取和网络自动化平台，使您能够构建自己的网络爬虫和网络抓取器。
bing_search: Bing Web Search API 的包装器。
google_search: 来自 Langchain 的 Google Search API 的包装器。
searx_search: Searx API 的包装器。Google/Bing Search 的替代方案。
google_serper: SerpApi Google Search API 的包装器。它可以用于添加来自 Google Search 的答案框和知识图谱。
openweather_query: OpenWeatherMap API 的包装器，用于检索天气信息。
serp_api_query: SerpAPI API 的包装器。它提供对搜索引擎的访问，并帮助回答有关当前事件的问题。
wikipedia_query: Wikipedia API 的包装器。它使用 MediaWiki API 从维基百科检索信息。
wolfram_alpha_query: Wolfram Alpha API 的包装器。它可以用于回答数学和科学问题。
zapier_nla_query: Zapier NLA API 的包装器。它提供对超过 5k 个应用程序和 20k 个动作的访问，以自动化您的工作流程。

链作为动作

您可以使用 LLMRails.register_action 方法将 Langchain 链注册为动作

app.register_action(some_chain, name="some_chain")

当链作为动作被调用时，动作的参数对应于链的输入键。对于返回值，如果链的输出只有一个键，则将返回该值。如果链有多个输出键，则返回输出键及其值的字典。有关更多详细信息，请参阅 LangChain 集成指南。

自定义动作

您可以使用 action 装饰器或 LLMRails(RailsConfig).register_action(action: callable, name: Optional[str]) 将任何 python 函数注册为自定义动作。

from nemoguardrails.actions import action

@action()
async def some_action():
    # Do some work

    return "some_result"

默认情况下，动作的名称设置为函数的名称。但是，您可以通过指定不同的名称来更改它。

from nemoguardrails.actions import action

@action(name="some_action_name")
async def some_action():
    # Do some work

    return "some_result"

动作可以接受任意数量的参数。由于动作是从 Colang 流程调用的，因此参数的类型仅限于 *string*、*integer*、*float*、*boolean*、*list* 和 *dictionary*。

特殊参数

如果以下参数出现在动作的签名中，NeMo Guardrails 工具包会自动提供这些特殊参数

events: 到目前为止的事件历史记录；最后一个是触发动作本身的事件；
context: 动作可用的上下文数据；
llm: 访问 LLM 实例 (来自 LangChain 的 BaseLLM)；
config: 完整的 RailsConfig 实例。

这些参数仅用于高级用例。

动作参数

以下是可以用于动作的参数

参数	描述	类型	示例
`events`	到目前为止的事件历史记录；最后一个是触发动作本身的事件。	List[dict]	`[ {'type': 'UtteranceUserActionFinished', ...}, {'type': 'StartInternalSystemAction', 'action_name': 'generate_user_intent', ...}, {'type': 'InternalSystemActionFinished', 'action_name': 'generate_user_intent', ...} ]`
`context`	动作可用的上下文数据。	dict	`{ 'last_user_message': ..., 'last_bot_message': ..., 'retrieved_relevant_chunks': ... }`
`llm`	访问 LLM 实例 (来自 LangChain 的 BaseLLM)。	BaseLLM	`OpenAI(model="gpt-3.5-turbo-instruct",...)`