Migrating your Rasa 1.x assistant to Rasa 2.0

Last week we released Rasa Open Source 2.0 - a major new version marking a new milestone in the development of Rasa Open Source. It comes with a bunch of new features and improvements which we hope will make it even easier to build great conversational AI assistants with Rasa.

If you have built your assistant with Rasa 1.x, you will notice that there are quite a few changes in how things work in Rasa 2.0.

In this post, we would like to show you how you can safely migrate your assistant built with Rasa Open Source 1.x to 2.0.

What we'll cover:

1. Setting up the environment
2. Training data format
3. Policy configuration
4. Forms
5. Slots

Setting up the environment

When migrating your existing application to a new version of Rasa Open Source, we recommend working with a copy of your project so that you can always revert back to the original version in case something goes wrong.

To start the migration, create a directory with a copy of your assistant inside of it. Inside that directory, create a virtual environment and install Rasa 2.0:

python3 -m venv ./venv
source ./venv/bin/activate
pip install rasa==2.0

Once installed, you can start working on migrating your assistant.

Training data format

A change that will affect most assistants built with Rasa 1.x is the new training data format. Since the release of Rasa 2.0 the default data format for NLU, stories and NLG training data is YAML.

To convert your existing training data from the markdown format used in previous Rasa versions, you can use a data converter which can automatically convert nlu, stories and nlg data.

Let's say your Rasa 1.x assistant follows the usual project structure, where nlu and stories training data files are stored inside the ./data/nlu and ./data/stories directories respectively:

To convert the data files to the YAML format, run the following commands:

rasa data convert nlu -f yaml --data=./data/nlu --out=./data/nlu

rasa data convert core -f yaml --data=./data/stories --out=./data/stories

Here, the --data argument points to the existing training data files, while the --out argument points to a directory where the converted data files should be stored.

The converted files will have the same names as the original ones, but they will have the suffix "_converted" attached to the name:

If your training data contains any stories with forms or response selectors, as of now, you will have to update those stories manually. We will cover how you can achieve that in the next steps of this post.

Policy configuration

Another part of Rasa that has changed in Rasa 2.0 is policy configuration. Mapping Policy, Fallback Policy, Two Stage Fallback Policy and Form Policy have been deprecated and replaced by the Rule Policy. To migrate your policy configuration to Rasa 2.0, you can run a converter command which will automatically implement the changes for you.

Let's take the following Rasa 1.x policy configuration as an example. Here we have Mapping Policy, Fallback Policy and Form Policy, which were deprecated:

To migrate this configuration to Rasa 2.0 we can run the following command:

rasa data convert config

This function will update the config.yml file to be compatible with Rasa 2.0. It will replace the deprecated policies with the Rule Policy and migrate the configuration parameters to be compatible with Rasa 2.0. Here's how the config.yml file from the example above looks after conversion:

In addition to updating the config.yml file, this function will make updates to the domain.yml file, and it will create a rules.yml file where you can further add new rules to the policy configuration.

Note: if your Rasa 1.x assistant contains forms, you will have to make some additional manual changes to the configuration. We will cover those details in the next section of this post.

Forms

Forms received a major makeover in Rasa Open Source 2.0. First, they have been moved out of the Rasa SDK and into Rasa Open Source to simplify the implementation and make it easier to write action servers in other languages. Second, instead of being implemented using FormAction, in Rasa Open Source 2.0, forms have to be implemented inside the domain.yml file.

Here are the steps to migrate your existing forms to Rasa 2.0:

1.Update the policy configuration inside the config.yml file and replace the FormPolicy with RulePolicy (if you have updated your policy configuration using the rasa data convert config command, this will be done for you automatically).

2. Update the domain.yml file and include the configuration for the forms you have in your assistant. The configuration should include the name of the form, the requested slots, and the slot mappings where applicable. For example:

3. If you used the `rasa data convert` command to migrate your stories data to Rasa Open Source 2.0, the stories with forms will be updated to include the form activation and form deactivation steps. To properly migrate the forms to 2.0, we recommend removing those stories from your stories.yml file and updating the rules.yml file instead by adding rules for the form activation and form submission. For example:

4. If your forms include slot validation, update the domain.yml file to include the custom action for validating slots. For example:

5. Create a custom action in your actions.py file to validate the slots. This works similarly to the way it did in Rasa Open Source 1.x, but the main difference is that the custom action class for the slot validation inherits from the FormValidationAction class in Rasa SDK. We recommend checking out the Rasa documentation for more details on how to create custom actions for validating slots.

Slots

Another change that has been introduced in Rasa Open Source 2.0 is the deprecation of the `unfeaturized` slot type . In Rasa Open Source 1.x this slot type was used to define slots that should not influence the dialogue. In Rasa Open Source 2.0, the same can be achieved by defining the `text` slot type and using the `influence_conversation` flag to control whether the slot should influence the dialogue. For example:

Summary

Rasa Open Source 2.0 is packed with new exciting features and improvements, which we hope will make it easier for developers to build great conversational AI assistants with Rasa. Have you migrated your Rasa 1.x assistant to Rasa 2.0? Share your experience and feedback with us on Rasa Community Forum.