Embedding 模型
对比全部受支持的本地与远程模型，再选择合适的起点。
Embedding 模型会影响语言覆盖、内存、输入长度、索引速度与语义质量。
建议起点
直接使用内置默认模型：
zg --index未配置模型时，Zvec-Grep 使用 local/potion-code-16m-v2。仅当工作区对语言覆盖、输入长度或检索质量有不同要求时再更换模型。
配置本地模型
默认值与覆盖
新索引依次读取 --embedding、ZVEC_GREP_EMBEDDING 和全局默认配置。以下是三种相互独立的用法：
# 选择并保存此工作区索引使用的模型
zg --index --embedding local/potion-multilingual-128m
# 设置后续新索引的全局默认模型
zg --config model set local/potion-multilingual-128m --default
# 仅覆盖当前进程的默认模型
ZVEC_GREP_EMBEDDING=local/potion-retrieval-32m zg --index支持的本地模型
| 模型 | 适用场景 | 运行时 |
|---|---|---|
local/potion-code-16m-v2 | 快速建立代码索引 | Model2Vec FP16 |
local/potion-retrieval-32m | 英文文档 | Model2Vec FP32 |
local/potion-multilingual-128m | 多语言文档 | Model2Vec FP32 |
local/all-minilm-l6-v2 | 较短的英文文本 | ONNX Q4 |
local/bge-small-en-v1.5 | 英文段落 | ONNX Q4 |
local/multilingual-e5-small | 轻量多语言检索 | ONNX Q8 |
local/jina-embeddings-v2-base-code | 长上下文、多语言代码 | ONNX Q8 |
local/gte-modernbert-base | 较长的英文文档 | ONNX Q4 |
local/nomic-embed-text-v1.5 | 较长的英文文档与查询 | ONNX Q4 |
local/embeddinggemma-300m | 多语言代码与文档 | GGUF Q8_0 |
local/qwen3-embedding-0.6b | 更高容量的多语言检索 | GGUF Q8_0 |
设备与缓存
设备支持取决于模型后端、平台和已安装的运行时：
- Potion 模型使用 CPU。
- GGUF 模型支持 CPU、macOS 上的 Metal，以及受支持的 Linux/Windows x64 安装中的 CUDA。
- ONNX 模型在 macOS 上使用 CPU，包括显式指定
metal的情况。Linux/Windows x64 的 CUDA 需要匹配的运行时；兼容的 Windows 运行时也可以使用 DirectML。 - Vulkan 需要自定义构建或运行时，发布的安装包不包含该支持。
zg --index --embedding local/jina-embeddings-v2-base-code --device auto
zg --config model set local/jina-embeddings-v2-base-code --device cpu可通过 ZVEC_GREP_DEVICE 临时覆盖设备。本地模型默认缓存在 ~/.zvec-grep/models，可通过 --model-cache 或 ZVEC_GREP_MODEL_CACHE 修改。
zg --index 显式传入的 --device 和 --model-cache 会保存到工作区；搜索时传入这些参数则只影响本次查询及其刷新。
更换本地模型
已有索引沿用建索引时保存的模型。更换模型需要重建，仅更换设备则不需要。
zg --index --rebuild --embedding local/potion-multilingual-128m配置远程模型
远程模型无需本地推理，但会将已授权的工作区内容和查询发送给所配置的提供方。
支持的远程模型
| 模型 | 适用场景 |
|---|---|
qwen/text-embedding-v4 | 托管文本检索 |
qwen/qwen3.7-text-embedding | 超长文本输入 |
qwen/qwen3-vl-embedding | 通过多模态接口进行文本检索 |
Zvec-Grep 当前只索引文本，即使所选模型本身支持图片也是如此。
配置 Provider
zg --config provider set qwen --api-key "$DASHSCOPE_API_KEY"
zg --config model set qwen/text-embedding-v4 --default授权远程访问
Provider 凭据只用于访问服务，不等于允许传输数据。可以只授权一次命令，或为当前工作区持续授权：
zg --index --embedding qwen/text-embedding-v4 --allow-remote
zg --auth grant --capability embedding --scope workspace \
--embedding qwen/text-embedding-v4使用 zg --auth status 查看授权，使用 zg --auth revoke 撤销授权。
更换远程配置
更换模型或 Endpoint 需要重建索引，仅更换 API Key 则不需要。