Chunky - RAG チャンキングツールキット チートシート
Chunky はオープンソースのツールキット — 確実な RAG 取り込みパイプライン用、チャンキング段階に焦点。PDF を Markdown に変換、ドキュメントをクリーン、チャンキング戦略を検査・比較できる、チャンクメタデータを充実化して LLM アプリケーション向けに。取得品質は文書がどのように分割されるかで上限となるため、Chunky の価値はチャンキング段階を見えて調整可能にすることで、盲目的なデフォルトの代わりに。
インストール
| 方法 | コマンド |
|---|
| pip | pip install chunky |
| uv | uv add chunky |
| ソースから | git clone https://github.com/GiovanniPasq/chunky && cd chunky && pip install -e . |
| 確認 | python -c "import chunky; print('ok')" |
パイプラインステージ
| ステージ | 目的 |
|---|
| 変換 | PDF/ドキュメントをクリーン Markdown に変換 |
| クリーン | ボイラープレート、アーティファクトを削除 |
| チャンク | 選択した戦略を使用してテキストを分割 |
| 検査 | 結果のチャンクを可視化 |
| 比較 | 複数の戦略を実行して比較 |
| 充実化 | メタデータを添付（見出し、ソース、位置） |
変換 & クリーン
import chunky
# PDF をクリーン Markdown に変換
md = chunky.to_markdown("report.pdf")
# 一般的なアーティファクトをクリーン（ヘッダー/フッター、ハイフン化、ノイズ）
md = chunky.clean(md)
| 関数 | 説明 |
|---|
to_markdown(path) | ドキュメントを Markdown に変換 |
clean(text) | ボイラープレートを削除して正規化 |
チャンキング戦略
| 戦略 | 分割対象 |
|---|
| 固定サイズ | N トークン/文字とオーバーラップ |
| 再帰的 | 段落 → 文 → 単語（必要に応じて） |
| Markdown / 見出し認識 | ドキュメント構造（#、##、セクション） |
| セマンティック | 埋め込み類似度の境界 |
| トークン認識の改善 | 小さすぎるチャンクをマージ、大きすぎるチャンクを分割 |
chunks = chunky.chunk(
md,
strategy="header_aware",
max_tokens=512,
overlap=64,
repeat_headers=True, # テーブル分割全体で見出しを実施
)
for c in chunks:
print(len(c.tokens), c.metadata["heading"])
検査 & 比較
差別化：各戦略がコミット前に何を生成するかを見て比較。
# チャンク境界とサイズを検査
chunky.inspect(chunks) # サイズ、オーバーラップ、境界
# 同じドキュメント上の戦略を比較
report = chunky.compare(
md,
strategies=["fixed", "recursive", "header_aware", "semantic"],
max_tokens=512,
)
print(report) # 戦略ごとの統計：カウント、サイズ分布、断片化
| 関数 | 表示 |
|---|
inspect(chunks) | サイズ分布、オーバーラップ、境界 |
compare(text, strategies=[...]) | サイドバイサイド戦略メトリクス |
メタデータ充実化
| メタデータ | 取得で使用 |
|---|
| 見出しパス | コンテキスト拡張 / フィルタリング |
| ソース + ページ | 引用 |
| 位置/インデックス | 順序付けおよび隣接ルックアップ |
| トークンカウント | プロンプト時のバジェット管理 |
enriched = chunky.enrich(chunks, source="report.pdf")
# 各 chunk.metadata は見出しパス、ページ、ソース、インデックスを実施
一般的なワークフロー
# エンドツーエンド：PDF → クリーン Markdown → 見出し認識チャンク → 充実化
import chunky
md = chunky.clean(chunky.to_markdown("manual.pdf"))
chunks = chunky.chunk(md, strategy="header_aware", max_tokens=512, overlap=64)
chunks = chunky.enrich(chunks, source="manual.pdf")
# chunk.text を埋め込み、chunk.metadata をベクトル DB と共に保存
# 推測ではなく証拠を使用して戦略を選択
print(chunky.compare(md, strategies=["recursive", "header_aware", "semantic"]))
Chunky vs その他のアプローチ
| 側面 | Chunky | フレームワークデフォルト分割器 | Docling |
|---|
| 戦略比較 | 一級市民 | 手動 | 限定的 |
| 変換 + クリーン | 組み込み | 別 | 組み込み |
| 最適用途 | チャンキング段階をチューニング | クイックスタート | 完全なパース + チャンク |
Docling での解析およびベクトル DB での保存とペアリングすると良好 — Chunky の仕事は分割を正しく取得することです。
リソース
