rag‑chunk: CLI 工具，用于基准测试和优化 RAG 分块
rag‑chunk: CLI 工具，用于基准测试和优化 RAG 分块
检索增强生成（RAG）正成为现代 NLP 流水线的基石，但 RAG 系统的质量在很大程度上取决于源文本如何被拆分成易于处理的块。碎片太多会导致索引膨胀；块太大则会失去上下文保真度。
rag‑chunk 通过一个简单的命令行界面解决了此痛点，让你可以 测试、基准化并比较 多种分块策略。它用 Python 编写，在 MIT 许可证下发布，已托管在 PyPI，你可以轻松将其加入任何容器或 CI 工作流。
核心功能
| Feature | Description |
|---|---|
| Multiple Strategies | 固定大小（按词或令牌）、滑动窗口（保留上下文）、段落（语义边界）、递归字符（LangChain 集成）。 |
| Token‑accurate Splitting | 可选 tiktoken 支持 GPT 3.5 和 4 令牌限制；可用 --tiktoken-model 选择模型。 |
| Recall Evaluation | 提供 JSON 测试文件（examples/questions.json），计算在前‑k 检索块中出现的相关短语数。 |
| Rich CLI Output | 通过 Rich 渲染的漂亮表格——清晰、易读且可导出。 |
| Export | 将结果保存为 JSON、CSV 或表格格式；块可导出到 .chunks/ 文件夹以便检查。 |
| Extensible | 可在 src.chunker.py 中添加自定义分块逻辑，并在 STRATEGIES 字典中注册。 |
快速开始
安装
# 从 PyPI
pip install rag-chunk # 基础版
pip install rag-chunk[tiktoken] # 带可选 tiktoken 支持
小窍门 – 如果你在虚拟环境中工作，请仅在需要精确令牌拆分时才安装
tiktoken。
简单块生成
rag‑chunk analyze examples/ --strategy paragraph
对所有策略进行基准测试
rag‑chunk analyze examples/ \n --strategy all \n --chunk-size 100 \n --overlap 20 \n --output table
使用测试文件验证
rag‑chunk analyze examples/ \n --strategy all \n --chunk-size 150 \n --overlap 30 \n --test-file examples/questions.json \n --top-k 3 \n --output json > results.json
选择合适的策略
| Strategy | When to Use | Chunk Size Recommendation |
|---|---|---|
| Fixed‑size | 一致延迟、基线比较 | 150–250 词（或使用 --use‑tiktoken 的令牌） |
| Sliding‑window | 长段落上下文需保留 | 120–200 词、20–30% 重叠 |
| Paragraph | Markdown 或文档段落 | 可变 – 自然段落边界 |
| Recursive‑character | 语义丰富文本、LangChain 整合 | 按 LangChain 默认，但可通过 --chunk‑size 覆盖 |
如果某策略的 avg_recall 低于 0.70，请考虑调整块大小、切换策略或增加重叠令牌。
扩展 rag‑chunk
若你有专有拆分算法，可按如下方式接入：
# src/chunker.py
from typing import List, Dict
def my_custom_chunks(text: str, chunk_size: int, overlap: int) -> List[Dict]:
chunks = []
# 你的逻辑，例如按特定 Markdown 标题拆分
return chunks
# 在全局策略中注册
STRATEGIES = {
"custom": my_custom_chunks,
...
}
rag‑chunk analyze docs/ --strategy custom --chunk-size 180
实际案例
- RAG 模型原型 – 快速衡量嵌入是否捕捉到重要内容。
- 生产索引调优 – 减少块数以节省存储，同时保持召回率。
- 模型专属令牌边界 – 适用于 GPT‑4 32k 上下文，生成恰好 512 令牌的块。
- 自动化 CI 检查 – 将
rag‑chunk作为 CI 步骤，监测块质量回归。
获取帮助与贡献
- 源码 – https://github.com/messkan/rag‑chunk
- 文档 – 在仓库中阅读完整 README 或使用
rag‑chunk --help。 - Issues/PRs – 本仓库接受 Pull Request，欢迎提出新策略或改进文档。
- 社区 – 若遇到错误或有功能需求，可在 issues 页面发帖。
TL;DR
- rag‑chunk 是一款 MIT 许可的 Python CLI，帮助你基准测试 RAG 分块策略。
- 通过
pip install rag‑chunk[tiktoken]安装。 - 使用
rag‑chunk analyze <folder> --strategy all --chunk-size 150快速基准。 - 结果可导出为表格、JSON 或 CSV；可通过
--use‑tiktoken调整令牌精度。
消除块选择的猜测，获取可操作指标，今天就加速你的 RAG 流水线开发！
原创文章:
查看原文