vai explain

Learn about embeddings, local inference, reranking, RAG, vector search, and more. Covers 30+ topics with explanations, key points, try-it commands, and links to further reading.

CLI

Synopsis

vai explain [topic]

Description

vai explain is an interactive learning tool built into vai. Run it without arguments to see all available topics, or pass a topic name to get a detailed explanation.

Each explanation includes:

• Clear, formatted content explaining the concept
• Practical "Try it" commands you can run immediately
• Links to official documentation

Topic names support fuzzy matching, so you don't need to type the exact key.

Options

Flag	Description	Default
[topic]	Topic to explain (optional, lists all if omitted)	—
--json	Machine-readable JSON output	—

Examples

List all topics

vai explain

Learn about embeddings

vai explain embeddings

Learn about reranking

vai explain reranking

Learn about shared embedding spaces

vai explain shared-space

Learn about nano and local inference

vai explain nano

JSON output

vai explain embeddings --json

Playground

Learning in the Playground

The vai playground integrates learning content throughout the interface with contextual help and tooltips.

Contextual Help

Each tab in the playground includes inline guidance:

Embed tab: Explains input types, dimensions, and model selection with tooltips on each option.

Search tab: Describes how $vectorSearch works, what numCandidates means, and how filters are applied.

Rerank tab: Explains the difference between embedding-based similarity and cross-attention reranking.

Similarity tab: Describes cosine similarity and what the scores mean.

Explore Topics

For deep dives into specific concepts, use the CLI:

vai explain embeddings
vai explain reranking
vai explain shared-space
vai explain rag

The playground complements the explain command by letting you immediately try concepts hands-on. Read about embeddings, then switch to the Embed tab and generate one.

Available Topics

Topics include (non-exhaustive):

• embeddings — What are vector embeddings?
• reranking — Two-stage retrieval with rerankers
• shared-space — Asymmetric retrieval across Voyage 4 models
• nano — Local inference, the Python bridge, and the local-to-API workflow
• cosine-similarity — How similarity scoring works
• input-types — Query vs. document input types
• quantization — Reducing embedding size with int8/binary
• rag — Retrieval-augmented generation
• vector-search — How ANN search works
• moe — Mixture of Experts architecture
• matryoshka — Flexible dimensions via Matryoshka learning
• chunking — Document chunking strategies
• two-stage — The two-stage retrieval pattern

Run vai explain to see the full list with summaries.

Related Commands

• vai models — See available models
• vai demo — Interactive walkthrough of vai features
• Local Inference Guide — Understand nano, shared space, and setup flow