Edit

Share via

Migrate from QnA Maker knowledge bases to custom question answering

  • Article

Custom question answering, a feature of Azure AI Language was introduced in May 2021 with several new capabilities including enhanced relevance using a deep learning ranker, precise answers, and end-to-end region support. Each custom question answering project is equivalent to a knowledge base in QnA Maker. You can easily migrate knowledge bases from a QnA Maker resource to custom question answering projects within a language resource. You can also choose to migrate knowledge bases from multiple QnA Maker resources to a specific language resource.

To successfully migrate knowledge bases, the account performing the migration needs contributor access to the selected QnA Maker and language resource. When a knowledge base is migrated, the following details are copied to the new custom question answering project:

  • QnA pairs including active learning suggestions.
  • Synonyms and default answer from the QnA Maker resource.
  • Knowledge base name is copied to project description field.

Resource level settings such as Role-based access control (RBAC) aren't migrated to the new resource. These resource level settings would have to be reconfigured for the language resource post migration. You'll also need to re-enable analytics for the language resource.

Steps to migrate SDKs

This SDK Migration Guide is intended to help the migration to the new custom question answering client library, Azure.AI.Language.QuestionAnswering, from the old one, Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker. It focuses on side-by-side comparisons for similar operations between the two packages.

Steps to migrate knowledge bases

You can follow the steps below to migrate knowledge bases:

  1. Create a language resource with custom question answering enabled in advance. When you create the language resource in the Azure portal, you'll see the option to enable custom question answering. When you select that option and proceed, you'll be asked for Azure Search details to save the knowledge bases.

  2. If you want to add knowledge bases in multiple languages to your language resource, visit Language Studio to create your first custom question answering project and select the first option as shown below. Language settings for the language resource can be specified only when creating a project. If you want to migrate existing knowledge bases in a single language to the language resource, you can skip this step.

    Screenshot of choose language UI screen"

  3. Visit https://www.qnamaker.ai and select Start Migration in the migration note on the knowledge base page. A dialog box will open to initiate the migration.

    Start Migration button that appears in a banner on qnamaker.ai

  4. Fill in the details required to initiate migration. The tenant will be auto-selected. You can choose to switch the tenant.

    Migrate QnAMaker with red selection box around the tenant selection option

  5. Select the QnA Maker resource, which contains the knowledge bases to be migrated.

    Migrate QnAMaker with red selection box around the QnAMaker resource selection option

  6. Select the language resource to which you want to migrate the knowledge bases. You'll only be able to see those language resources that have custom question answering enabled. The language setting for the language resource is displayed in the options. You won’t be able to migrate knowledge bases in multiple languages from QnA Maker resources to a language resource if its language setting isn't specified.

    Migrate QnAMaker with red selection box around the language resource option currently selected resource contains the information that language is unspecified

    If you want to migrate knowledge bases in multiple languages to the language resource, you must enable the multiple language setting when creating the first custom question answering project for the language resource. You can do so by following the instructions in step #2. If the language setting for the language resource isn't specified, it is assigned the language of the selected QnA Maker resource.

  7. Select all the knowledge bases that you wish to migrate > select Next.

    Migrate QnAMaker with red selection box around the knowledge base selection option with a drop-down displaying three knowledge base names

  8. You can review the knowledge bases you plan to migrate. There could be some validation errors in project names as we follow stricter validation rules for custom question answering projects. To resolve these errors occurring due to invalid characters, select the checkbox (in red) and select Next. This is a one-click method to replace the problematic characters in the name with the accepted characters. If there's a duplicate, a new unique project name is generated by the system.

    Caution

    If you migrate a knowledge base with the same name as a project that already exists in the target language resource, the content of the project will be overridden by the content of the selected knowledge base.

    Screenshot of an error message starting project names can't contain special characters.

  9. After resolving the validation errors, select Start migration

    Screenshot with special characters removed.

  10. It will take a few minutes for the migration to occur. Don't cancel the migration while it is in progress. You can navigate to the migrated projects within the Language Studio post migration.

    Screenshot of successfully migrated knowledge bases with information that you can publish by using Language Studio.

    If any knowledge bases fail to migrate to custom question answering projects, an error will be displayed. The most common migration errors occur when:

    • Your source and target resources are invalid.
    • You're trying to migrate an empty knowledge base (KB).
    • You've reached the limit for an Azure Search instance linked to your target resources.

    Screenshot of a failed migration with an example error.

    Once you resolve these errors, you can rerun the migration.

  11. The migration will only copy the test instances of your knowledge bases. Once your migration is complete, you need to manually deploy the knowledge bases to copy the test index to the production index.

Next steps