Skip to content

Latest commit

 

History

History
200 lines (148 loc) · 8.48 KB

using-luis-build.md

File metadata and controls

200 lines (148 loc) · 8.48 KB
Raw

luis:build

The luis:build commmand makes it easy for you to manage working with multiple model definitions among team members across data centers and languages.

For each LU file (and its language variants) luis:build will do the following:

  1. If there isn't a LUIS AppId for the model, it will create one
  2. It runs bf luis:convert tool to generate the model
  3. It uploads the model to the appid as a new versionId (incremented)
  4. It trains the version of the model
  5. It publishes the version as the new model
  6. (OPTIONAL) It deletes the old version
  7. (OPTIONAL) It outputs a .dialog definition of a LuisRecognizer configured to use that model.

Usage

  1. Get LUIS.ai authoringKey for your desired authoringRegion
  2. Invoke bf luis:build --authoringKey <key> --region <authoringRegion> --in <.lu file | folder with .lu files> --luconfig <path to luconfig.json> ...

luis:build will create all assets you need from your local .LU files

Note: When using --in option, luis:build will create one LUIS application for every .lu file found per lang x locale.

luconfig.json

Some times you might need to have more control over which specific .lu files correspond to a luis application within your project folder. This is especially helpful if you are leveraging external references in your .lu files so not every single .lu file is treated as a LUIS application. To achieve this, you can author a luconfig.json with command line switches in it and provide it via bf luis:build --luconfig <luconfig.json path>. You will need to also specify --authoringKey <yourKey> or set it via bf config:set:luis --authoringKey=<yourKey>.

{
    // CLI argument --botName.  Serves as a prefix for your LUIS applications.
    "botName":"MyProject",

    // CLI argument --region.  Where to publish your LUIS applications.
    "region": "westus",
    
    // CLI argument for --defaultCulture. This is the application culture if a single .lu file is passed via --in. This is also the default culture for any .lu file without a lang-code in file name if a folder is passed in to --in. (e,.g. foo.lu will be foo.fr-fr.lu assuming --defaultCulture is set to fr-fr. This will continue to default to en-us
    "defaultCulture":"en-us",
    
    // CLI argument --deleteOldVersion. When set to true, old model version (when we create a new version) is automatically deleted for all applications
    "deleteOldVersion": true, 
        
    // CLI argument --dialog.  Specifies to generate either multiLanguage or crossTrain recongizers. 
    "dialog": "multiLanguage",

    // CLI argument --falbackLocale. Locale to be used at the fallback if no locale specific recognizer is found. Only valid if --dialog is specified.
    "fallbackLocale": "en-us",
    
    // CLI argument --force. If --dialog flag is provided, overwrites relevant dialog file.
    "force": true,  
    
    // CLI argument --out.  Absolute or relative path to set the output folder. When specified in conjunction with --dialog, any generated .dialog files are written out to the "out" folder.
    "out": ".",

    // CLI argument --suffix.  Environment name as a suffix identifier to include in LUIS app name. Defaults to current logged in user alias.
    "suffix": "bobd",

    // Each model is a LUIS application.
    "models": [
        // Each line is to an lu file and corresponds to a LUIS application. 
        // relative paths here are relative to the luconfig.json file itself. 
        "test/test.lu",
        "test/sample/x/Contoso.Foo.lu",
        "test/test.fr-fr.lu"
    ]
}

LU and language variations files

Every LU file can have multiple language variations. luis:build will build a model for each one.

The pattern for .lu files and the language variants are

example.en-us.lu
example.fr-fr.lu
example.de-de.lu
etc.

Each one of these .lu files will have a language specific model created for it.

Note: If you prefer to have more flexibility with the actual file naming convention, you can use the Model description capability offered by .lu format and include the culture code for the application in the .lu file.

Note: If no languge code can be deduced either via file name or via Model description, the value specified for CLI argument --defaultCulture will be used or defaults to en-us if none are present.

LUIS Applications created

Every combination of project, environment, and file name (with locale) will be used to name the application created on your behalf.

LUIS application names will use this format:

{botName}-{suffix}-{LUfilename}-{langcode}.lu

Example:

MyProject(vishwac)-GetAddresss.en-us.lu
MyProject(vishwac)-GetAddresss.fr-fr.lu
MyProject(vishwac)-GetAddresss.de-de.lu

The same application name will be used in each azure region, with endpoints internal to it.

Environments

When multiple people are working with models you want to be able to work with models independently from each other tied to the source control.

By default, luis:build uses the logged in user alias as the environment, so that you can simply create and work with local changes.

You can override the environment via cli argument --suffix foo file.

Generated Settings file

The output of LUBuild includes a settings file per environment which contains the mapping of lu file variants to the LUIS applicationID for the model.

Example for user vishwac targeting authoring region westus

luis.settings.vishwac.westus.json

{
    "luis": {
        "RootDialog_en-us_lu": "66976439-3197-4937-88bb-7b95aea2f462",
        "TodoPhraseList_en-us_lu": "5e8d3f95-619a-4fbb-b6f6-6fad3050e286"
    }
}

Generated .Dialog file for each lu file

With --dialog option specified, all language variations of a .LU files with the same prefix will get a .dialog file created which is a LUIS recognizer configured for it.

Example:

./rootDialog/Contoso.GetAddresss.lu.dialog <-- MultiLanguageRecognizer configured to use all of the languages 
./rootDialog/Contoso.GetAddresss.en-us.lu.dialog <-- LuisRecognizer 
./rootDialog/Contoso.GetAddresss.fr-fr.lu.dialog <-- LuisRecognizer 
./rootDialog/Contoso.GetAddresss.de-de.lu.dialog <-- LuisRecognizer

The net result is that to consume all of the language models in a dialog you simply can do this:

{
    "$kind":"Microsoft.AdaptiveDialog",
    "recognizer": "Contoso.GetAddresss.lu"  <-- this will be the multilanguage model with all variations
}

This will configure your recognizer to a LURecognizer("Contsoso.GetAddresss.lu") which internally will use your memory settings.luis.projectname and settings.luis.environment settings to bind to the correct .dialog file for your model and runtime environment.

Example

With this set of files, and this luconfig.json, running this command bf luis:build --dialog --luconfig luconfig.json --authoringkey <key> --region <region>

generates the following files

  1. luis.settings.development.westus.json
{
    "luis": {
        // LUIS application IDs for every application created/ updated
        "root_en-us_lu": "c571f17e-7f10-4211-a21e-17ebb1f7f89b",
        "root_fr-fr_lu": "d71ae2fe-d3e0-49e6-80a3-68a22fa666dc",
        "add_en-us_lu": "f3674ea3-0ae5-4c06-af57-49d76fb86fba",
        "add_es-es_lu": "53dc2dd2-8435-47ac-a080-b26249a57c6c",
        "add_fr-fr_lu": "06f7ba22-41dd-4df0-b0f8-17608afa2aec",
        "del_en-us_lu": "ecb34067-7917-45a5-821f-b0aace36df68",
        "del_it-it_lu": "5299ca26-ec4f-4270-9221-196fcf834f84"
    }
}
  1. Multi-language recognizer configuration, one per luFileName
{
    "$kind": "Microsoft.MultiLanguageRecognizer",
    "recognizers": {
        "fr-fr": "root.fr-fr.lu",
        "en-us": "root.en-us.lu",
        "": "root.en-us.lu"
    }
}
  1. LUISrecognizer configuration, one per luFileName.locale
{
    "$kind": "Microsoft.LuisRecognizer",
    "applicationId": "=settings.luis.root_en-us_lu",
    "endpoint": "=settings.luis.endpoint",
    "endpointKey": "=settings.luis.endpointKey"
}