从 Colang 1 迁移到 Colang 2#

NeMo Guardrails CLI 提供了一个工具 (nemoguardrails convert ...)，用于将 guardrail 配置从 Colang 1.0 格式转换为 Colang 2.x。它对文件内容执行多项语法转换，例如转换某些关键字和更改某些标识符的大小写。

警告

转换工具未能涵盖所有边缘情况。转换后应始终手动审查 guardrail 配置。

工作原理#

该工具会遍历 path 参数指定的目录，并对每个以 .co 结尾的文件应用转换。转换包括

  • 将 define flow 转换为 flow。

  • 将 define subflow 转换为 flow。

  • 将 define bot 转换为 flow bot。

  • 将 define user 转换为 flow user。

  • 将 execute 转换为 await。

  • 将 await 后的 snake_case 标识符转换为 CamelCase，并追加关键字 Action，同时保留使用的任何参数。

  • 将 else when 转换为 or when。

  • 将 stop 转换为 abort。

  • 将 bot 后的引用字符串转换为 bot say 或 or bot say。

  • 将 user 后的引用字符串转换为 user said 或 or user said。

  • 转换匿名 flows。

  • 对根 flows (需要激活的 flows) 使用 active decorator。

  • 为全局变量添加 global 关键字。

  • 将 ... 转换为 Colang 2 中的相应语法。

生成操作符#

生成操作的语法在 Colang 1.0 和 2.0 之间略有变化。以下 Colang 1.0 代码片段

# some instruction in natural language
$var_name = ...

它被翻译为

$name = ... "some instruction in natural language"

泛型匹配#

在 Colang 1.0 中，可以使用 user ... 和 bot ... 进行泛型匹配。这些在 Colang 2.0 中有不同的等价形式。... 不再用于匹配，仅用于生成。

转换过程中应用以下更改

  • user ... 转换为 user said something

  • bot ... 转换为 bot said something

Rails 配置#

Colang 1.0 配置可以在 rails 字段中定义某些 rails。

  • 如果在 config.yml 中定义了 rails，则会生成一个包含这些 rails 的 _rails.co 文件。

Flow 转换示例#

例如，以下 flow

define flow
  user express greeting
  bot express greeting

被转换为

@active
flow express_greeting
  user express greeting
  bot express greeting

注意

约定俗成地，user flows 使用过去时态，bot flows 使用现在时态。但是，迁移工具不强制执行此约定。

该工具会跟踪处理的行数和每个文件中的更改次数。它还会统计更改的文件总数。

警告

该工具会修改原始文件。建议使用版本控制来跟踪工具所做的更改。这还可以帮助您查看原始文件和修改后的文件之间的差异。

用法#

要使用转换工具，请使用以下命令

nemoguardrails convert --from-version '1.0' "path/to/config"

convert 命令有几个选项

  • --from-version: 要从中迁移 colang 文件的版本。可用选项：[‘1.0’, ‘2.0-alpha’]。默认为 1.0。

  • --verbose 或 --no-verbose: 迁移是否应详细输出日志。默认为 no-verbose。

  • --validate 或 --no-validate: 迁移是否应使用 Colang Parser 验证输出。默认为 no-validate。

  • --use-active-decorator 或 --no-use-active-decorator: 迁移是否应使用 active decorator。默认为 use-active-decorator。

  • --include-main-flow 或 --no-include-main-flow: 迁移是否应向配置添加 main flow。默认为 include-main-flow。

假设与限制#

  • 该工具假定输入文件格式正确。如果文件格式不正确，工具可能无法按预期工作。

  • 该工具使用正则表达式查找和替换文本中的特定模式。如果输入文件包含与这些模式匹配但不应替换的文本，工具可能会产生错误的结果。

  • 该工具会重命名原始文件，并将转换后的内容写入使用原始文件名的文件中。使用版本控制来跟踪工具所做的更改。

  • 该工具不处理文件读写操作中可能发生的错误。如果发生错误，工具会记录错误并继续处理下一个文件。

  • 在 flow 定义中使用 -、+ 等字符以及 or、and 等 token 是不支持的，迁移工具不处理此转换。

  • 最好在 flow 的开头定义全局变量。但是，迁移工具不强制执行此操作。