Chunky：RAG 文档分块的全链路工作台

图1：Chunky 项目 Logo — 简洁直观，展现"分块"核心概念

痛点故事：一份年报毁掉整个 RAG 系统

想象这样一个场景：某金融团队花了两周时间构建 RAG 系统，索引了上百份年报、研报和法律文档。系统上线第一天，开发者满怀信心地向 AI 提问：「我们公司去年第四季度的毛利率是多少？」AI 的回答却是「根据文档……第三段提到……第一季度的数据显示……」——完全答非所问。

问题出在哪里？不是模型，不是检索算法，而是分块（Chunking）。PDF 转换时表格被撕成乱码、段落在中间被截断、标题和内容被分到不同块里——这些肉眼难辨的问题，到了上下文中就变成了灾难。

NVIDIA 的研究明确指出：没有哪种分块策略能 universally winning。不同文档类型、不同查询意图，最优分块方式截然不同。但大多数 RAG 系统把分块当成一个"调一次就完事"的隐藏参数，从来不在实际文档上验证效果。

Chunky 正是为解决这个被忽视的问题而生。

项目起源：把分块变成可见、可比、可优化的步骤

Chunky 由独立开发者 GiovanniPasq 创建，是一个专注于 RAG 文档预处理的开源工具包。项目将 PDF 转 Markdown、Markdown 清洗、分块可视化、分块策略对比、LLM 元数据增强这五个步骤，串联成一个完整的本地工作流。

项目的核心设计理念是**「inspect before you index」**——在文档进入向量数据库之前，先用可视化界面看清楚文档被切成什么样子，对比不同分块策略的实际效果，而不是盲目地碰运气。

从 GitHub 数据看，项目于 2025 年初创建，目前 143 Stars、13 Forks，MIT 许可证，Python + TypeScript/React 技术栈。它不是一个追求大而全的框架，而是围绕"文档分块质量保障"这一垂直场景，做深做透。

核心功能：从 PDF 到高质量分块的完整流水线

Chunky 提供了全链路的功能支持，每个环节都可以独立使用，也能串联成完整流程：

文档转换引擎：支持 PyMuPDF、Docling、MarkItDown、LiteParse 四种 PDF→Markdown 转换器，并提供 VLM（视觉语言模型）云端转换作为高端选项。每种引擎对复杂排版（多栏、表格、公式）的处理能力不同，Chunky 允许你在界面上同时对比多个引擎的转换结果，选择最适合你文档类型的那一个。

Markdown 清洗：PDF 转出的 Markdown 常常残留大量噪声——多余的空格、歪斜的换行、乱码的特殊字符。Chunky 内置确定性清洗规则（无需 LLM 调用），同时支持 LLM 修正模式，对清洗结果进行语义级润色。

分块可视化与对比：这是 Chunky 最核心的差异化功能。传统的分块过程是"黑盒"——你配置参数，出来什么结果就用什么结果。Chunky 则提供了实时可视化界面，将原始 PDF、转换后的 Markdown、以及分块结果并排展示。你可以清晰看到：这段文字被分到了哪个块、块的边界在哪里、块的元数据（标题、摘要、关键词）长什么样。

多种分块策略对比：支持 LangChain TextSplitters、Chonkie（项目推荐的语义分块库）、Docling 三种分块器，可配置块大小、重叠长度。同一份文档，同一个查询，你可以切换不同策略，对比检索结果。这种对比能力在 Chunky 出现之前，几乎只有专业 RAG 评估工具才有。

LLM 元数据增强：在分块之前，可以对 Markdown 或单个块进行 LLM 增强：为每个块生成描述性标题、摘要、关键词，甚至检索问题（"用户可能用什么问题检索这个块？"）。这对于提升检索相关性至关重要——块本身可能只包含技术术语，而元数据可以补充语义上下文。LLM 部分通过 Ollama 接口调用本地模型，完全离线运行。

批量处理：支持多文档批量转换、增强和分块，通过侧边栏管理文档队列，适合处理大量文档的 RAG 管道。

技术架构：前后端分离，插件化设计

Chunky 采用典型的前后端分离架构：

后端基于 FastAPI（Python），提供 REST API + SSE（Server-Sent Events）接口。核心模块按职责分为：

• converters/：PDF 转换引擎（6 种实现：PyMuPDF、Docling、MarkItDown、LiteParse、VLM、云端 API）
• chunkers/：分块策略（3 种：LangChain、Chonkie、Docling）
• services/：Enrichment 服务（LLM 元数据增强）
• routers/：API 路由（Documents、Chunks、Enrichment、Capabilities、Health）

并发控制方面值得注意：后端使用 ProcessPoolExecutor 包装 CPU 密集型操作（转换和分块），避免阻塞事件循环；FastAPI lifespan 初始化阶段注入全局 httpx.AsyncClient（复用连接池）和信号量（conversion_semaphore、chunk_semaphore、enrichment_chunks_semaphore）来控制并发上限，配置均可通过环境变量调节。Python 3.11 slim 镜像，构建包含 cairo/pango 等字体渲染依赖。

前端基于 React 19 + Vite + TypeScript，通过 /api/v1 接口与后端通信。前端通过界面动态配置 LLM 模型名称、base URL 和 API Key，无需修改代码即可切换不同 LLM 提供商。

存储层采用本地文件系统：docs/pdfs/ 存原始 PDF，docs/mds/ 存转换后的 Markdown，docs/chunks/ 存分块结果。版本化的分块结果可持久化保存，方便对比不同参数下的效果。

部署体验：docker-compose 一键启动

Chunky 在部署设计上非常友好。docker-compose.yml 定义了后端（端口 8000）和前端（端口 5173）两个服务，后端依赖 Ollama 进行 LLM 增强。启动方式极为简单：

# 安装 Ollama（可选，如需 LLM 增强）
ollama pull llama3.2

# 一键启动
chmod +x start_all.sh && ./start_all.sh
# 或 Windows PowerShell
./start_all.ps1

启动脚本会自动构建 Docker 镜像并启动容器。首次启动需要拉取依赖镜像，预计 5-10 分钟（取决于网络）。之后每次重启基本在 30 秒内完成。

硬件需求方面，不使用 VLM 转换和 LLM 增强时，仅需 CPU 模式运行，2GB RAM 即可；使用 LLM 增强（通过 Ollama）则建议 4GB+ RAM。GPU 可选（Ollama 有 GPU 加速模式，但 Chunky 本身不强制要求）。

行业意义：填补 RAG 质量保障的工具空白

RAG 领域过去两年的焦点主要在三个方向：检索优化（向量数据库、混合检索）、生成增强（多跳推理、Agentic RAG）、框架完善（LangChain、LlamaIndex 的易用性）。但文档预处理质量这个根本问题，长期缺乏专门工具。

Chunky 的出现填补了这个空白。它不追求替代 LangChain 或 LlamaIndex，而是作为这些框架的上游数据质量保障层。在实际生产中，RAG 系统质量问题的 60-70% 可以追溯到文档分块阶段，Chunky 让这个问题变得可视化、可优化。

从更宏观的视角看，Chunky 代表了 RAG 工具链精细化分工的趋势。随着 RAG 从"能用"向"好用"演进，专注于特定环节的工具会越来越有市场——正如软件工程领域从大一统 IDE 向专业化工具链演进一样。

局限与争议

尽管 Chunky 解决了分块可视化的核心痛点，但仍有一些局限值得注意：

VLM 转换的成本：VLM（视觉语言模型）转换提供最高质量的结果，但需要调用商业 API 或部署大型 VLM 模型，成本和延迟都较高。项目推荐使用 Ollama 本地运行 VLM（如 bakllava），但本地 VLM 在 CPU 模式下速度极慢。

存储设计：使用本地文件系统存储文档和分块结果，适合个人/小团队使用，但不支持分布式协作和版本管理。对于企业级场景，需要自行对接对象存储或文档管理系统。

PDF 格式支持：虽然支持多种转换引擎，但对某些特殊 PDF（如扫描件加密、动态表单、3D 内容）支持仍然有限。

生态整合：目前缺乏与主流向量数据库（Milvus、Pinecone、Weaviate）的直接对接，需要手动导出分块结果后另行导入。

总结

Chunky 是一个专注于 RAG 文档预处理质量的开源工具包。它将 PDF 转 Markdown、Markdown 清洗、分块可视化、策略对比、LLM 元数据增强整合为一体化的本地工作流，特别适合那些希望认真对待分块质量的 RAG 开发者和数据工程师。

如果你在构建 RAG 系统时遇到过"检索结果看着对但实际答不对"的问题，不妨先用 Chunky 看看你的文档被切成什么样子——答案往往就在分块的细节里。

图2：Chunky 流水线架构 — 从 PDF 转换到分块增强的完整流程