Quickstart

The fastest way to get started is the interactive quickstart:

vai quickstart

This walks you through setting up local inference or API-backed credentials, embedding your first document, and running a search query. If you prefer to do it manually, follow the steps below.

Fastest path

Start with the same friendly entry point the CLI is designed around

If you are brand new to vai, the local nano path is now the most approachable first moment: install once, run vai nano setup, then embed locally before you decide how much hosted infrastructure you want to turn on.

Jump to local inference overview

Fastest Local Start

If you want the shortest path to a working embedding in v1.31.0, start with local nano inference:

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

This uses voyage-4-nano through vai's lightweight Python bridge and does not require a Voyage API key.

Step 1: Set Credentials

For the full MongoDB-backed quickstart, configure:

export VOYAGE_API_KEY="your-key"
export MONGODB_URI="mongodb+srv://user:pass@cluster.mongodb.net/"

Get a free Voyage AI key at dash.voyageai.com and a free MongoDB Atlas cluster at mongodb.com/atlas.

Step 2: Initialize a Project

vai init --yes

This creates a .vai.json file with sensible defaults (model, database, collection, chunking settings). Every command reads this file automatically, so you don't need to repeat flags.

Step 3: Embed a Document

vai embed "MongoDB Atlas provides fully managed cloud databases with built-in vector search."

You should see the embedding vector printed to the terminal, confirming the embedding path is working. To test local inference instead, run:

vai embed "MongoDB Atlas provides fully managed cloud databases with built-in vector search." --local

Step 4: Store and Search

# Store a few documents
vai store --text "MongoDB Atlas is a cloud database service" --db demo --collection docs
vai store --text "Vector search finds semantically similar documents" --db demo --collection docs
vai store --text "Embeddings convert text into numerical vectors" --db demo --collection docs

# Create a vector search index
vai index create --db demo --collection docs

# Search
vai search --query "cloud database" --db demo --collection docs

Step 5: Try the Full Pipeline

For a complete RAG experience with chunking and two-stage retrieval:

# Pipeline a directory of files
vai pipeline ./my-docs/ --db demo --collection knowledge --create-index

# Query with reranking
vai query "How does authentication work?" --db demo --collection knowledge

What's Next

• 5-Minute RAG Pipeline: Expanded tutorial with real documents
• Local Inference Guide: Learn how nano and the Python bridge work
• Configuration: All environment variables and options
• Command Reference: Browse the full CLI surface
• Chat: Talk to your knowledge base with an LLM