> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate Embedding Models

> Switch a namespace to a new embedding model by re-extracting into a target namespace — safely, with validation and dry-run

Embedding dimensions are **locked at namespace creation** — you can't swap the embedding model in place, because the vector index dimensionality is fixed and vectors from different models aren't comparable. To move to a new model, you **re-extract** your data into a target namespace using the new extractor config, validate it, then cut over.

<Note>
  This is the right path whenever you change the embedding model (e.g. a new frontier text model, or switching `text_extractor` → a higher-dim model). For routine model upgrades within the same family, the [model registry](/processing/model-registry) hot-swaps the default for **new** collections without touching existing ones.
</Note>

## How it works

A **migration** of type `re_extract` reads your source namespace's objects and re-runs extraction with a new `feature_extractors` config (the new model) into a target namespace. Your source stays live and untouched until you choose to cut over.

| Migration type | What it does                                                                            |
| -------------- | --------------------------------------------------------------------------------------- |
| `re_extract`   | Re-run extraction with new extractor/model config (use this to change embedding models) |
| `copy`         | Copy resources as-is to another namespace (no re-extraction)                            |
| `extend`       | Add new features to existing documents without a full re-extract                        |

## 1. Validate first (dry run)

Always validate the migration config before committing compute — it checks the source, target, and extractor config without extracting anything.

```bash theme={null}
curl -sS -X POST "$MP_API_URL/v1/namespaces/migrations/validate" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "migration_type": "re_extract",
      "source_namespace_id": "ns_prod",
      "target_namespace_name": "prod-v2",
      "feature_extractors": [
        { "feature_extractor_name": "text_extractor", "version": "v1",
          "params": { "embedding_model": "<new-model-id>" } }
      ]
    }
  }'
```

## 2. Create the migration

```bash theme={null}
curl -sS -X POST "$MP_API_URL/v1/namespaces/migrations/" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "migration_type": "re_extract",
      "source_namespace_id": "ns_prod",
      "target_namespace_name": "prod-v2",
      "feature_extractors": [
        { "feature_extractor_name": "text_extractor", "version": "v1",
          "params": { "embedding_model": "<new-model-id>" } }
      ],
      "dry_run": false,
      "webhook_url": "https://example.com/migration-status"
    },
    "start_immediately": false
  }'
```

The response includes a `migration_id`.

| Config field                                    | Purpose                                                 |
| ----------------------------------------------- | ------------------------------------------------------- |
| `migration_type`                                | `re_extract` to change the model                        |
| `source_namespace_id`                           | Namespace to migrate from                               |
| `target_namespace_name` / `target_namespace_id` | Where the re-extracted data lands                       |
| `feature_extractors`                            | New extractor config — the new embedding model          |
| `filters`                                       | Optionally migrate a subset (by collection, date, etc.) |
| `batch_options`                                 | Tune batch size / parallelism                           |
| `dry_run`                                       | Validate only, don't execute                            |
| `webhook_url`                                   | Get progress callbacks                                  |

## 3. Start and monitor

```bash theme={null}
# Start (if you didn't set start_immediately)
curl -sS -X POST "$MP_API_URL/v1/namespaces/migrations/{migration_id}/start" \
  -H "Authorization: Bearer $MP_API_KEY"

# Poll status
curl -sS "$MP_API_URL/v1/namespaces/migrations/{migration_id}" \
  -H "Authorization: Bearer $MP_API_KEY"
```

Cancel a running migration with `POST /v1/namespaces/migrations/{migration_id}/cancel`.

## 4. Cut over

Re-extraction re-pays GPU/extraction cost for every document, so validate on a subset first (use `filters`) and confirm quality before migrating everything. Once the target namespace is populated and validated:

1. Re-run your [evaluations](/retrieval/evaluations) against the target namespace to confirm relevance is at least as good. For a head-to-head old-vs-new read on real query logs, run the same query set through both namespaces' retrievers as [benchmarks](/retrieval/benchmarks), or [generate an evaluation dataset from recorded interactions](/retrieval/interactions) so the comparison reflects production traffic rather than synthetic queries.
2. Point your application's `X-Namespace` (and retrievers) at the target namespace.
3. Retire the source namespace when you're confident.

## Rollback

The source namespace stays live and untouched until you retire it — that **is** the rollback path. If post-cutover metrics regress, point `X-Namespace` back at the source namespace; no re-extraction is needed in either direction. Only retire the source once the target has survived real traffic for as long as your risk tolerance requires.

<Warning>
  Vectors from different embedding models are **not** comparable — you cannot mix old and new vectors in the same index, and you cannot copy embeddings across models (only `re_extract` regenerates them). Plan for the full re-extraction cost.
</Warning>

## Related

* [Model Registry](/processing/model-registry) — how default models are resolved and hot-swapped
* [Feature Extractors](/processing/feature-extractors) — extractor + model configuration
* [Evaluations](/retrieval/evaluations) — verify the new model before cutting over
* [Reprocess existing content](/tutorials/reprocess-existing-content) — the underlying re-extraction flow, step by step
* [Monitoring ingestion](/processing/tasks) — track re-extraction progress