AutoAlign 集成#

此包实现了 AutoAlign 的 guardrails API 集成 - 由 AutoAlign 提供的全面的 guardrail 库。

AutoAlign 提供了一个内置 guardrails 库，您可以轻松使用

性别偏见检测
危害检测
越狱检测
机密信息检测
知识产权检测
种族偏见检测
语气检测
毒性检测
PII
事实核查

注意：与其他的 guardrails 相比，事实核查的实现方式略有不同。请查阅本文档中对其的描述以了解其用法。

AutoAlign API KEY#

为了使用 AutoAlign 的 guardrails，您需要在系统中设置环境变量 AUTOALIGN_API_KEY，其值为您的 API 密钥。

请联系 hello@autoalign.ai 获取您自己的 API 密钥。请在邮件主题行中提及 NeMo 和 AutoAlign，以便 AutoAlign 团队能快速回复。

用法#

要使用 AutoAlign 的 guardrails

您必须使用 guardrails_config 部分来配置 guardrails，该部分可以提供给 config.yml 文件中 autoalign 部分下的 input 部分和 output 部分。

rails:
    config:
        autoalign:
            parameters:
                endpoint: "https://<AUTOALIGN_ENDPOINT>/guardrail"
                multi_language: False
            input:
                guardrails_config:
                    {
                      "pii": {
                          "enabled_types": [
                              "[BANK ACCOUNT NUMBER]",
                              "[CREDIT CARD NUMBER]",
                              "[DATE OF BIRTH]",
                              "[DATE]",
                              "[DRIVER LICENSE NUMBER]",
                              "[EMAIL ADDRESS]",
                              "[RACE/ETHNICITY]",
                              "[GENDER]",
                              "[IP ADDRESS]",
                              "[LOCATION]",
                              "[MONEY]",
                              "[ORGANIZATION]",
                              "[PASSPORT NUMBER]",
                              "[PASSWORD]",
                              "[PERSON NAME]",
                              "[PHONE NUMBER]",
                              "[PROFESSION]",
                              "[SOCIAL SECURITY NUMBER]",
                              "[USERNAME]",
                              "[SECRET_KEY]",
                              "[TRANSACTION_ID]",
                              "[RELIGION]",
                          ],
                          "contextual_rules":[
                                  [ "[PERSON NAME]", "[CREDIT CARD NUMBER]", "[BANK ACCOUNT NUMBER]" ],
                                  [ "[PERSON NAME]", "[EMAIL ADDRESS]", "[DATE OF BIRTH]" ]
                          ],
                          "matching_scores": {
                              "[BANK ACCOUNT NUMBER]": 0.5,
                              "[CREDIT CARD NUMBER]": 0.5,
                              "[DATE OF BIRTH]": 0.5,
                              "[DATE]": 0.5,
                              "[DRIVER LICENSE NUMBER]": 0.5,
                              "[EMAIL ADDRESS]": 0.5,
                              "[RACE/ETHNICITY]": 0.5,
                              "[GENDER]": 0.5,
                              "[IP ADDRESS]": 0.5,
                              "[LOCATION]": 0.5,
                              "[MONEY]": 0.5,
                              "[ORGANIZATION]": 0.5,
                              "[PASSPORT NUMBER]": 0.5,
                              "[PASSWORD]": 0.5,
                              "[PERSON NAME]": 0.5,
                              "[PHONE NUMBER]": 0.5,
                              "[PROFESSION]": 0.5,
                              "[SOCIAL SECURITY NUMBER]": 0.5,
                              "[USERNAME]": 0.5,
                              "[SECRET_KEY]": 0.5,
                              "[TRANSACTION_ID]": 0.5,
                              "[RELIGION]": 0.5
                          }
                        },
                        "confidential_info_detection": {
                              "matching_scores": {
                                  "No Confidential": 0.5,
                                  "Legal Documents": 0.5,
                                  "Business Strategies": 0.5,
                                  "Medical Information": 0.5,
                                  "Professional Records": 0.5
                              }
                        },
                        "gender_bias_detection": {
                              "matching_scores": {
                                  "score": 0.5
                              }
                        },
                        "harm_detection": {
                              "matching_scores": {
                                  "score": 0.5
                              }
                        },
                        "toxicity_detection": {
                              "matching_scores": {
                                  "score": 0.5
                              }
                        },
                        "racial_bias_detection": {
                              "matching_scores": {
                                  "No Racial Bias": 0.5,
                                  "Racial Bias": 0.5,
                                  "Historical Racial Event": 0.5
                              }
                        },
                        "tonal_detection": {
                              "matching_scores": {
                                  "Negative Tones": 0.5,
                                  "Neutral Tones": 0.5,
                                  "Professional Tone": 0.5,
                                  "Thoughtful Tones": 0.5,
                                  "Positive Tones": 0.5,
                                  "Cautious Tones": 0.5
                              }
                        },
                        "jailbreak_detection": {
                              "matching_scores": {
                                  "score": 0.5
                              }
                        },
                        "intellectual_property": {
                              "matching_scores": {
                                  "score": 0.5
                              }
                        }
                    }
            output:
                guardrails_config:
                  {
                      "pii": {
                          "enabled_types": [
                              "[BANK ACCOUNT NUMBER]",
                              "[CREDIT CARD NUMBER]",
                              "[DATE OF BIRTH]",
                              "[DATE]",
                              "[DRIVER LICENSE NUMBER]",
                              "[EMAIL ADDRESS]",
                              "[RACE/ETHNICITY]",
                              "[GENDER]",
                              "[IP ADDRESS]",
                              "[LOCATION]",
                              "[MONEY]",
                              "[ORGANIZATION]",
                              "[PASSPORT NUMBER]",
                              "[PASSWORD]",
                              "[PERSON NAME]",
                              "[PHONE NUMBER]",
                              "[PROFESSION]",
                              "[SOCIAL SECURITY NUMBER]",
                              "[USERNAME]",
                              "[SECRET_KEY]",
                              "[TRANSACTION_ID]",
                              "[RELIGION]",
                          ],
                          "contextual_rules": [
                              [ "[PERSON NAME]", "[CREDIT CARD NUMBER]", "[BANK ACCOUNT NUMBER]" ],
                              [ "[PERSON NAME]", "[EMAIL ADDRESS]", "[DATE OF BIRTH]" ]
                          ],
                          "matching_scores": {
                              "[BANK ACCOUNT NUMBER]": 0.5,
                              "[CREDIT CARD NUMBER]": 0.5,
                              "[DATE OF BIRTH]": 0.5,
                              "[DATE]": 0.5,
                              "[DRIVER LICENSE NUMBER]": 0.5,
                              "[EMAIL ADDRESS]": 0.5,
                              "[RACE/ETHNICITY]": 0.5,
                              "[GENDER]": 0.5,
                              "[IP ADDRESS]": 0.5,
                              "[LOCATION]": 0.5,
                              "[MONEY]": 0.5,
                              "[ORGANIZATION]": 0.5,
                              "[PASSPORT NUMBER]": 0.5,
                              "[PASSWORD]": 0.5,
                              "[PERSON NAME]": 0.5,
                              "[PHONE NUMBER]": 0.5,
                              "[PROFESSION]": 0.5,
                              "[SOCIAL SECURITY NUMBER]": 0.5,
                              "[USERNAME]": 0.5,
                              "[SECRET_KEY]": 0.5,
                              "[TRANSACTION_ID]": 0.5,
                              "[RELIGION]": 0.5
                          }
                      },
                      "confidential_info_detection": {
                          "matching_scores": {
                              "No Confidential": 0.5,
                              "Legal Documents": 0.5,
                              "Business Strategies": 0.5,
                              "Medical Information": 0.5,
                              "Professional Records": 0.5
                          }
                      },
                      "gender_bias_detection": {
                          "matching_scores": {
                              "score": 0.5
                          }
                      },
                      "harm_detection": {
                          "matching_scores": {
                              "score": 0.5
                          }
                      },
                      "toxicity_detection": {
                          "matching_scores": {
                              "score": 0.5
                          }
                      },
                      "racial_bias_detection": {
                          "matching_scores": {
                              "No Racial Bias": 0.5,
                              "Racial Bias": 0.5,
                              "Historical Racial Event": 0.5
                          }
                      },
                      "tonal_detection": {
                          "matching_scores": {
                              "Negative Tones": 0.5,
                              "Neutral Tones": 0.5,
                              "Professional Tone": 0.5,
                              "Thoughtful Tones": 0.5,
                              "Positive Tones": 0.5,
                              "Cautious Tones": 0.5
                          }
                      },
                      "jailbreak_detection": {
                          "matching_scores": {
                              "score": 0.5
                          }
                      },
                      "intellectual_property": {
                          "matching_scores": {
                              "score": 0.5
                          }
                      }
                  }
    input:
        flows:
            - autoalign check input
    output:
        flows:
            - autoalign check output

我们还需要在参数中添加 AutoAlign 的 guardrail 端点。

“multi_language” 是一个可选参数，用于启用非英语信息的 guardrails

一个高级配置是匹配分数（范围从 0 到 1），它是一个阈值，决定了 guardrail 是否会阻止输入/输出。如果匹配分数越高（即接近 1），则 guardrail 会越严格。一些 guardrails 的 matching_scores 配置格式非常不同，在每个 guardrail 的描述中，我们都添加了示例来展示该 guardrail 如何实现 matching_scores。PII 有一些更高级的配置，如 contextual_rules 和 enabled_types，更多详情可以在下面的 PII 部分阅读。

请注意，所有附加配置（如 matching_scores、contextual_rules 和 enabled_types）都是可选的；如果未指定，将应用默认值。

如上例所示，必须分别为输入和输出端定义 guardrails 的配置。

colang 文件在库中按以下格式实现：

define flow autoalign check input
  $input_result = execute autoalign_input_api(show_autoalign_message=True)

  if $input_result["guardrails_triggered"]
    $autoalign_input_response = $input_result['combined_response']
    bot refuse to respond
    stop

define flow autoalign check output
  $output_result = execute autoalign_output_api(show_autoalign_message=True)

  if $output_result["guardrails_triggered"]
    bot refuse to respond
    stop
  else
    $pii_message_output = $output_result["pii"]["response"]
    if $output_result["pii"]["guarded"]
      bot respond pii output
      stop

define bot respond pii output
  "$pii_message_output"


define bot refuse to respond
  "I'm sorry I can't respond."

actions autoalign_input_api 和 autoalign_output_api 接受两个参数：show_autoalign_message 和 show_toxic_phrases。这两个参数都期望布尔值。 show_autoalign_message 的默认值为 True，而 show_toxic_phrases 的默认值为 False。show_autoalign_message 控制是否显示来自 autoalign 的任何输出。当 show_autoalign_message 设置为 True 时，AutoAlign 的响应将显示为副文本。关于第二个参数的详细信息可在 toxicity_detection 部分找到。

从 execute autoalign_input_api 或 execute autoalign_output_api 获得的结果是一个字典，其中键是 guardrail 名称（还有一些额外的键，我们稍后会描述），值也是一个字典，包含 guarded 和 response 键。guarded 键的值是一个布尔值，告诉我们 guardrail 是否被触发；response 的值包含 AutoAlign 的响应。

现在来谈谈额外的键，其中一个键是 guardrails_triggered，其值是一个布尔值，告诉我们除了 PII 之外是否有任何 guardrail 被触发。另一个键是 combined_response，其值提供了所有被触发的 guardrails 的组合 guardrail 消息。

用户可以创建自己的流程，并通过在流程中使用 execute autoalign_input_api 和 execute autoalign_output_api action 来利用 AutoAlign 的 guardrails。

性别偏见检测#

性别偏见检测 rail 的目标是确定文本是否包含任何性别偏见内容。此 rail 可应用于输入和输出。通过在 config.yml 文件中 autoalign 部分下的 input 或 output 部分下的 guardrails_config 部分的字典中添加 gender_bias_detection 键来配置此 guardrail。

对于性别偏见检测，匹配分数必须采用以下格式：

"matching_scores": { "score": 0.5}

危害检测#

危害检测 rail 的目标是确定文本是否包含任何对人类有害的内容。此 rail 可应用于输入和输出。通过在 config.yml 文件中 autoalign 部分下的 input 或 output 部分的已配置 guardrails 列表中添加 harm_detection 来添加此 guardrail。

对于危害检测，匹配分数必须采用以下格式：

"harm_detection": { "score": 0.5}

越狱检测#

越狱检测 rail 的目标是确定文本中是否存在任何越狱尝试。通过在 config.yml 文件中 autoalign 部分下的 input 或 output 部分下的 guardrails_config 部分的字典中添加 jailbreak_detection 键来添加此 guardrail。

对于越狱检测，匹配分数必须采用以下格式：

"matching_scores": { "score": 0.5}

知识产权检测#

知识产权检测 rail 的目标是确定文本是否提及任何知识产权。通过在 config.yml 文件中 autoalign 部分下的 input 或 output 部分下的 guardrails_config 部分的字典中添加 intellectual_property 键来添加此 guardrail。

对于知识产权检测，匹配分数必须采用以下格式：

"matching_scores": { "score": 0.5}

机密信息检测#

警告

由于 AutoAlign API 更改，v0.12.0 中引入了不向后兼容的更改。

机密信息检测 rail 的目标是确定文本中是否存在任何机密信息。此 rail 可应用于输入和输出。通过在 config.yml 文件中 autoalign 部分下的 input 或 output 部分下的 guardrails_config 部分的字典中添加 confidential_info_detection 键来添加此 guardrail。

对于机密信息检测，匹配分数必须采用以下格式：

"matching_scores": {
    "No Confidential": 0.5,
    "Legal Documents": 0.5,
    "Business Strategies": 0.5,
    "Medical Information": 0.5,
    "Professional Records": 0.5
}

种族偏见检测#

种族偏见检测 rail 的目标是确定文本是否包含任何种族偏见内容。此 rail 可应用于输入和输出。通过在 config.yml 文件中 autoalign 部分下的 input 或 output 部分下的 guardrails_config 部分的字典中添加 racial_bias_detection 键来添加此 guardrail。

对于种族偏见检测，匹配分数必须采用以下格式：

"matching_scores": {
    "No Racial Bias": 0.5,
    "Racial Bias": 0.5,
    "Historical Racial Event": 0.5
}

语气检测#

语气检测 rail 的目标是确定文本是否以负面语气书写。通过在 config.yml 文件中 autoalign 部分下的 input 或 output 部分下的 guardrails_config 部分的字典中添加 tonal_detection 键来添加此 guardrail。

对于语气检测，匹配分数必须采用以下格式：

"matching_scores": {
    "Negative Tones": 0.5,
    "Neutral Tones": 0.5,
    "Professional Tone": 0.5,
    "Thoughtful Tones": 0.5,
    "Positive Tones": 0.5,
    "Cautious Tones": 0.5
}

毒性提取#

警告

由于 AutoAlign API 更改，v0.12.0 中引入了不向后兼容的更改。

毒性检测 rail 的目标是确定文本是否包含任何毒性内容。此 rail 可应用于输入和输出。此 guardrail 不仅检测文本的毒性，还从文本中提取毒性短语。通过在 config.yml 文件中 autoalign 部分下的 input 或 output 部分下的 guardrails_config 部分的字典中添加 toxicity_detection 键来添加此 guardrail。

对于文本毒性检测，匹配分数必须采用以下格式：

"matching_scores": { "score": 0.5}

可以通过稍微修改 colang 文件来提取毒性短语

define subflow autoalign check input
  $input_result = execute autoalign_input_api(show_autoalign_message=True, show_toxic_phrases=True)
  if $input_result["guardrails_triggered"]
    $autoalign_input_response = $input_result['combined_response']
    bot refuse to respond
    stop
  else if $input_result["pii"] and $input_result["pii"]["guarded"]:
    $user_message = $input_result["pii"]["response"]

define subflow autoalign check output
  $output_result = execute autoalign_output_api(show_autoalign_message=True, show_toxic_phrases=True)
  if $output_result["guardrails_triggered"]
    bot refuse to respond
    stop
  else
    $pii_message_output = $output_result["pii"]["response"]
    if $output_result["pii"]["guarded"]
      $bot_message = $pii_message_output

define subflow autoalign groundedness output
  if $check_facts == True
    $check_facts = False
    $threshold = 0.5
    $output_result = execute autoalign_groundedness_output_api(factcheck_threshold=$threshold, show_autoalign_message=True)
    bot provide response

define bot refuse to respond
  "I'm sorry, I can't respond to that."

PII#

警告

由于 AutoAlign API 更改，v0.12.0 中引入了不向后兼容的更改。

要使用 AutoAlign 的 PII（个人身份信息）模块，您必须在 guardrails_config 字典中 pii 键下的 enabled_types 中列出您希望编辑的实体；如果未列出，则所有 PII 类型都将被编辑。

上面的示例显示了 AutoAlign 当前支持的所有 PII 实体。

一个高级配置是匹配分数，它是一个阈值，决定了 guardrail 是否会在文本中掩码该实体。这是可选的，如果未指定，则将应用默认匹配分数 (0.5)。

另一个配置是上下文规则，它决定了在何种情况下，PII 类型必须存在于文本中，才能进行编辑。只有当满足其中一个上下文规则时，才会进行 PII 编辑。

您必须根据 guardrail 应用的位置，分别为输出和输入端定义配置。

PII 配置示例

"pii": {
  "enabled_types": [
      "[BANK ACCOUNT NUMBER]",
      "[CREDIT CARD NUMBER]",
      "[DATE OF BIRTH]",
      "[DATE]",
      "[DRIVER LICENSE NUMBER]",
      "[EMAIL ADDRESS]",
      "[RACE/ETHNICITY]",
      "[GENDER]",
      "[IP ADDRESS]",
      "[LOCATION]",
      "[MONEY]",
      "[ORGANIZATION]",
      "[PASSPORT NUMBER]",
      "[PASSWORD]",
      "[PERSON NAME]",
      "[PHONE NUMBER]",
      "[PROFESSION]",
      "[SOCIAL SECURITY NUMBER]",
      "[USERNAME]",
      "[SECRET_KEY]",
      "[TRANSACTION_ID]",
      "[RELIGION]",
  ],
  "contextual_rules": [
      [ "[PERSON NAME]", "[CREDIT CARD NUMBER]", "[BANK ACCOUNT NUMBER]" ],
      [ "[PERSON NAME]", "[EMAIL ADDRESS]", "[DATE OF BIRTH]" ]
  ],
  "matching_scores": {
      "[BANK ACCOUNT NUMBER]": 0.5,
      "[CREDIT CARD NUMBER]": 0.5,
      "[DATE OF BIRTH]": 0.5,
      "[DATE]": 0.5,
      "[DRIVER LICENSE NUMBER]": 0.5,
      "[EMAIL ADDRESS]": 0.5,
      "[RACE/ETHNICITY]": 0.5,
      "[GENDER]": 0.5,
      "[IP ADDRESS]": 0.5,
      "[LOCATION]": 0.5,
      "[MONEY]": 0.5,
      "[ORGANIZATION]": 0.5,
      "[PASSPORT NUMBER]": 0.5,
      "[PASSWORD]": 0.5,
      "[PERSON NAME]": 0.5,
      "[PHONE NUMBER]": 0.5,
      "[PROFESSION]": 0.5,
      "[SOCIAL SECURITY NUMBER]": 0.5,
      "[USERNAME]": 0.5,
      "[SECRET_KEY]": 0.5,
      "[TRANSACTION_ID]": 0.5,
      "[RELIGION]": 0.5
  }
}

基于证据的核查 (Groundness Check)#

警告

由于 AutoAlign API 更改，v0.12.0 中引入了不向后兼容的更改。

基于证据的核查需要一个输入语句（表示为 ‘prompt’）作为证据文档列表。要使用 AutoAlign 的基于证据的核查模块，您必须按以下格式修改 config.yml：

rails:
  config:
    autoalign:
      guardrails_config:
        {
          "groundedness_checker":{
            "verify_response": false
          }
        }
      parameters:
        groundedness_check_endpoint: "https://<AUTOALIGN_ENDPOINT>/groundedness_check"
  output:
    flows:
      - autoalign groundedness output

在 autoalign 配置的 parameters 部分指定 groundness endpoint。然后，您必须调用相应的 subflows 进行 groundness guardrails。

在 groundness check 的 guardrails 配置中，您可以切换 “verify_response” 标志，这将启用(true) / 禁用(false) LLM 响应的额外处理。此处理确保只有相关的 LLM 响应会经过事实核查，而像问候语（'Hi', 'Hello' 等）之类的响应不会经过事实核查过程。

请注意，verify_response 默认为 False，因为它需要额外的计算，我们鼓励用户尽可能确定哪些 LLM 响应应该经过 AutoAlign basedness check。

以下是库中 colang 文件的格式：

define subflow autoalign groundedness output
  if $check_facts == True
    $check_facts = False
    $threshold = 0.5
    $output_result = execute autoalign_groundedness_output_api(factcheck_threshold=$threshold)

可以根据用例更改 threshold，output_result 变量存储事实核查得分，可用于进一步处理。show_autoalign_message 控制是否显示来自 autoalign 的任何输出。当 show_autoalign_message 设置为 True 时，AutoAlign 的响应将显示为副文本。

要使用此流程，您需要一个以下格式的 colang 文件：

define user ask about pluto
  "What is pluto?"
  "How many moons does pluto have?"
  "Is pluto a planet?"

define flow answer report question
  user ask about pluto
  # For pluto questions, we activate the fact checking.
  $check_facts = True
  bot provide report answer

上面的示例是一个关于知识库是关于冥王星的用例流程。您需要按照上面的示例为您的用例定义流程，这确保了事实核查仅针对特定主题进行，而不是用于闲聊。

basedness check endpoint 的输出为您提供了一个事实核查得分，我们可以根据该得分添加一个阈值，该阈值决定了给定的输出是否事实正确。

支持文档或证据必须放在 config 文件夹内的 kb 文件夹中。

事实核查 (Fact Check)#

警告

由于 AutoAlign API 更改，v0.12.0 中引入了不向后兼容的更改。

事实核查使用机器人响应和用户输入提示来根据用户提示检查机器人响应的事实正确性。与基于证据的核查不同，事实核查不使用预先存在的内部知识库。要使用 AutoAlign 的事实核查模块，请修改示例 autoalign_factcheck_config 中的 config.yml。

models:
  - type: main
    engine: openai
    model: gpt-3.5-turbo-instruct
rails:
    config:
        autoalign:
            parameters:
                fact_check_endpoint: "https://<AUTOALIGN_ENDPOINT>/content_moderation"
                multi_language: False
            output:
                guardrails_config:
                    {
                        "fact_checker": {
                            "mode": "DETECT",
                            "knowledge_base": [
                                {
                                    "add_block_domains": [],
                                    "documents": [],
                                    "knowledgeType": "web",
                                    "num_urls": 3,
                                    "search_engine": "Google",
                                    "static_knowledge_source_type": ""
                                }
                            ],
                            "content_processor": {
                                "max_tokens_per_chunk": 100,
                                "max_chunks_per_source": 3,
                                "use_all_chunks": false,
                                "name": "Semantic Similarity",
                                "filter_method": {
                                    "name": "Match Threshold",
                                    "threshold": 0.5
                                },
                                "content_filtering": true,
                                "content_filtering_threshold": 0.6,
                                "factcheck_max_text": false,
                                "max_input_text": 150
                            },
                            "mitigation_with_evidence": false
                        },
                    }
    output:
        flows:
            - autoalign factcheck output

将 fact_check_endpoint 指定到正确的 AutoAlign 环境。然后设置为相应的事实核查 guardrail subflows。

事实核查 endpoint 的输出为您提供一个事实核查得分，该得分结合了机器人响应中各种陈述的事实正确性。然后，如果机器人响应被确定为事实不正确，将根据用户设置的阈值记录警告。