Chunkr：Lumina AI 推出的开源文档解析工具，支持 OCR、布局分析与语义分块

1. Chunkr是什么？

Chunkr是由Lumina AI开发的开源文档智能处理工具，核心功能是将PDF、PPT、Word、图片等复杂文档转化为适用于RAG（检索增强生成）和LLM（大语言模型）的结构化数据。该项目提供布局分析、OCR识别（含边界框标注）、结构化HTML/Markdown输出、视觉语言模型（VLM）处理等核心能力，支持自托管部署，并通过Docker Compose实现快速启动。项目采用AGPL-3.0开源许可与商业许可双模式，同时提供Cloud API（托管版）和Enterprise（企业版）满足不同场景需求——开源版适合开发测试，Cloud版面向生产 workload，Enterprise版针对大规模高安全场景。用户可灵活配置OpenAI、Google AI等主流LLM，快速搭建从文档解析到LLM应用的完整链路。

从核心价值来看，Chunkr解决了传统文档处理的两大痛点：

一是复杂文档的“非结构化”难题——PDF中的表格、图片、多栏文本，PPT的幻灯片布局，Word的嵌套格式等，传统工具难以精准提取结构；
二是文档数据与LLM/RAG的“适配鸿沟”——LLM需要结构化、片段化的“分块数据”（Chunks）才能高效检索与生成，而原始文档无法直接满足该需求，Chunkr通过“语义分块”能力直接输出“LLM友好型”数据。

需要特别注意的是，Chunkr并非单一工具，而是分三个版本的“文档智能服务体系”，各版本定位差异明确：

• 开源版（Open Source Repo）：基于社区开源模型开发，支持自托管，适合开发者实验、小团队测试，核心功能覆盖主流文档格式解析，但暂不支持Excel；

• Cloud API（chunkr.ai）：Lumina AI提供的全托管服务，采用 proprietary（专有）自研模型，在准确率、处理速度、可靠性上优于开源版，支持Excel原生解析，面向生产环境；

• Enterprise（企业版）：针对高安全、强合规行业（如金融、医疗），提供“托管部署”或“本地部署（On-prem）”选项，支持模型自定义微调、 domain-tuned OCR，并配备专属迁移与技术团队。

2. 核心功能特色

Chunkr的功能设计围绕“从文档到LLM/RAG的全链路适配”展开，既覆盖基础的文档解析能力，也包含面向AI应用的进阶功能，结合版本差异可分为以下核心模块：

2.1 基础功能：文档解析与结构化提取

这是Chunkr的核心能力，所有版本均具备基础支持，具体包括：

• 多格式文档兼容：
  开源版支持PDF、PPT、Word、图片（如JPG/PNG）；Cloud版与Enterprise版在此基础上新增Excel原生解析（开源版暂不支持），无需依赖第三方工具转换，直接提取表格数据与公式结构。

• 精准布局分析：
  识别文档中的元素类型（标题、正文、表格、图片、列表、页眉页脚等），并标注各元素的位置信息（边界框，Bounding Boxes）。例如，PDF中的多栏文本会被按“栏”拆分，PPT中的图文组合会被拆分为“文本块+图片块”，避免元素混淆。
  版本差异：开源版使用YOLO等社区开源模型（文档中提到“fix: replaced vgt with yolo model as it's more practical for consumer”），Cloud版用专有自研模型，Enterprise版可基于行业数据自定义微调。

• OCR识别与文字提取：
  对图片类文档（如扫描件PDF、拍照图片）进行光学字符识别（OCR），将不可编辑的图像文字转化为可检索的文本。同时输出文字的边界框信息，便于后续关联“文字位置-内容”。
  版本差异：开源版依赖社区OCR引擎（如Tesseract），Cloud版采用“优化后的OCR栈”（Optimized OCR stack），Enterprise版在此基础上增加“领域适配OCR”（如识别金融文档中的特殊符号、医疗报告中的专业术语）。

• 结构化输出格式：
  支持将解析后的内容导出为HTML或Markdown格式，保留原始文档的结构层级（如标题层级、列表缩进、表格结构）。例如，PPT中的幻灯片会被拆分为独立Markdown文件，每个文件包含“幻灯片标题+文本块+图片链接”，直接满足RAG的分块需求。

2.2 进阶功能：AI与LLM集成能力

Chunkr并非仅做“文档解析”，而是深度适配LLM/RAG场景，提供以下进阶功能：

• 视觉语言模型（VLM）处理：
  结合视觉模型与语言模型，理解“图文结合”的文档内容（如含图表的科研论文、含产品图的说明书）。例如，识别图表中的坐标轴含义、图例对应关系，并生成文字描述，帮助LLM更好地理解图表信息。
  版本差异：开源版仅支持基础开源VLMs（如LLaVA），Cloud版用“增强型专有VLMs”，Enterprise版可基于行业数据微调（如针对工程图纸、医疗影像的VLM）。

• 灵活的LLM配置：
  支持集成主流LLM提供商（OpenAI、Google AI、OpenRouter、自托管模型等），用户可根据成本、性能需求选择LLM，并通过配置实现“多LLM fallback”（默认模型失效时自动切换备用模型）。
  配置方式：提供两种方案——“models.yaml（推荐，支持多模型、速率限制）”和“环境变量（基础，单模型）”，详见“5. 详细使用方法”。

• 语义分块（Semantic Chunking）：
  不同于“按页数/固定长度”的机械分块，Chunkr基于文档语义逻辑拆分内容（如按“段落主题”“章节小节”“表格独立块”拆分），确保每个分块的“语义完整性”。例如，一篇论文的“实验方法”章节会被拆分为“实验设计-数据来源-分析工具”三个语义块，避免跨主题拆分导致LLM理解偏差。

2.3 部署与服务支持：适配不同场景需求

Chunkr在部署灵活性和服务支持上做了分层设计，满足从个人开发到企业级应用的需求：

• 部署方式：
  开源版支持“Docker Compose自托管”，提供GPU、CPU、Mac ARM（M1/M2/M3）三种部署配置，无需复杂环境依赖；Cloud版为“全托管服务”，用户无需关注基础设施，直接调用API；Enterprise版支持“托管部署”（Lumina AI维护）或“本地部署”（用户自有服务器），满足数据不出境需求。

• 服务支持：
  开源版依赖Discord社区支持（用户互助）；Cloud版提供“专属支持”（Dedicated support）；Enterprise版直接对接Lumina AI创始团队，提供“专属迁移团队”（如帮助用户从旧文档系统迁移至Chunkr）。

2.4 版本功能对比

为更清晰区分三个版本的差异，以下是官方提供的核心功能对比表：

3. 关键技术细节

Chunkr的技术设计围绕“易用性”“灵活性”“可扩展性”展开，核心技术细节集中在部署架构、模型选型、LLM配置机制三个方面：

3.1 部署架构：Docker Compose标准化

为降低部署门槛，Chunkr采用Docker Compose作为核心部署方案，将“文档解析服务”“API服务”“Web UI服务”“LLM适配服务”等封装为独立容器，用户无需手动安装依赖（如Python库、模型文件），仅需通过配置文件指定环境即可启动。

官方提供三种部署配置文件，适配不同硬件环境：

• compose.yaml：默认配置，适用于支持GPU的环境（需提前安装NVIDIA Container Toolkit），可加速模型推理（如布局分析、VLM处理）；

• compose.cpu.yaml：CPU-only配置，移除GPU依赖，适合无GPU的服务器或开发机；

• compose.mac.yaml：适配Mac ARM架构（M1/M2/M3芯片），解决ARM架构下容器兼容性问题（如部分模型库的ARM编译适配）。

部署架构的核心优势是“环境隔离”与“快速启停”——所有依赖均在Docker容器内，不会污染本地环境；通过docker compose up/down命令即可一键启动/停止所有服务，简化运维成本。

3.2 模型选型：开源与专有分层

Chunkr的模型选型遵循“版本定位匹配”原则，不同版本采用不同层级的模型，平衡“开源透明”与“商业性能”：

• 开源版模型：

• 布局分析：采用YOLO（目标检测模型），官方提到“YOLO更适合消费级场景”（more practical for consumer），替代原有的VGT模型；

• OCR：依赖Tesseract等社区开源OCR引擎，支持多语言识别，但对特殊字体、模糊文本的准确率较低；

• VLM：支持LLaVA、MiniGPT-4等开源视觉语言模型，可通过models.yaml配置自定义模型路径；

• Cloud/Enterprise版模型：

• 布局分析：专有自研模型，官方称其“准确率、速度优于开源模型”，支持更复杂的文档结构（如嵌套表格、动态多栏文本）；

• OCR：“优化后的OCR栈”，集成多引擎融合（如Tesseract+自研纠错模型），降低识别错误率；

• VLM：专有视觉语言模型，针对“文档场景”优化（如更好理解图表、公式、手写批注），Enterprise版可基于用户数据微调。

3.3 LLM配置机制：两种方案适配不同需求

Chunkr支持“多LLM集成”，并提供两种配置方案，满足从“快速测试”到“生产级灵活调度”的需求：

3.3.1 models.yaml（推荐，进阶配置）

适用于需要配置多个LLM、设置速率限制、指定默认/备用模型的场景，配置文件采用YAML格式，结构清晰且易维护。

核心能力：

• 配置多个LLM提供商（如同时集成OpenAI和自托管VLLM）；

• 为每个LLM设置“速率限制”（rate-limit，如每分钟200次请求），避免超量调用；

• 指定“默认模型”（default: true），API请求未指定模型时自动使用默认模型；

• 通过“模型ID”在API中指定使用的LLM（如model_id: gpt-4o）。

配置示例（来自官方models.example.yaml）：

models:
 - id: gpt-4o # 模型唯一ID，用于API调用
  model: gpt-4o # LLM模型名称（需与提供商一致）
  provider_url: https://api.openai.com/v1/chat/completions # 提供商API地址
  api_key: "your_openai_api_key_here" # 个人API密钥
  default: true # 设为默认模型
  rate-limit: 200 # 速率限制：每分钟200次请求（可选）
 - id: self-hosted-vllm # 第二个模型（自托管VLLM）
  model: llama3-70b # 自托管模型名称
  provider_url: http://localhost:8000/v1/chat/completions # 自托管API地址
  api_key: "empty" # 自托管模型可能无需API密钥
  rate-limit: 100 # 速率限制：每分钟100次请求

3.3.2 环境变量（基础配置）

适用于仅需单个LLM、快速测试的场景，通过.env文件设置三个核心变量，无需编写YAML格式：

• LLM__KEY：LLM提供商的API密钥（如OpenAI的sk-xxx）；

• LLM__MODEL：使用的模型名称（如gpt-3.5-turbo、llama3-8b）；

• LLM__URL：LLM提供商的API地址（如OpenAI的https://api.openai.com/v1/chat/completions）。

配置示例（来自.env.example）：

LLM__KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
LLM__MODEL=gpt-3.5-turbo
LLM__URL=https://api.openai.com/v1/chat/completions

3.4 可观测性与合规：OpenTelemetry与双许可

• 可观测性：开源版支持OpenTelemetry（文档中.dev/otel-collector目录提到“feat: added Open telemetry support for better analytics”），可收集服务调用日志、性能指标（如文档处理耗时、LLM响应时间），便于排查问题与优化性能；

• 许可模式：采用“双许可”策略——核心代码基于AGPL-3.0开源许可（用户需开源修改后的代码），同时提供商业许可（用户无需开源，需联系官方获取）。若企业商用且不愿开源修改，需购买商业许可，避免合规风险。

4. 典型应用场景

Chunkr的应用场景围绕“文档数据向LLM/RAG转化”展开，不同版本适配不同用户需求，具体可分为三类：

4.1 开发者/小团队：文档处理测试与轻量应用

目标用户：个人开发者、创业团队、高校实验室
核心需求：低成本验证文档解析方案，搭建轻量RAG/LLM应用，无需复杂基础设施
适配版本：开源版（Open Source Repo）
典型场景示例：

• 搭建“个人知识库RAG”：将PDF论文、Word笔记、PPT课件通过Chunkr解析为语义分块，存入向量数据库（如Pinecone），再集成LLM（如OpenAI GPT-3.5）实现“问答式检索”（如“查询论文中提到的实验方法”）；

• 开发“文档格式转换工具”：利用Chunkr的布局分析与结构化输出能力，将扫描件PDF（图片格式）转化为可编辑的Markdown，或把PPT批量转为HTML用于网页展示；

• 测试“多模态文档理解”：通过开源版的VLM功能，验证“图表+文本”类文档的解析效果，为后续产品迭代提供参考。

4.2 企业级生产：稳定可靠的文档智能化

目标用户：中小企业、互联网公司、非合规敏感行业
核心需求：高准确率、高可用性、低运维成本，支持Excel等全格式文档，需专业技术支持
适配版本：Cloud API（chunkr.ai）
典型场景示例：

• 客户支持知识库：将产品说明书（PDF/Word）、FAQ文档（PPT）通过Cloud API解析为RAG分块，集成到客服LLM系统，实现“用户提问→系统检索文档→生成精准回答”（如“用户问如何重置密码，系统自动检索说明书相关章节并生成步骤”）；

• 财务报表自动化处理：利用Cloud API的原生Excel解析能力，提取财务报表中的数据（如营收、成本），结构化后传入LLM生成“报表摘要”，减少人工整理时间；

• 内容管理系统（CMS）集成：将企业内部文档（如员工手册、流程规范）通过API自动解析为HTML，存入CMS系统，实现“文档上传→自动结构化→网页展示”的全流程自动化。

4.3 高安全合规：数据本地化与定制化

目标用户：金融机构（银行、保险）、医疗行业、政府部门
核心需求：数据不出境（本地部署）、模型自定义（适配行业术语）、强合规支持（如审计日志）、专属技术服务
适配版本：Enterprise（企业版）
典型场景示例：

• 银行信贷文档处理：将贷款申请材料（PDF扫描件、Excel财务数据）通过本地部署的Chunkr解析，OCR识别身份证、银行卡信息（领域适配OCR），布局分析提取收入证明中的关键数据，结构化后传入银行内部LLM生成“信贷风险评估初稿”，数据全程不离开银行服务器；

• 医院电子病历管理：将医生手写病历（图片）、检查报告（PDF）通过Enterprise版的VLM处理，识别病历中的诊断术语、检查结果，转化为结构化数据存入电子病历系统，同时生成“病历摘要”供医生快速参考，满足医疗数据隐私合规要求；

• 政府公文自动化：将政策文件（Word/PPT）通过本地部署的服务解析为语义分块，集成到政府内部RAG系统，实现“工作人员查询政策→系统精准返回相关条款”，同时支持公文格式的定制化解析（如特定红头文件的布局识别）。

5. 详细使用方法

Chunkr开源版的核心使用方式是“Docker Compose部署”，官方提供了清晰的步骤，适用于GPU、CPU、Mac ARM三种环境，以下是完整流程：

5.1 前置条件（Prerequisites）

在开始前需确保本地环境满足以下要求：

1. 安装Docker与Docker Compose（版本需支持Compose V2，推荐Docker Desktop 4.0+）；

2. 若使用GPU部署：安装NVIDIA Container Toolkit（用于Docker容器调用GPU，参考NVIDIA官方文档）；

3. 网络环境：需能访问GitHub（克隆仓库）、LLM提供商API（如OpenAI，若使用自托管LLM则无需）；

4. 硬件建议：GPU部署推荐NVIDIA GPU（显存≥8GB，支持CUDA 11.0+）；CPU部署推荐4核8GB以上配置；Mac ARM部署需M1及以上芯片。

5.2 步骤1：克隆代码仓库

打开终端，执行以下命令克隆GitHub仓库并进入项目目录：

# 克隆仓库
git clone https://github.com/lumina-ai-inc/chunkr
# 进入项目根目录
cd chunkr

5.3 步骤2：配置环境变量与LLM

Chunkr需要两个核心配置文件：.env（基础环境变量）和models.yaml（LLM配置，推荐），需从示例文件复制并修改：

5.3.1 复制环境变量示例文件

执行以下命令复制.env.example为.env（无需修改基础配置，后续LLM配置通过models.yaml完成）：

cp .env.example .env

5.3.2 配置LLM（models.yaml）

1. 复制LLM配置示例文件：

   cp models.example.yaml models.yaml

2. 编辑models.yaml文件，根据使用的LLM提供商填写配置（以OpenAI为例）：

   models:
    - id: gpt-4o # 自定义模型ID，如“gpt-4o”“self-hosted-llama”
     model: gpt-4o # LLM模型名称，需与提供商一致
     provider_url: https://api.openai.com/v1/chat/completions # 提供商API地址
     api_key: "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # 替换为你的OpenAI API密钥
     default: true # 设为默认模型（API请求未指定时使用）
     rate-limit: 200 # 可选，速率限制：每分钟200次请求

3. 若使用其他LLM提供商（如Google AI、自托管VLLM），参考以下配置模板（来自官方常见LLM提供商表格）：

5.4 步骤3：启动Chunkr服务

根据硬件环境选择对应的启动命令，首次启动会自动拉取Docker镜像（可能需要几分钟，取决于网络速度）：

5.4.1 GPU部署（推荐，需NVIDIA GPU）

docker compose up -d

• 说明：-d表示“后台运行”，启动后可通过docker compose logs -f查看服务日志。

5.4.2 CPU-only部署（无GPU）

docker compose -f compose.yaml -f compose.cpu.yaml up -d

• 说明：通过-f指定两个配置文件，覆盖默认的GPU依赖。

5.4.3 Mac ARM部署（M1/M2/M3芯片）

docker compose -f compose.yaml -f compose.cpu.yaml -f compose.mac.yaml up -d

• 说明：新增compose.mac.yaml适配ARM架构，解决容器兼容性问题。

5.5 步骤4：访问Chunkr服务

服务启动后，可通过以下地址访问Web UI和API：

• Web UI：http://localhost:5173（可视化操作界面，支持上传文档、查看解析结果、测试LLM集成）；

• API：http://localhost:8000（开发者接口，支持通过API上传文档、获取解析结果，具体接口文档可在Web UI中查看或参考GitHub README）。

Web UI使用示例：

1. 打开http://localhost:5173，点击“Upload Document”上传一个PDF文件；

2. 等待解析完成（进度条显示），解析后可查看“布局分析结果”（元素类型与边界框）、“OCR文本”（若为图片类文档）、“结构化Markdown”（可下载）；

3. 点击“Test LLM”，输入问题（如“总结该文档的核心内容”），系统会调用配置的LLM生成回答（基于解析后的分块数据）。

5.6 步骤5：停止Chunkr服务

使用完成后，执行以下命令停止服务（根据部署方式选择对应命令）：

• GPU部署停止：

  docker compose down

• CPU-only部署停止：

  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

• 说明：down命令会停止并移除容器，若需保留容器数据，可添加--volumes参数（如docker compose down --volumes，但会删除数据卷，谨慎使用）。

6. 常见问题解答（FAQ）

Q1：Chunkr开源版与Cloud API、Enterprise版的核心区别是什么？

A1：核心区别集中在模型能力、功能支持、基础设施、服务保障四个维度：

• 模型能力：开源版用社区模型（准确率较低），Cloud/Enterprise用专有模型（准确率、速度更优）；

• 功能支持：开源版不支持Excel，Cloud/Enterprise支持原生Excel解析；

• 基础设施：开源版需自托管（需维护硬件/软件），Cloud版全托管（无需运维），Enterprise版支持本地部署（数据不出境）；

• 服务保障：开源版依赖社区支持（无官方技术支持），Cloud版有专属支持，Enterprise版对接创始团队。
  若需生产环境使用，官方推荐Cloud API；若需数据本地化，选择Enterprise版；若仅测试，选择开源版。

Q2：开源版为什么不支持Excel？如何处理Excel文档？

A2：开源版暂未集成Excel解析功能（官方未明确说明原因，推测是优先保障核心格式稳定性）。若需处理Excel文档，有两种方案：

1. 升级至Cloud API或Enterprise版：两者提供“原生Excel parser”，可直接提取表格数据、公式、格式；

2. 临时转换：将Excel另存为CSV或PDF，再用开源版解析（但会丢失部分格式信息，如公式、合并单元格）。

Q3：如何切换LLM模型？比如从OpenAI切换为自托管VLLM。

A3：通过修改models.yaml文件实现，步骤如下：

1. 打开models.yaml，新增自托管VLLM的配置（参考5.3.2中的自托管模板）：

   models:
    - id: self-hosted-vllm
     model: llama3-8b
     provider_url: http://localhost:8000/v1/chat/completions # 自托管VLLM的API地址
     api_key: "empty" # 自托管模型无需API密钥
     default: true # 设为默认模型（替换原OpenAI模型）

2. 重启Chunkr服务（如GPU部署：docker compose down && docker compose up -d）；

3. 验证：在Web UI的“Test LLM”中提问，查看日志确认是否使用自托管模型（docker compose logs -f）。

Q4：部署时遇到“GPU无法识别”的错误，如何解决？

A4：该问题通常是NVIDIA Container Toolkit未正确安装，解决方案如下：

1. 检查GPU是否支持CUDA：执行nvidia-smi，若显示GPU信息则支持，否则需更换支持CUDA的GPU；

2. 重新安装NVIDIA Container Toolkit：参考官方安装指南，确保步骤正确；

3. 验证Docker GPU支持：执行docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi，若显示GPU信息则配置成功；

4. 若仍失败，改用CPU部署（执行5.4.2中的CPU启动命令）。

Q5：AGPL-3.0许可意味着什么？商用是否需要付费？

A5：AGPL-3.0是“强copyleft”开源许可，核心要求是：

• 若你修改了Chunkr的开源代码，且将修改后的版本用于“提供网络服务”（如部署在服务器上供他人使用），则必须开源你的修改代码；

• 若仅用于“个人本地测试”或“内部使用（不对外提供服务）”，则无需开源修改。

商用场景需分情况：

1. 若使用未修改的开源版，且仅内部使用（不对外提供服务）：无需付费，但需遵守AGPL-3.0的其他条款（如保留版权声明）；

2. 若修改开源版并对外提供服务：需开源修改代码，或购买官方商业许可（无需开源）；

3. 若使用Cloud API或Enterprise版：需按官方定价付费（商用许可已包含在服务中）。

如需商业许可，可通过邮件联系官方。

Q6：解析文档时出现“OCR识别错误”（如文字乱码、漏识别），如何优化？

A6：分版本提供优化方案：

• 开源版：

1. 确保文档清晰度：避免模糊、倾斜、低分辨率的图片/PDF；

2. 更换OCR引擎：若默认Tesseract效果差，可在models.yaml中配置其他开源OCR引擎（需修改对应服务的Docker配置）；

3. 增加预处理：先通过工具（如Adobe Acrobat）将扫描件PDF转为“可搜索PDF”，再用Chunkr解析；

• Cloud/Enterprise版：直接联系官方支持，提供错误文档样本，官方会优化OCR模型（专有模型支持迭代升级）。

7. 相关链接

• 代码仓库：https://github.com/lumina-ai-inc/chunkr

8. 总结

Chunkr是一套定位清晰、功能分层的开源文档智能处理基础设施，核心价值是打通“复杂文档→结构化数据→RAG/LLM应用”的链路，通过“开源版+Cloud版+Enterprise版”的分层设计，满足从开发测试到企业级高安全场景的需求。其优势在于：一是通过Docker Compose实现低门槛自托管，支持多硬件环境（GPU/CPU/Mac ARM）；二是提供灵活的LLM配置机制，兼容主流LLM提供商与自托管模型；三是结构化输出直接适配RAG/LLM，减少中间转换成本。对于开发者，开源版是免费实验文档解析与LLM集成的理想工具；对于企业，Cloud版提供生产级可靠性与全格式支持，Enterprise版则解决高安全合规场景的数据本地化需求。整体而言，Chunkr为不同规模、不同需求的用户提供了“从文档到AI”的一站式解决方案，是RAG/LLM应用落地中“文档预处理”环节的优质选择。