一、背景RAG 落地的第一道门槛检索增强生成RAGRetrieval-Augmented Generation已成为企业将私有文档、代码库接入大模型的标配方案。然而开发者落地时需自行拼接“切分 - 向量化 - 入库 - 检索”这条不轻松的流水线每一步都要写脚本、对格式、处理异常中间产物还散落各处、难以复现。针对此痛点基于 Java 17 的开源命令行工具“Pragmatic Chunker”正式发布。它将“切片 - 嵌入向量 - 写入向量库 - 检索验证 - 供 AI Agent 检索”的完整链路收敛到一个可执行 JAR 中每一步都产出可独立理解、自包含、可复现的中间文件。二、它是什么Pragmatic Chunker 是面向 RAG 场景的命令行工具能把 Markdown 与 Java 源码按语义结构切分成信息密度充分、可独立理解的文本块chunk并串联起从切片到检索的完整流水线源文件 (.md / .java)│ chunk 文件切片语义 chunk 化▼*.chunks.json 切片中间文件chunk 原文 元数据│ embed 嵌入向量生成▼*.embeddings.json 向量中间文件向量 原文 完整元数据自包含│ push 推送到向量库▼Qdrant 集合 向量数据入库Point 向量 payload│ search / mcp▼检索验证 / AI AgentRAG 检索环节三、核心特性能力说明✂️ 语义切片Markdown 按标题层级 原子块代码块/表格/列表切分Java 按类 / 方法 / 逻辑块切分 嵌入向量支持本地 Ollama 与 OpenAI含兼容协议服务批次重试、连通性预检 向量入库首期支持 Qdrant按 source_file 先删后加重复推送幂等 检索验证单条查询快速验证检索效果输出 text / raw / payload 三种格式 MCP Server以 mcp 子命令启动向 AI Agent 暴露只读检索工具stdio / HTTP 双传输 可扩展FileChunker / EmbeddingProvider / VectorStore 三套 SPI新增类型/提供方零侵入四、两种使用方式Pragmatic Chunker 既照顾新手上手体验也兼顾工程化批量集成**交互式向导**不带参数启动按欢迎页提示逐步选择能力与配置零学习成本即可跑通流程。**CLI 子命令**chunk / embed / push / search / mcp适合脚本集成与批量处理。五、快速上手一个最小可用的完整流水线本地 Ollama Qdrant 已启动# 1. 切片把 docs 目录下的 Markdown 切成 chunkjava -jar pragmatic-chunker.jar chunk -i ./docs/ -o ./output --type markdown# 2. 嵌入把切片结果向量化默认 Ollama / nomic-embed-textjava -jar pragmatic-chunker.jar embed -i ./output/markdown -o ./embeddings# 3. 推送把向量写入 Qdrant 集合java -jar pragmatic-chunker.jar push -i ./embeddings --collection my_docs# 4. 检索验证java -jar pragmatic-chunker.jar search -q 切片的最大长度如何配置六、技术亮点**语义感知的切片策略**Markdown 按标题层级与原子块代码块、表格、列表切分Java 借助 JavaParser AST 按类 / 方法 / 逻辑块切分并支持 import、Javadoc、字段声明等上下文携带保证每个 chunk 信息自洽。**自包含、可复现的中间产物***.chunks.json 与 *.embeddings.json 既包含原文也包含完整元数据可单独查看、调试与复用链路任意一段出错都能从断点续跑。**幂等入库**对同一 source_file 重复推送采用“先删后加”同一 chunk 使用确定性 UUID v5upsert 幂等集合状态始终与最新中间文件一致。**开箱即用的 MCP 接入**以 mcp 子命令启动 MCP Server向 Qoder、Claude Desktop 等 AI Agent 暴露 search_vector_store、list_collections、list_sources 三个只读检索工具支持 stdio 与 HTTP 双传输并可配置 Bearer Token 鉴权。七、技术栈与运行环境项目要求JDK17 及以上构建工具Maven 3.6仅编译打包时需要操作系统macOS / Linux / Windows可选外部服务本地嵌入用 Ollama云端嵌入用 OpenAI或兼容协议服务向量库首期支持 Qdrant。八、开源与获取Pragmatic Chunker 基于 Apache License 2.0 开源协议发布。开发者可通过 mvn clean package 一键构建出可执行 fat JAR开箱即跑。项目仓库https://gitee.com/wizard-lee/pragmatic-chunker许可证Apache License 2.0欢迎对 RAG 工程化、文档/代码检索感兴趣的开发者试用、提 Issue 与 PR一起把这条“切片到检索”的链路打磨得更顺滑。