用 Chunkr 自托管把 PDF、PPT、Word 转成 RAG 可用的分块

Chunkr 是一个开源的文档智能服务，核心工作是把 PDF、PPT、Word 文档和图片做版面分析、OCR 识别与语义分块，最终输出结构化的 HTML、Markdown 和带坐标的分块结果，直接可以喂给 RAG 检索链路或大模型上下文。它适合两类人：一类是想在本地或自有服务器上跑通文档解析流水线、又不希望把文件交给第三方云服务的开发者；另一类是正在搭 RAG 系统、需要把杂乱版式的文档切成语义完整片段的后端工程师。如果你只是想快速验证效果，也可以先看站内的 Chunkr 工具页了解它处理文档的基本形态，再决定是否自托管。

需要先分清一件事：开源版本和托管云服务不是同一套东西。开源版本使用社区与开源模型，适合开发测试、需要透明可控或本地部署的场景；云服务跑的是自研模型，在准确率、速度和稳定性上更强，并且额外支持 Excel 文件的原生解析。开源版本不支持 Excel。本文只讲开源版本的自托管部署，涉及模型能力差异、价格与配额的部分，请以官网当前信息为准。

准备工作

在动手之前，把下面几项确认清楚，能省掉大部分启动失败。

• Docker 与 Docker Compose：这是唯一的运行前提，所有服务都通过 Compose 编排拉起。
• NVIDIA Container Toolkit：只有在需要 GPU 加速时才装。纯 CPU 部署可以跳过，但解析速度会明显下降。
• 一个大模型接口：Chunkr 的视觉语言模型处理环节需要调用 LLM。任何兼容 OpenAI 接口规范的端点都可以，包括自建的 vLLM 或 Ollama。
• 仓库代码：把项目克隆到本地，后续所有命令都在仓库根目录执行。

先把代码拉下来：

git clone <仓库地址>
cd chunkr

然后准备两份配置文件。项目里带了示例文件，复制成实际使用的文件名即可：

cp .env.example .env
cp models.example.yaml models.yaml

这两步不要跳过。.env 负责基础环境变量，models.yaml 负责模型清单，缺一个服务都起不来或者起来后无法处理文档。

操作步骤

第一步：按硬件选择启动命令

Chunkr 的 Compose 配置拆成了基础文件和若干覆盖文件，不同硬件组合不同的文件。三条命令对应三种环境，选一条执行即可。

有 GPU 的机器，直接用基础配置：

docker compose up -d

只有 CPU 的机器，叠加 CPU 覆盖文件：

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

Mac 的 ARM 架构（M1、M2、M3 等芯片），在 CPU 的基础上再叠加 Mac 覆盖文件：

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

-d 表示后台运行。第一次执行会拉取镜像，耗时取决于网络状况。启动完成后，Web 界面和 API 服务都会在本机端口上可用，具体端口以实际启动日志和配置文件为准。

第二步：配置大模型

Chunkr 提供两种配置 LLM 的方式，能力范围不同，建议优先用第一种。

方式一：models.yaml（推荐）

这种方式支持同时配置多个模型、设置默认模型与回退模型、给每个模型单独设定速率限制，并且在 API 请求里可以通过模型 ID 指定用哪一个。编辑 models.yaml，结构大致如下：

models:
  - id: gpt-4o
    model: gpt-4o
    provider_url: <服务端点地址>
    api_key: "your_api_key_here"
    default: true
    rate-limit: 200   # 每分钟请求数，可选

几个字段的含义：id 是这个模型在 Chunkr 内部的引用名，API 请求里用它来指定模型；model 是服务端真实的模型名；provider_url 是兼容 OpenAI 规范的接口地址；api_key 是访问凭证；default: true 把它设为默认模型；rate-limit 是分布式限流，单位是每分钟请求数，可以不填。

示例文件 models.example.yaml 里列了全部可用选项，配置前值得通读一遍，尤其是回退模型和限流相关的字段。

方式二：环境变量（基础）

如果只需要接一个模型，直接在 .env 里写三个变量更省事：

LLM__KEY=<你的密钥>
LLM__MODEL=<模型名>
LLM__URL=<兼容 OpenAI 的接口地址>

注意变量名是两个下划线，不是点也不是单下划线。这种方式不支持多模型、默认回退和按模型限流。

常见的接入来源包括 OpenAI 官方接口、Google AI Studio、OpenRouter，以及自建的 vLLM 或 Ollama。自建服务只要暴露了兼容 OpenAI 的端点，填进 LLM__URL 或 provider_url 就能用。各家接口地址与鉴权方式不同，以对应服务商当前文档为准。

第三步：重启服务让配置生效

改完 .env 或 models.yaml 之后，需要让容器重新读取配置。最稳妥的做法是先停再起，命令与启动时保持一致，把 up -d 换成 down：

# 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

停掉之后再用第二步里对应的启动命令重新拉起。如果只改了 .env，也可以只重启受影响的容器，但用完整的 down/up 流程更不容易出错。

第四步：确认服务可用

服务起来后有两个入口可以验证：Web 界面用来直观查看解析结果，API 用来接入你自己的程序。先打开 Web 界面传一份文档，看版面分析、OCR 框选和分块结果是否正常输出；确认无误后再去写 API 调用代码。如果 Web 界面能跑通但 API 报错，问题通常出在鉴权或请求体格式上，而不是模型配置。

一个完整示例

下面走一遍从零到拿到分块结果的最小流程。假设你在一台有 GPU 的 Linux 机器上，已经装好 Docker 和 NVIDIA Container Toolkit。

1. 拉代码并进入目录

git clone <仓库地址>
cd chunkr

2. 生成配置文件

cp .env.example .env
cp models.example.yaml models.yaml

3. 填入模型信息

编辑 models.yaml，写入一个可用的模型条目。这里以兼容 OpenAI 接口的端点为例：

models:
  - id: default-model
    model: <模型名>
    provider_url: <接口地址>
    api_key: "<密钥>"
    default: true
    rate-limit: 200

4. 启动全部服务

docker compose up -d

5. 打开 Web 界面验证

在浏览器访问本机对应的 Web 界面端口，上传一份带表格和图片的 PDF。观察输出里是否包含：按版面切分出的区块、OCR 识别出的文字及其边界框、以及最终的结构化 Markdown 或 HTML。这三样都正常，说明整条流水线是通的。

6. 通过 API 处理文档

Web 界面验证通过后，就可以用 API 把处理流程接进自己的系统。请求里可以按 models.yaml 中定义的 id 指定使用哪个模型；不指定时走 default: true 的那个。具体的接口路径、请求字段和返回结构以项目文档为准，不同版本之间可能有调整。

7. 用完停掉服务

docker compose down

如果是 CPU 或 Mac ARM 环境，第 4 步和第 7 步换成前面给出的对应命令即可，其余步骤完全一致。

注意事项

开源版与云服务的模型不同。开源版本用的是社区与开源模型，云服务用的是自研模型。这意味着同一份文档在两边跑出来的准确率和速度会有差距，不要拿开源版的结果去推断云服务的表现，反过来也一样。

Excel 支持是分版本的。开源版本不支持 Excel 文件，云服务和 Enterprise 版本才有原生解析能力。如果你的文档集里有大量表格类 Excel，开源路线需要另想办法。

许可证是双轨的。项目核心采用 AGPL-3.0，另有商业许可。AGPL-3.0 对通过网络提供服务的使用方式有传染性要求，如果你打算把 Chunkr 作为对外服务的一部分部署，需要先确认自己的使用方式是否落在 AGPL 条款范围内；不打算遵守 AGPL 条款的话，需要走商业许可。这是法律层面的判断，具体条款请查阅许可证原文并咨询专业人士。

硬件覆盖文件不能混用。CPU 和 Mac ARM 的启动命令必须带上对应的覆盖文件，只跑 docker compose up -d 在无 GPU 的机器上会失败。反过来，有 GPU 的机器不需要叠加 CPU 文件。

环境变量名容易写错。LLM__KEY、LLM__MODEL、LLM__URL 用的是双下划线。写成单下划线或点号，服务读不到配置，表现为文档处理时模型调用失败。

两种 LLM 配置方式的取舍。环境变量方式只支持单个模型，没有默认与回退机制，也没有按模型的限流。生产环境建议用 models.yaml，至少配一个回退模型，避免主模型限流或故障时整条流水线卡死。

限流要按实际配额设置。rate-limit 的单位是每分钟请求数，填多少取决于你所接模型服务商的实际配额。填得比配额高不会提速，只会换来大量 429 错误；填得太低则浪费吞吐。具体配额以服务商当前信息为准。

版本与功能会变。本文涉及的启动命令、配置字段和模型能力描述，都可能随项目迭代调整。部署前请以项目当前文档和官网信息为准，尤其是价格、配额、模型清单这类易变内容。