从 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 装饰器。

  • 向全局变量添加 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.co 文件，其中包含定义的 rails。

示例 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 装饰器。默认为 use-active-decorator。

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

假设和局限性#

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

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

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

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

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

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

本页内容