LUIS 的 DevOps 实践DevOps practices for LUIS

正在开发语言理解 (LUIS) 应用的软件工程师可以通过遵循这些指南,对源代码管理自动生成测试发布管理应用 DevOps 实践。Software engineers who are developing a Language Understanding (LUIS) app can apply DevOps practices around source control, automated builds, testing, and release management by following these guidelines.

LUIS 的源代码管理和分支策略Source control and branch strategies for LUIS

DevOps 成功的关键因素之一是源代码管理One of the key factors that the success of DevOps depends upon is source control. 源代码管理系统允许开发人员围绕代码开展协作并跟踪更改。A source control system allows developers to collaborate on code and to track changes. 使用分支可允许开发人员在不同版本的代码库之间进行切换,并允许独立于团队的其他成员开展工作。The use of branches allows developers to switch between different versions of the code base, and to work independently from other members of the team. 开发人员提出拉取请求提议从一个分支更新到另一个分支时,或合并更改时,可能会触发自动生成进程生成并连续测试代码。When developers raise a pull request (PR) to propose updates from one branch to another, or when changes are merged, these can be the trigger for automated builds to build and continuously test code.

通过使用本文档所述的概念和指南,你可以在跟踪源代码管理系统中的更改的同时开发 LUIS 应用程序,然后按照以下软件工程最佳做法进行操作:By using the concepts and guidance that are described in this document, you can develop a LUIS app while tracking changes in a source control system, and follow these software engineering best practices:

  • 源代码管理Source Control

    • LUIS 应用的源代码采用人类易于阅读的格式。Source code for your LUIS app is in a human-readable format.
    • 可以反复从源生成模型。The model can be built from source in a repeatable fashion.
    • 可以通过源代码存储库管理源代码。The source code can be managed by a source code repository.
    • 凭据和机密(例如创作和订阅密钥)永远不会存储在源代码中。Credentials and secrets such as authoring and subscription keys are never stored in source code.
  • 分支和合并Branching and Merging

    • 开发人员可以使用独立分支。Developers can work from independent branches.
    • 开发人员可以同时使用多个分支。Developers can work in multiple branches concurrently.
    • 可以通过变基或合并将 LUIS 应用的更改从一个分支集成到另一个分支。It's possible to integrate changes to a LUIS app from one branch into another through rebase or merge.
    • 开发人员可以将 PR 合并到父分支。Developers can merge a PR to the parent branch.
  • 版本控制Versioning

    • 应对大型应用程序中的每个组件单独进行版本控制,使开发人员可以通过直接查看版本号来检测重大更改或更新。Each component in a large application should be versioned independently, allowing developers to detect breaking changes or updates just by looking at the version number.
  • 代码评审Code Reviews

    • PR 中的更改显示为易于阅读的源代码,可以在接受 PR 之前查看该代码。The changes in the PR are presented as human readable source code that can be reviewed before accepting the PR.

源代码管理Source control

若要在源代码管理系统中维护 LUIS 应用的应用架构定义,请使用应用的 LUDown 格式 (.lu) 表示形式。To maintain the App schema definition of a LUIS app in a source code management system, use the LUDown format (.lu) representation of the app. .lu 格式优于 .json 格式,因为前者易于阅读,这使开发人员可以更轻松地在 PR 中进行更改和查看更改。.lu format is preferred to .json format because it's human readable, which makes it easier to make and review changes in PRs.

将 LUIS 应用另存为 LUDown 格式Save a LUIS app using the LUDown format

若要将 LUIS 应用另存为 .lu 格式,并将其置于源代码管理下方:To save a LUIS app in .lu format and place it under source control:

  • 任一方法:从 LUIS 门户将应用版本导出.lu,然后将其添加到源代码管理存储库EITHER: Export the app version as .lu from the LUIS portal and add it to your source control repository

  • 或:使用文本编辑器为 LUIS 应用创建 .lu 文件,然后将其添加到源代码管理存储库OR: Use a text editor to create a .lu file for a LUIS app and add it to your source control repository

提示

如果 LUIS 应用是以 JSON 格式导出,则可以使用 BotBuilder-Tools LUIS CLI 将其转换为 LUDownIf you are working with the JSON export of a LUIS app, you can convert it to LUDown using the BotBuilder-Tools LUIS CLI. 使用 --sort 选项可确保意向和言语按字母顺序排序。Use the --sort option to ensure that intents and utterances are sorted alphabetically.
请注意,LUIS 门户中内置的 .LU 导出功能已对输出进行了排序。Note that the .LU export capability built into the LUIS portal already sorts the output.

从源生成 LUIS 应用Build the LUIS app from source

对于 LUIS 应用,从源生成意味着通过导入 .lu 源新建 LUIS 应用版本定型版本以及发布版本For a LUIS app, to build from source means to create a new LUIS app version by importing the .lu source , to train the version and topublish it. 可以在 LUIS 门户中或在命令行中执行此操作:You can do this in the LUIS portal, or at the command line:

在源代码管理下维护的文件Files to maintain under source control

LUIS 应用程序的以下类型的文件应在源代码管理下进行维护:The following types of files for your LUIS application should be maintained under source control:

未签入凭据和密钥Credentials and keys are not checked in

请勿在签入到存储库的文件中包含订阅密钥或类似的机密值,否则未经授权的人员可能会看到这些信息。Do not include subscription keys or similar confidential values in files that you check in to your repo where they might be visible to unauthorized personnel. 应阻止签入的密钥和其他值包括:The keys and other values that you should prevent from check-in include:

  • LUIS 创作和预测密钥LUIS Authoring and Prediction keys
  • LUIS 创作和预测终结点LUIS Authoring and Prediction endpoints
  • Azure 订阅密钥Azure subscription keys
  • 访问令牌,例如自动化身份验证中所使用的 Azure 服务主体的令牌Access tokens, such as the token for an Azure service principal used for automation authentication

安全管理机密的策略Strategies for securely managing secrets

安全管理机密的策略包括:Strategies for securely managing secrets include:

  • 如果使用的是 Git 版本控制,则可以将运行时机密存储到本地文件,然后通过添加将文件名与 .gitignore 文件匹配的模式来阻止签入文件If you're using Git version control, you can store runtime secrets in a local file and prevent check in of the file by adding a pattern to match the filename to a .gitignore file
  • 在自动化工作流中,可以将机密安全地存储在该自动化技术提供的参数配置中。In an automation workflow, you can store secrets securely in the parameters configuration offered by that automation technology. 例如,如果使用的是 GitHub Actions,则可以将机密安全地存储在 GitHub 机密中。For example, if you're using GitHub Actions, you can store secrets securely in GitHub secrets.

分支和合并Branching and merging

Git 等分布式版本控制系统使团队成员可以灵活地通过与他人共享的开发分支来发布、共享、查看和迭代代码更改。Distributed version control systems like Git give flexibility in how team members publish, share, review, and iterate on code changes through development branches shared with others. 采用适用于团队的 Git 分支策略Adopt a Git branching strategy that is appropriate for your team.

无论采用哪种分支策略,所有策略的主要原则如下:团队成员可以独立于功能分支以外的其他分支中的工作,来使用该功能分支中的解决方案。Whichever branching strategy you adopt, a key principle of all of them is that team members can work on the solution within a feature branch independently from the work that is going on in other branches.

若要支持独立地使用 LUIS 项目中的分支,请执行以下操作:To support independent working in branches with a LUIS project:

  • 主分支有自己的 LUIS 应用。The master branch has its own LUIS app. 该应用表示项目解决方案的当前状态,并且其当前活动版本应始终映射到主分支中的 .lu 源。This app represents the current state of your solution for your project and its current active version should always map to the .lu source that is in the master branch. 应检查和测试此应用中对 .lu 源的所有更新,以便随时部署该应用以生成环境(例如生成环境)。All updates to the .lu source for this app should be reviewed and tested so that this app could be deployed to build environments such as Production at any time. .lu 的更新从功能分支合并到主分支时,你应在 LUIS 应用中新建版本,然后增大版本号When updates to the .lu are merged into master from a feature branch, you should create a new version in the LUIS app and bump the version number.

  • 每个功能分支都必须使用自己的 LUIS 应用实例Each feature branch must use its own instance of a LUIS app . 开发人员可以在功能分支中使用该应用,不会影响使用其他分支的开发人员。Developers work with this app in a feature branch without risk of affecting developers who are working in other branches. 该“开发分支”应用是工作副本,应在删除功能分支时将其删除。This 'dev branch' app is a working copy that should be deleted when the feature branch is deleted.

Git 功能分支

开发人员可以使用独立分支Developers can work from independent branches

开发人员可以通过以下方式独立于其他分支在 LUIS 应用中进行更新:Developers can work on updates on a LUIS app independently from other branches by:

  1. 从主分支创建功能分支(取决于分支策略,通常是 master 或 develop)。Creating a feature branch from the main branch (depending on your branch strategy, usually master or develop).

  2. 在 LUIS 门户中新建 LUIS 应用(“开发分支应用”)以支持使用功能分支。Create a new LUIS app in the LUIS portal (the " dev branch app ") solely to support the work in the feature branch.

    • 如果分支中已存在解决方案的 .lu 源,则由于该源是在项目早期使用另一个分支后保存的,因此请通过导入 .lu 文件来创建开发分支 LUIS 应用。If the .lu source for your solution already exists in your branch, because it was saved after work done in another branch earlier in the project, create your dev branch LUIS app by importing the .lu file.

    • 如果你是开始处理新项目,则存储库中尚没有主 LUIS 应用的 .lu 源。If you are starting work on a new project, you will not yet have the .lu source for your master LUIS app in the repo. 你完成功能分支中的工作后将通过从门户中导出开发分支应用来创建 .lu 文件,然后将其作为 PR 的一部分提交。You will create the .lu file by exporting your dev branch app from the portal when you have completed your feature branch work, and submit it as a part of your PR.

  3. 使用开发分支应用的活动版本以实现所需的更改。Work on the active version of your dev branch app to implement the required changes. 对于所有功能分支工作,建议只使用开发分支应用的一个版本。We recommend that you work only in a single version of your dev branch app for all the feature branch work. 如果在开发分支应用中创建多个版本,请谨慎跟踪哪个版本包含要在提出 PR 时签入的更改。If you create more than one version in your dev branch app, be careful to track which version contains the changes you want to check in when you raise your PR.

  4. 测试更新 - 有关测试开发分支应用的详细信息,请参阅 LUIS DevOps 测试Test the updates - see Testing for LUIS DevOps for details on testing your dev branch app.

  5. 版本列表中将开发分支应用的活动版本导出为 .luExport the active version of your dev branch app as .lu from the versions list.

  6. 签入你的更新并邀请对你的更新进行同级评审。Check in your updates and invite peer review of your updates. 如果使用的是 GitHub,你将提出拉取请求If you're using GitHub, you'll raise a pull request.

  7. 更改获批后,将更新合并到主分支。When the changes are approved, merge the updates into the master branch. 此时,你将使用 master 中更新的 .lu 创建新版本的主 LUIS 应用。At this point, you will create a new version of the master LUIS app, using the updated .lu in master. 有关设置版本名称的注意事项,请参阅版本控制See Versioning for considerations on setting the version name.

  8. 删除功能分支后,最好删除为功能分支工作创建的开发分支 LUIS 应用。When the feature branch is deleted, it's a good idea to delete the dev branch LUIS app you created for the feature branch work.

开发人员可以同时使用多个分支Developers can work in multiple branches concurrently

如果遵循开发人员可以使用独立分支中的模式,则你将在每个功能分支中使用唯一的 LUIS 应用程序。If you follow the pattern described above in Developers can work from independent branches, then you will use a unique LUIS application in each feature branch. 一个开发人员可以同时使用多个分支,只要能够为当前正在使用的分支切换到正确的开发分支 LUIS 应用即可。A single developer can work on multiple branches concurrently, as long as they switch to the correct dev branch LUIS app for the branch they're currently working on.

建议对功能分支和为功能分支工作创建的开发分支 LUIS 应用使用同一名称,降低意外使用错误应用的可能性。We recommend that you use the same name for both the feature branch and for the dev branch LUIS app that you create for the feature branch work, to make it less likely that you'll accidentally work on the wrong app.

如上所述,为简单起见,建议在每个开发分支应用中使用一个版本。As noted above, we recommend that for simplicity, you work in a single version in each dev branch app. 如果使用的是多个版本,请在切换开发分支应用时注意使用正确的版本。If you are using multiple versions, take care to activate the correct version as you switch between dev branch apps.

多个开发人员可以同时使用同一分支Multiple developers can work on the same branch concurrently

你可以支持多个开发人员同时使用同一功能分支:You can support multiple developers working on the same feature branch at the same time:

  • 开发人员可以签出同一功能分支,并推送和拉取自己和其他开发人员提交的更改,同时工作将如常进行。Developers check out the same feature branch and push and pull changes submitted by themselves and other developers while work proceeds, as normal.

  • 如果遵循开发人员可以使用独立分支中的模式,则该分支将使用唯一的 LUIS 应用程序支持开发。If you follow the pattern described above in Developers can work from independent branches, then this branch will use a unique LUIS application to support development. 该“开发分支”LUIS 应用将由开始使用功能分支的开发团队中的第一个成员创建。That 'dev branch' LUIS app will be created by the first member of the development team who begins work in the feature branch.

  • 将团队成员以参与者身份添加到开发分支 LUIS 应用。Add team members as contributors to the dev branch LUIS app.

  • 功能分支工作完成后,从版本列表中将开发分支 LUIS 应用的活动版本导出为 .lu,将更新的 .lu 文件保存到存储库,然后签入并 PR 更改。When the feature branch work is complete, export the active version of the dev branch LUIS app as .lu from the versions list, save the updated .lu file in the repo, and check in and PR the changes.

通过变基或合并,将更改从一个分支合并到另一个分支Incorporating changes from one branch to another with rebase or merge

你团队中使用其他分支的其他一些开发人员可能已对 .lu 源进行了更新,并在你创建功能分支后将更新合并到了主分支。Some other developers on your team working in another branch may have made updates to the .lu source and merged them to the master branch after you created your feature branch. 你可能想要将他们的更改合并到你的工作版本中,然后继续在自己的功能分支内进行自己的更改。You may want to incorporate their changes into your working version before you continue to make own changes within your feature branch. 你可以按照其他任何代码资产中的方式,通过变基或合并到 master 来实现这一目标。You can do this by rebase or merge to master in the same way as any other code asset. 由于 LUDown 格式的 LUIS 应用易于阅读,因此它支持使用标准合并工具进行合并。Since the LUIS app in LUDown format is human readable, it supports merging using standard merge tools.

如果要在功能分支中对 LUIS 应用进行变基,请遵循以下提示:Follow these tips if you're rebasing your LUIS app in a feature branch:

  • 在变基或合并之前,请先从门户重新导出应用,确保应用的 .lu 源的本地副本具有你通过 LUIS 门户应用的所有最新更改。Before you rebase or merge, make sure your local copy of the .lu source for your app has all your latest changes that you've applied using the LUIS portal, by re-exporting your app from the portal first. 这样可以确保在门户中进行的但尚未导出的所有更改都不会丢失。That way, you can make sure that any changes you've made in the portal and not yet exported don't get lost.

  • 在合并过程中,使用标准工具解决任何合并冲突。During the merge, use standard tools to resolve any merge conflicts.

  • 完成变基或合并后,请勿忘记将应用重新导回门户,以便在继续应用自己的更改时使用更新的应用。Don't forget after rebase or merge is complete to re-import the app back into the portal, so that you're working with the updated app as you continue to apply your own changes.

合并 PRMerge PRs

PR 获批后,可以将更改合并到主分支。After your PR is approved, you can merge your changes to your master branch. LUIS 应用的 LUDown 源没有特殊的注意事项:它易于阅读,因此它支持使用标准合并工具进行合并。No special considerations apply to the LUDown source for a LUIS app: it's human readable and so supports merging using standard Merge tools. 可以以其他源文件中的方式解决任何合并冲突。Any merge conflicts may be resolved in the same way as with other source files.

合并 PR 后,建议将其清除:After your PR has been merged, it's recommended to cleanup:

  • 删除存储库中的分支Delete the branch in your repo

  • 删除为功能分支工作创建的“开发分支”LUIS 应用。Delete the 'dev branch' LUIS app you created for the feature branch work.

你应该以应用程序代码资产中的方式编写单元测试,为 LUIS 应用更新做补充。In the same way as with application code assets, you should write unit tests to accompany LUIS app updates. 你应采用持续集成工作流进行测试:You should employ continuous integration workflows to test:

  • PR 合并前 PR 中的更新Updates in a PR before the PR is merged
  • PR 获批后且更改合并到 master 后的主分支 LUIS 应用。The master branch LUIS app after a PR has been approved and the changes have been merged into master.

有关 LUIS DevOps 测试的详细信息,请参阅 LUIS 的 DevOps 测试For more information on testing for LUIS DevOps, see Testing for DevOps for LUIS. 有关实现工作流的更多详细信息,请参阅 LUIS DevOps 的自动化工作流For more details on implementing workflows, see Automation workflows for LUIS DevOps.

代码评审Code reviews

LUDown 格式的 LUIS 应用易于阅读,它支持在适用于审查的 PR 中关于更改进行通信。A LUIS app in LUDown format is human readable, which supports the communication of changes in a PR suitable for review. 单元测试文件也是 LUDown 格式,也易于在 PR 中审查。Unit test files are also written in LUDown format and also easily reviewable in a PR.

版本控制Versioning

应用程序由多个组件组成,其中可能包括 Azure 机器人服务QnA MakerAzure 语音服务等中运行的机器人等。An application consists of multiple components that might include things such as a bot running in Azure Bot Service, QnA Maker, Azure Speech service, and more. 若要实现松散耦合的应用程序,请使用版本控制以便独立地对应用程序的每个组件进行版本控制,使开发人员可以通过直接查看版本号来检测重大更改或更新。To achieve the goal of loosely coupled applications, use version control so that each component of an application is versioned independently, allowing developers to detect breaking changes or updates just by looking at the version number. 如果在 LUIS 应用自己的存储库中对其进行维护,则可以独立于其他组件轻松地对其进行版本控制。It's easier to version your LUIS app independently from other components if you maintain it in its own repo.

主分支的 LUIS 应用应该应用版本控制方案。The LUIS app for the master branch should have a versioning scheme applied. 将 LUIS 应用的 .lu 的更新合并到 master 后,你会将更新后的该源导入到主分支的 LUIS 应用中的新版本。When you merge updates to the .lu for a LUIS app into master, you'll then import that updated source into a new version in the LUIS app for the master branch.

建议对主 LUIS 应用版本使用数字版本控制方案,例如:It is recommended that you use a numeric versioning scheme for the master LUIS app version, for example:

major.minor[.build[.revision]]

每次更新后,版本号的最后一位递增。Each update the version number is incremented at the last digit.

主要/次要版本可用于指示 LUIS 应用功能的更改范围:The major / minor version can be used to indicate the scope of the changes to the LUIS app functionality:

  • 主版本:重大更改,例如支持新意向实体Major Version: A significant change, such as support for a new Intent or Entity
  • 次版本:后向兼容的次要更改,例如在重要的新培训之后Minor Version: A backwards-compatible minor change, such as after significant new training
  • 内部版本:不会更改任何功能,只是另一个内部版本。Build: No functionality change, just a different build.

确定最新版的主 LUIS 应用的版本号后,你需要生成和测试新的应用版本,然后将其发布到可用于各种内部版本环境(例如质量保证或生产)的终结点。Once you've determined the version number for the latest revision of your master LUIS app, you need to build and test the new app version, and publish it to an endpoint where it can be used in different build environments, such as Quality Assurance or Production. 强烈建议自动执行持续集成 (CI) 工作流中的所有这些步骤。It's highly recommended that you automate all these steps in a continuous integration (CI) workflow.

请参阅:See:

对“功能分支”LUIS 应用进行版本控制Versioning the 'feature branch' LUIS app

使用为支持功能分支中的工作而创建的“开发分支”LUIS 应用时,你将在完成工作后导出你的应用,然后在 PR 中加入更新后的 'luWhen you are working with a 'dev branch' LUIS app that you've created to support work in a feature branch, you will be exporting your app when your work is complete and you will include the updated 'lu in your PR. PR 合并到 master 后,应删除存储库中的分支和“开发分支”LUIS 应用。The branch in your repo, and the 'dev branch' LUIS app should be deleted after the PR is merged into master. 由于该应用仅用于支持功能分支中的工作,因此无需在该应用中应用特定的版本控制方案。Since this app exists solely to support the work in the feature branch, there's no particular versioning scheme you need to apply within this app.

PR 中的更改合并到 master 时,应该应用版本控制,以便独立地对 master 的所有更新进行版本控制。When your changes in your PR are merged into master, that is when the versioning should be applied, so that all updates to master are versioned independently.

后续步骤Next steps