id | sidebar_label | title | description | abstract |
---|---|---|---|---|
command-line-interface |
Command Line Interface |
Command Line Interface |
Command line interface for open source chatbot framework Rasa. Learn how to train, test and run your machine learning-based conversational AI assistants |
The command line interface (CLI) gives you easy-to-remember commands for common tasks. This page describes the behavior of the commands and the parameters you can pass to them. |
Command | Effect |
---|---|
rasa init |
Creates a new project with example training data, actions, and config files. |
rasa train |
Trains a model using your NLU data and stories, saves trained model in ./models . |
rasa interactive |
Starts an interactive learning session to create new training data by chatting to your assistant. |
rasa shell |
Loads your trained model and lets you talk to your assistant on the command line. |
rasa run |
Starts a server with your trained model. |
rasa run actions |
Starts an action server using the Rasa SDK. |
rasa visualize |
Generates a visual representation of your stories. |
rasa test |
Tests a trained Rasa model on any files starting with test_ . |
rasa data split nlu |
Performs a 80/20 split of your NLU training data. |
rasa data convert |
Converts training data between different formats. |
rasa data migrate |
Migrates 2.0 domain to 3.0 format. |
rasa data validate |
Checks the domain, NLU and conversation data for inconsistencies. |
rasa export |
Exports conversations from a tracker store to an event broker. |
rasa evaluate markers |
Extracts markers from an existing tracker store. |
rasa -h |
Shows all available commands. |
Rasa produces log messages at several different levels (eg. warning, info, error and so on). You can control which level of logs you would like to see with --verbose
(same as -v
) or --debug
(same as -vv
) as optional command line arguments. See each command below for more explanation on what these arguments mean.
In addition to CLI arguments, several environment variables allow you to control log output in a more granular way. With these environment variables, you can configure log levels for messages created by external libraries such as Matplotlib, Pika, and Kafka. These variables follow standard logging level in Python. Currently, following environment variables are supported:
- LOG_LEVEL_LIBRARIES: This is the general environment variable to configure log level for the main libraries Rasa Open Source uses. It covers Tensorflow,
asyncio
, APScheduler, SocketIO, Matplotlib, RabbitMQ, Kafka. - LOG_LEVEL_MATPLOTLIB: This is the specialized environment variable to configure log level only for Matplotlib.
- LOG_LEVEL_RABBITMQ: This is the specialized environment variable to configure log level only for AMQP libraries, at the moment it handles log levels from
aio_pika
andaiormq
. - LOG_LEVEL_KAFKA: This is the specialized environment variable to configure log level only for kafka.
General configuration (LOG_LEVEL_LIBRARIES
) has less priority than library level specific configuration (LOG_LEVEL_MATPLOTLIB
, LOG_LEVEL_RABBITMQ
etc); and CLI parameter sets the lowest level log messages which will be handled. This means variables can be used together with a predictable result. As an example:
LOG_LEVEL_LIBRARIES=ERROR LOG_LEVEL_MATPLOTLIB=WARNING LOG_LEVEL_KAFKA=DEBUG rasa shell --debug
The above command run will result in showing:
- messages with
DEBUG
level and higher by default (due to--debug
) - messages with
WARNING
level and higher for Matplotlib - messages with
DEBUG
level and higher for kafka - messages with
ERROR
level and higher for other libraries not configured
Note that CLI config sets the lowest level log messages to be handled, hence the following command will set the log level to INFO
(due to --verbose
) and no debug messages will be seen (library level configuration will not have any effect):
LOG_LEVEL_LIBRARIES=DEBUG LOG_LEVEL_MATPLOTLIB=DEBUG rasa shell --verbose
As an aside, CLI log level sets the level at the root logger (which has the important handler - coloredlogs
handler); this means even if an environment variable sets a library logger to a lower level, the root logger will reject messages from that library. If not specified, the CLI log level is set to INFO
.
This command sets up a complete assistant for you with some example training data:
rasa init
It creates the following files:
.
├── actions
│ ├── __init__.py
│ └── actions.py
├── config.yml
├── credentials.yml
├── data
│ ├── nlu.yml
│ └── stories.yml
├── domain.yml
├── endpoints.yml
├── models
│ └── <timestamp>.tar.gz
└── tests
└── test_stories.yml
It will ask you if you want to train an initial model using this data.
If you answer no, the models
directory will be empty.
Any of the default CLI commands will expect this project setup, so this is the
best way to get started. You can run rasa train
, rasa shell
and rasa test
without any additional configuration.
The following command trains a Rasa Open Source model:
rasa train
If you have existing models in your directory (under models/
by default), only
the parts of your model that have changed will be re-trained. For example, if you edit
your NLU training data and nothing else, only the NLU part will be trained.
If you want to train an NLU or dialogue model individually, you can run
rasa train nlu
or rasa train core
. If you provide training data only for one one of
these, rasa train
will fall back to one of these commands by default.
rasa train
will store the trained model in the directory defined by --out
, models/
by default.
The name of the model by default is <timestamp>.tar.gz
. If you want to name your model differently,
you can specify the name using the --fixed-model-name
flag.
The following arguments can be used to configure the training process:
See the section on data augmentation for info on how data augmentation works
and how to choose a value for the flag. Note that TEDPolicy
is the only policy affected by data augmentation.
See the following section on incremental training for more information about the --epoch-fraction
argument.
:::info New in 2.2 This feature is experimental. We introduce experimental features to get feedback from our community, so we encourage you to try it out! However, the functionality might be changed or removed in the future. If you have feedback (positive or negative) please share it with us on the Rasa Forum.
:::
In order to improve the performance of an assistant, it's helpful to practice CDD
and add new training examples based on how your users have talked to your assistant. You can use rasa train --finetune
to initialize the pipeline with an already trained model and further finetune it on the
new training dataset that includes the additional training examples. This will help reduce the
training time of the new model.
By default, the command picks up the latest model in the models/
directory. If you have a specific model
which you want to improve, you may specify the path to this by
running rasa train --finetune <path to model to finetune>
. Finetuning a model usually
requires fewer epochs to train machine learning components like DIETClassifier
, ResponseSelector
and TEDPolicy
compared to training from scratch.
Either use a model configuration for finetuning
which defines fewer epochs than before or use the flag
--epoch-fraction
. --epoch-fraction
will use a fraction of the epochs specified for each machine learning component
in the model configuration file. For example, if DIETClassifier
is configured to use 100 epochs,
specifying --epoch-fraction 0.5
will only use 50 epochs for finetuning.
You can also finetune an NLU-only or dialogue management-only model by using
rasa train nlu --finetune
and rasa train core --finetune
respectively.
To be able to fine tune a model, the following conditions must be met:
-
The configuration supplied should be exactly the same as the configuration used to train the model which is being finetuned. The only parameter that you can change is
epochs
for the individual machine learning components and policies. -
The set of labels(intents, actions, entities and slots) for which the base model is trained should be exactly the same as the ones present in the training data used for finetuning. This means that you cannot add new intent, action, entity or slot labels to your training data during incremental training. You can still add new training examples for each of the existing labels. If you have added/removed labels in the training data, the pipeline needs to be trained from scratch.
-
The model to be finetuned is trained with
MINIMUM_COMPATIBLE_VERSION
of the currently installed rasa version.
You can start an interactive learning session by running:
rasa interactive
This will first train a model and then start an interactive shell session.
You can then correct your assistants predictions as you talk to it.
If UnexpecTEDIntentPolicy
is
included in the pipeline, action_unlikely_intent
can be triggered at any conversation turn. Subsequently, the following message will be displayed:
The bot wants to run 'action_unlikely_intent' to indicate that the last user message was unexpected
at this point in the conversation. Check out UnexpecTEDIntentPolicy docs to learn more.
As the message states, this is an indication that you have explored a conversation path which is unexpected according to the current set of training stories and hence adding this path to training stories is recommended. Like other bot actions, you can choose to confirm or deny running this action.
If you provide a trained model using the --model
argument, training is skipped
and that model will be loaded instead.
During interactive learning, Rasa will plot the current conversation
and a few similar conversations from the training data to help you
keep track of where you are. You can view the visualization
at http://localhost:5005/visualization.html
as soon as the session has started. This diagram can take some time to generate.
To skip the visualization, run rasa interactive --skip-visualization
.
The following arguments can be used to configure the interactive learning session:
You can start a chat session by running:
rasa shell
By default this will load up the latest trained model.
You can specify a different model to be loaded by using the --model
flag.
If you start the shell with an NLU-only model, rasa shell
will output the
intents and entities predicted for any message you enter.
If you have trained a combined Rasa model but only want to see what your model
extracts as intents and entities from text, you can use the command rasa shell nlu
.
To increase the logging level for debugging, run:
rasa shell --debug
:::note
In order to see the typical greetings and/or session start behavior you might see
in an external channel, you will need to explicitly send /session_start
as the first message. Otherwise, the session start behavior will begin as described in
Session configuration.
:::
The following arguments can be used to configure the command.
Most arguments overlap with rasa run
; see the following section for more info on those arguments.
Note that the --connector
argument will always be set to cmdline
when running rasa shell
.
This means all credentials in your credentials file will be ignored,
and if you provide your own value for the --connector
argument it will also be ignored.
To start a server running your trained model, run:
rasa run
By default the Rasa server uses HTTP for its communication. To secure the communication with
SSL and run the server on HTTPS, you need to provide a valid certificate and the corresponding
private key file. You can specify these files as part of the rasa run
command.
If you encrypted your keyfile with a password during creation,
you need to add the --ssl-password
as well.
rasa run --ssl-certificate myssl.crt --ssl-keyfile myssl.key --ssl-password mypassword
Rasa by default listens on each available network interface. You can limit this to a specific
network interface using the -i
command line option.
rasa run -i 192.168.69.150
Rasa will by default connect to all channels specified in your credentials file.
To connect to a single channel and ignore all other channels in your credentials file,
specify the name of the channel in the --connector
argument.
rasa run --connector rest
The name of the channel should match the name you specify in your credentials file. For supported channels see the page about messaging and voice channels.
The following arguments can be used to configure your Rasa server:
For more information on the additional parameters, see Model Storage. See the Rasa HTTP API page for detailed documentation of all the endpoints.
To start an action server with the Rasa SDK, run:
rasa run actions
The following arguments can be used to adapt the server settings:
To generate a graph of your stories in the browser, run:
rasa visualize
If your stories are located somewhere other than the default location data/
,
you can specify their location with the --stories
flag.
The following arguments can be used to configure this command:
To evaluate a model on your test data, run:
rasa test
This will test your latest trained model on any end-to-end stories you have
defined in files with the test_
prefix.
If you want to use a different model, you can specify it using the --model
flag.
To evaluate the dialogue and NLU models separately, use the commands below:
rasa test core
and
rasa test nlu
You can find more details on specific arguments for each testing type in Evaluating an NLU Model and Evaluating a Dialogue Management Model.
The following arguments are available for rasa test
:
To create a train-test split of your NLU training data, run:
rasa data split nlu
This will create a 80/20 split of train/test data by default. You can specify the training data, the fraction, and the output directory using the following arguments:
If you have NLG data for retrieval actions, this will be saved to seperate files:
ls train_test_split
nlg_test_data.yml test_data.yml
nlg_training_data.yml training_data.yml
You can convert NLU data from
- LUIS data format,
- WIT data format,
- Dialogflow data format, or
- JSON
to
- YAML or
- JSON
You can start the converter by running:
rasa data convert nlu
You can specify the input file or directory, output file or directory, and the output format with the following arguments:
The domain is the only data file whose format changed between 2.0 and 3.0. You can automatically migrate a 2.0 domain to the 3.0 format.
You can start the migration by running:
rasa data migrate
You can specify the input file or directory and the output file or directory with the following arguments:
rasa data migrate -d DOMAIN --out OUT_PATH
If no arguments are specified, the default domain path (domain.yml
) will be used for both input and output files.
This command will also back-up your 2.0 domain file(s) into a different original_domain.yml
file or
directory labeled original_domain
.
Note that the slots in the migrated domain will contain mapping conditions if these
slots are part of a form's required_slots
.
:::caution Exceptions will be raised and the migration process terminated if invalid domain files are provided or if they are already in the 3.0 format, if slots or forms are missing from your original files or if the slots or forms sections are spread across multiple domain files. This is done to avoid duplication of migrated sections in your domain files. Please make sure all your slots' or forms' definitions are grouped into a single file.
:::
You can learn more about this command by running:
rasa data migrate --help
You can check your domain, NLU data, or story data for mistakes and inconsistencies. To validate your data, run this command:
rasa data validate
The validator searches for errors in the data, e.g. two intents that have some identical training examples. The validator also checks if you have any stories where different assistant actions follow from the same dialogue history. Conflicts between stories will prevent a model from learning the correct pattern for a dialogue.
If you pass a max_history
value to one or more policies in your config.yml
file, provide the
smallest of those values in the validator command using the --max-history <max_history>
flag.
You can also validate only the story structure by running this command:
rasa data validate stories
:::note
Running rasa data validate
does not test if your rules are consistent with your stories.
However, during training, the RulePolicy
checks for conflicts between rules and stories. Any such conflict will abort training.
Also, if you use end-to-end stories, then this might not capture all conflicts. Specifically, if two user inputs result in different tokens yet exactly the same featurization, then conflicting actions after these inputs may exist but will not be reported by the tool. :::
To interrupt validation even for minor issues such as unused intents or responses, use the --fail-on-warnings
flag.
:::caution check your story names
The rasa data validate stories
command assumes that all your story names are unique!
:::
You can use rasa data validate
with additional arguments, e.g. to specify the location of your data and
domain files:
To export events from a tracker store using an event broker, run:
rasa export
You can specify the location of the environments file, the minimum and maximum timestamps of events that should be published, as well as the conversation IDs that should be published:
:::tip Import conversations into Rasa Enterprise This command is most commonly used to import old conversations into Rasa Enterprise to annotate them. Read more about importing conversations into Rasa Enterprise. :::
:::caution
This feature is currently experimental and might change or be removed in the future. Share your feedback in the forum to help us make it production-ready.
:::
The following command applies the markers you defined in your marker configuration file,
to pre-existing dialogues stored in your tracker store, and produces .csv
files containing
the extracted markers and summary statistics:
rasa evaluate markers all extracted_markers.csv
Use the following arguments to configure the marker extraction process:
usage: rasa evaluate markers [-h] [-v] [-vv] [--quiet] [--config CONFIG] [--no-stats | --stats-file-prefix [STATS_FILE_PREFIX]] [--endpoints ENDPOINTS] [-d DOMAIN] output_filename {first_n,sample,all} ...
positional arguments:
output_filename The filename to write the extracted markers to (CSV format).
{first_n,sample,all}
first_n Select trackers sequentially until N are taken.
sample Select trackers by sampling N.
all Select all trackers.
optional arguments:
-h, --help show this help message and exit
--config CONFIG The config file(s) containing marker definitions. This can be a single YAML file, or a directory that contains several files with marker definitions in it. The content of these files will be read and
merged together. (default: markers.yml)
--no-stats Do not compute summary statistics. (default: True)
--stats-file-prefix [STATS_FILE_PREFIX]
The common file prefix of the files where we write out the compute statistics. More precisely, the file prefix must consist of a common path plus a common file prefix, to which suffixes `-overall.csv` and
`-per-session.csv` will be added automatically. (default: stats)
--endpoints ENDPOINTS
Configuration file for the tracker store as a yml file. (default: endpoints.yml)
-d DOMAIN, --domain DOMAIN
Domain specification. This can be a single YAML file, or a directory that contains several files with domain specifications in it. The content of these files will be read and merged together. (default:
domain.yml)
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)