This article is a simple translation of Rasa official website documents for daily viewing.

Official document address: Rasa document

1. User guide

The installation

It is recommended to install Rasa using the PIP command

pip install rasa-x --extra-index-url https://pypi.rasa.com/simple
Copy the code

This command installs Rasa and Rasa X. If you do not want to use Rasa X, use PIP Install Rasa instead. Unless you already have Numpy and Scipy installed, we strongly recommend that you install and use Anaconda.

If you want to use the Rasa development version, you can get it from GitHub:

git clone https://github.com/RasaHQ/rasa.git
cd rasa
pip install -r requirements.txt
pip install -e .
Copy the code

Windows Prerequisites

Make sure the Microsoft VC ++ compiler is installed so Python can compile any dependencies. You can get the compiler from Visual Studio. Download the installer and select the VC ++ Build tool from the list.

NLU Pipeline Dependencies

Rasa NLU has different components for identifying intents and entities, most of which have some additional dependencies.

When you train the NLU model, Rasa checks to see if all the required dependencies are installed and tells you if any are missing. The Select pipe page will help you select the pipe to use.

If you want to make sure you have dependencies installed for any components you might need, and you don’t mind additional dependencies, you can install all of them using the following command.

pip install -r alt_requirements/requirements_full.txt
Copy the code

Getting started: UsingspaCyPretraining vector

The Pretrained_EMBEddings_spacy pipeline combines several different libraries and is a popular choice. See the spaCy documentation for more information. You can install it by using the following command:

pip install rasa[spacy]
python -m spacy download en_core_web_md
python -m spacy link en_core_web_md en
Copy the code

The command installs Rasa NLU and Spacy and its English language model. We recommend using the latest “medium” size model (_MD) instead of spacy’s default minimum en_CORE_web_SM model. Smaller models require less memory to run, but sometimes reduce the performance of intent classification.

The first option: Tensorflow

In order to use the container container, tensorFlow will be installed and the Sklearn-CrFSuite library will be installed for entity recognition. Run the following command:

pip install rasa
Copy the code

Option two: MITIE

Back-end MITIE is better for small data sets, and if you have hundreds of examples, the training time can be long. We may be ditching Mities in the future. First, run:

pip install git+https://github.com/mit-nlp/MITIE.git
pip install rasa[mitie]
Copy the code

Download the MITIE model file total_word_feature_extractor.dat.

MITIE complete pipeline:

language: "en"

pipeline:
- name: "MitieNLP"
  model: "data/total_word_feature_extractor.dat"
- name: "MitieTokenizer"
- name: "MitieEntityExtractor"
- name: "EntitySynonymMapper"
- name: "RegexFeaturizer"
- name: "MitieFeaturizer"
- name: "SklearnIntentClassifier"
Copy the code

MITIE training alone can be slow, but you can use the following configuration:

language: "en"

pipeline:
- name: "MitieNLP"
  model: "data/total_word_feature_extractor.dat"
- name: "MitieTokenizer"
- name: "MitieEntityExtractor"
- name: "EntitySynonymMapper"
- name: "RegexFeaturizer"
- name: "MitieIntentClassifier"
Copy the code

Rasa tutorial

This page introduces the basics of building assistants using Rasa and shows the structure of a Rasa project. You can test it here without installing anything. You can also install Rasa and operate from the command line.

  1. Create a new project
  2. View NLU training data
  3. Defining the model configuration
  4. Write your first story
  5. Define the domain
  6. Training model
  7. Talk to your assistant

In this tutorial, you’ll set up a simple, friendly assistant that will ask you what you’re doing and send you a fun picture to cheer you up.

1. Create a new project

The first step is to create a new Rasa project that runs:

rasa init --no-prompt
Copy the code

The rasa init command creates all the files needed for the RASA project and trains a simple bot on some sample data. If you omit the –no-prompt flag, you will be asked questions about how you want your project to be set up. The following files will be created:

file meaning
__init__py An empty file that helps Python find actions
actions.py Customize the code for actions
config.yml‘*’ Configuration of NLU and Core models
credentials.yml Details for connecting to other services
data/nlu.md‘*’ NLU training data
data/stories.md‘*’ stories
domain.yml‘*’ Assistant of domain
endpoints.yml Details of the connection channel
model/<timestamp>.tar.gz Initialization model

Important documents are marked with ‘*’.

2. View training data

The first part of the Rasa assistant is the NLU model. NLU stands for natural Language understanding, which means transforming user messages into structured data. To do this with Rasa, you need to provide training examples of how Rasa should understand user messages, and then train the model by showing them to it.

## intent:greet
- hey
- hello
- hi
- good morning
- good evening
- hey there

## intent:goodbye
- bye
- goodbye
- see you around
- see you later
Copy the code

The lines beginning with ## define the names of intents, which are groups of messages with the same meaning. When your user sends a new, invisible message to the assistant, Rasa’s job will be to predict the correct intent. You can find all the details of data formats in training Data Formats.

3. Define your model configuration

The configuration file defines the NLU and Core components that the model will use. In this example, your NLU model will use the container embeddings pipeline. You can learn about the different NLU pipes here. Let’s take a look at your model configuration file:

cat config.yml

The configuration is as follows:

# Configuration for Rasa NLU.
# https://rasa.com/docs/rasa/nlu/components/
language: en
pipeline: supervised_embeddings

# Configuration for Rasa Core.
# https://rasa.com/docs/rasa/core/policies/
policies:
  - name: MemoizationPolicy
  - name: KerasPolicy
  - name: MappingPolicy
Copy the code

The keywords language and pipeline specify how the NLU model is built. Policy defines the decision information used by the Core model.

Write your first stories

In this phase, you will teach your assistant how to reply to your messages, which is called conversation management and is handled by your Core model. The Core model learns from real session data in the form of training “stories.” Stories are real conversations between users and assistants. The rows with intent and entity reflect the user’s input, and the action name shows what the assistant should do in response.

Here is an example of a simple conversation. The user says hello, and the assistant says hello. Here’s what it looks like a story:

## story1
* greet
   - utter_greet
Copy the code

Lines beginning with – are actions taken by the assistant. In this tutorial, all of our operations are messages sent back to the user, such as utter_greet, but typically, operations can do anything, including calling apis and interacting with the outside world.

Run the following command line to see an example of data/stories.md:

## happy path
* greet
  - utter_greet
* mood_great
  - utter_happy

## sad path 1
* greet
  - utter_greet
* mood_unhappy
  - utter_cheer_up
  - utter_did_that_help
* affirm
  - utter_happy
Copy the code

5. Define the domain

The domain defines the domain in which your helper resides: the user input it should receive, the actions it should be able to predict, how it should respond, and the information to store. Our assistant’s domain is saved in a file named doma.yml:

intents:
  - greet
  - goodbye
  - affirm
  - deny
  - mood_great
  - mood_unhappy

actions:
- utter_greet
- utter_cheer_up
- utter_did_that_help
- utter_happy
- utter_goodbye

templates:
  utter_greet:
  - text: "Hey! How are you?"

  utter_cheer_up:
  - text: "Here is something to cheer you up:"
    image: "https://i.imgur.com/nGF1K8f.jpg"

  utter_did_that_help:
  - text: "Did that help you?"
Copy the code
The name of the meaning
intents things you expect users to say
actions things your assistant can do and say
templates template strings for the things your assistant can say

How does this fit together? The job of Rasa Core is to select the correct action to perform at each step of the conversation. In this case, our operation is just to send a message to the user, and these simple utter_ actions are actions in the field beginning with utter_. The assistant will reply to the message based on the template in the template section. See customizing operations to build operations that do more than send messages.

6. Training model

Whenever we add new NLU or Core data, or update the domain or configuration, we need to retrain the neural network on our sample Stories and NLU data. To do this, run the following command. This command invokes Rasa Core and NLU training and stores the trained model in the model/directory. If data or configuration changes, this command will automatically retrain only the different model parts.

rasa train
Copy the code

The rasa train command will find the NLU and Core data and train the composite model.

7. Talk to your assistant

A: congratulations! 🚀 You’ve just built an assistant powered entirely by machine learning. The next step is to try it! If you are following this tutorial on your local computer, please call the assistant by running:

rasa shell
Copy the code

You can also use Rasa X to collect more conversations and improve the assistant.

Command line interface

Cheat sheet

The command line interface (CLI) provides you with easy-to-remember commands for common tasks.

The command role
rasa_init Create a new project with sample training data, actions, and configuration files
rasa_train NLU data and STORIES were used to train the model, and the model was saved in./modelsIn the
rasa interactive Start a new interactive learning session by talking to create new training data
rasa shell Load the training model and talk to the assistant through the command line
rasa run Start a Rasa service using the trained model
rasa run actions Start the Action server using the Rasa SDK
rasa visualize Visual stories
rasa test Test the trained Rasa model using test NLU data and stories
rasa data split nlu Performs splitting of NLU data based on the specified percentage
rasa data convert nlu Convert NLU training data between different formats
rasa x Start Rasa X locally
rasa -h Displays all available commands

Creating a new project

A single command sets up a complete project for you with some sample training data.

rasa init
Copy the code

Contains the following files:

. ├ ─ ─ just set py ├ ─ ─ actions. Py ├ ─ ─ config. Yml ├ ─ ─ credentials. Yml ├ ─ ─ data │ ├ ─ ─ nlu. Md │ └ ─ ─ stories. The md ├ ─ ─ ├── models ├─ <timestamp>.tar.gzCopy the code

The rasa init command will ask you if you want to train an initial model using data, and if you say no, the model directory will be empty.

Training model

Command:

rasa train
Copy the code

This command trains the Rasa model, which combines the Rasa NLU and Rasa Core models. If you just want to train the NLU or Core model, you can run rasA Train NLU or RASa Train Core. However, Rasa will automatically skip training Core or NLU if the training data and configuration are not changed.

Rasa Trian stores the trained model to the target specified by –out. The default name of the model is

.tar.gz. If you want to name it yourself, use –fixed-model-name.

The following parameters can be used to configure the training process:

usage: rasa train [-h] [-v] [-vv] [--quiet] [--data DATA [DATA ...]]
                  [-c CONFIG] [-dDOMAIN] [--out OUT] [--augmentation AUGMENTATION] [--debug-plots] [--dump-stories] [--fixed-model-name FIXED_MODEL_NAME]  [--force] {core,nlu} ... positional arguments: {core,nlu} core Trains a Rasa Core model using your stories. nlu Trains a Rasa NLU model using your NLU data. optional arguments: -h, --help show thishelp message and exit--data DATA [DATA ...]  Paths to the Core and NLU data files. (default: ['data'])
  -c CONFIG, --config CONFIG
                        The policy and NLU pipeline configuration of your bot.
                        (default: config.yml)
  -d DOMAIN, --domain DOMAIN
                        Domain specification (yml file). (default: domain.yml)
  --out OUT             Directory where your models should be stored.
                        (default: models)
  --augmentation AUGMENTATION
                        How much data augmentation to use during training.
                        (default: 50)
  --debug-plots         If enabled, will create plots showing checkpoints and
                        their connections between story blocks in a file
                        called `story_blocks_connections.html`. (default:
                        False)
  --dump-stories        If enabled, save flattened stories to a file.
                        (default: False)
  --fixed-model-name FIXED_MODEL_NAME
                        If set, the name of the model file/directory will be
                        set to the given name. (default: None)
  --force               Force a model training even if the data has not
                        changed. (default: False)

Python Logging Options:
  -v, --verbose         Be verbose. Sets logging level to INFO. (default:
                        None)
  -vv, --debug          Print lots of debugging statements. Sets logging level
                        to DEBUG. (default: None)
  --quiet               Be quiet! Sets logging level to WARNING. (default:
                        None)
Copy the code

When using the rasa train command to train the model, make sure the training data for Core and NLU exists. If only one model type of training data exists, the command will automatically fall back to RASA Train NLU or RASA Train Core based on the training file provided.

Interactive learning

To start an interactive learning session with an assistant, run:

rasa interactive
Copy the code

If the training model is specified with the –model parameter, the interactive learning process is started with the supplied model. If no model is specified, RASA Interactive trains a new RASA model whose data is in data/if no other directory is passed to the –data flag. After training the initial model, the interactive learning session begins. If the training data and configuration have not changed, the training will be skipped.

All parameters of RASA Interactive are listed as follows:

usage: rasa interactive [-h] [-v] [-vv] [--quiet] [-m MODEL]
                        [--data DATA [DATA ...]] [--skip-visualization]
                        [--endpoints ENDPOINTS] [-c CONFIG] [-d DOMAIN]
                        [--out OUT] [--augmentation AUGMENTATION]
                        [--debug-plots] [--dump-stories] [--force]
                        {core} ... [model-as-positional-argument]

positional arguments:
  {core}
    core                Starts an interactive learning session model to create
                        new training data for a Rasa Core model by chatting.
                        Uses the 'RegexInterpreter'. i.e. `/<intent>` input format. model-as-positional-argument Path to a trained Rasa model. If a directory is specified, it will use the latest modelin this
                        directory. (default: None)

optional arguments:
  -h, --help            show this help message and exit
  -m MODEL, --model MODEL
                        Path to a trained Rasa model. If a directory is
                        specified, it will use the latest model inthis directory. (default: None) --data DATA [DATA ...]  Paths to the Core and NLU data files. (default: ['data'])
  --skip-visualization  Disable plotting the visualization during interactive
                        learning. (default: False)
  --endpoints ENDPOINTS
                        Configuration file for the model server and the
                        connectors as a yml file. (default: None)

Python Logging Options:
  -v, --verbose         Be verbose. Sets logging level to INFO. (default:
                        None)
  -vv, --debug          Print lots of debugging statements. Sets logging level
                        to DEBUG. (default: None)
  --quiet               Be quiet! Sets logging level to WARNING. (default:
                        None)

Train Arguments:
  -c CONFIG, --config CONFIG
                        The policy and NLU pipeline configuration of your bot.
                        (default: config.yml)
  -d DOMAIN, --domain DOMAIN
                        Domain specification (yml file). (default: domain.yml)
  --out OUT             Directory where your models should be stored.
                        (default: models)
  --augmentation AUGMENTATION
                        How much data augmentation to use during training.
                        (default: 50)
  --debug-plots         If enabled, will create plots showing checkpoints and
                        their connections between story blocks in a file
                        called `story_blocks_connections.html`. (default:
                        False)
  --dump-stories        If enabled, save flattened stories to a file.
                        (default: False)
  --force               Force a model training even if the data has not
                        changed. (default: False)
Copy the code

Talk to your assistant

Use the following command:

rasa shell
Copy the code

The model that should be used to interact with the robot can be specified by –model. If you start the shell using the NLU-only model, the Rasa shell lets you get the intent and entity of any text you type on the command line. If your model includes a trained Core model, you can chat with the robot and see what the robot predicts to do next. If you have trained a combined Rasa model, but want to see the intents and entities that the model extracts from the text, you can use the command Rasa shell nlu.

To increase the logging level for debugging, run:

rasa shell --debug
Copy the code

The list of all rasa Shell options is as follows:

usage: rasa shell [-h] [-v] [-vv] [--quiet] [-m MODEL] [--log-file LOG_FILE]
                  [--endpoints ENDPOINTS] [-p PORT] [-t AUTH_TOKEN]
                  [--cors [CORS [CORS ...]]] [--enable-api]
                  [--remote-storage REMOTE_STORAGE]
                  [--credentials CREDENTIALS] [--connector CONNECTOR]
                  [--jwt-secret JWT_SECRET] [--jwt-method JWT_METHOD]
                  {nlu} ... [model-as-positional-argument]

positional arguments:
  {nlu}
    nlu                 Interprets messages on the command line using your NLU
                        model.
  model-as-positional-argument
                        Path to a trained Rasa model. If a directory is
                        specified, it will use the latest model in this
                        directory. (default: None)

optional arguments:
  -h, --help            show this help message and exit
  -m MODEL, --model MODEL
                        Path to a trained Rasa model. If a directory is
                        specified, it will use the latest model in this
                        directory. (default: models)
  --log-file LOG_FILE   Store logs in specified file. (default: None)
  --endpoints ENDPOINTS
                        Configuration file for the model server and the
                        connectors as a yml file. (default: None)

Python Logging Options:
  -v, --verbose         Be verbose. Sets logging level to INFO. (default:
                        None)
  -vv, --debug          Print lots of debugging statements. Sets logging level
                        to DEBUG. (default: None)
  --quiet               Be quiet! Sets logging level to WARNING. (default:
                        None)

Server Settings:
  -p PORT, --port PORT  Port to run the server at. (default: 5005)
  -t AUTH_TOKEN, --auth-token AUTH_TOKEN
                        Enable token based authentication. Requests need to
                        provide the token to be accepted. (default: None)
  --cors [CORS [CORS ...]]
                        Enable CORS for the passed origin. Use * to whitelist
                        all origins. (default: None)
  --enable-api          Start the web server API in addition to the input
                        channel. (default: False)
  --remote-storage REMOTE_STORAGE
                        Set the remote location where your Rasa model is
                        stored, e.g. on AWS. (default: None)

Channels:
  --credentials CREDENTIALS
                        Authentication credentials for the connector as a yml
                        file. (default: None)
  --connector CONNECTOR
                        Service to connect to. (default: None)

JWT Authentication:
  --jwt-secret JWT_SECRET
                        Public key for asymmetric JWT methods or shared
                        secretfor symmetric methods. Please also make sure to
                        use --jwt-method to select the method of the
                        signature, otherwise this argument will be ignored.
                        (default: None)
  --jwt-method JWT_METHOD
                        Method used for the signature of the JWT
                        authentication payload. (default: HS256)
Copy the code

Start the server

To start the server running the Rasa model, run:

rasa run
Copy the code

The following parameters can be used to configure your Rasa server

usage: rasa run [-h] [-v] [-vv] [--quiet] [-m MODEL] [--log-file LOG_FILE]
                [--endpoints ENDPOINTS] [-p PORT] [-t AUTH_TOKEN]
                [--cors [CORS [CORS ...]]] [--enable-api]
                [--remote-storage REMOTE_STORAGE] [--credentials CREDENTIALS]
                [--connector CONNECTOR] [--jwt-secret JWT_SECRET]
                [--jwt-method JWT_METHOD]
                {actions} ... [model-as-positional-argument]

positional arguments:
  {actions}
    actions             Runs the action server.
  model-as-positional-argument
                        Path to a trained Rasa model. If a directory is
                        specified, it will use the latest model in this
                        directory. (default: None)

optional arguments:
  -h, --help            show this help message and exit
  -m MODEL, --model MODEL
                        Path to a trained Rasa model. If a directory is
                        specified, it will use the latest model in this
                        directory. (default: models)
  --log-file LOG_FILE   Store logs in specified file. (default: None)
  --endpoints ENDPOINTS
                        Configuration file for the model server and the
                        connectors as a yml file. (default: None)

Python Logging Options:
  -v, --verbose         Be verbose. Sets logging level to INFO. (default:
                        None)
  -vv, --debug          Print lots of debugging statements. Sets logging level
                        to DEBUG. (default: None)
  --quiet               Be quiet! Sets logging level to WARNING. (default:
                        None)

Server Settings:
  -p PORT, --port PORT  Port to run the server at. (default: 5005)
  -t AUTH_TOKEN, --auth-token AUTH_TOKEN
                        Enable token based authentication. Requests need to
                        provide the token to be accepted. (default: None)
  --cors [CORS [CORS ...]]
                        Enable CORS for the passed origin. Use * to whitelist
                        all origins. (default: None)
  --enable-api          Start the web server API in addition to the input
                        channel. (default: False)
  --remote-storage REMOTE_STORAGE
                        Set the remote location where your Rasa model is
                        stored, e.g. on AWS. (default: None)

Channels:
  --credentials CREDENTIALS
                        Authentication credentials for the connector as a yml
                        file. (default: None)
  --connector CONNECTOR
                        Service to connect to. (default: None)

JWT Authentication:
  --jwt-secret JWT_SECRET
                        Public key for asymmetric JWT methods or shared
                        secretfor symmetric methods. Please also make sure to
                        use --jwt-method to select the method of the
                        signature, otherwise this argument will be ignored.
                        (default: None)
  --jwt-method JWT_METHOD
                        Method used for the signature of the JWT
                        authentication payload. (default: HS256)
Copy the code

Start the Action Server

Run the following command:

rasa run actions
Copy the code

The following parameters can be used to adjust the server Settings:

usage: rasa run actions [-h] [-v] [-vv] [--quiet] [-p PORT]
                        [--cors [CORS [CORS ...]]] [--actions ACTIONS]

optional arguments:
  -h, --help            show this help message and exit
  -p PORT, --port PORT  port to run the server at (default: 5055)
  --cors [CORS [CORS ...]]
                        enable CORS for the passed origin. Use * to whitelist
                        all origins (default: None)
  --actions ACTIONS     name of action package to be loaded (default: None)

Python Logging Options:
  -v, --verbose         Be verbose. Sets logging level to INFO. (default:
                        None)
  -vv, --debug          Print lots of debugging statements. Sets logging level
                        to DEBUG. (default: None)
  --quiet               Be quiet! Sets logging level to WARNING. (default:
                        None)
Copy the code

Visualize your Stories

rasa visualize
Copy the code

Typically, trained stories are visible in the data directory. To store your stories elsewhere, use — Stories to specify their location.

The parameters are as follows:

usage: rasa visualize [-h] [-v] [-vv] [--quiet] [-d DOMAIN] [-s STORIES]
                      [-c CONFIG] [--out OUT] [--max-history MAX_HISTORY]
                      [-u NLU]

optional arguments:
  -h, --help            show this help message and exit
  -d DOMAIN, --domain DOMAIN
                        Domain specification (yml file). (default: domain.yml)
  -s STORIES, --stories STORIES
                        File or folder containing your training stories.
                        (default: data)
  -c CONFIG, --config CONFIG
                        The policy and NLU pipeline configuration of your bot.
                        (default: config.yml)
  --out OUT             Filename of the output path, e.g. 'graph.html'.
                        (default: graph.html)
  --max-history MAX_HISTORY
                        Max history to consider when merging paths in the
                        output graph. (default: 2)
  -u NLU, --nlu NLU     File or folder containing your NLU data, used to
                        insert example messages into the graph. (default:
                        None)

Python Logging Options:
  -v, --verbose         Be verbose. Sets logging level to INFO. (default:
                        None)
  -vv, --debug          Print lots of debugging statements. Sets logging level
                        to DEBUG. (default: None)
  --quiet               Be quiet! Sets logging level to WARNING. (default:
                        None)
Copy the code

A graph.html file will be generated in the current path.

Validate the model on test data

Run:

rasa test
Copy the code

Use –model to specify the model. The parameters are as follows:

usage: rasa test [-h] [-v] [-vv] [--quiet] [-m MODEL] [-s STORIES]
                 [--max-stories MAX_STORIES] [--e2e] [--endpoints ENDPOINTS]
                 [--fail-on-prediction-errors] [--url URL]
                 [--evaluate-model-directory] [-u NLU] [--out OUT]
                 [--report [REPORT]] [--successes [SUCCESSES]]
                 [--errors ERRORS] [--histogram HISTOGRAM] [--confmat CONFMAT]
                 [-c CONFIG [CONFIG ...]] [--cross-validation] [-f FOLDS]
                 [-r RUNS] [-p PERCENTAGES [PERCENTAGES ...]]
                 {core,nlu} ...

positional arguments:
  {core,nlu}
    core                Tests Rasa Core models using your test stories.
    nlu                 Tests Rasa NLU models using your test NLU data.

optional arguments:
  -h, --help            show this help message and exit
  -m MODEL, --model MODEL
                        Path to a trained Rasa model. If a directory is
                        specified, it will use the latest model in this
                        directory. (default: models)

Python Logging Options:
  -v, --verbose         Be verbose. Sets logging level to INFO. (default:
                        None)
  -vv, --debug          Print lots of debugging statements. Sets logging level
                        to DEBUG. (default: None)
  --quiet               Be quiet! Sets logging level to WARNING. (default:
                        None)

Core Test Arguments:
  -s STORIES, --stories STORIES
                        File or folder containing your test stories. (default:
                        data)
  --max-stories MAX_STORIES
                        Maximum number of stories to test on. (default: None)
  --e2e, --end-to-end   Run an end-to-end evaluation for combined action and
                        intent prediction. Requires a story file in end-to-end
                        format. (default: False)
  --endpoints ENDPOINTS
                        Configuration file for the connectors as a yml file.
                        (default: None)
  --fail-on-prediction-errors
                        If a prediction error is encountered, an exception is
                        thrown. This can be used to validate stories during
                        tests, e.g. on travis. (default: False)
  --url URL             If supplied, downloads a story file from a URL and
                        trains on it. Fetches the data by sending a GET
                        request to the supplied URL. (default: None)
  --evaluate-model-directory
                        Should be set to evaluate models trained via 'rasa train core --config 
       
       
        '
       
      . All models
                        in the provided directory are evaluated and compared
                        against each other. (default: False)

NLU Test Arguments:
  -u NLU, --nlu NLU     File or folder containing your NLU data. (default:
                        data)
  --out OUT             Output path for any files created during the
                        evaluation. (default: results)
  --report [REPORT]     Output path to save the intent/entity metrics report.
                        (default: None)
  --successes [SUCCESSES]
                        Output path to save successful predictions. (default:
                        None)
  --errors ERRORS       Output path to save model errors. (default:
                        errors.json)
  --histogram HISTOGRAM
                        Output path for the confidence histogram. (default:
                        hist.png)
  --confmat CONFMAT     Output path forthe confusion matrix plot. (default: confmat.png) -c CONFIG [CONFIG ...] , --config CONFIG [CONFIG ...]  Model configuration file. If a single file is passed and cross validation mode is chosen, cross-validation is performed,if multiple configs or a folder of
                        configs are passed, models will be trained and
                        compared directly. (default: None)
Copy the code

To split NLU data, run:

rasa data split nlu
Copy the code

You can specify training data, output directory, etc., with the following parameters:

usage: rasa data split nlu [-h] [-v] [-vv] [--quiet] [-u NLU]
                           [--training-fraction TRAINING_FRACTION] [--out OUT]

optional arguments:
  -h, --help            show this help message and exit
  -u NLU, --nlu NLU     File or folder containing your NLU data. (default:
                        data)
  --training-fraction TRAINING_FRACTION
                        Percentage of the data which should be inThe training data. (default: 0.8) -- Out out Directorywhere the split files should be stored.
                        (default: train_test_split)

Python Logging Options:
  -v, --verbose         Be verbose. Sets logging level to INFO. (default:
                        None)
  -vv, --debug          Print lots of debugging statements. Sets logging level
                        to DEBUG. (default: None)
  --quiet               Be quiet! Sets logging level to WARNING. (default:
                        None)
Copy the code

This command will attempt to maintain the same ratio of intent in training and testing.

Convert data between Markdown and JSON

To convert NLU data from LUIS data format, WIT data format, Dialogflow data format, JSON or Markdown to JSON or Markdown, run:

rasa data convert nlu
Copy the code

You can specify input file, output file, output format, etc. Parameters are as follows:

usage: rasa data convert nlu [-h] [-v] [-vv] [--quiet] --data DATA --out OUT
                             [-l LANGUAGE] -f {json,md}

optional arguments:
  -h, --help            show this help message and exit
  --data DATA           Path to the file or directory containing Rasa NLU
                        data. (default: None)
  --out OUT             File where to save training data in Rasa format.
                        (default: None)
  -l LANGUAGE, --language LANGUAGE
                        Language of data. (default: en)
  -f {json,md}, --format {json,md}
                        Output format the training data should be converted
                        into. (default: None)

Python Logging Options:
  -v, --verbose         Be verbose. Sets logging level to INFO. (default:
                        None)
  -vv, --debug          Print lots of debugging statements. Sets logging level
                        to DEBUG. (default: None)
  --quiet               Be quiet! Sets logging level to WARNING. (default:
                        None)
Copy the code

Start the Rasa X

Rasa X is a tool that helps you build, improve and deploy AI Assistants supported by the Rasa framework. You can find out more about it here.

You can start Rasa X locally by executing:

rasa x
Copy the code

In order to be able to start Rasa X, you need to install Rasa X and you need to enter the Rasa project.

By default, Rasa X runs on port 5002. It can be changed to any other port with the argument –rasa-x-port.

The following parameters are available for RASA X:

usage: rasa x [-h] [-v] [-vv] [--quiet] [-m MODEL] [--data DATA] [--no-prompt]
              [--production] [--rasa-x-port RASA_X_PORT] [--log-file LOG_FILE]
              [--endpoints ENDPOINTS] [-p PORT] [-t AUTH_TOKEN]
              [--cors [CORS [CORS ...]]] [--enable-api]
              [--remote-storage REMOTE_STORAGE] [--credentials CREDENTIALS]
              [--connector CONNECTOR] [--jwt-secret JWT_SECRET]
              [--jwt-method JWT_METHOD]

optional arguments:
  -h, --help            show this help message and exit
  -m MODEL, --model MODEL
                        Path to a trained Rasa model. If a directory is
                        specified, it will use the latest model in this
                        directory. (default: models)
  --data DATA           Path to the file or directory containing stories and
                        Rasa NLU data. (default: data)
  --no-prompt           Automatic yes or default options to prompts and
                        oppressed warnings. (default: False)
  --production          Run Rasa X in a production environment. (default:
                        False)
  --rasa-x-port RASA_X_PORT
                        Port to run the Rasa X server at. (default: 5002)
  --log-file LOG_FILE   Store logs in specified file. (default: None)
  --endpoints ENDPOINTS
                        Configuration file for the model server and the
                        connectors as a yml file. (default: None)

Python Logging Options:
  -v, --verbose         Be verbose. Sets logging level to INFO. (default:
                        None)
  -vv, --debug          Print lots of debugging statements. Sets logging level
                        to DEBUG. (default: None)
  --quiet               Be quiet! Sets logging level to WARNING. (default:
                        None)

Server Settings:
  -p PORT, --port PORT  Port to run the server at. (default: 5005)
  -t AUTH_TOKEN, --auth-token AUTH_TOKEN
                        Enable token based authentication. Requests need to
                        provide the token to be accepted. (default: None)
  --cors [CORS [CORS ...]]
                        Enable CORS for the passed origin. Use * to whitelist
                        all origins. (default: None)
  --enable-api          Start the web server API in addition to the input
                        channel. (default: False)
  --remote-storage REMOTE_STORAGE
                        Set the remote location where your Rasa model is
                        stored, e.g. on AWS. (default: None)

Channels:
  --credentials CREDENTIALS
                        Authentication credentials for the connector as a yml
                        file. (default: None)
  --connector CONNECTOR
                        Service to connect to. (default: None)

JWT Authentication:
  --jwt-secret JWT_SECRET
                        Public key for asymmetric JWT methods or shared
                        secretfor symmetric methods. Please also make sure to
                        use --jwt-method to select the method of the
                        signature, otherwise this argument will be ignored.
                        (default: None)
  --jwt-method JWT_METHOD
                        Method used for the signature of the JWT
                        authentication payload. (default: HS256)
Copy the code

The framework

Message processing

This figure shows the basic steps of how a helper built using Rasa responds to a message:

The steps are as follows:

  1. The message is received and passed to the interpreter, which turns it into a dictionary containing the original text, intent, and any entities found. This part is handled by the NLU.
  2. TrackerIs the object that tracks the state of the conversation. It receives incoming information about new messages.
  3. Strategy to receiveTrackerThe current state of.
  4. The policy selects what to do next.
  5. The operation selected byTrackerRecord.
  6. The response is sent to the user.

Messages can be human input text or structured input such as button presses.

Messaging and Voice channels

If you are testing on a local computer (not a server), you need to use ngrok. This will give your machine a domain name so that Facebook, Slack, etc. know where messages are being sent to your local machine.

To make your assistants available on the messaging platform, you need to provide credentials in the credentials.yml file. A sample file is created when you run Rasa Init, so the easiest way is to edit the file and add credentials to it. Here is an example of Facebook credentials:

facebook:
  verify: "rasa-bot"
  secret: "3e34709d01ea89032asdebfe5a74518"
  page-access-token: "EAAbHPa7H9rEBAAuFk4Q3gPKbDedQnx4djJJ1JmQ7CAqO4iJKrQcNT0wtD"
Copy the code

Evaluation model

Evaluate the NLU model

Use the following command to separate NLU training and test data:

rasa data split nlu
Copy the code

Use NLU model to predict on test cases:

rasa test nlu -u test_set.md --model models/nlu-xxx.tar.gz
Copy the code

If you don’t want to create a separate set of tests, you can still use cross-validation to estimate how optimized your model is. To do this, add the tag –cross-validation:

rasa test nlu -u data/nlu.md --config config.yml --cross-validation
Copy the code

The complete list of options for the script is as follows:

usage: rasa test nlu [-h] [-v] [-vv] [--quiet] [-m MODEL] [-u NLU] [--out OUT]
                     [--report [REPORT]] [--successes [SUCCESSES]]
                     [--errors ERRORS] [--histogram HISTOGRAM]
                     [--confmat CONFMAT] [-c CONFIG [CONFIG ...]]
                     [--cross-validation] [-f FOLDS] [-r RUNS]
                     [-p PERCENTAGES [PERCENTAGES ...]]

optional arguments:
  -h, --help            show this help message and exit
  -m MODEL, --model MODEL
                        Path to a trained Rasa model. If a directory is
                        specified, it will use the latest model in this
                        directory. (default: models)
  -u NLU, --nlu NLU     File or folder containing your NLU data. (default:
                        data)
  --out OUT             Output path for any files created during the
                        evaluation. (default: results)
  --report [REPORT]     Output path to save the intent/entity metrics report.
                        (default: None)
  --successes [SUCCESSES]
                        Output path to save successful predictions. (default:
                        None)
  --errors ERRORS       Output path to save model errors. (default:
                        errors.json)
  --histogram HISTOGRAM
                        Output path for the confidence histogram. (default:
                        hist.png)
  --confmat CONFMAT     Output path forthe confusion matrix plot. (default: confmat.png) -c CONFIG [CONFIG ...] , --config CONFIG [CONFIG ...]  Model configuration file. If a single file is passed and cross validation mode is chosen, cross-validation is performed,if multiple configs or a folder of
                        configs are passed, models will be trained and
                        compared directly. (default: None)

Python Logging Options:
  -v, --verbose         Be verbose. Sets logging level to INFO. (default:
                        None)
  -vv, --debug          Print lots of debugging statements. Sets logging level
                        to DEBUG. (default: None)
  --quiet               Be quiet! Sets logging level to WARNING. (default:
                        None)

Cross Validation:
  --cross-validation    Switch on cross validation mode. Any provided model
                        will be ignored. (default: False)
  -fFOLDS, --folds FOLDS Number of cross validation folds (cross validation only). (default: 10) Comparison Mode: -r RUNS, --runs RUNS Number of comparison runs to make. (default: 3) -p PERCENTAGES [PERCENTAGES ...] , --percentages PERCENTAGES [PERCENTAGES ...]  Percentages of training data to exclude during comparison. (default: [0, 25, 50, 75])Copy the code

Compare NLU pipes by passing multiple pipe configurations (or folders containing them) to the CLI, and Rasa makes comparison checks between pipes.

rasa testnlu --config pretrained_embeddings_spacy.yml supervised_embeddings.yml --nlu data/nlu.md --runs 3 --percentages 0 25 50 70, 90,Copy the code

The command in the above example creates a training/test set based on the data, and then trains each pipeline multiple times, with 0,25,50,70, and 90% of the intent data excluded from the training set. The model is then evaluated on the test set and F1-scores for each exclusion percentage are recorded. This process is run three times (for a total of three test sets) and then the chart is plotted using the mean and standard deviation of F1-scores. F1-score chart – along with all training/test sets, training models, classifications and error reports will be saved in a folder named nlu_comparison_Results.

Intent classification

The evaluation script will generate reports, confusion matrices, and confidence histograms for your model.

The report documents accuracy, recall rates and F1 metrics for each intent and entity and provides an overall average. You can save these reports as JSON files using the –report parameter.

The confusion matrix shows you which intentions are mistaken for other intentions; Samples of any false predictions are logged and saved to a file named errors.json for easy debugging.

The histogram generated by the script allows you to visualize the confidence distribution of all predictions, with the amount of correct and wrong predictions shown by blue and red bars, respectively. Improving the quality of training data moves the blue bar to the right and the red bar to the left of the graph.

The obfuscation matrix is created only when evaluating the model on the test set. In cross-validation mode, no obfuscation matrix will be generated.

Entity recognition

CRFEntityExtractor is the only entity extractor that you train with your own data, and therefore the only entity extractor that will be evaluated. If you use spaCy or Duckling pre-trained entity extractors, Rasa NLU will not include these in the evaluation.

Rasa NLU will report recall, accuracy and F1 metrics for each entity type CRFEntityExtractor is trained to identify.

Entity score

To evaluate entity extraction, we apply a simple label-based approach. We do not consider BILOU tags, but only the entity type tags for each tag. For positional entities like “near Alexanderplatz”, we expect the label LOC LOC rather than bilou-based B-LOc L-LOc. Our approach is more lenient in evaluation because it rewards partial extraction and does not penalize entity fragmentation.

Evaluate the Core model

rasa test core --stories test_stories.md --out results
Copy the code

Output the failed stories in results/failed_stories.md. We consider any story a failure if at least one action is incorrectly predicted.

In addition, this saves the obfuscation matrix to a file named Results/story_confMate.pdf. For each operation in your Domian, the obfuscation matrix shows how often the operation is correctly predicted and how often the operation is incorrectly predicted.

The list of all options in the script is as follows:

usage: rasa test core [-h] [-v] [-vv] [--quiet] [-m MODEL [MODEL ...]]
                      [-s STORIES] [--max-stories MAX_STORIES] [--out OUT]
                      [--e2e] [--endpoints ENDPOINTS]
                      [--fail-on-prediction-errors] [--url URL]
                      [--evaluate-model-directory]

optional arguments:
  -h, --help            show this help message and exit-m MODEL [MODEL ...] , --model MODEL [MODEL ...]  Path to a pre-trained model. If it is a'tar.gz' file
                        that model file will be used. If it is a directory,
                        the latest model in that directory will be used
                        (exception: '--evaluate-model-directory' flag is set).
                        If multiple 'tar.gz' files are provided, all those
                        models will be compared. (default: [None])
  -s STORIES, --stories STORIES
                        File or folder containing your test stories. (default:
                        data)
  --max-stories MAX_STORIES
                        Maximum number of stories to test on. (default: None)
  --out OUT             Output path for any files created during the
                        evaluation. (default: results)
  --e2e, --end-to-end   Run an end-to-end evaluation for combined action and
                        intent prediction. Requires a story file in end-to-end
                        format. (default: False)
  --endpoints ENDPOINTS
                        Configuration file for the connectors as a yml file.
                        (default: None)
  --fail-on-prediction-errors
                        If a prediction error is encountered, an exception is
                        thrown. This can be used to validate stories during
                        tests, e.g. on travis. (default: False)
  --url URL             If supplied, downloads a story file from a URL and
                        trains on it. Fetches the data by sending a GET
                        request to the supplied URL. (default: None)
  --evaluate-model-directory
                        Should be set to evaluate models trained via 'rasa train core --config 
       
       
        '
       
      . All models
                        in the provided directory are evaluated and compared
                        against each other. (default: False)

Python Logging Options:
  -v, --verbose         Be verbose. Sets logging level to INFO. (default:
                        None)
  -vv, --debug          Print lots of debugging statements. Sets logging level
                        to DEBUG. (default: None)
  --quiet               Be quiet! Sets logging level to WARNING. (default:
                        None)
Copy the code

Comparison Policy

By selecting a particular policy configuration, or by selecting the hyperparameters of a particular policy, you need to measure the extent to which Rasa Core will generalize into conversations that have never been seen before. Especially at the beginning of the project, you don’t have a lot of real dialogue to train your robot with, so you don’t just want to throw some away for a test set.

Rasa Core has scripts to help you select and fine-tune policy configurations. Once you are satisfied, you can train the final configuration on the full data set. To do this, models must first be trained for different strategies. Create two (or more) profiles, including the policies to be compared (each containing only one policy), and then train the model using the comparison mode of the training script:

rasa train core -c config_1.yml config_2.yml \
  -d domain.yml -s stories_folder --out comparison_models --runs 3 \
  --percentages 0 5 25 50 70 95
Copy the code

Below each policy configuration provided, Rasa Core will be trained multiple times, excluding 0,5,25,50,70, and 95% training stories from the training data. This is done for multiple runs to ensure consistent results.

After the training is completed, assess:

rasa test core -m comparison_models --stories stories_folder
--out comparison_results --evaluate-model-directory
Copy the code

This will evaluate each model on the training set and draw some charts to show which strategy performed best. By evaluating the entire set of stories, you can measure how well Rasa Core predicts predicted stories.

If you are unsure which policies to compare, we recommend that you try using EmbeddingPolicy and KerasPolicy to see which one is best for you.

This training process can take a long time, so we recommend letting it run in the background without interruption.

End to end evaluation

Rasa allows you to evaluate conversations end-to-end, run test conversations, and ensure that both NLU and Core make correct predictions. To do this, you need some end-to-end format for the story, including NLU output and raw text. Here’s an example:

## end-to-end story 1
* greet: hello
   - utter_ask_howcanhelp
* inform: show me [chinese](cuisine) restaurants
   - utter_ask_location
* inform: in [Paris](location)
   - utter_ask_price
Copy the code

If you save end-to-end stories as a file named e2e_stories.md, you can evaluate your model by running the following command:

rasa test --stories e2e_stories.md --e2e
Copy the code

Make sure the model file in the model is the combined Core and NLU model. If it does not contain an NLU model, Core will use the default RegexInterpreter.

Error testing Domain and Data files

To verify if there are any errors in the domain file, NLU data, or story data, run the validation script. You can run it using the following command:

rasa data validate
Copy the code

The script above runs all the validation of the file. Here is a list of options for the script:

usage: rasa data validate [-h] [-v] [-vv] [--quiet] [-d DOMAIN] [--data DATA]

optional arguments:
  -h, --help            show this help message and exit
  -d DOMAIN, --domain DOMAIN
                        Domain specification (yml file). (default: domain.yml)
  --data DATA           Path to the file or directory containing Rasa data.
                        (default: data)

Python Logging Options:
  -v, --verbose         Be verbose. Sets logging level to INFO. (default:
                        None)
  -vv, --debug          Print lots of debugging statements. Sets logging level
                        to DEBUG. (default: None)
  --quiet               Be quiet! Sets logging level to WARNING. (default:
                        None)
Copy the code

You can also run these validations by importing the Validator class, which has the following methods:

  • from_files(): creates an instance from a file in the string path.
  • verify_intents(): Check that the Intents list in the domain file contains NLU data.
  • verify_intents_in_stories(): Validate the intentions in stories and check that they are valid.
  • verify_utterances(): Examines the domain file to determine consistency between the discourse template and the discourse listed below.
  • verify_utterances_in_stories(): Verify the statements in stories to see if they are valid.
  • verify_all(): Run all of the above validations.

To use these functions, you must create a Validator object and initialize the logger. See the following code:

import logging
from rasa import utils
from rasa.core.validator import Validator

logger = logging.getLogger(__name__)

utils.configure_colored_logging('DEBUG')

validator = Validator.from_files(domain_file='domain.yml',
                                 nlu_data='data/nlu_data.md',
                                 stories='data/stories.md')

validator.verify_all()
Copy the code

Running the Server

Running the HTTP server

A trained Rasa model can be used to run a simple HTTP server to handle requests:

rasa run -m models --enable-api --log-file out.log
Copy the code

All endpoints exposed by this API are documented in the HTTP API.

  • -m: Folder path containing the Rasa model
  • --enable-api: enable this additional API
  • --log-file: log file path

Rasa can load your model in three different ways:

  • Get the model from the server
  • Obtaining models from remote storage (see Cloud Storage)
  • The IP address passes through the local storage system-mLoads the specified model

Rasa tries to load the models in the order described above, that is, if the model server and remote storage are not configured, it only tries to load the models from the local storage system.

Reminder: Be sure to protect your server by limiting access to it (for example, using a firewall) or enabling authentication methods: security considerations.

Note:

  • If you use custom actions, make sure the action server is running (see Starting the action Server). If your operation is running on another computer, or you are not using itRasa SDKPlease make sure to update yourendpoints.ymlFile.
  • If you start the server using an NLU-only model, you cannot invoke all available endpoints. Note that some endpoints will return a 409 status code because a trained Core model is required to process the request.

Get the model from the server

You can configure the HTTP server to fetch models from other urls:

rasa run --enable-api --log-file out.log --endpoints my_endpoints.yml
Copy the code

The model server is specified in the endpoint configuration (my_endpoints.yml), where you can specify the server URL Rasa to query the compressed Rasa model periodically:

models:
  url: http://my-server.com/models/default@latest
  wait_time_between_pulls: 10   # [optional](default: 100)
Copy the code

Note To pull models from the server only once, set wait_time_between_branch to None.

Note Your model server must provide a compressed Rasa model with {” ETag “:

} as one of its headers. If this model hash changes, Rasa will only download the new model.

Sample requests that Rasa might make to your model server are as follows:

curl --header "If-None-Match: d41d8cd98f00b204e9800998ecf8427e" http://my-server.com/models/default@latest
Copy the code

Get the model from remote storage

Rasa servers can be configured to fetch models from remote storage:

rasa run -m 20190506-100418.tar.gz --enable-api --log-file out.log --remote-storage aws
Copy the code

The model will be downloaded and stored in a temporary directory on the local storage system.

Safety considerations

We recommend not exposing the Rasa server to the outside world, but connecting to it from the back end through dedicated connections (for example, between Docker containers). However, there are two built-in authentication methods:

  • Token-based authentication: used when starting the server--auth-token thisismysecretPass token: 
    rasa run \
-m models \
--enable-api \
--log-file out.log \
--auth-token thisismysecret
Copy the code

    The request should pass the token, in our case it isthisismysecret, as a parameter:

    curl -XGET localhost:5005/conversations/default/tracker? token=thisismysecretCopy the code
  • Jwt-based Auth: use--jwt-secret thisismysecretEnable JWT-BASED authentication. Requests to the server are required before using this key andHS256 Indicates the algorithm signatureAuthorizationThe header contains a valid JWT token. The user must haveusernameandroleProperties. If the role isadmin, all endpoints can be accessed. ifroleisuser, the onlysender_idThe username can be accessed only if it matches the user usernamesender_idThe endpoint of a parameter. 
    rasa run \
-m models \
--enable-api \
--log-file out.log \
--jwt-secret thisismysecret
Copy the code

    The request should set the correct JWT header:

    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ"
             "zdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIi"
             "wiaWF0IjoxNTE2MjM5MDIyfQ.qdrr2_a7Sd80gmCWjnDomO"
             "Gl8eZFVfKXA6jhncgRn-I"
Copy the code

The Endpoint configuration

To connect Rasa to other endpoints, you can specify the endpoint configuration in the YAML file. Then run Rasa with the flag –endpoints . Such as: 

rasa run \
     --m <Rasa model> \
     --endpoints <path to endpoint configuration>.yml
Copy the code

You can specify environment variables in the configuration file using ${name of environment variable}. These placeholders are then replaced with the values of the environment variables.