chonkie

Chonkie — 面向 RAG 的快速轻量级文本分块

Chonkie 是一个高性能 Python 库，可将文本拆分为适用于检索增强生成的块。它提供 11 种专用分块器、可组合的 Pipeline API，以及与 30 多种嵌入服务提供商、向量数据库和大模型的集成。

何时使用此技能

在用户希望进行以下操作时使用此技能：

• 为 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(
    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 的分块器之一。

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 的分块器之一。

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]"

适用场景：需要由机器学习预测分块边界时。提供三种预训练模型。

SlumberChunker — 基于大模型的语义分块

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)

适用场景：使用大模型获得最高质量的语义拆分。速度最慢，但最智能。

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"（无需依赖项）。如需与大模型对齐的分块，请使用 "tiktoken:gpt-4"，或使用与嵌入模型匹配的 HuggingFace 分词器。

Pipeline 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=["..."])

Pipeline 步骤类型

步骤	方法	选项
获取	.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" | ...)	导入向量数据库

重叠与上下文

Chonkie 提供两种不同的机制，为分块添加周边上下文。理解二者的区别很重要。

内置的 chunk_overlap（分块时）

只有 TokenChunker 和 SentenceChunker 支持 chunk_overlap 参数。此参数会在分块时创建实际重叠的 token 窗口——相邻分块会在边界处共享内容。

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 值：精确的 token 重叠数量
• 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	要添加的上下文 token 数量。Float（0-1）= 分块 token_count 的比例
method	"suffix" 或 "prefix"	"suffix"	suffix：追加下一个分块的开头部分。prefix：在开头添加上一个分块的结尾部分
mode	"token" 或 "recursive"	"token"	token：精确按 token 切片。recursive：在逻辑边界（分隔符）处分割
merge	bool	True	若为 True，上下文会合并到 chunk.text 中，并更新 token_count。若为 False，上下文仅存储在 chunk.context 字段中
inplace	bool	True	原地修改分块或返回副本

Suffix 方法（默认）：取下一个分块的前 N 个 token，并将其追加到当前分块——提供“后续内容”上下文。

Prefix 方法：取上一个分块的最后 N 个 token，并将其添加到当前分块开头——提供“先前内容”上下文。

当 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

向量数据库集成

一行代码即可将分块导入向量存储：

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 — 创建可复用的 Pipeline
• POST /v1/pipelines/{id}/run — 执行已保存的 Pipeline
• GET /docs — 交互式 API 文档

Pipeline 会持久化到 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 倍
• Wheel 大小： 505KB | 安装后： 约 49MB（默认）
• 支持使用多进程和进度条进行批量处理

常见模式

完整的工作流示例请参阅 references/pipeline_patterns.md，生产就绪的摄取脚本请参阅 scripts/rag_pipeline_example.py。