> For a complete page index of the Captain API documentation, fetch https://docs.captain.dev/llms.txt?excludeSpec=true

# Upgrading Models

> Add a new vector space, re-embed against a GPU endpoint, atomically swap the default, and delete the old space when you're confident.

## Agent Quick Reference - Model Upgrades

* **Add space**: `POST /collections/:name/vector-spaces` with `{ name, dims, model }`.
* **Trigger rebuild**: `POST /collections/:name/vector-spaces/:space/rebuild` with `{ embed_endpoint }`.
* **Poll status**: `GET /collections/:name/vector-spaces/:space/status` returns `{ status, progress, total, completed }`.
* **Swap default**: `PUT /collections/:name/default-vector-space` with `{ name }`. Zero downtime. Old space stays for rollback.
* **Delete old space**: `DELETE /collections/:name/vector-spaces/:space`. Irreversible.
* **Key constraint**: The rebuild reads all existing chunks and re-embeds them via the `embed_endpoint` URL. That endpoint must implement the HuggingFace TEI `/embed` interface.
* **Common pitfall**: Do not delete the old space until you have validated recall on the new space. The swap is atomic; the delete is not reversible.

Compass lets you swap embedding models without taking the collection offline. The pattern is blue-green deployment for vector spaces: build the new space alongside the existing one, re-embed in the background, test it, then swap the default. The collection serves queries from the old space the entire time, the swap itself is atomic, and the old space stays in place for rollback.

Common reasons to do this: a newer model scores better on your eval set, you're adding a language your current model wasn't trained on, you're going from text-only to multimodal and need a second space, or your current model is being deprecated.

The examples below send `Authorization: Bearer $COMPASS_API_KEY`. Set `COMPASS_BASE_URL` and `COMPASS_API_KEY` in your shell first (see the [quickstart](/guides/compass/quickstart)).

## Step 1. Add the new vector space

```bash
curl -X POST $COMPASS_BASE_URL/collections/media/vector-spaces \
  -H "Authorization: Bearer $COMPASS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "qwen3",
    "dims": 1024,
    "model": "Qwen/Qwen3-Embedding-8B"
  }'
```

The new space is created with `status: "building"`. The collection continues serving queries from the existing default space.

## Step 2. Trigger the rebuild

Point the rebuild at your GPU embedding endpoint. Compass reads all chunks from the collection and posts them to `embed_endpoint` in batches. The endpoint must implement the HuggingFace TEI `/embed` interface:

```bash
curl -X POST $COMPASS_BASE_URL/collections/media/vector-spaces/qwen3/rebuild \
  -H "Authorization: Bearer $COMPASS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "embed_endpoint": "http://gpu-server:8080/embed"
  }'
```

To spin up a TEI instance against the target model:

```bash
docker run -p 8080:80 --gpus all \
  ghcr.io/huggingface/text-embeddings-inference \
  --model-id Qwen/Qwen3-Embedding-8B
```

A single A10G running Qwen3-Embedding-8B processes around 1,500 documents per second.

## Step 3. Poll rebuild status

```bash
curl $COMPASS_BASE_URL/collections/media/vector-spaces/qwen3/status \
  -H "Authorization: Bearer $COMPASS_API_KEY"
```

Response:

```json
{
  "name": "qwen3",
  "status": "building",
  "progress": 0.61,
  "total": 142000,
  "completed": 86620
}
```

When `status` is `"active"` and `progress` is `1.0`, the space is ready. Run your evaluation queries against it by passing `"vector_space": "qwen3"` to the search endpoint before you swap the default.

## Step 4. Swap the default

The swap is atomic. Queries in flight against the old space finish normally. New queries after the swap use the new space:

```bash
curl -X PUT $COMPASS_BASE_URL/collections/media/default-vector-space \
  -H "Authorization: Bearer $COMPASS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name": "qwen3"}'
```

The old space stays in place. If you find a regression, swap back by repeating this call with the old space name.

## Step 5. Delete the old space (optional)

Once you're confident in the new space, free the disk:

```bash
curl -X DELETE \
  -H "Authorization: Bearer $COMPASS_API_KEY" \
  $COMPASS_BASE_URL/collections/media/vector-spaces/OLD_SPACE_NAME
```

Replace `OLD_SPACE_NAME` with the name of the space you swapped away from (the previous default), not the new `qwen3` space you just promoted.

> **Error**
>
> This is irreversible. The vectors for the old space are deleted from disk. Only do this after you have validated recall on the new space across your real query distribution.

## Using your own GPU endpoint

The `embed_endpoint` parameter accepts any URL that implements the TEI `/embed` POST interface. That includes vLLM, custom FastAPI servers, or any other inference server that accepts:

```json
{ "inputs": ["text one", "text two"] }
```

and returns:

```json
[[0.12, -0.34], [0.56, 0.78]]
```

This means the rebuild can run against your own VPC-internal GPU fleet. The vectors never leave your network.