厌倦了反复编写自己的分块逻辑？受够了大型库带来的性能开销？想快速高效地对文本进行分块吗？强大的河马 Chonkie 来帮您解决问题！

🚀 功能丰富：满足你所有分块需求
🔄 端到端：获取数据、分块、精炼、嵌入，直接送入你的向量数据库！
✨ 易于使用：安装、导入、分块
⚡ 高速：以光速分块！嗖的一下！
🪶 轻量级：无冗余，只做分块
🔌 32+ 种 [集成]：开箱即用，兼容你最喜爱的工具和向量数据库！
💬 多语言支持：原生支持56种语言
☁️ 云友好：可在本地或在 云端 进行分块
🦛 可爱的分块吉祥物：悄悄告诉你，它是一只侏儒河马哦
❤️ Moto Moto 最喜欢的 Python 库

Chonkie 是一款“开箱即用”的分块库 ✨

📦 安装

基本安装

使用 pip：

pip install chonkie

或者使用 uv（更快）：

uv pip install chonkie

完整安装

Chonkie 遵循最小化安装原则。如果你有偏好的分块器，可以参考我们的文档，只安装你需要的部分。不想费心？那就直接安装 all 吧（不建议用于生产环境）。

使用 pip：

pip install "chonkie[all]"

或者使用 uv：

uv pip install "chonkie[all]"

🚀 使用

基本用法

以下是一个简单的入门示例：

# 首先从 Chonkie 中导入你想要使用的分块器
from chonkie import RecursiveChunker

# 初始化分块器
chunker = RecursiveChunker()

# 对一段文本进行分块
chunks = chunker("Chonkie 是最棒的小伙伴！我最喜欢的分块河马嘿嘿。")

# 访问分块结果
for chunk in chunks:
    print(f"分块内容: {chunk.text}")
    print(f"Token 数量: {chunk.token_count}")

流水线用法

你还可以使用 chonkie.Pipeline 将各个组件串联起来，处理复杂的流程。更多关于流水线的信息，请参阅文档！

from chonkie import Pipeline

# 创建一个包含多个分块和精炼步骤的流水线
pipe = (
    Pipeline()
    .chunk_with("recursive", tokenizer="gpt2", chunk_size=2048, recipe="markdown")
    .chunk_with("semantic", chunk_size=512)
    .refine_with("overlap", context_size=128)
    .refine_with("embeddings", embedding_model="sentence-transformers/all-MiniLM-L6-v2")
)

# 对文本进行分块！
doc = pipe.run(texts="Chonkie 是最棒的小伙伴！我最喜欢的分块河马嘿嘿。")

# 在 `doc` 对象中访问处理后的分块
for chunk in doc.chunks:
    print(chunk.text)

# 对于高吞吐量的应用，可以异步运行
import asyncio

async def main():
    doc = await pipe.arun(texts="Chonkie 跑得真快！")
    print(len(doc.chunks))

asyncio.run(main())

更多使用示例请查看文档！

🌐 API 服务器

将 Chonkie 部署为自托管的 REST API，轻松集成到任何应用中：

# 安装时包含 API 相关依赖（包括 catsu，用于多提供商嵌入）
pip install "chonkie[api,semantic,code,catsu]"

# 使用命令行启动服务器
chonkie serve

# 或者使用自定义选项
chonkie serve --port 3000 --reload --log-level debug

# 或者直接使用 uvicorn
uvicorn chonkie.api.main:app --host 0.0.0.0 --port 8000

也可以使用 Docker：

docker compose up

该 API 提供了所有分块器、精炼器以及 流水线 的端点——这些可重用的工作流配置存储在一个本地 SQLite 数据库中。

# 创建一个可重用的流水线
curl -X POST http://localhost:8000/v1/pipelines \
  -H "Content-Type: application/json" \
  -d '{
    "name": "rag-chunker",
    "steps": [
      {"type": "chunk", "chunker": "semantic", "config": {"chunk_size": 512}},
      {"type": "refine", "refinery": "embeddings", "config": {"embedding_model": "text-embedding-3-small"}}
    ]
  }'

# 列出你的流水线
curl http://localhost:8000/v1/pipelines

当服务器运行时，交互式文档可在 /docs 页面访问。

✂️ 分块器

Chonkie 提供了多种分块器，帮助您为 RAG 应用高效地拆分文本。以下是可用分块器的简要概述：

有关这些方法及其内部实现的更多信息，请参阅 文档。

🔌 集成

Chonkie 拥有 32 多种集成，涵盖分词器、嵌入提供商、LLM、精炼器、搬运工、向量数据库和实用工具，确保其能够无缝融入您现有的工作流。

def custom_token_counter(text: str) -> int:
    return len(text)

chunker = RecursiveChunker(tokenizer=custom_token_counter)

from chonkie import OpenAIGenie

genie = OpenAIGenie(model="meta-llama/llama-4-maverick",
                    base_url="https://openrouter.ai/api/v1",
                    api_key="your_api_key")

借助 Chonkie 丰富的集成选项，你可以轻松将其接入现有基础设施，立即开始 CHONKING！

📊 基准测试

“我可能是一只小河马，但我能量十足！” 🦛

Chonkie 不仅可爱，还非常快速高效！以下是它与竞争对手的对比：

体积📦

• Wheel 包大小： 505KB（相比之下，其他方案为 1–12MB）
• 安装后大小： 49MB（相比之下，其他方案为 80–171MB）
• 含语义功能时： 仍比最接近的竞争产品轻 10 倍！

速度⚡

• 按标记分块： 比最慢的替代方案快 33 倍
• 按句子分块： 几乎是竞争对手速度的 2 倍
• 语义分块： 最快可达其他方案的 2.5 倍

查看我们的详细 基准测试，了解 Chonkie 是如何超越竞争对手的！ 🏃‍♂️💨

🤝 贡献

想帮助 Chonkie 不断成长吗？请参阅 CONTRIBUTING.md，开始行动吧！无论是修复 bug、添加新功能，还是改进文档，每一份贡献都能让 Chonkie 成为更适合所有人的 CHONK 工具。

记住：对于这只小河马来说，没有太小的贡献！ 🦛

🙏 致谢

Chonkie 特别感谢所有用户和贡献者，正是你们的帮助才让这个库发展到今天的水平！你们的反馈、问题报告和改进建议，都让 Chonkie 变得更加 CHONKIEST。

当然，还要特别感谢 Moto Moto，他用那句经典名言为 Chonkie 打了广告：

“我喜欢大的，我喜欢 CHONK 的。” ~ Moto Moto

📝 引用

如果你在研究中使用了 Chonkie，请按如下方式引用：

@software{chonkie2025,
  author = {Minhas, Bhavnick AND Nigam, Shreyash},
  title = {Chonkie: 轻量级数据摄取库，用于构建快速、高效且稳健的 RAG 流程},
  year = {2025},
  publisher = {GitHub},
  howpublished = {\url{https://github.com/chonkie-inc/chonkie}},
}

Chonkie 快速上手指南

Chonkie 是一款轻量级、高性能的文本分块（Chunking）库，专为构建快速、高效的 RAG（检索增强生成）管道而设计。它支持多种分块策略、多语言处理，并能无缝对接主流向量数据库。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：Python 3.8 及以上
• 前置依赖：无特殊系统级依赖，仅需标准的 Python 环境。
• 网络要求：首次运行若使用特定 Tokenizer（如 tiktoken）或嵌入模型，需下载相关资源，建议确保网络通畅或使用国内镜像加速。

安装步骤

基础安装

仅安装核心分块功能（推荐用于生产环境，体积最小）：

pip install chonkie -i https://pypi.tuna.tsinghua.edu.cn/simple

或使用更快的 uv 工具：

uv pip install chonkie

全量安装

安装所有分块器、集成组件及依赖（适合本地测试，不推荐生产环境）：

pip install "chonkie[all]" -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

1. 简单分块示例

使用内置的 RecursiveChunker 对文本进行递归分块：

# 导入分块器
from chonkie import RecursiveChunker

# 初始化分块器
chunker = RecursiveChunker()

# 执行分块
text = "Chonkie is the goodest boi! My favorite chunking hippo hehe."
chunks = chunker(text)

# 遍历结果
for chunk in chunks:
    print(f"内容：{chunk.text}")
    print(f"Token 数：{chunk.token_count}")

2. 构建处理管道 (Pipeline)

通过 Pipeline 串联多个分块和优化步骤，实现复杂工作流：

from chonkie import Pipeline

# 构建管道：先递归分块，再语义分块，最后添加重叠上下文
pipe = (
    Pipeline()
    .chunk_with("recursive", tokenizer="gpt2", chunk_size=2048, recipe="markdown")
    .chunk_with("semantic", chunk_size=512)
    .refine_with("overlap", context_size=128)
)

# 运行管道
doc = pipe.run(texts="Chonkie is the goodest boi! My favorite chunking hippo hehe.")

# 输出处理后的分块
for chunk in doc.chunks:
    print(chunk.text)

3. 异步高并发处理

适用于高吞吐量场景：

import asyncio
from chonkie import Pipeline

async def main():
    pipe = Pipeline().chunk_with("recursive", chunk_size=512)
    doc = await pipe.arun(texts="Chonkie runs fast!")
    print(f"生成分块数量：{len(doc.chunks)}")

asyncio.run(main())