Embedding Models
Compare every supported local and remote model, then choose a practical starting point.
The embedding model affects language coverage, memory use, input length, indexing speed, and semantic quality.
Recommended Starting Point
Start with the built-in default:
zg --indexZvec-Grep uses local/potion-code-16m-v2 when no model is configured. Change it only when the workspace needs different language coverage, input length, or retrieval quality.
Configure Local Models
Defaults and overrides
For a new index, --embedding takes priority over ZVEC_GREP_EMBEDDING, then the configured global default. These are independent options:
# Select the model stored in this workspace's index
zg --index --embedding local/potion-multilingual-128m
# Set the default for future indexes
zg --config model set local/potion-multilingual-128m --default
# Override the default for this process
ZVEC_GREP_EMBEDDING=local/potion-retrieval-32m zg --indexSupported local models
| Model | Best for | Runtime |
|---|---|---|
local/potion-code-16m-v2 | Fast first index for code | Model2Vec FP16 |
local/potion-retrieval-32m | English documents | Model2Vec FP32 |
local/potion-multilingual-128m | Multilingual documents | Model2Vec FP32 |
local/all-minilm-l6-v2 | Short English text | ONNX Q4 |
local/bge-small-en-v1.5 | English passages | ONNX Q4 |
local/multilingual-e5-small | Compact multilingual retrieval | ONNX Q8 |
local/jina-embeddings-v2-base-code | Long-context multilingual code | ONNX Q8 |
local/gte-modernbert-base | Long English documents | ONNX Q4 |
local/nomic-embed-text-v1.5 | Long English documents and queries | ONNX Q4 |
local/embeddinggemma-300m | Multilingual code and documents | GGUF Q8_0 |
local/qwen3-embedding-0.6b | Higher-capacity multilingual retrieval | GGUF Q8_0 |
Device and cache
Device support depends on the model backend, platform, and installed runtime:
- Potion models run on CPU.
- GGUF models support CPU, Metal on macOS, and CUDA on supported Linux/Windows x64 installations.
- ONNX models use CPU on macOS, including when
metalis requested. CUDA requires the matching runtime on Linux/Windows x64; compatible Windows runtimes can also use DirectML. - Vulkan requires a custom build/runtime and is not included in the published packages.
zg --index --embedding local/jina-embeddings-v2-base-code --device auto
zg --config model set local/jina-embeddings-v2-base-code --device cpuUse ZVEC_GREP_DEVICE for a process-level override. Models are cached in ~/.zvec-grep/models by default; change it with --model-cache or ZVEC_GREP_MODEL_CACHE.
Explicit --device and --model-cache options on zg --index are saved for the workspace. The same options on a search apply only to that query and its refresh.
Change a local model
Existing indexes keep their stored model. Rebuild to change it; changing only the device does not require a rebuild.
zg --index --rebuild --embedding local/potion-multilingual-128mConfigure Remote Models
Remote models avoid local inference but send authorized workspace content and queries to the configured provider.
Supported remote models
| Model | Best for |
|---|---|
qwen/text-embedding-v4 | Managed text retrieval |
qwen/qwen3.7-text-embedding | Very long text inputs |
qwen/qwen3-vl-embedding | Text retrieval through the multimodal endpoint |
Zvec-Grep currently indexes text only, including when the selected model also supports images.
Configure the provider
zg --config provider set qwen --api-key "$DASHSCOPE_API_KEY"
zg --config model set qwen/text-embedding-v4 --defaultAuthorize remote access
Provider credentials enable access but do not authorize data transfer. Use --allow-remote once, or grant access for the current workspace:
zg --index --embedding qwen/text-embedding-v4 --allow-remote
zg --auth grant --capability embedding --scope workspace \
--embedding qwen/text-embedding-v4Use zg --auth status to inspect grants and zg --auth revoke to remove them.
Change remote configuration
Changing the model or endpoint requires a rebuild. Changing only the API key does not.