chonkie

Chonkie — RAG 向けの高速で軽量なテキストチャンク分割

Chonkie は、検索拡張生成に最適化されたチャンクにテキストを分割する、高性能な Python ライブラリです。11 種類の特化型チャンク分割器、組み合わせ可能な Pipeline API、30 以上の埋め込みプロバイダー、ベクトルデータベース、LLM との連携機能を提供します。

このスキルを使用する場面

次のようなことをユーザーが希望する場合に、このスキルを使用します。

• RAG 向けにテキスト、ドキュメント、コード、Markdown をチャンクに分割する
• ベクトルデータベース向けのドキュメント取り込みパイプラインを構築する
• チャンク分割戦略（トークン、文、セマンティック、再帰、コード認識型）を選ぶ
• エンドツーエンドのワークフローを設定する：取得 → 前処理 → チャンク分割 → 埋め込み → 保存
• チャンク分割をサービスとして提供する Chonkie REST API サーバーを使用する
• 非同期処理やマルチプロセス処理で大量のドキュメントを処理する
• トークナイザー、埋め込みモデル、再帰チャンク分割ルールを設定する

インストール

# Core (lightweight, ~50MB installed)
pip install chonkie
# or with uv (faster)
uv pip install chonkie

# With specific features
pip install "chonkie[semantic]"       # Semantic chunking (model2vec)
pip install "chonkie[code]"           # Code-aware chunking (tree-sitter)
pip install "chonkie[openai]"         # OpenAI embeddings
pip install "chonkie[qdrant,chroma]"  # Vector DB integrations
pip install "chonkie[api]"            # REST API server

# Everything
pip install "chonkie[all]"

オプションの追加機能： hub、viz、cli、api、table、tokenizers、tiktoken、code、neural、semantic、st、openai、gemini、azure-openai、groq、cerebras、voyageai、cohere、jina、litellm、catsu、chroma、qdrant、pgvector、weaviate、pinecone、mongodb、elastic、milvus、lancedb、tpuf、datasets

基本概念

Chunk 型

すべてのチャンク分割器は Chunk オブジェクトを返します。

Chunk(
    text="...",            # The chunk text
    start_index=0,         # Start position in original text
    end_index=512,         # End position in original text
    token_count=128,       # Token count (per configured tokenizer)
    context=None,          # Optional surrounding context
    embedding=None,        # Optional embedding vector (after refinement)
    metadata={},           # Arbitrary metadata dict
    id="uuid-...",         # Auto-generated UUID
)

チャンク分割器の呼び出し

from chonkie import RecursiveChunker

chunker = RecursiveChunker(chunk_size=2048)

# Single text
chunks = chunker("Your long document text here...")

# Batch processing
batch_results = chunker(["doc1...", "doc2...", "doc3..."], show_progress=True)
# Returns: list[list[Chunk]]

チャンク分割器の種類

TokenChunker — 固定サイズのトークンウィンドウ

from chonkie import TokenChunker

# chunk_overlap accepts int (exact tokens) or float (fraction of chunk_size)
chunker = TokenChunker(chunk_size=512, chunk_overlap=64)
chunker = TokenChunker(chunk_size=512, chunk_overlap=0.1)  # 10% = 51 tokens
chunks = chunker(text)

最適な用途：シンプルで予測可能なチャンクサイズ。基本的なチャンク分割。組み込みの chunk_overlap を備えた、わずか2種類のチャンク分割器の1つです。

FastChunker — SIMD によるバイトレベルの分割（約100 GB/s）

from chonkie import FastChunker
chunker = FastChunker(chunk_size=512)
chunks = chunker(text)

最適な用途：大規模なコーパスで最高のスループットを実現します。Rust による SIMD 高速化を使用します。組み込みのオーバーラップ機能はありません。チャンク分割後に OverlapRefinery を使用してください。

SentenceChunker — 文境界を考慮した分割

from chonkie import SentenceChunker
chunker = SentenceChunker(
    chunk_size=512,
    chunk_overlap=64,            # optional, int token overlap
    min_sentences_per_chunk=1,
)
chunks = chunker(text)

最適な用途：文のまとまりを保つことが重要な自然言語のドキュメント。組み込みの chunk_overlap を備えた、わずか2種類のチャンク分割器の1つです。

RecursiveChunker — 階層的な分割（デフォルトとして推奨）

from chonkie import RecursiveChunker

# With default rules (paragraphs → sentences → words)
chunker = RecursiveChunker(chunk_size=2048)

# With custom rules
from chonkie.types import RecursiveRules, RecursiveLevel
rules = RecursiveRules(levels=[
    RecursiveLevel(delimiters=["\n\n"]),        # Split on paragraphs
    RecursiveLevel(delimiters=["\n"]),           # Then lines
    RecursiveLevel(delimiters=[". ", "! ", "?"]),# Then sentences
    RecursiveLevel(whitespace=True),             # Then words
])
chunker = RecursiveChunker(chunk_size=2048, rules=rules)

# With a language-specific recipe from HuggingFace Hub
chunker = RecursiveChunker(chunk_size=2048, recipe="markdown", lang="en")
chunks = chunker(text)

最適な用途：汎用的なチャンク分割。ドキュメントの構造を階層的に保持します。迷った場合は、まずこちらをお試しください。

SemanticChunker — 埋め込みの類似度に基づく分割

from chonkie import SemanticChunker
chunker = SemanticChunker(
    embedding_model="minishlab/potion-base-32M",
    chunk_size=512,
    similarity_window=2,
)
chunks = chunker(text)

必要条件：pip install "chonkie[semantic]"

最適な用途：意味的に関連するコンテンツのグループ化。品質は高くなりますが、処理に時間がかかります。

LateChunker — 埋め込み品質を高めるチャンク分割後の埋め込み

from chonkie import LateChunker
chunker = LateChunker(
    embedding_model="minishlab/potion-base-32M",
    chunk_size=512,
)
chunks = chunker(text)

最適な用途：チャンクの埋め込み品質が重要な場合。各チャンクにコンテキストを考慮した埋め込みが付与されます。

CodeChunker — 構造を考慮したコード分割

from chonkie import CodeChunker
chunker = CodeChunker(
    language="python",  # or auto-detect
    chunk_size=512,
)
chunks = chunker(code_text)

必要条件：pip install "chonkie[code]"

最適な用途：ソースコード。tree-sitter による解析で関数やクラスの境界を尊重します。

NeuralChunker — トークン分類モデル

from chonkie import NeuralChunker
chunker = NeuralChunker(
    model="mirth/chonkie_bert_uncased_1",  # Pre-trained
)
chunks = chunker(text)

必要条件：pip install "chonkie[neural]"

最適な用途：機械学習で予測したチャンク境界を使用したい場合。事前学習済みモデルが3種類用意されています。

SlumberChunker — LLM によるセマンティックチャンク分割

from chonkie import SlumberChunker
from chonkie.genie import OpenAIGenie

genie = OpenAIGenie(model="gpt-4o-mini")
chunker = SlumberChunker(genie=genie, chunk_size=1024)
chunks = chunker(text)

最適な用途：LLM を使用した最高品質のセマンティック分割。最も遅い一方で、最も高精度です。

TableChunker — Markdown／HTML テーブルの分割

from chonkie import TableChunker
chunker = TableChunker(chunk_size=512)
chunks = chunker(markdown_with_tables)

必要条件：pip install "chonkie[table]"

最適な用途：行単位の分割が必要な大きなテーブルを含むドキュメント。

TeraflopAIChunker — 外部 API による分割

from chonkie import TeraflopAIChunker
chunker = TeraflopAIChunker(api_key="...", chunk_size=512)
chunks = chunker(text)

最適な用途：TeraflopAI のホスト型セグメンテーションサービスを使用する場合。

チャンク分割器の選択ガイド

シナリオ	推奨するチャンク分割器
汎用／選び方がわからない	RecursiveChunker
最高速度、大規模なコーパス	FastChunker
自然言語の文章	SentenceChunker または RecursiveChunker
セマンティックなグループ化が必要	SemanticChunker
ソースコードファイル	CodeChunker
最高品質を求め、コストを許容できる	SlumberChunker（LLM）
テーブルを含む Markdown	TableChunker + RecursiveChunker
トークン予算の遵守	TokenChunker

詳しい選択ガイドについては、references/chunker_selection.md を参照してください。

トークナイザー

すべてのチャンカーは、テキストサイズの測定方法を制御する tokenizer パラメーターを受け取ります。

from chonkie import RecursiveChunker

# Built-in (no extra deps)
chunker = RecursiveChunker(tokenizer="character", chunk_size=4000)  # char count
chunker = RecursiveChunker(tokenizer="word", chunk_size=500)        # word count

# HuggingFace tokenizers (pip install "chonkie[tokenizers]")
chunker = RecursiveChunker(tokenizer="tokenizers:gpt2", chunk_size=512)

# OpenAI tiktoken (pip install "chonkie[tiktoken]")
chunker = RecursiveChunker(tokenizer="tiktoken:gpt-4", chunk_size=512)

# Custom callable
def my_counter(text: str) -> int:
    return len(text.split())
chunker = RecursiveChunker(tokenizer=my_counter, chunk_size=500)

デフォルトのトークナイザーは "character" です（依存関係はありません）。LLM に合わせたチャンク分割には、"tiktoken:gpt-4" または埋め込みモデルに適合する HuggingFace トークナイザーを使用してください。

パイプライン API

Pipeline では、処理ステップを流れるようにつなげられます。

from chonkie import Pipeline

# Full end-to-end pipeline
docs = (Pipeline()
    .fetch_from("file", path="./documents/")
    .process_with("markdown")
    .chunk_with("recursive", chunk_size=1024)
    .refine_with("embeddings", embedding_model="openai:text-embedding-3-small")
    .store_in("qdrant", url="http://localhost:6333", collection="my_docs")
    .run(show_progress=True)
)

# Chain multiple chunkers
docs = (Pipeline()
    .chunk_with("table", chunk_size=2048)          # Split tables first
    .chunk_with("recursive", chunk_size=512)        # Then recursive split
    .refine_with("overlap", context_size=128)       # Add overlap context
    .export_with("json", file="chunks.json")        # Save to JSON
    .run(texts=["Your document text..."])
)

# Async execution for high throughput
docs = await (Pipeline()
    .chunk_with("semantic", chunk_size=512)
    .arun(texts=large_text_list)
)

# Load from a HuggingFace recipe
pipeline = Pipeline.from_recipe(name="default", lang="en")
docs = pipeline.run(texts=["..."])

パイプラインのステップタイプ

ステップ	メソッド	オプション
取得	.fetch_from("file", path=...)	拡張子でフィルタリングできる単一ファイルまたはディレクトリ
処理	.process_with("markdown" | "text" | "table")	生テキストを前処理します
チャンク分割	.chunk_with("recursive" | "semantic" | ...)	11 種類のチャンカーから選択できます
調整	.refine_with("overlap" | "embeddings", ...)	チャンク分割後の処理
エクスポート	.export_with("json" | "datasets", ...)	ファイルまたは HF データセットに保存します
格納	.store_in("chroma" | "qdrant" | "pinecone" | ...)	ベクトル DB への取り込み

オーバーラップとコンテキスト

Chonkie には、チャンクに周辺コンテキストを追加するための明確に異なる仕組みが 2 つあります。この違いを理解することが重要です。

組み込みの chunk_overlap（チャンク分割時）

chunk_overlap パラメーターに対応しているのは、TokenChunker と SentenceChunker のみです。チャンク分割時に実際にトークンウィンドウを重ねるため、隣接するチャンクは境界部分のコンテンツを共有します。

from chonkie import TokenChunker

chunker = TokenChunker(chunk_size=512, chunk_overlap=64)
chunks = chunker(text)
# Chunk N ends at token 512, Chunk N+1 starts at token 448 (512-64)

• int 値：正確なトークン数のオーバーラップ
• float 値（0～1）：chunk_size に対する割合（例：0.1 = 10%）
• start_index/end_index に影響し、チャンクはソーステキスト内で実際に重なります

その他のすべてのチャンカー（Recursive、Semantic、Code、Fast、Neural、Slumber、Table、Late、TeraflopAI）には、組み込みのオーバーラップ機能がありません。代わりに OverlapRefinery を使用してください。

OverlapRefinery（チャンク分割後）

どのチャンカーで作成されたチャンクにも、作成後に周辺コンテキストを追加します。すべてのチャンカーで推奨される方法です。

from chonkie import RecursiveChunker
from chonkie.refinery import OverlapRefinery

chunker = RecursiveChunker(chunk_size=512)
chunks = chunker(text)

refinery = OverlapRefinery(
    context_size=128,         # int (exact tokens) or float (fraction of chunk token_count)
    method="suffix",          # "suffix" (default) or "prefix"
    mode="token",             # "token" (default) or "recursive"
    merge=True,               # True: append/prepend to chunk.text; False: store in chunk.context only
    inplace=True,             # modify chunks in place
)
refined = refinery(chunks)

パラメーター：

パラメーター	型	デフォルト	説明
context_size	int または float	0.25	追加するコンテキストのトークン数。float（0～1）は、チャンクの token_count に対する割合です
method	"suffix" または "prefix"	"suffix"	suffix：次のチャンクの先頭を追加します。prefix：前のチャンクの末尾を前置します
mode	"token" または "recursive"	"token"	token：正確なトークン単位の切り出し。recursive：論理的な境界（区切り文字）で分割します
merge	bool	True	True の場合、コンテキストを chunk.text に統合し、token_count を更新します。False の場合、コンテキストは chunk.context フィールドのみに格納されます
inplace	bool	True	チャンクをその場で変更するか、コピーを返します

サフィックス方式（デフォルト）：次のチャンクの先頭から N 個のトークンを取り出し、現在のチャンクに追加します。「この後に何が続くか」というコンテキストを提供します。

プレフィックス方式：前のチャンクの末尾から N 個のトークンを取り出し、現在のチャンクの先頭に追加します。「この前に何があったか」というコンテキストを提供します。

merge=False の場合、chunk.text と start_index/end_index は変更されず、コンテキストは chunk.context フィールドに別途格納されます。

Pipeline での使用

from chonkie import Pipeline

docs = (Pipeline()
    .chunk_with("recursive", chunk_size=512)
    .refine_with("overlap", context_size=0.25, method="suffix")
    .refine_with("embeddings", embedding_model="openai:text-embedding-3-small")
    .run(texts=documents)
)

埋め込み

EmbeddingsRefinery または Pipeline を使って、チャンクに埋め込みを追加します。

from chonkie import AutoEmbeddings, EmbeddingsRefinery

# Local models
embed = AutoEmbeddings.get_embeddings("minishlab/potion-base-32M")
embed = AutoEmbeddings.get_embeddings("sentence-transformers/all-MiniLM-L6-v2")

# API-based
embed = AutoEmbeddings.get_embeddings("openai:text-embedding-3-small")
embed = AutoEmbeddings.get_embeddings("cohere")
embed = AutoEmbeddings.get_embeddings("voyageai")

# Apply to chunks
refinery = EmbeddingsRefinery(embedding_model=embed)
chunks_with_embeddings = refinery(chunks)
# Each chunk now has chunk.embedding populated

ベクトルデータベースとの統合

チャンクをベクトルストアに 1 行で取り込みます。

from chonkie.handshakes import ChromaHandshake, QdrantHandshake, PineconeHandshake

# ChromaDB
ChromaHandshake(collection_name="docs").write(chunks)

# Qdrant
QdrantHandshake(url="http://localhost:6333", collection_name="docs").write(chunks)

# Pinecone
PineconeHandshake(index_name="docs", namespace="prod").write(chunks)

# Also: Weaviate, Elastic, MongoDB, PostgreSQL (pgvector),
#        LanceDB, Milvus, Turbopuffer

すべてのハンドシェイクは非同期に対応しています：await handshake.awrite(chunks)

REST API サーバー

Chonkie を API として提供します。

pip install "chonkie[api]"
chonkie serve --port 3000 --reload

主なエンドポイント：

• POST /v1/chunking/{chunker_name} — テキストをチャンク分割します
• POST /v1/refineries/{refinery_name} — チャンクを調整します
• POST /v1/pipelines — 再利用可能なパイプラインを作成します
• POST /v1/pipelines/{id}/run — 保存済みのパイプラインを実行します
• GET /docs — 対話型 API ドキュメント

パイプラインは SQLite に保存され、複数のアプリケーションで再利用できます。

レシピ

HuggingFace Hub から言語固有のチャンク分割ルールを読み込みます。

from chonkie.types import RecursiveRules

rules = RecursiveRules.from_recipe(name="markdown", lang="en")
chunker = RecursiveChunker(rules=rules, chunk_size=2048)

# 56 languages supported
rules_ja = RecursiveRules.from_recipe(name="default", lang="ja")

レシピは HuggingFace Hub の chonkie-ai/recipes でホストされています。

パフォーマンス

• FastChunker: 100+ GB/s（Rust コアによる SIMD アクセラレーション）
• RecursiveChunker: LangChain の同等機能より 33 倍高速
• SemanticChunker: 競合製品より約 2.5 倍高速
• ホイールサイズ: 505KB | インストール後: 約 49MB（デフォルト）
• マルチプロセッシングとプログレスバーによるバッチ処理

一般的なパターン

完全なパイプラインの例は references/pipeline_patterns.md を、本番環境対応の取り込みスクリプトは scripts/rag_pipeline_example.py をご覧ください。