Migration Guide

These docs are for version 1.x of Rasa Open Source.

Migration Guide

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

Rasa 1.7 to Rasa 1.8

Warning

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 the 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
    ```

- 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 [Choosing a Pipeline](https://legacy-docs-v1.rasa.com/1.10.2/nlu/choosing-a-pipeline/#choosing-a-pipeline) to decide on what components you should use in your configuration file.

- The [Embedding Policy](https://legacy-docs-v1.rasa.com/1.10.2/core/policies/#embedding-policy) was renamed to [TED Policy](https://legacy-docs-v1.rasa.com/1.10.2/core/policies/#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 option | New model option |
| --- | --- |
| hidden_layers_sizes_a | dictionary “hidden_layers_sizes” with key “text” |
| hidden_layers_sizes_b | dictionary “hidden_layers_sizes” with key “label” |
| hidden_layers_sizes_pre_dial | dictionary “hidden_layers_sizes” with key “dialogue” |
| hidden_layers_sizes_bot | dictionary “hidden_layers_sizes” with key “label” |
| num_transformer_layers | number_of_transformer_layers |
| num_heads | number_of_attention_heads |
| max_seq_length | maximum_sequence_length |
| dense_dim | dense_dimension |
| embed_dim | embedding_dimension |
| num_neg | number_of_negative_examples |
| mu_pos | maximum_positive_similarity |
| mu_neg | maximum_negative_similarity |
| use_max_sim_neg | use_maximum_negative_similarity |
| C2 | regularization_constant |
| C_emb | negative_margin_scale |
| droprate_a | droprate_dialogue |
| droprate_b | droprate_label |
| evaluate_every_num_epochs | evaluate_every_number_of_epochs |
| evaluate_on_num_examples | evaluate_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.

- [EmbeddingIntentClassifier](https://legacy-docs-v1.rasa.com/1.10.2/nlu/components/#embedding-intent-classifier) is now deprecated and will be replaced by [DIETClassifier](https://legacy-docs-v1.rasa.com/1.10.2/nlu/components/#diet-classifier) 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
    ```
- If your pipeline contains `CRFEntityExtractor` and `EmbeddingIntentClassifier` you can substitute both components with [DIETClassifier](https://legacy-docs-v1.rasa.com/1.10.2/nlu/components/#diet-classifier). 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

Warning

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 the dataset 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

Warning

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.