XERJ嵌入模式怎么选?lexical、neural与proxy三种模式深度对比指南
XERJ嵌入模式怎么选?lexical、neural与proxy三种模式深度对比指南
XERJ 是一款为 AI 数据检索而生的搜索引擎,通过 autoindex 一条命令即可把代码、文档、日志和 PDF 索引用起来。它的语义检索能力由嵌入(embedding)后端驱动,内置 lexical、neural、proxy 三种可互换的嵌入模式。本文帮你在 5 分钟内搞懂三者的原理、差异与切换方法,选对适合自己场景的那一种。
嵌入模式是什么:一个后端,三种实现
XERJ 的向量检索建立在 semantic_text 字段之上:写入时把文本转成向量,查询时把问题也转成向量,再做最近邻搜索。关键设计是——映射和 semantic 查询在三种模式下完全一致,你只需在服务器端决定"向量由谁生成"。
所有后端都收敛到一个统一的 Embedder 句柄,引擎的写入与查询路径从不针对具体后端分支,源码见 embedder.rs:
| 模式 | 一句话定位 | 依赖 |
|---|---|---|
lexical |
内置特征哈希,零配置的诚实默认 | 无,离线可用 |
neural |
内置 BERT 句向量模型,真语义 | 首次使用自动下载 ~90 MB 模型 |
proxy |
外接 OpenAI 兼容嵌入服务,自带模型 | 需配置 embedding.default_endpoint |
配置错误的处理策略也很友好:解析不了的模式会降级为 lexical 而不是崩溃,auto 则保留历史行为。
lexical:零配置的默认模式
lexical 是默认后端。它不是神经网络,而是一个**特征哈希(feature hashing)**嵌入器,实现只有百余行:单词 unigram 加权重 1.0、词内字符三元组加权重 0.35,经 FNV-1a 哈希落入 384 维桶,最后做 L2 归一化,代码见 local.rs。
它的强项:
- 🚀 零下载、零依赖、离线可用——没有任何外部服务,开箱即用;
- 🔁 完全确定性——同一输入在任何进程、任何重启后都产生逐位相同的向量(384 维特意对齐
all-MiniLM-L6-v2,方便日后无缝切换到同宽度的真实模型); - ✅ 向量空间被冻结——官方用黄金向量测试锁死词表,保证
autoindex跨重启续跑时不会混用两个向量空间。
它的边界(官方文档明确承认): 它捕捉的是词汇与子词重叠,不是深度语义。官方配方里有个经典反例:问 "how do I rotate my API key",文档标题是 "Rotating an API key",但正文从不出现 "rotate" 一词——lexical 模式会答错,把答案排到 "Rate limits" 之后。
neural:内置 BERT,真正读懂语义
neural 模式把语义做"真"了:内置 all-MiniLM-L6-v2(384 维 BERT 句向量编码器)通过 candle 在进程内推理——纯 Rust,无 Python,无外部服务,实现见 neural.rs。
- 📦 首次使用时自动下载约 90 MB 权重并缓存到磁盘,启动不减速(懒加载);
- 🏭 离线/气隙部署:把
embedding.local_model_dir指向预置的config.json/tokenizer.json/ 权重目录即可完全断网运行; - 🧠 上一节那个 "rotate" 问题,neural 模式直接命中正确文档——它理解 rotate ≈ regenerate ≈ replace,即使没有一个共享词。
代价也要心里有数(官方基准的实测数据):CPU 上神经索引用量约 3–7 文档/秒,5,183 篇摘要的 SciFact 数据集约需 25 分钟;带嵌入的查询 p50 约 220–370 ms(对比纯 BM25 的 ~18 ms)。大批量建索引请预留时间。
proxy:自带模型,接入任意嵌入服务
proxy 模式把嵌入工作委托给任意 OpenAI 兼容的 /v1/embeddings 端点——OpenAI、Cohere、本地 vLLM 或 Ollama 都行。配置客户端是异步 HTTP,自带令牌桶限速、指数退避重试与超时控制,实现见 embed.rs。
典型配置(节选自 xerj.default.toml):
[embedding]
default_endpoint = "http://localhost:11434/v1/embeddings" # 本地 Ollama
default_model = "nomic-embed-text"
batch_size = 64
timeout_ms = 5000
- 🔑 API Key 走环境变量
XERJ_EMBEDDING_API_KEY,不落配置文件; - 📌 嵌入发生在写入时(无持续重嵌入),所以换模型意味着重建索引;
- 完整示例工程见 xerj-proxy.toml。
注意数据边界:proxy 会把文档文本发送到端点,属于需要运营者显式配置才生效的外联功能。
如何切换嵌入模式:三种写法
三种配置方式,优先级从高到低:
# 1. 命令行参数(最高优先级)
xerj --insecure --data-dir ./data --embed-mode neural
# 2. 配置文件 xerj.toml
[embedding]
mode = "neural"
# 3. 环境变量
XERJ_EMBED_MODE=proxy
取值为 lexical、neural、proxy、auto(实验构建另有 onnx-experimental)。端到端演示脚本可参考 autoindex_semantic.sh:同一份 autoindex 流程和查询,仅靠这一个开关就在"词法检索"与"神经语义检索"之间切换。
选型建议:一张表看懂怎么选
| 你的场景 | 推荐模式 | 理由 |
|---|---|---|
| 快速验证、纯离线、无网络环境 | lexical |
零依赖零下载,确定性向量,足够支撑"共享词汇"类检索 |
| 需要真语义(同义词、改写问句),又不想引入外部服务 | neural |
内置 BERT 进程内推理,单二进制搞定,支持气隙部署 |
| 已有 OpenAI/Cohere/自建 vLLM 等嵌入服务,追求最强模型 | proxy |
自带模型,质量上限最高,批量+重试机制完善 |
| 生产环境想要最稳召回 | 任意模式 + hybrid 查询 |
BM25 + 向量 RRF 融合,是官方实测最强的检索形态 |
官方 BEIR 基准(nDCG@10,--embed-mode neural 节点)给出了量化的支撑:SciFact 上 BM25 为 0.6572,纯向量 semantic 达 0.6764,Hybrid RRF 最高 0.6993;NFCorpus 上 BM25 有 25 条查询零命中——这正是词法鸿沟(lexical gap),向量模式是唯一能救回的路径,详见 BEIR 基准说明 与 lexical_gap.py。
实用结论: 新手先用默认的 lexical 跑通全流程;一旦遇到"换了个词就搜不到"的情况,加上 --embed-mode neural 一个开关即可升级到真语义——映射、索引、查询代码一个字都不用改。
延伸阅读
- 向量与 kNN 完整参考:vectors.html
- 语义检索与 RAG 端到端配方:semantic-search-rag.html
- 可运行的 RAG 演示脚本:rag_demo.py
- 外部嵌入服务接入示例:external-embeddings
<output_article>


