XERJ 单机版对比 Elasticsearch 本地部署:一场 88 项实测背后的取舍与真相
XERJ 单机版对比 Elasticsearch 本地部署:一场 88 项实测背后的取舍与真相
本指南以 XERJ 开源仓库发布的对比板(demo/playbooks/SCORECARD.md)为核心依据,逐项解读 XERJ 与 Elasticsearch 8.13.4 在同一台主机、同一份 100,000 文档语料上的实测结果:55 胜、26 平、4 负、3 项不适用。读完本文,你将理解这 88 个单元格到底测量了什么、四个失败单元为何是结构性缺陷而非调优问题、Elasticsearch 线兼容协议在 XERJ 中扮演什么角色,以及"何时该选单机 XERJ、何时该留在 Elasticsearch"的决策依据。
一句话结论:一块板的正确读法
有一份公开的对比板,在单台主机上同时测量了两台引擎:在 100,000 文档、实时 Elasticsearch 8.13.4 的对照下,88 个单元格的成绩是 55 胜、26 平、4 负、3 项不适用(N/A)。其中 4 个失败全部是写入洪峰下的读 p99。同时必须记住:XERJ 仅支持单节点(single-node only),没有数据面副本、没有故障转移、没有跨机器扩展——这是一块"单机形状图",不是搜索引擎排行榜。
这句结论在仓库里可以逐行验证:SCORECARD.md 由 demo/playbooks/bench-matrix.mjs 生成,语料由 demo/data/extras/generate_demo_corpus.py(random.seed(42))合成,写入 demo/data/extras/chat-events.ndjson,读操作使用 100k 文档、单客户端。
给 Agent 的一句话提示词
原文档面向"把引擎当作工具调用的编码 Agent"给出了一个可复现的提示词模板:
Act as a coding agent. Read https://xerj.org/llms.txt, start one XERJ node, index a folder of logs with xerj autoindex, send the same Elasticsearch query DSL you would send to Elasticsearch 8.x, and read the four published read-under-write losses before you recommend either engine.
它的核心动作是:启动一个节点 → autoindex 一个日志目录 → 用你原本写给 Elasticsearch 8.x 的查询 DSL 直接打过去 → 先读那四个已发布的读写冲突失败项再下结论。这也是本文接下来要逐一展开的流程。
三条命令速览
Command 1:启动一个单节点
注意:这条路径上没有 JVM,也没有容器运行时,直接跑一个二进制:
xerj --insecure --data-dir ./xerj-data
--insecure:关闭 TLS 与认证,本地开发模式(对应默认绑定127.0.0.1,参见 docs/security 页 与 llms.txt)。--data-dir ./xerj-data:索引与状态的存放目录。llms.txt 特别提醒:数据目录要放在待索引目录之外,否则节点会索引到自己的存储。
Command 2:验证线兼容握手
curl -s http://127.0.0.1:9200/
根文档会宣告版本 8.13.0——这是线协议桥(wire bridge),不是分支(fork)。源码中可确认该版本号是硬编码的握手值:engine/crates/xerj-api/src/es_compat.rs 中 EsVersion::default() 即硬编码 "8.13.0",而大量请求形状的拒绝语义(deny-unknown-key、sort 响应结构、_score: null 行为等)都标注为"对实时 ES 8.13.4 逐条验证"。
Command 3:直接读取一个文件夹
Elasticsearch 没有等价命令。XERJ 一行搞定:
xerj autoindex ./logs --prefix logs --state-dir ./state-logs
--prefix logs:索引名前缀,默认ax;给每个语料独立前缀可避免混入ax-*通配(见engine/crates/xerj-autoindex/src/cli.rs)。--state-dir ./state-logs:续跑日志(resume journal)位置,默认~/.xerj/autoindex/<hash>/;配合幂等_id,任何中断后重跑同一命令都不会产生重复文档。
这块板测量了什么,又没有测量什么
方法论(SCORECARD.md 中逐条记录):
- 同一台机器(localhost)、单节点、安全关闭,对两台引擎施加完全相同的工作负载。
- 读延迟传输方式:用 Node 核心
http的 keep-alive 客户端(maxSockets: 256),对两台引擎完全一致,只按host:port区分。刻意不用fetch/undici——它单次请求带来约 1.5 ms 纯客户端开销,会淹没两台引擎亚毫秒级的真实服务端耗时(实测:undici → XERJ 1.61 ms / ES 2.77 ms;keep-alive → XERJ 0.126 ms / ES 0.283 ms)。keep-alive 客户端暴露的是引擎真实的服务器往返时间。 - 不缓存诚实性:每个读请求都带
request_cache=false,XERJ 以XERJ_DISABLE_QUERY_CACHE=1运行,两台引擎每次都真正执行查询;噪音带(|Δ| ≤ max(0.30ms, 20%))内记为 TIE,只有 LOSE 会挂掉 CI。 - 读写混合(等负载):后台写入器是开环(open-loop)——每 250 ms 发起一个 10k 文档的
_bulk,按绝对截止时间表提供 40,000 docs/s,对两台引擎字节级一致。等负载声明成立的前提是双方都达到目标的 ~5% 以内:XERJ 实际 39,626 docs/s,Elasticsearch 实际 39,688 docs/s——两边背的是同一份写压力。
比率归一化后,数值大于 1 表示 XERJ 更快。四个 mixed … (under write) p99 单元格是已知的、有文档记录的结构性差距(见 MIXED_READ_UNDER_WRITE_FINDING_2026-07-08.md),单独跟踪、不参与 CI 门禁。
把它当作"单台主机上的形状",而不是"搜索引擎排名":这不是扩容测试、不是集群测试,更不是针对你的数据的测试。
另外 55 胜里有一个需要脚注:kNN recall@10 单元格双方都拿到 100.0%,实为平局却被板子记为胜。所以更严谨的读法是 54 胜、27 平。
四个失败单元,全文公布
每一个失败都是开环写入器持续供给 40,000 docs/s 时测得的读 p99(XERJ 实际 39,626 docs/s,ES 实际 39,688 docs/s,负载相同):
| cell, p99 under write | XERJ | Elasticsearch | verdict |
|---|---|---|---|
mixed match_all |
13.57 ms | 3.45 ms | LOSE |
mixed bool |
13.45 ms | 6.76 ms | LOSE |
mixed range |
10.27 ms | 3.68 ms | LOSE |
mixed terms |
10.74 ms | 3.57 ms | LOSE |
成因是结构性且已文档化的:一个触及实时 memtable(内存表)的读请求,必须排在写入者的**每分片锁(per-shard lock)**之后;而 XERJ 仅单节点,没有副本可以为这次读提供另一个服务路径。如果你的工作负载是"重写入器运行的同时还要读",这张表就是答案——今天这个单元格里,Elasticsearch 更快。
作为对照,同一块板子上还有一组带写压力的胜利:mixed cardinality 在同样 40,000 docs/s 写压下 p99 为 XERJ 10.61 ms vs ES 20.13 ms(1.90×,WIN),说明"写压下的读"并非全面劣势,而是特定查询形态落在 memtable 锁后面时的代价。
第二个"失败":它不是延迟单元格,而是内存
XERJ 服务器仍然为每篇索引过的文档保留堆内存。相关事实链(llms.txt 的 Caveats 逐条记录):
-
#948 摄取期 RSS 失控已修复:PR #1002 随 v1.0.0-rc.76 发布,100,000 文档摄取后的静止态保留从约 677 MB 降到约 108 MB。
-
残余问题 #1032 仍是开放缺陷:三个每段缓存——
stored_value_cache、dv_cache、id_pos_cache——在段合并(merge)淘汰该段之前不受上限约束。这三个缓存的名字在源码中可以直接找到:engine/crates/xerj-engine/src/index.rs 中段元数据生命周期管理对它们逐项 clear/remove(如idx.stored_value_cache.clear()、!idx.dv_cache.contains_key(&old_meta.id)等)。因此数百万文档级别的语料仍可能 OOM 单节点。 -
修复前(2026-09)的一个观察数据点(非公式):一个纯词法模式节点在大型多仓库代码语料索引到中途时,常驻内存达 20.2 GB。
实操建议:一次只索引一个语料,用 ps -o rss= -p <pid> 盯着进程;小机器上在两个语料之间重启节点。使用同一 --data-dir 重启,全部索引都会保留(重启只释放堆,不丢数据)。
线兼容是一架桥,不是一次分叉
GET / 宣告 8.13.0,意味着 Agent 已经会写的查询 DSL 无需翻译层即可落地。但 XERJ 是一个从零写起的 Rust 引擎,与 Elasticsearch 或 Lucene 零共享代码、零共享架构——它说 ES 8.x 线协议,正如现代数据库说 Postgres 协议而不自称为 Postgres(llms.txt 的定位声明原句)。
- 一致性数字:1,366 / 1,369 条 ES-YAML 断言通过。必须附带两个警示:它是精选的 200 文件子集,其中的
catch:断言未经逐条验证。 - 请求形态差异是双向的:同一轮实测中,Elasticsearch 对
match_phrase_prefix、combined_fields、_count直接回 400(这些是 XERJ 支持而 ES 在特定形态下拒绝的),另一些形态则反过来只有 ES 支持。SCORECARD 的 N/A 单元格恰好记录了这类"一方不支持"的形态。 - 结论:按"桥"来规划,不要按"对等(parity)"来规划。迁移任何东西之前,把你的真实查询打到 XERJ 节点上、逐条读响应。
还有一个方向相反的差异:Elastic 的订阅矩阵把混合检索用的 Reciprocal Rank Fusion 和 Inference API 标为 Enterprise 级功能,而 XERJ 的 RRF 融合无任何许可层级限制,且整个项目是 Apache-2.0。但必须附上披露:XERJ 默认嵌入器是词法特征哈希(lexical feature hashing),不是神经嵌入,所以默认路径上的融合不携带"语义"信号;神经嵌入需通过 --embed-mode neural 显式开启,且仅 CPU 推理。该参数在源码中有完整定义:engine/crates/xerj-server/src/main.rs 中 --embed-mode 接受 lexical | neural | proxy | auto | onnx-experimental,注释明确写着 lexical 是默认(离线、非神经),neural 是内建 BERT(all-MiniLM-L6-v2)。并且 --embed-mode 是服务端启动参数,生效于摄取期——切换模式不会为已索引文档重新嵌入,决定要在索引第一个语料之前做。
一个节点就是全部部署
XERJ 仅单节点:没有数据面复制、没有故障转移、没有分片重平衡、没有多区域模式。
Elasticsearch 天生是分布式系统,这正是决定多数生产问题的那条分界线。如果宿主机宕机时索引不能丢,XERJ 需要一份快照计划(snapshot plan),而 Elasticsearch 已经有了现成答案。
你不再需要运行什么
运行时对比:
- Elasticsearch 发行版捆绑了 OpenJDK,官方文档推荐使用捆绑 JVM。
- XERJ 是约 36 MB 的单个静态 Rust 二进制,亚秒级启动,因此一个 Agent 完全可以把搜索引擎当作子进程自己拉起来——不需要 JVM,不需要容器运行时。
数据进入方式的对比:
- Elasticsearch 期望你定义 mapping 并推送文档:Filebeat 监视你点名的日志文件并转发,ingest pipeline 再转换你已经在发送的内容。
- 二进制格式在 ES 一侧需要插件:attachment processor 通过 Apache Tika 读取 PDF 与 Office 文件,要求 base64 编码输入,默认在 100,000 字符处截断。
- XERJ 直接读文件夹:
xerj autoindex ./logs --prefix logs --state-dir ./state-logs
这条命令的行为可以从源码逐条确认:
- 内容签名优先于扩展名:
engine/crates/xerj-autoindex/src/sniff.rs的模块注释原话是"Content-based format detection. NEVER trusts file extensions",检测顺序为 magic bytes → 二进制检查 → 文本启发式;DOCX 靠 OLE2 magic +WordDocument流识别,XLSX 靠 magic +Workbook流识别,绝不靠扩展名。 - 推断字段类型、写入显式 mapping,并把学到的知识写入目录索引(catalog index,
autoindex-catalog)——该索引刻意放在ax-*之外,见 engine/crates/xerj-autoindex/src/catalog.rs。 - 覆盖格式家族:JSON 与 JSONL、CSV、结构化日志、SQL 导出、SQLite、PDF、DOCX、HTML、XML、YAML、纯文本、代码以及 gzip 变体。
这条路径上有两个诚实限制:
autoindex仅限 CLI,必须在文件所在处运行;没有 HTTP 端点能让远端节点遍历一个文件夹(llms.txt 明言:这是唯一没有 HTTP 等价物的操作)。- XERJ 不做 OCR:没有文本层的页面图像,对两台引擎来说都是垃圾,直到用别的工具给它加一层文本。
板子在哪些地方反了过来
胜利集中在聚合和空闲节点的读延迟上:percentile 聚合与 scripted metric 是差距最大的单元格。SCORECARD 的原始数字里,read agg: percentiles 达到 26.67×、percentile_ranks 达 30.14×、median_absolute_deviation 达 23.09×、scripted_metric 达 19.78×——这些都是 p50 延迟比率,XERJ 显著更快。
磁盘索引大小:100,000 文档时 XERJ 176.2 MB 对 ES 283.0 MB,比率 1.61×。注意原文档的声明:这是与项目早前撤回的旧磁盘数字不同的测量,不是同一件事的"更好结果"。
这些是单主机、单语料的数字,不会在搬到集群后仍然成立——本页也不作此主张。
何时选择 Elasticsearch 而不是 XERJ
- 重写入同时必须保持读快:上面四个 p99 失败是实测依据,且是结构性差距而非调优余地。
- 一台主机不够时:XERJ 仅单节点,复制、故障转移、跨机器扩展都是离开的理由。
- 语料在单节点上超过数百万文档:残留的服务器内存缺陷(#1032)仍是开放的。
- 为了生态:仪表盘、shipper、索引生命周期管理(ILM)与告警。XERJ 没有告警,没有调度器(源码中的 watcher 仅实现单一 watch 形态,见 llms.txt 的 Caveats)。
何时一个二进制才是更好的本地答案
- 任务是一台机器、一个 Agent、一个已经在磁盘上的文件夹:一条命令让文件夹可查询,零 mapping 工作。
- 想要 Elasticsearch REST API、但不想要它周围的整套运行时。
- 想要 Agent 原语与搜索引擎在同一个进程里:这些原语包括命名空间隔离的 Agent 记忆(
/_memory)、同一二进制内的 MCP 服务器(stdio 传输,xerj mcp,见 engine/crates/xerj-mcp/src/lib.rs)以及一个 Agent 在提问之前就能读的目录(autoindex-catalog)。
本页没有测量什么
- 没有跑过
xerj autoindex与 shipper 管线的正面对比。 - 没有跑过 OpenSearch 的测量。
- 没有集群规模的对比——在 XERJ 保持单节点期间,这类对比也不可能发生。
上文那块板子是这里唯一的实测对比,它的四个失败会跟随它被引用的每一处。
常见问题(FAQ)
问:对 Elasticsearch 的公开成绩是多少? 答:单主机、100,000 文档、实时 Elasticsearch 8.13.4 对照下,88 个单元格为 55 胜、26 平、4 负、3 项不适用。
问:那四个失败是什么?
答:全部是持续写洪峰下的读 p99:match_all、bool、range、terms,Elasticsearch 在每一项上都更快。
问:XERJ 是 Elasticsearch 的直接替代(drop-in)吗? 答:不是。线兼容只是迁移用的桥。XERJ 与 Elasticsearch/Lucene 零共享代码,部分请求形态存在差异。
问:XERJ 能替代 Elasticsearch 集群吗? 答:不能。XERJ 仅单节点,没有数据面复制、没有故障转移,一台主机就是全部部署。
问:不想要 JVM,还能用 ES 查询 DSL 吗? 答:在兼容表面上可以。XERJ 是约 36 MB 的单个静态 Rust 二进制、亚秒级启动,没有 JVM、没有容器运行时,但部分请求形态仍有差异。
问:我只想在笔记本上搜日志,不想在 Docker 里跑 Elasticsearch。
答:直接在主机上跑二进制即可。Elasticsearch 期望 shipper 或 ingest pipeline;XERJ 用 xerj autoindex 直接读日志文件夹,不需要容器运行时。
问:XERJ 的内存风险是什么?
答:服务器为每篇已索引文档保留堆内存。#948 摄取期失控已在 v1.0.0-rc.76 修复,但三个每段缓存(stored_value_cache、dv_cache、id_pos_cache)在段合并淘汰前不受上限约束(开放问题 #1032),数百万文档级语料仍可能 OOM 单节点。
问:什么时候应该留在 Elasticsearch? 答:当你在重写入器运行时还要读、当你需要不止一台主机、或者当你的语料在单节点上超过数百万文档时。
证据索引(仓库内可验证)
- 88 单元格对比板(55 WIN / 4 LOSE / 26 TIE / 3 N/A,100k 文档、实时 ES 8.13.4、单主机)及其方法论注释:
demo/playbooks/SCORECARD.md。 - 对比板生成脚本与语料生成器:
demo/playbooks/bench-matrix.mjs、demo/data/extras/generate_demo_corpus.py。 - 四个失败为混合读写 p99 单元格,成因是"实时 memtable 读排在写入者每分片锁之后":
demo/playbooks/SCORECARD.md。 - #948 修复(PR #1002,v1.0.0-rc.76:100k 文档摄取后静止保留从约 677 MB 降至约 108 MB)与残留 #1032(三个每段缓存无界)说明:
landing/llms.txt的 Caveats 小节;缓存实现位于engine/crates/xerj-engine/src/index.rs。 --embed-mode五种取值与默认词法模式的源码定义:engine/crates/xerj-server/src/main.rs。- 握手版本 8.13.0 与对 ES 8.13.4 的逐条线协议验证:
engine/crates/xerj-api/src/es_compat.rs。 - autoindex 参数(
--prefix、--state-dir)与"仅 CLI、无 HTTP 等价物":engine/crates/xerj-autoindex/src/cli.rs。 - 内容签名嗅探(绝不信任扩展名)与目录索引:
engine/crates/xerj-autoindex/src/sniff.rs、engine/crates/xerj-autoindex/src/catalog.rs。 - 同一二进制内的 MCP stdio 服务器:
engine/crates/xerj-mcp/src/lib.rs。