# 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.8.1/core/policies/#ted-policy) replaced the [Keras Policy](https://legacy-docs-v1.rasa.com/1.8.1/core/policies/#keras-policy) as recommended machine learning policy. New projects generated with `rasa init` will automatically use this policy.

```yaml
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 remains the same**.
- The [Embedding Policy](https://legacy-docs-v1.rasa.com/1.8.1/core/policies/#embedding-policy) was renamed to [TED Policy](https://legacy-docs-v1.rasa.com/1.8.1/core/policies/#ted-policy). The functionality of the policy stayed the same.
- 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                        |

- `EmbeddingIntentClassifier` is now deprecated and will be replaced by `DIETClassifier` in the future.

```yaml
pipeline:
# - ... other components
- name: DIETClassifier
  intent_classification: True
  entity_recognition: False
  use_masked_language_model: False
  BILOU_flag: False
  number_of_transformer_layers: 0
  # ... any other parameters
```
- `CRFEntityExtractor` is now deprecated and will be replaced by `DIETClassifier` in the future. If you want to get the same model behaviour as the current `CRFEntityExtractor`, you can use the following configuration:

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

## 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"`.

## Rasa 1.2 to Rasa 1.3

### General
- Default parameters of `EmbeddingIntentClassifier` are changed. See [Components](https://legacy-docs-v1.rasa.com/1.8.1/nlu/components/#components) for details.
- Old trained models cannot be loaded. Default parameters for `EmbeddingPolicy` are changed. 
- We recommend to increase `batch_size` for `MaxHistoryTrackerFeaturizer`.