Skip to main content

vai refresh

Re-embed existing documents in MongoDB with a new model, different dimensions, or updated chunk settings — without re-ingesting from source files.

Synopsis​

vai refresh [options]

Description​

vai refresh reads documents from your MongoDB collection, re-generates their embeddings with a new model or dimensions, and updates them in-place. Optionally, it can re-chunk the text before re-embedding using the --rechunk flag.

This is useful when upgrading to a newer model (e.g., migrating from voyage-3.5-lite to voyage-4-large) or changing dimensions without needing to re-ingest from source files.

After refreshing, vai updates your .vai.json project config with the new model and dimensions.

Options​

FlagDescriptionDefault
--db <database>Database nameFrom .vai.json or VAI_DB
--collection <name>Collection nameFrom .vai.json or VAI_COLLECTION
--field <name>Embedding field nameFrom .vai.json or embedding
-m, --model <model>New embedding modelFrom .vai.json or voyage-3.5-lite
-d, --dimensions <n>New dimensionsFrom .vai.json
--rechunkRe-chunk text before re-embedding—
-s, --strategy <strategy>Chunk strategy (with --rechunk)recursive
-c, --chunk-size <n>Chunk size (with --rechunk)512
--overlap <n>Chunk overlap (with --rechunk)50
--batch-size <n>Texts per API call25
--filter <json>Only refresh matching documents (JSON)—
--forceSkip confirmation prompt—
--dry-runShow plan without executing—
--jsonMachine-readable JSON output—
-q, --quietSuppress non-essential output—

Examples​

Upgrade to a new model​

vai refresh --model voyage-4-large

Refresh with new dimensions​

vai refresh --model voyage-4 --dimensions 512

Re-chunk and re-embed​

vai refresh --model voyage-4-large --rechunk --strategy recursive --chunk-size 1024

Refresh only specific documents​

vai refresh --model voyage-4-large --filter '{"_model": "voyage-3.5-lite"}'

Dry run to see the plan​

vai refresh --model voyage-4-large --dry-run

Tips​

  • Use --dry-run first to see how many documents will be affected.
  • The --rechunk flag deletes the original documents and inserts new chunked versions. Make sure you have the text stored in the documents.
  • Refreshing updates embeddings in-place (via $set), preserving _id and other fields.
  • After a successful refresh, .vai.json is automatically updated with the new model and dimensions.