# 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](https://legacy-docs-v1.rasa.com/1.10.25/core/policies/#ted-policy) replaced the [Keras Policy](https://legacy-docs-v1.rasa.com/1.10.25/core/policies/#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](https://legacy-docs-v1.rasa.com/1.10.25/core/policies/#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.25/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.25/core/policies/#embedding-policy) was renamed to [TED Policy](https://legacy-docs-v1.rasa.com/1.10.25/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.25/nlu/components/#embedding-intent-classifier) is now deprecated and will be replaced by [DIETClassifier](https://legacy-docs-v1.rasa.com/1.10.25/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](https://legacy-docs-v1.rasa.com/1.10.25/nlu/components/#diet-classifier) 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](https://legacy-docs-v1.rasa.com/1.10.25/nlu/components/#lexicalsyntacticfeaturizer). Thus, in order to obtain the same results as before, you need to add this featurizer to your pipeline before the [DIETClassifier](https://legacy-docs-v1.rasa.com/1.10.25/nlu/components/#diet-classifier). 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](https://legacy-docs-v1.rasa.com/1.10.25/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](https://legacy-docs-v1.rasa.com/1.10.25/migration-guide/#migration-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:** 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](https://legacy-docs-v1.rasa.com/1.10.25/nlu/components/#components) for details. Architecture implementation is changed as well, so **old trained models cannot be loaded**.

- `/` 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.