This is for anyone already running a vector search index who wants the retrieval boost from Voyage AI without a maintenance window.

Can you mix old and new embeddings in one index?

No, and this is the mistake that ruins the migration. Querying an index built from two different models returns garbage — the nearest-neighbor search compares distances across incompatible vector spaces.

That means a full re-embed of every document. There is no partial upgrade path. Plan for the token cost of the whole corpus, not just the new documents arriving each day.

How do you migrate without downtime?

Run two indexes side by side and cut over when the new one is complete:

1. Create a new index with the Voyage model and its dimension count.
2. Backfill historical documents in batches, writing to the new index only.
3. Dual-write new and updated documents to both indexes so the new one stays current.
4. Point a small percentage of traffic at the new index and compare relevance offline.
5. Flip the read path fully, then delete the old index.

The dual-write window is the risky part. Keep it short — days, not weeks — because every missed write is a document that goes missing after cutover.

How do you verify the new index is actually better?

Replay a set of real queries against both indexes and compare ranking. Use a fixed query log of at least a few hundred entries and check how often the correct document appears in the top three results. Do this before you flip production traffic, not after.

Note the storage column. Bigger embeddings cost more to store and query, so a marginal relevance gain may not be worth it on a huge corpus.

What does re-indexing cost?

You pay the Voyage token cost for every document, once for the backfill and again for any re-embeds after edits. For a million-document corpus this is the line item that decides whether the upgrade is worth doing. Run the numbers before the backfill, not halfway through it.

Should you upgrade at all?

Yes if retrieval quality is a user-visible complaint, or if you moved from a generic model to a domain one like voyage-code-3. No if your current index already returns the right chunk most of the time — the cost and migration risk buy you little.

Quick Summary

• Never mix embeddings from two models in one index — do a full re-embed.
• Migrate with dual indexes and dual-write, then cut over.
• Verify with a fixed query log before flipping production traffic.
• Larger vectors mean higher storage and query cost — factor that in.
• Upgrade when retrieval is a complaint, not on a whim.

It is a narrow tool. No chatbot, no dashboard. If you need a full RAG platform, look elsewhere; if you need the embedding layer done well, this is the part that decides whether retrieval works.

How do you get an API key and make a first call?

Sign up at voyageai.com, create a key, then call the API. A minimal Python example:

import voyageai
vo = voyageai.Client(api_key="YOUR_KEY")
res = vo.embed(["how do vector databases work"], model="voyage-3")
print(len(res.embeddings[0]))

Each model returns a fixed-length vector — 1024 dimensions for voyage-3. You store those alongside your text in whatever vector store you run, then query with the same model at search time.

Which Voyage model should you pick?

Match the model to the job:

• voyage-3 — general-purpose, good default for mixed content.
• voyage-3-lite — cheaper and faster, fine for high-volume, low-stakes search.
• voyage-code-3 — trained on code, better for repositories and technical docs.
• voyage-law-2 — legal text, where terminology matters.

Domain models beat the general model on their own turf. Do not assume voyage-3 is always the answer; on a code index, voyage-code-3 usually retrieves more relevant chunks.

Is Voyage AI free to start?

New accounts get a free token allowance — on the order of hundreds of millions of tokens for the lite model, enough to embed a large corpus before paying. After that it is usage-based per token, with cheaper rates on the lite and domain models. Check current rates before a big ingestion job, because embedding a million documents is not free.

What are the common mistakes?

Mixing models between indexing and querying. If you embed documents with voyage-3 and query with voyage-3-lite, the vectors live in different spaces and results degrade badly. Pick one model per index and write it down.

Second: not batching. The API takes a list of texts up to a per-request limit, so sending one string at a time wastes most of your throughput. Batch a hundred documents per call and the ingestion job finishes far sooner.

Quick Summary

• Voyage AI is an embeddings API for search and retrieval, not a chatbot platform.
• voyage-3 is the general default; code and legal content have dedicated models.
• New accounts get a free token allowance on the lite model.
• Never mix embedding models between indexing and querying one index.
• Batch documents per request — one-at-a-time calls waste throughput.

If you want a managed pipeline around these vectors, see Contextual AI.