vai embed

Generate vector embeddings from text using Voyage AI models or local voyage-4-nano inference.

CLI

Synopsis

vai embed [text] [options]

Description

vai embed generates dense vector embeddings from text. By default it uses the Voyage AI API. With --local, it routes embedding through local voyage-4-nano inference using vai's lightweight Python bridge.

Local mode is the fastest way to try vai in v1.31.0. Run vai nano setup once, then use --local whenever you want to embed without a Voyage API key.

When no --input-type is specified, vai shows a tip recommending --input-type query or --input-type document for better retrieval accuracy.

Options

Flag	Description	Default
-m, --model <model>	Embedding model. In local mode, voyage-4-nano is the supported local model	voyage-4-large
--local	Use local voyage-4-nano inference through the Python bridge	false
-t, --input-type <type>	Input type: query or document	—
-d, --dimensions <n>	Output dimensions (256, 512, 1024, 2048)	Model default
-f, --file <path>	Read text from a file	—
--truncation	Enable truncation for long inputs	—
--no-truncation	Disable truncation	—
--precision <type>	Local nano precision: float32, int8, uint8, binary	float32 in local mode
--output-dtype <type>	Output data type: float, int8, uint8, binary, ubinary	float
-o, --output-format <format>	Output format: json or array	json
--estimate	Show estimated tokens and cost without calling the API	—
--json	Machine-readable JSON output	—
-q, --quiet	Suppress non-essential output	—

Examples

Embed inline text

vai embed "What is MongoDB Atlas Vector Search?"

Embed locally with nano

vai nano setup
vai embed "What is vector search?" --local

Embed a document file with input type

vai embed --file article.txt --input-type document

Get raw array output for piping

vai embed "search query" --output-format array --input-type query

Use a lighter model with reduced dimensions

vai embed "hello world" --model voyage-4-lite --dimensions 256

Local embedding with reduced dimensions

vai embed "hello world" --local --model voyage-4-nano --dimensions 512

Estimate cost before embedding

vai embed --file large-document.txt --estimate

Quantized output for smaller storage

vai embed "vector search" --output-dtype int8

Playground

Using the Embed Tab

The Embed tab in vai playground provides a visual interface for generating embeddings.

Getting Started

1. Run vai playground to start the web app
2. Select the Embed tab from the navigation
3. Enter your text in the input field
4. Click Embed to generate the vector

Features

Model selection: Choose from all available Voyage AI models using the dropdown. The playground defaults to voyage-4-large.

Input type: Toggle between query and document input types. This affects how the model optimizes the embedding for retrieval accuracy.

Dimensions: Select output dimensions (256, 512, 1024, 2048) for models that support flexible sizing.

Output preview: The playground displays the embedding vector with metadata including token count, model used, and dimensions.

Cost estimation: View estimated cost before generating the embedding.

Workflow Integration

The Embed tab is also available as a step in the Workflows tab. Add an embed node to your workflow to embed text as part of a larger pipeline.

Tips

• Use --input-type query for search queries and --input-type document for corpus text. The model optimizes embeddings differently for each.
• Use --local when you want zero-API-key local embedding with voyage-4-nano.
• All Voyage 4 models share the same embedding space, so you can embed documents with voyage-4-lite and queries with voyage-4-large for cost savings.
• voyage-4-nano shares that same embedding space, so local-first indexing can grow into API-backed workflows later.
• Use --output-format array (CLI) when piping embeddings to another tool.
• The --estimate flag shows a cost comparison table and lets you switch models before calling the API.

Related Commands

• vai similarity — Compare text similarity using embeddings
• vai store — Embed and store in MongoDB
• vai pipeline — End-to-end chunk → embed → store
• vai estimate — Compare embedding costs across models
• Local Inference Guide — Set up nano and learn how local mode works