Migrate repository embeddings through CometAPI safely.

Last reviewed: 2026-08-25

Direct answer

A safe CometAPI repository embedding migration is a versioned, reversible index rebuild—not a model-name edit performed against the live index. Define the target embedding contract, create separate target storage, dual-write repository changes, backfill vectors from the original chunks, validate search quality, and then move query traffic. Keep the old index available until the new path has passed a rollback window.

The CometAPI embeddings endpoint accepts one or more text inputs and returns one vector per input in the same order. That makes ordered batch backfills practical, but it does not make two embedding models interchangeable. Your contract still has to bind the model identifier, supported output dimensions, chunking rules, normalization, vector-store dimension, and distance metric.

For zero-downtime operation, use either parallel collections or an additional named vector. The Qdrant migration workflow describes both patterns: keep the old search path live, enable dual writes, populate the new vectors in the background, validate them, and switch only after completion. The same control pattern applies when another vector store provides equivalent isolation and cutover mechanisms.

Who this is for

This guide is for teams whose coding agents use semantic search to find repository files, symbols, examples, tests, or documentation. It assumes you have stable document or chunk identifiers and can recover the original normalized text used to create each vector.

If the vector database is your only copy of the repository chunks, restore a durable source of truth before migrating. Re-embedding requires the original input, not merely the old vector. Teams that are also changing model routing should record the embedding decision in a model change checklist .

Key takeaways

Version the embedding model, dimensions, preprocessing, chunker, and distance metric as one retrieval contract.
Keep the current index authoritative while a separate target is populated and tested.
Dual-write upserts, updates, and deletions; a backfill alone cannot keep a moving repository consistent.
Check mechanical integrity and retrieval relevance before cutover.
Retain the old route long enough to make rollback an ordinary routing change.

Sources checked

CometAPI Create embeddings documentation defines the endpoint, array input, ordered output, usage fields, and model-dependent dimension control.
Qdrant zero-downtime embedding migration documents blue-green and named-vector migrations, dual writes, background re-embedding, cutover, and mutation caveats.
Qdrant collections reference establishes collection-level dimensionality and metric requirements and explains separately configured named vectors.
OpenAI vector embeddings guide explains embeddings-based search and the storage-versus-size tradeoff available through supported dimension controls.

Contract details to verify

Write a migration manifest before sending the first target request. Record the exact source and target model identifiers, endpoint route, requested dimensions if supported, observed vector length, distance metric, chunker version, text-normalization version, exclusion rules, source revision, and stable chunk-ID algorithm. Also record the baseline query set, cutover thresholds, rollback owner, and the point at which the old index may be retired.

The dimensions setting is not universal. CometAPI documents it for text-embedding-3-* models, so omit it unless the selected target model supports it. Generate a smoke-test vector and measure its actual length before creating target storage. The vector store must be configured for that length and the intended metric. As the Qdrant collection contract notes, ordinary collection vectors share dimensionality and a comparison metric, while named vectors can have separate size and metric settings.

Happy-path operator workflow

Capture a baseline. Save current index settings, document count, update lag, and a fixed set of repository questions with expected files or symbols. Include easy lookups, cross-module concepts, renamed code, and terms that appear in many files.
Provision the target. For blue-green migration, create an empty target collection with the measured vector length and selected metric. If the existing collection was designed for named vectors and supports adding another configuration, add the target vector without removing the old one.
Enable dual writes. New chunks and changed chunks must be embedded under both contracts and written with the same stable ID. Apply deletion and partial-update semantics to both paths. Keep queries on the old route while measuring target-write lag.
Backfill from the source text. Read chunks in stable ID order and submit bounded arrays to CometAPI. The documented response order matches input order, but the worker should still assert response count, expected index positions, finite numeric values, and exact vector length before writing. Advance the durable cursor only after the vector-store write succeeds.
Validate integrity and relevance. Compare source-record count, target-record count, missing IDs, duplicate IDs, and dual-write lag. Run the fixed query set against both indexes. Store the query, expected result, old result, new result, and reviewer decision in an agent run evidence ledger . Do not use the old model’s raw similarity threshold as the sole target gate.
Shadow and cut over. Embed live queries with the target contract and issue read-only shadow searches. Once integrity and relevance gates pass, shift a small portion of search traffic or flip an alias through a controlled deployment. Monitor no-result rate, latency, errors, update lag, and failed retrieval examples.
Soak before cleanup. Keep the old index queryable while the new route handles normal workloads. Retire it only after the rollback window closes and the final source revision, counts, and validation results are recorded.

Error-path operator workflow

If an embedding request times out or returns a non-success result, keep the old index serving and do not advance the backfill cursor. Retry within a bounded policy; split a repeatedly failing batch to isolate the problematic chunk.
If response count, ordering assumptions, or vector length fails validation, write none of that batch. Quarantine its sanitized IDs and stop that partition until the contract mismatch is understood.
If either side of a dual write fails, record the operation in a replayable queue and expose the lag. Do not silently accept a target that is missing recent repository changes.
If blue-green delete or partial-update handling is incomplete, pause those mutations or reconcile them from an ordered change journal before cutover. Qdrant explicitly warns that its basic blue-green example covers upserts and needs extra handling for these operations.
If retrieval quality misses the agreed gate, route all searches back to the old index. Investigate model choice, chunking, normalization, metric, and query construction separately rather than repeatedly changing several variables at once. Use documented stop, retry, and escalation rules for repeated failures.

Keep logs useful without copying repository contents or vectors into general-purpose telemetry. A sanitized event can look like this:

{
  "migration_id": "repo-embed-v2",
  "phase": "backfill",
  "document_id": "doc-042",
  "source_revision": "commit-8f2c1a",
  "target_model": "embedding-model-b",
  "requested_dimensions": 512,
  "observed_dimensions": 512,
  "distance_metric": "cosine",
  "batch_item_count": 64,
  "response_item_count": 64,
  "attempt": 1,
  "http_status": 200,
  "latency_ms": 480,
  "prompt_tokens": 920,
  "write_target": "repository-green",
  "validation_outcome": "pass",
  "error_class": null
}

Log stable internal IDs, contract versions, counts, timing, usage, status, and validation outcomes. Do not log raw repository text, returned embedding arrays, request headers, or credential material. If an error payload can echo input, sanitize it before storage.

Failure modes

Overwriting the live vectors first. An in-place replacement removes the clean rollback path and can leave the index partly encoded by each model. Build an isolated target or a separate named vector instead.
Treating equal vector lengths as compatibility. Two models producing the same number of values do not thereby share a retrieval space. Keep document and query embedding routes bound to the same versioned target contract.
Creating storage from an assumed dimension. A target write will fail if the observed vector length disagrees with the collection configuration. Smoke-test the selected model and validate every response before writing.
Keeping the old metric by habit. The vector-store metric is part of the model contract. Verify it explicitly and rebuild the target with the correct setting rather than changing it during cutover.
Losing deletes or partial updates. A backfill may recreate a deleted point, while a one-sided update can make old and new results diverge. Dual-write every mutation or replay a complete ordered change journal.
Misaligning batch results and chunk IDs. CometAPI returns results in input order, but local filtering, asynchronous joins, or retries can still corrupt the mapping. Freeze each batch manifest and validate its response count before pairing results.
Changing chunking and embeddings simultaneously. That makes a relevance regression difficult to attribute. If both changes are necessary, version them separately and test each transition.
Cutting over on count parity alone. Matching counts can hide irrelevant rankings. Require both mechanical integrity and a repository-specific query evaluation.
Deleting the old index too early. Keep it immutable or continuously synchronized through the rollback window. Cleanup is the last migration step, not part of cutover.

FAQ

Can we update vectors in place?

Avoid doing so for a live coding-agent search index. A separate collection is the broadly applicable pattern. A separate named vector can reduce copying and make rollback easier when the collection was created for named vectors and the deployed vector store supports the required operation.

Do equal dimensions mean two embedding models are interchangeable?

No. Dimension is a storage constraint, not proof that two vector spaces are compatible. Embed target documents and target queries with the same model and preprocessing contract.

Should we reduce the target dimensions to save storage?

Only when the selected model supports dimension control. CometAPI documents this parameter for text-embedding-3-* models, and the OpenAI guide describes the size tradeoff. Test repository retrieval at the proposed size rather than assuming a general quality result applies to your codebase.

What is the minimum cutover gate?

Require target count parity, no unexplained missing or duplicate IDs, acceptable dual-write lag, correct vector lengths, a passing fixed query set, and acceptable error and latency measurements. High-impact repositories should also review real shadow-search misses before traffic moves.

What if we no longer have the original chunk text?

Recover it from the repository and the same preprocessing pipeline, or from another durable source of truth. The old vectors cannot be converted reliably into embeddings from a different model. Reconstruct stable IDs and normalization before starting the migration.

When is rollback complete?

Rollback is complete when all queries use the old contract again, any failed target-only writes have been reconciled or safely discarded, and operators have confirmed that the old index still reflects current repository mutations. Preserve the target for diagnosis rather than deleting evidence immediately.

Reader next step

Create a one-page migration manifest now: name the source and target contracts, select a small repository query set, define count and relevance gates, and choose either a green collection or a separate named vector. Run a smoke test, verify the observed dimensions, and rehearse rollback before launching the full backfill.

When you are ready to test the embedding route and target model, Start with CometAPI .