面向 RAG 场景的语义化文件切片与向量入库工具，Java 17 构建，从切片到检索一气呵成。

一、背景：RAG 落地的第一道门槛

检索增强生成（RAG，Retrieval-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 Agent（RAG 检索环节）

三、核心特性

四、两种使用方式

• Pragmatic Chunker 既照顾了新手的上手体验，也兼顾了工程化的批量集成：

• 交互式向导：不带参数启动，按欢迎页提示逐步选择能力与配置，零学习成本即可跑通流程；

• CLI 子命令：chunk / embed / push / search / mcp，适合脚本集成与批量处理。

五、快速上手

• 一个最小可用的完整流水线（本地 Ollama + Qdrant 已启动）：

# 1. 切片：把 docs 目录下的 Markdown 切成 chunk
java -jar pragmatic-chunker.jar chunk -i ./docs/ -o ./output --type markdown
# 2. 嵌入：把切片结果向量化（默认 Ollama / nomic-embed-text）
java -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 v5，upsert 幂等，集合状态始终与最新中间文件一致。

• 开箱即用的 MCP 接入。以 mcp 子命令启动 MCP Server，向 Qoder、Claude Desktop 等 AI Agent 暴露 search_vector_store、list_collections、list_sources 三个只读检索工具，支持 stdio 与 HTTP 双传输，并可配置 Bearer Token 鉴权。

七、技术栈与运行环境

• 可选外部服务： 本地嵌入用 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，一起把这条"切片到检索"的链路打磨得更顺滑。