Version: Master/Unreleased

Version Migration Guide

This page contains information about changes between major versions and how you can migrate from one version to another.

Rasa 1.10 to Rasa 2.0

General

  • The deprecated brokers FileProducer, KafkaProducer, PikaProducer and the SQLProducer have been removed. If you used these brokers in your endpoints.yml make sure to use the renamed variants instead:

    • FileProducer became FileEventBroker
    • KafkaProducer became KafkaEventBroker
    • PikaProducer became PikaEventBroker
    • SQLProducer became SQLEventBroker
  • The deprecated EmbeddingIntentClassifier has been removed. If you used this component in your pipeline configuration (config.yml) you can replace it with DIETClassifier. It accepts the same configuration parameters.

  • The deprecated KerasPolicy has been removed. If you used this component in your policies configuration (config.yml) you can replace it with TEDPolicy. It accepts the same configuration parameters.

Training data files

You can convert existing NLU, Stories, and NLG (i.e. responses.md) training data files in the Markdown format to the new YAML format using following commands:

rasa data convert nlu -f yaml --data={SOURCE_DIR} --out={TARGET_DIR}
rasa data convert nlg -f yaml --data={SOURCE_DIR} --out={TARGET_DIR}
rasa data convert core -f yaml --data={SOURCE_DIR} --out={TARGET_DIR}

Converted files will have the same names as the original ones but with a _converted.yml suffix.

Please note, that it's not currently possible to convert stories that contain forms automatically, these stories will be skipped and should be converted manually, see Rule Policy below.

Rule Policy

With the introduction of Rules, the following policies are deprecated:

Migrating from the Mapping Policy

If you previously used the Mapping Policy, you can follow the documentation on FAQs to convert your mapped intents to rules. Suppose you previously mapped an intent ask_is_bot as follows:

intents:
- ask_is_bot:
triggers: action_is_bot

This becomes the following rule:

rules:
- rule: Rule to map `ask_is_bot` intent
steps:
- intent: ask_is_bot
- action: action_is_bot

Migrating from the Fallback Policy

If you previously used the Fallback Policy, the following model configuration would translate as follows given a previous configuration like this:

policies:
- name: "FallbackPolicy"
nlu_threshold: 0.4
core_threshold: 0.3
fallback_action_name: "action_default_fallback"
ambiguity_threshold: 0.1

The new configuration would then look like:

policies:
# Other policies
- name: RulePolicy
core_fallback_threshold: 0.3
core_fallback_action_name: "action_default_fallback"
pipeline:
# Other components
- name: FallbackClassifier
threshold: 0.4
ambiguity_threshold: 0.1

In addition, you need to add a Rule to specify which action to run in case of low NLU confidence:

rules:
- rule: Ask the user to rephrase whenever they send a message with low NLU confidence
steps:
- intent: nlu_fallback
- action: utter_please_rephrase

Please see the Fallback Actions documentation for more information.

Migrating from the Two-Stage-Fallback Policy

If you previously used the Two-Stage-Fallback Policy, the following model configuration would translate as follows given a previous configuration like this:

policies:
- name: TwoStageFallbackPolicy
nlu_threshold: 0.4
ambiguity_threshold: 0.1
core_threshold: 0.3
fallback_core_action_name: "action_default_fallback"
fallback_nlu_action_name: "action_default_fallback"
deny_suggestion_intent_name: "out_of_scope"

The new configuration would then look like:

policies:
# Other policies
- name: RulePolicy
core_fallback_threshold: 0.3
core_fallback_action_name: "action_default_fallback"
pipeline:
# Other components
- name: FallbackClassifier
threshold: 0.4
ambiguity_threshold: 0.1

In addition you need to add a Rule to activate the Two-Stage Fallback for messages with low NLU confidence.

rules:
- rule: Implementation of the TwoStageFallbackPolicy
steps:
# This intent is automatically triggered by the `FallbackClassifier` in the NLU
# pipeline in case the intent confidence was below the specified threshold.
- intent: nlu_fallback
# The Fallback is now implemented as a form.
- action: two_stage_fallback
- active_loop: two_stage_fallback

Note that the previous parameters fallback_nlu_action_name and deny_suggestion_intent_name are no longer configurable and have the fixed values action_default_fallback and out_of_scope.

Please see the Fallback Actions documentation for more information.

Form Policy

As of Rasa Open Source 2.0 the logic for Forms has been moved from the Rasa SDK to Rasa Open Source to simplify implementations of custom action libraries. This means that you no longer need to use the FormAction when implementing custom actions with the Python SDK. Instead you can use a regular Action to validate and request slots.

It is now recommended to move the slot mappings from your custom action to the Domain of your bot. Consider a custom form action like this:

class RestaurantForm(FormAction):
def name(self) -> Text:
return "restaurant_form"
@staticmethod
def required_slots(tracker: Tracker) -> List[Text]:
return ["cuisine"]
def slot_mappings(self) -> Dict[Text, Union[Dict, List[Dict]]]:
return {
"cuisine": self.from_entity(entity="cuisine", not_intent="chitchat"),
}
@staticmethod
def cuisine_db() -> List[Text]:
"""Database of supported cuisines"""
return ["caribbean", "chinese", "french"]
def validate_cuisine(
self,
value: Text,
dispatcher: CollectingDispatcher,
tracker: Tracker,
domain: Dict[Text, Any],
) -> Dict[Text, Any]:
"""Validate cuisine value."""
if value.lower() in self.cuisine_db():
# validation succeeded, set the value of the "cuisine" slot to value
return {"cuisine": value}
else:
dispatcher.utter_message(template="utter_wrong_cuisine")
# validation failed, set this slot to None, meaning the
# user will be asked for the slot again
return {"cuisine": None}
def submit(
self,
dispatcher: CollectingDispatcher,
tracker: Tracker,
domain: Dict[Text, Any],
) -> List[Dict]:
"""Define what the form has to do
after all required slots are filled"""
# utter submit template
dispatcher.utter_message(template="utter_submit")
return []

Start the migration by adding the RulePolicy to your model configuration:

policies:
# Other policies
# ...
- name: RulePolicy

Then you need to define the form and the required slots in the domain as described in Forms:

forms:
restaurant_form:
cuisine:
- type: cuisine
entity: cuisine
not_intent: chitchat

You don't have to add a rule for activating the form as this is already covered by your existing stories. However, you have to add a story for handle the submission of the form.

rules:
- rule: Submit form
condition:
# Condition that form is active.
- active_loop: restaurant_form
steps:
- action: restaurant_form
- active_loop: null
- slot_was_set:
- requested_slot: null
# The action we want to run when the form is submitted.
- action: utter_submit

The last step is to implement a custom action to validate the form slots. Start by adding the custom action to your domain:

actions:
# Other actions
# ...
- validate_restaurant_form

Then add a custom action which validates the cuisine slot:

class RestaurantFormValidator(Action):
def name(self) -> Text:
return "validate_restaurant_form"
def run(
self, dispatcher: CollectingDispatcher, tracker: Tracker, domain: Dict
) -> List[EventType]:
extracted_slots: Dict[Text, Any] = tracker.form_slots_to_validate()
cuisine_slot_value = extracted_slots.get("cuisine")
validated_slot_event = self.validate_cuisine(
cuisine_slot_value, dispatcher, tracker, domain
)
return [validated_slot_event]
@staticmethod
def cuisine_db() -> List[Text]:
"""Database of supported cuisines"""
return ["caribbean", "chinese", "french"]
def validate_cuisine(
self,
value: Text,
dispatcher: CollectingDispatcher,
tracker: Tracker,
domain: Dict[Text, Any],
) -> EventType:
"""Validate cuisine value."""
if value.lower() in self.cuisine_db():
# validation succeeded, set the value of the "cuisine" slot to value
return SlotSet("cuisine", value)
else:
dispatcher.utter_message(template="utter_wrong_cuisine")
# validation failed, set this slot to None, meaning the
# user will be asked for the slot again
return SlotSet("cuisine", None)

Please see Forms if you have further customizations in your FormAction.

Response Selectors

  • Response Selectors are now trained on retrieval intent labels by default instead of the actual response text. For most models, this should improve training time and accuracy of the ResponseSelector.

  • If you want to revert to the pre-2.0 default behavior, add the use_text_as_label=true parameter to your ResponseSelector component.

  • All response selector related evaluation artifacts - report.json, successes.json, errors.json, confusion_matrix.png now use the sub-intent of the retrieval intent as the target and predicted labels instead of the actual response text. This means that the output in these files should look like -

response_selection_successes.json
{
"text": "Is this really legit?",
"intent_response_key_target": "faq/is_legit",
"intent_response_key_prediction": {
"name": "faq/is_legit",
"confidence": 0.88
}
}
response_selection_errors.json
{
"text": "Is this really legit?",
"intent_response_key_target": "faq/is_legit",
"intent_response_key_prediction": {
"name": "faq/ask_cost",
"confidence": 0.6
}
}
  • Retrieval actions with respond_ prefix are now replaced with usual utterance actions with utter_ prefix. If you were using retrieval actions before, rename all of them to start with utter_ prefix. For example, respond_chitchat becomes utter_chitchat. Also, in order to keep the response templates more consistent, you should now add the utter_ prefix to all response templates defined for retrieval intents. For example, a response template chitchat/ask_name becomes utter_chitchat/ask_name. Note that the NLU examples for this will still be under chitchat/ask_name intent. The example responseselectorbot should help clarify these changes further.

  • The output schema of ResponseSelector has changed - full_retrieval_intent and name have been deprecated in favour of intent_response_key and response_templates respectively. Additionally, two keys are added to the output -

  1. all_retrieval_intents - Holds a list of all retrieval intents(faq, chitchat, etc.) that are present in the training data.
  2. template_name - Holds the name of the response template which is predicted by the response selector(utter_faq/is_legit) An example output looks like this -
{
"response_selector": {
"all_retrieval_intents": [
"faq"
],
"default": {
"response": {
"id": 1388783286124362000,
"confidence": 1,
"intent_response_key": "faq/is_legit",
"response_templates": [
{
"text": "absolutely",
"image": "https://i.imgur.com/nGF1K8f.jpg"
},
{
"text": "I think so."
}
]
"template_name": "utter_faq/is_legit"
},
"ranking": [
{
"id": 1388783286124362000,
"confidence": 1,
"intent_response_key": "faq/is_legit"
}
]
}
}
}

As a result of this, if you were previously querying for the key full_retrieval_intent as:

response_selector_output.get("default")
.get("full_retrieval_intent")

you should instead now do this:

response_selector_output.get("default")
.get("response")
.get("intent_response_key")

Core Featurization

  • LabelTokenizerSingleStateFeaturizer is deprecated and will be removed in the future. Please use SingleStateFeaturizer with appropriate NLU pipeline. To replicate LabelTokenizerSingleStateFeaturizer functionality, add a Tokenizer with the option intent_tokenization_flag: True and CountVectorsFeaturizer to the NLU pipeline. Please update your configuration file.

    For example:

    language: en
    pipeline:
    - name: WhitespaceTokenizer
    intent_tokenization_flag: True
    - name: CountVectorsFeaturizer

    Please train both NLU and Core (using rasa train) to use a trained tokenizer and featurizer for Core featurization.

  • BinarySingleStateFeaturizer is deprecated and will be removed in the future. If you train both NLU and Core (using rasa train), use SingleStateFeaturizer with NLU pipeline where intent_tokenization_flag of a Tokenizer is set to False.

    For example:

    language: en
    pipeline:
    - name: WhitespaceTokenizer
    intent_tokenization_flag: False

    Alternatively, you can train a Core model without NLU using rasa train core.

Rasa 1.7 to Rasa 1.8

caution

This is a release breaking backwards compatibility. It is not possible to load previously trained models. Please make sure to retrain a model before trying to use it with this improved version.

General

  • The TED Policy replaced the keras_policy as recommended machine learning policy. New projects generated with rasa init will automatically use this policy. In case you want to change your existing model configuration to use the TED Policy add this to the policies section in your config.yml and remove potentially existing KerasPolicy entries:

    policies:
    # - ... other policies
    - name: TEDPolicy
    max_history: 5
    epochs: 100

    The given snippet specifies default values for the parameters max_history and epochs. max_history is particularly important and strongly depends on your stories. Please see the docs of the TED Policy if you want to customize them.

  • All pre-defined pipeline templates are deprecated. Any templates you use will be mapped to the new configuration, but the underlying architecture is the same. Take a look at Tuning Your Model to decide on what components you should use in your configuration file.

  • The Embedding Policy was renamed to TED Policy. The functionality of the policy stayed the same. Please update your configuration files to use TEDPolicy instead of EmbeddingPolicy.

  • Most of the model options for EmbeddingPolicy, EmbeddingIntentClassifier, and ResponseSelector got renamed. Please update your configuration files using the following mapping:

    Old model optionNew model option
    hidden_layers_sizes_adictionary “hidden_layers_sizes” with key “text”
    hidden_layers_sizes_bdictionary “hidden_layers_sizes” with key “label”
    hidden_layers_sizes_pre_dialdictionary “hidden_layers_sizes” with key “dialogue”
    hidden_layers_sizes_botdictionary “hidden_layers_sizes” with key “label”
    num_transformer_layersnumber_of_transformer_layers
    num_headsnumber_of_attention_heads
    max_seq_lengthmaximum_sequence_length
    dense_dimdense_dimension
    embed_dimembedding_dimension
    num_negnumber_of_negative_examples
    mu_posmaximum_positive_similarity
    mu_negmaximum_negative_similarity
    use_max_sim_neguse_maximum_negative_similarity
    C2regularization_constant
    C_embnegative_margin_scale
    droprate_adroprate_dialogue
    droprate_bdroprate_label
    evaluate_every_num_epochsevaluate_every_number_of_epochs
    evaluate_on_num_examplesevaluate_on_number_of_examples

    Old configuration options will be mapped to the new names, and a warning will be thrown. However, these will be deprecated in a future release.

  • The Embedding Intent Classifier is now deprecated and will be replaced by DIETClassifier in the future. DIETClassfier performs intent classification as well as entity recognition. If you want to get the same model behavior as the current EmbeddingIntentClassifier, you can use the following configuration of DIETClassifier:

    pipeline:
    # - ... other components
    - name: DIETClassifier
    hidden_layers_sizes:
    text: [256, 128]
    number_of_transformer_layers: 0
    weight_sparsity: 0
    intent_classification: True
    entity_recognition: False
    use_masked_language_model: False
    BILOU_flag: False
    # ... any other parameters

    See DIETClassifier for more information about the new component. Specifying EmbeddingIntentClassifier in the configuration maps to the above component definition, the behavior is unchanged from previous versions.

  • CRFEntityExtractor is now deprecated and will be replaced by DIETClassifier in the future. If you want to get the same model behavior as the current CRFEntityExtractor, you can use the following configuration:

    pipeline:
    # - ... other components
    - name: LexicalSyntacticFeaturizer
    features: [
    ["low", "title", "upper"],
    [
    "BOS",
    "EOS",
    "low",
    "prefix5",
    "prefix2",
    "suffix5",
    "suffix3",
    "suffix2",
    "upper",
    "title",
    "digit",
    ],
    ["low", "title", "upper"],
    ]
    - name: DIETClassifier
    intent_classification: False
    entity_recognition: True
    use_masked_language_model: False
    number_of_transformer_layers: 0
    # ... any other parameters

    CRFEntityExtractor featurizes user messages on its own, it does not depend on any featurizer. We extracted the featurization from the component into the new featurizer LexicalSyntacticFeaturizer. Thus, in order to obtain the same results as before, you need to add this featurizer to your pipeline before the DIETClassifier. Specifying CRFEntityExtractor in the configuration maps to the above component definition, the behavior is unchanged from previous versions.

  • If your pipeline contains CRFEntityExtractor and EmbeddingIntentClassifier you can substitute both components with DIETClassifier. You can use the following pipeline for that:

    pipeline:
    # - ... other components
    - name: LexicalSyntacticFeaturizer
    features: [
    ["low", "title", "upper"],
    [
    "BOS",
    "EOS",
    "low",
    "prefix5",
    "prefix2",
    "suffix5",
    "suffix3",
    "suffix2",
    "upper",
    "title",
    "digit",
    ],
    ["low", "title", "upper"],
    ]
    - name: DIETClassifier
    number_of_transformer_layers: 0
    # ... any other parameters

Rasa 1.6 to Rasa 1.7

General

  • By default, the EmbeddingIntentClassifier, EmbeddingPolicy, and ResponseSelector will now normalize the top 10 confidence results if the loss_type is "softmax" (which has been default since 1.3, see Rasa 1.2 to Rasa 1.3). This is configurable via the ranking_length configuration parameter; to turn off normalization to match the previous behavior, set ranking_length: 0.

Rasa 1.2 to Rasa 1.3

caution

This is a release breaking backwards compatibility. It is not possible to load previously trained models. Please make sure to retrain a model before trying to use it with this improved version.

General

  • Default parameters of EmbeddingIntentClassifier are changed. See Components for details. Architecture implementation is changed as well, so old trained models cannot be loaded. Default parameters and architecture for EmbeddingPolicy are changed. See Policies for details. It uses transformer instead of lstm. Old trained models cannot be loaded. They use inner similarity and softmax loss by default instead of cosine similarity and margin loss (can be set in config file). They use balanced batching strategy by default to counteract class imbalance problem. The meaning of evaluate_on_num_examples is changed. If it is non zero, random examples will be picked by stratified split and used as hold out validation set, so they will be excluded from training data. We suggest to set it to zero (default) if data set contains a lot of unique examples of dialogue turns. Removed label_tokenization_flag and label_split_symbol from component. Instead moved intent splitting to Tokenizer components via intent_tokenization_flag and intent_split_symbol flag.

  • Default max_history for EmbeddingPolicy is None which means it'll use the FullDialogueTrackerFeaturizer. We recommend to set max_history to some finite value in order to use MaxHistoryTrackerFeaturizer for faster training. See Featurization of Conversations for details. We recommend to increase batch_size for MaxHistoryTrackerFeaturizer (e.g. "batch_size": [32, 64])

  • Compare mode of rasa train core allows the whole core config comparison. Therefore, we changed the naming of trained models. They are named by config file name instead of policy name. Old naming style will not be read correctly when creating compare plots (rasa test core). Please remove old trained models in comparison folder and retrain. Normal core training is unaffected.

  • We updated the evaluation metric for our NER. We report the weighted precision and f1-score. So far we included no-entity in this report. However, as most of the tokens actually don't have an entity set, this will influence the weighted precision and f1-score quite a bit. From now on we exclude no-entity from the evaluation. The overall metrics now only include proper entities. You might see a drop in the performance scores when running the evaluation again.

  • / is reserved as a delimiter token to distinguish between retrieval intent and the corresponding response text identifier. Make sure you don't include / symbol in the name of your intents.

Rasa NLU 0.14.x and Rasa Core 0.13.x to Rasa 1.0

caution

This is a release breaking backwards compatibility. It is not possible to load previously trained models. Please make sure to retrain a model before trying to use it with this improved version.

General

  • The scripts in rasa.core and rasa.nlu can no longer be executed. To train, test, run, … an NLU or Core model, you should now use the command line interface rasa. The functionality is, for the most part, the same as before. Some changes in commands reflect the combined training and running of NLU and Core models, but NLU and Core can still be trained and used individually. If you attempt to run one of the old scripts in rasa.core or rasa.nlu, an error is thrown that points you to the command you should use instead. See all the new commands at Command Line Interface.

  • If you have written a custom output channel, all send_ methods subclassed from the OutputChannel class need to take an additional \*\*kwargs argument. You can use these keyword args from your custom action code or the templates in your domain file to send any extra parameters used in your channel's send methods.

  • If you were previously importing the Button or Element classes from rasa_core.dispatcher, these are now to be imported from rasa_sdk.utils.

  • Rasa NLU and Core previously used separate configuration files. These two files should be merged into a single file either named config.yml, or passed via the --config parameter.

Script parameters

  • All script parameter names have been unified to follow the same schema. Any underscores (_) in arguments have been replaced with dashes (-). For example: --max_history has been changed to --max-history. You can see all of the script parameters in the --help output of the commands in the Command Line Interface.

  • The --num_threads parameter was removed from the run command. The server will always run single-threaded, but will now run asynchronously. If you want to make use of multiple processes, feel free to check out the Sanic server documentation.

  • To avoid conflicts in script parameter names, connectors in the run command now need to be specified with --connector, as -c is no longer supported. The maximum history in the rasa visualize command needs to be defined with --max-history. Output paths and log files cannot be specified with -o anymore; --out and --log-file should be used. NLU data has been standarized to be --nlu and the name of any kind of data files or directory to be --data.

HTTP API

  • There are numerous HTTP API endpoint changes which can be found here.