★ FEATURED ARTICLE 【免费下载链接】xerjXERJ is the new way for AI to search data. Its autoindex capability activates agents to know your data without the token waste of grep and sed. One command indexes code, docs, logs and PDFs for search, RAG, security audits and agent memory, using 40x fewer tokens than grep. Elasticsearch compatible, so existing clients just work.项目地址https://gitcode.com/GitHub_Trending/xe/xerj点击查看免费下载导读本文以 XERJ 的xerj autoindex为工具讲解如何把一份大型 OpenAPI 规范JSON 与 YAML 两种序列化连同 SDK Markdown 一起变成 Agent 可查询的本地索引并深入源码说明为什么 XERJ 的提取是格式驱动而非规范感知spec-aware、命中文档上的ax_*溯源字段如何定位原文位置以及在使用聚合统计路由数量时为何必须先读 hits 再信 bucket。读完你将获得一套可复制的命令序列让你的编码 Agent 在一两条查询内查出路由名、操作描述与 operationId而不是把整个 spec 塞进上下文。为什么查 spec的正确姿势是索引文件本身编码 Agent 面对一份几百 KB 的 OpenAPI 文档时最常见也最浪费的做法是把整个文件读进上下文、再用 grep 或正则手工翻找路由。XERJ 提供的替代路径是把 spec 当作磁盘上的普通文件交给 autoindex让全文检索替你定位再由 Agent 自己解析命中文档中的参数结构。XERJ 官方 FAQ 对此给出的结论非常直接把 spec 放到磁盘上对其所在文件夹运行xerj autoindex然后让 Agent 对body字段发一个match查询即可——一次捕获运行里路由名、操作描述和 operationId 都只需 1 条命令就变得可查询。这套思路也回答了另一个实际问题spec 和 SDK 文档如何一起搜。把二者放在同一个文件夹里、索引一次spec 与 SDK Markdown 会在同一次运行中成为同一批文档一个索引模式就能同时覆盖两者每条命中都携带ax_path文件相对路径与ax_format文件格式族Agent 可以凭此直接区分这条描述来自 spec 的 YAML 版还是来自 SDK 的 Markdown。第一步把 spec 文件夹变成索引索引命令与参数解读核心命令只有一条从 关联文档 原样继承xerj autoindex ./api-specs --url http://127.0.0.1:9200 --prefix oa --progress plain各参数的实际语义可以直接在 xerj-autoindex 的 CLI 帮助文本 中核实--url UES 兼容端点默认http://localhost:9200。从源码看xerj autoindex只从--url取端点不读XERJ_URL环境变量这是刻意设计——写入操作不能被一个过期的环境变量悄悄重定向若设置了XERJ_URL但未传--url运行时会打印一条安全提示见xerj_url_ignored_note的实现。--prefix P索引前缀默认ax。这里用oa后续所有索引名以oa-开头例如oa-docs、oa-logs。--progress MODEstderr 上的 liveness 输出auto|plain|json|none默认auto。plain在非终端环境CI、管道、Agent 驱动下强制输出可解析的进度行这正是文档命令选择它的原因每行以xerj-bar给人看与xerj-progress给机器解析两个 token 区分。其他与本场景相关的默认值--bulk-mb默认 8bulk 切割大小 1..24、--workers默认按核心数、--max-minutes默认 10超时触发决策门进程以退出码 4 请求--approve proceed|fast|cancel。捕获运行的实际结果文档记录的捕获运行读入2 个文件、产出 1 个数据集、oa-docs下存活 4 条文档、0 个 junk 文件。这 2 个文件本质上是同一份合法 OpenAPI 3.0.3 文档的两种序列化——一次写成.json、一次写成.yaml由 fixture 生成器产出。也就是说一次索引同时覆盖了 JSON 与 YAML 两种写法Agent 不必关心 spec 以哪种格式分发。源码视角文件如何被路由到对应的提取器JSON 走 JSON 族、YAML 走 YAML 族并非文档口号而是 sniff.rs 中明确的格式分派逻辑Family::Jsonl / Json / … / Yaml / UnityYaml各司其职.json与.yaml分别落到 JSON 提取器 与 YAML 提取器。从实现细节看两种提取器都是整体值路线JSON 族整文件上限 64 MBYAML 族 16 MBYAML 提取器还支持多文档流---分隔的每个文档各成一条记录。这正是把 spec 当作结构数据、按自身格式处理的底层依据。两种序列化回答同一查询命中表与 curl 实战同一文本两条命中靠ax_format区分下列每个查询都只对/oa-*/_search运行一次却返回每个序列化 1 条命中共 2 条命中上的ax_format字段直接告诉你匹配的是哪份文件查询命中数返回的格式matchonbody查quokka-orders2json和yamlmatch_phraseonbody查Retrieve quokka orders by region2json和yamlmatchonbody查getOrderCheckpointJournal2json和yaml可复制的最小查询模板查路由名quokka-orderscurl -s -XPOST http://127.0.0.1:9200/oa-*/_search \ -H content-type: application/json \ -d {query:{match:{body:quokka-orders}},size:10,_source:[ax_path,ax_format,ax_locator],track_total_hits:true}查操作描述spec 的 summary 里写的整句描述curl -s -XPOST http://127.0.0.1:9200/oa-*/_search \ -H content-type: application/json \ -d {query:{match_phrase:{body:Retrieve quokka orders by region}},size:10,_source:[ax_path,ax_format,ax_locator],track_total_hits:true}两个查询都刻意只取ax_path、ax_format、ax_locator三个溯源字段命中之后Agent 拿到的是这份 spec 的相对路径 格式 文档内定位符再决定是否自己打开文件解析参数类型、请求体和响应 schema。文档同时提醒只有当你确实需要两种写法时才保留两份文件否则单文件查询对同一文本只返回 1 条命中。索引模式与查询端点的来源查询走的是 ES 兼容的POST /{index}/_search端点这在 esclient.rs 中直接可查search_raw对/…/_search发 POST。通配索引oa-*之所以能覆盖所有数据集是因为--prefix oa让 autoindex 写出的索引统一以oa-开头。提取是格式驱动的不是 spec-aware 的mapping 实证一份 spec 只产生 body 和 title这是本文最重要的一个技术事实。文档明确记录整份 OpenAPI 文档最终只产生两个内容字段——body和title映射中其余字段全部是 XERJ 的溯源provenance字段ax_dataset、ax_file、ax_format、ax_locator、ax_path、ax_paths、ax_run这份字段清单与 lib.rs 中的PROVENANCE_FIELDS常量 完全一致。也就是说没有paths字段、没有operationId字段、没有每个 operation 一条文档路由名之所以能命中是因为该字符串就在文档文本里而不是因为 XERJ 建模了路由对象因此对XERJ 是否把 OpenAPI 当规范解析这一问题的官方回答是明确的Nopath是文本不是类型化的路由对象。底层原理flatten 与保真策略从源码看这种格式驱动来自 JSON/YAML 提取器的通用处理管线flatten_object 会把嵌套对象压平成a_b_c键超过两层的结构与对象数组以 JSON 字符串原样存储标量数组保持数组。同时有一个值得注意的细节数据字段若以ax_开头会被改名为data_ax_*以避免与溯源命名空间冲突——所以 spec 里若真有ax_开头的业务字段不会污染 provenance 字段。body与title则由 extractor 统一产出这就是为什么 JSON 版和 YAML 版最终落到同构的文档形态。对 Agent 工作流的直接建议规划时要围绕这一点用 XERJ 负责找到文档与位置用 Agent 自己负责解析参数结构。查询命中后Agent 打开ax_path指向的 spec 文件在paths节中定位对应路由读取parameters、requestBody、responses中的类型信息。需要类型化路由的话独立的 OpenAPI 解析器仍然是必需的——XERJ 不替代它。聚合的坑先读 hits再信 bucket文档专门用一小节警告一个反直觉现象当你在 spec 文档上做 terms 聚合时bucket 数并不总能与同一条查询返回的 hits 对齐——terms 聚合不会可靠地限定在它同行的全文查询范围内。捕获到的单索引矩阵让风险变得具体查询类型匹配文档数聚合 bucket 数match_all674331exists315315term630315match_phrase110match1174典型如match_phrase匹配 11 条文档、其 terms 聚合却返回 0 个 bucketmatch匹配 11 条、聚合却给出 74 个 bucket。文档同时强调这不是一条普适规律——第二次捕获中曾出现过聚合与 hits 完全一致的情况。结论是可操作的发布数字时以 hits 为准不要只汇报 bucket。边界与限制这次捕获没有覆盖什么原文档对证据边界交代得非常克制这些限制应原样继承到你的预期里本次 spec 来自 fixture 生成器不是厂商或线上 API没有 API 服务器运行XERJ 也没有从网络抓取任何东西。XERJ 没有$ref解析器也没有 schema 校验器。带$ref引用的复杂 spec 会被当作普通文本索引解析引用是 Agent 或外部工具的事。本次为单节点运行无副本、无故障转移。默认 embedder 是词法特征哈希lexical feature hashing与查询没有任何共同词的改写句不会命中神经向量嵌入是可选能力通过--embed-mode neural开启。从 CLI 帮助文本 的 EMBEDDINGS 一节可进一步确认autoindex 只负责把semantic_text发给服务器embedding 后端由服务器决定默认是 lexical实验性的 ONNX 后端通过--embed-mode onnx-experimental --onnx-model MODEL.onnx --onnx-tokenizer tokenizer.json启用且只对推断为semantic_text的长文本字段生效——动手前可用--dry-run或autoindex map确认字段是否为语义字段。文中所有数字来自 RUN-B 与 RUN-G捕获于 2026-08-21二进制为ci-testprofile 构建因此没有任何墙钟数字被当作性能指标发布。把整条流程交给 Agent一条可复制的 prompt原文档提供了一个粘贴即用的 Agent 指令本质上把上文所有步骤串成了一个闭环Act as a coding agent. Read https://xerj.org/llms.txt, start a local XERJ node, put an OpenAPI document on disk as both .json and .yaml, runxerj autoindex ./api-specs --url http://127.0.0.1:9200 --prefix oa --progress plain, then POST a match on body for a route name and for an operationId, GET /oa-docs/_mapping, and report the ax_format of every hit plus the complete field list the spec produced.Agent 执行后应当汇报每条命中的ax_format以及 spec 产生的完整字段列表即body、title加 7 个ax_*溯源字段。其中GET/oa-docs/_mapping用于直接核对字段清单验证提取确实是格式驱动的curl -s -XGET http://127.0.0.1:9200/oa-docs/_mappingFAQ 速查Agent 需要在大 OpenAPI spec 中查端点正确方式是什么把 spec 放到磁盘上对其文件夹运行xerj autoindex让 Agent 对body发match。捕获运行用 1 条命令就让路由名、描述和 operationId 全部可查询。如何让 OpenAPI spec 对编码 Agent 可搜索索引存放它的文件夹并把索引暴露给 Agent。提取是格式驱动的Agent 查询的是文档文本而非类型化路由对象。如何同时搜索 spec 和 docs 文件夹把它们放在同一个文件夹、索引一次。spec 与 SDK Markdown 在同一次运行中成为文档一个索引模式即可覆盖两者每条命中携带ax_path和ax_format。XERJ 会把 OpenAPI 当作规范来解析吗不会。整份文档除溯源字段外只产生body和title。提取是格式驱动的path是文本而非类型化路由对象。能搜 operationId 吗可以。对body执行match查getOrderCheckpointJournal返回 2 条命中每种序列化 1 条——operationId 只是文档里的普通文本。路径参数需要单独的解析器吗如果需要类型化路由需要。XERJ 返回匹配文档及其ax_path参数结构由 Agent 自行解析 spec。能用聚合数路由数量吗请读 hits 而不是只信 bucket。捕获矩阵显示match_phrase匹配 11 条文档时其 terms 聚合返回 0 个 bucket。延伸阅读如何在一个仓库里找出 YAML 与 XML 中每个配置键的设置位置同一套格式驱动索引思路在配置仓库上的应用。如何让 Agent 找到段落并引用文件而不是倾倒整棵树命中后如何以path:line形式向 Agent 交付证据。Agent 如何在搜索前摸清混乱数据目录里有什么用autoindex map做数据盘点再决定搜索策略。赞分享【免费下载链接】xerjXERJ is the new way for AI to search data. Its autoindex capability activates agents to know your data without the token waste of grep and sed. One command indexes code, docs, logs and PDFs for search, RAG, security audits and agent memory, using 40x fewer tokens than grep. Elasticsearch compatible, so existing clients just work.项目地址https://gitcode.com/GitHub_Trending/xe/xerj点击查看免费下载相关推荐用 xerj autoindex 直接搜索 S3 桶把对象存储当作可增量索引的文件夹用 xerj autoindex 直接搜索 S3 桶把对象存储当作可增量索引的文件夹 导读 本文讲解 xerj 的 xerj autoindex s3://vllm-ascend 精度问题诊断指南使用 msprobe 捕获与定位数值异常vllm ascend 精度问题诊断指南使用 msprobe 捕获与定位数值异常 导读 本文面向在华为昇腾AscendNPU 上运行 vllm ascen快思考反攻深理解laya-mlx 让『拿大模型当路由』成了笑话快思考反攻深理解laya mlx 让『拿大模型当路由』成了笑话 过去两年业界形成了一种近乎本能的路径依赖凡是智能的需求一律上生成式大模型。意图识别用人工智能大模型本地部署推理引擎上一篇DGX Spark集群踩坑一次解决spark-vllm-docker故障排查与常见问题完整清单OOM、卡死、加载慢下一篇Remote In Tech 公司档案解析以 Procurify全远程采购平台为例的 Frontmatter 数据模型与渲染流程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
求解)
