> ## 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](https://docs.mixpeek.com/docs/processing/model-registry.md) hot-swaps the default for **new** collections without touching existing ones.

## 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](https://docs.mixpeek.com/docs/retrieval/evaluations.md) 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](https://docs.mixpeek.com/docs/retrieval/benchmarks.md), or [generate an evaluation dataset from recorded interactions](https://docs.mixpeek.com/docs/retrieval/interactions.md) 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.

## Related

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.