快速入手
Chunkr 提供两种入门方式，云服务和本地部署。
方式一：云服务（最快）
访问官方网站chunkr.ai，创建账户并复制API密钥。
本地再安装 Python SDK
pipinstallchunkr-ai
Python 调用示例：
fromchunkr_aiimportChunkr
# 使用您的 API 密钥进行初始化
chunkr = Chunkr(api_key="your_api_key")
# 上传文档（URL 或本地文件路径）
url ="https://chunkr-web.s3.us-east-1.amazonaws.com/landing_page/input/science.pdf"
task = chunkr.upload(url)
# 以多种格式导出结果
html = task.html(output_file="output.html")
markdown = task.markdown(output_file="output.md")
content = task.content(output_file="output.txt")
task.json(output_file="output.json")
# 清理资源
chunkr.close()方式二：Docker 本地部署
前置要求：
• Docker 和 Docker Compose 已安装在您的系统上 • 8GB+ 可用内存（建议 16GB） • NVIDIA GPU（可选，用于获得更好的性能）
第 1 步：克隆项目
gitclonehttps://github.com/lumina-ai-inc/chunkr
cdchunkr第 2 步：配置环境
复制示例配置文件：
# 复制环境变量文件
cp.env.example .env
# 复制 LLM 模型配置文件
cpmodels.example.yaml models.yaml再编辑 models.yaml 来配置您的 LLM 提供商。这是最重要的一步——Chunkr 使用 LLM 进行智能文档处理：
models:
# OpenAI 配置示例
-id: gpt-4o
model: gpt-4o
provider_url: https://api.openai.com/v1/chat/completions
api_key:"your_openai_api_key_here"
default:true
rate-limit: 200# 每分钟请求数 - 可选
# 备用模型（必需）
-id: gemini-2.0-flash-lite
model: gemini-2.0-flash-lite
provider_url: https://generativelanguage.googleapis.com/v1beta/openai/chat/completions
api_key:"your_google_ai_studio_api_key_here"
fallback:true关键点：
• 必须有且仅有一个模型设置为 default: true• 必须有且仅有一个模型设置为 fallback: true• 可以添加多个模型，并在 API 请求中通过 ID 引用它们 • rate-limit是可选的，但建议在生产环境中使用
第 3 步：启动服务
根据系统选择合适的命令：
# 对于拥有 NVIDIA GPU 的系统（推荐）：
docker compose up -d
# 对于仅 CPU 的系统：
docker compose -f compose.yaml -f compose.cpu.yaml up -d
# 对于 Mac ARM 架构（M1, M2, M3 等）：
docker compose -f compose.yaml -f compose.cpu.yaml -f compose.mac.yaml up -d第 4 步：验证安装
服务运行后，验证一切是否正常工作：
•检查 Web UI：在浏览器中打开 http://localhost:5173•检查 API：访问 http://localhost:8000/health查看 API 状态•通过 Web 界面上传测试文档
第 5 步：处理你的第一个文档
现在 Chunkr 已经运行，让我们使用本地 API 处理一个文档：
import requests
# 本地 API 端点
API_URL ="http://localhost:8000"
# 上传文档
with open("your-document.pdf","rb") as f:
response = requests.post(
f"{API_URL}/api/v1/document/upload",
files={"file": f},
headers={"Authorization":"Bearer your-api-key"}
)
task_id = response.json()["task_id"]
# 检查状态
status_response = requests.get(
f"{API_URL}/api/v1/task/{task_id}",
headers={"Authorization":"Bearer your-api-key"}
)
print(status_response.json())第 6 步：管理服务
完成后，也可以停止服务：
# 对于 GPU 部署：
docker compose down
# 对于仅 CPU 部署：
docker compose -f compose.yaml -f compose.cpu.yaml down
# 对于 Mac ARM 架构：
docker compose -f compose.yaml -f compose.cpu.yaml -f compose.mac.yaml down应用场景
•文档问答：解析 PDF/Word/PPT 生成干净的结构化语料 •企业知识库：自动将内部资料转换为 AI 可用的分块数据 •OCR 场景：保留文字位置坐标，方便做表格/图文混排处理 •RAG 系统：直接将输出的 JSON/Markdown 接入检索增强生成
写在最后
Chunkr以其强大的文档处理能力，将PDF、PPTX、DOCX、Excel和图像转为RAG/LLM-ready的结构化数据，支持OCR、语义分块和多格式输出。
在 GitHub 已经收获了 2.6K Star，很受用户的青睐和使用。
相比传统的 Docling、olmOCR 这种单一文档解析工具，Chunkr 集 OCR、文档解析、分块、格式化于一体，非常适合直接做文档问答或知识库的底层能力