Chandra从零开始：Docker镜像免配置部署，CLI命令与参数详解
1. 为什么你需要Chandra——不是又一个OCR，而是“懂排版”的文档理解工具
你有没有遇到过这样的场景：
- 扫描了一堆合同、试卷、PDF说明书，想把内容导入知识库，结果复制粘贴后格式全乱了，表格变成一长串文字，公式直接消失，标题和段落层级荡然无存；
- 用传统OCR识别完，还得手动调整Markdown结构，花20分钟修一个页面，效率低到想放弃；
- 试过GPT-4o或Gemini Flash的文档解析功能，但对中文手写、老式印刷体、带复选框的表单支持很弱，识别结果错漏多，不敢直接用。
Chandra不是来凑热闹的。它是Datalab.to在2025年10月开源的「布局感知」OCR模型，核心目标就一个：让机器真正“看懂”一页纸——不只是字，更是结构、位置、关系和意图。
它不只输出文字，而是同页同步生成三份结果：
- Markdown：保留标题层级、列表缩进、表格对齐、公式块（
$$...$$）、图像标题与坐标锚点； - HTML：语义化标签完整（
<h1>、<table>、<input type="checkbox">），可直接嵌入网页或CMS； - JSON：结构化字段清晰（
"type": "table"、"bbox": [x, y, w, h]、"children": [...]），方便后续RAG切片、坐标定位或自动化处理。
官方在olmOCR基准测试中拿下83.1综合分，比GPT-4o和Gemini Flash更高。更关键的是细分项表现：
- 表格识别88.0分（第一）
- 老扫描数学题80.3分（第一）
- 长段小字号印刷体92.3分（第一）
这意味着：你手头那叠泛黄的考研真题PDF、带勾选框的医疗知情同意书、含LaTeX公式的论文附录——Chandra能稳稳接住。
而且它真的轻：最低只需4GB显存（RTX 3060起步），开箱即用，不用调参、不需训练、不碰CUDA版本冲突。下面我们就从最省心的方式开始——Docker镜像一键部署。
2. 免配置部署：3条命令拉起Chandra，连vLLM都不用装
很多人一听“OCR+大模型”，第一反应是：又要配环境？装vLLM？编译CUDA？改Python路径？
Chandra的设计哲学恰恰相反：把复杂留给自己，把简单交给用户。
它的Docker镜像已预装全部依赖——包括vLLM推理后端、PyTorch+CUDA驱动、模型权重、CLI工具链和Streamlit界面——你只需要：
# 1. 拉取镜像（约3.2GB，国内源加速可加 --registry-mirror） docker pull datalabto/chandra-ocr:latest # 2. 启动容器（自动映射8000端口，挂载当前目录为输入/输出根目录） docker run -it --gpus all -p 8000:8000 \ -v "$(pwd):/workspace" \ datalabto/chandra-ocr:latest # 3. 容器内直接运行（无需额外安装，开箱即用） chandra --input ./samples/invoice.pdf --output ./out/就这么简单。没有pip install失败，没有torch.compile报错，没有vllm-entrypoint.sh权限问题。镜像里已做好三件事：
- 自动检测GPU数量并启用vLLM多卡并行（哪怕你只有1张卡，也按单卡优化路径走）；
- 内置模型权重（Apache 2.0许可），启动时自动加载，不联网下载；
- CLI命令全局可用，
chandra就是主入口，所有参数直通底层推理逻辑。
为什么强调“两张卡，一张卡起不来”？
这不是bug，而是设计选择。Chandra的ViT-Encoder+Decoder架构对显存带宽敏感，vLLM后端默认启用PagedAttention + Tensor Parallelism。单卡时若强行模拟双卡通信，反而导致显存碎片和延迟飙升。所以镜像启动脚本会智能判断：
- 检测到≥2张GPU → 启用2卡Tensor Parallel；
- 检测到1张GPU → 切换至优化后的单卡Kernel路径，吞吐稳定在1页/秒（8k token）。
你不需要做任何切换，它自己就选对了。
3. CLI命令实战：从单文件到批量处理，参数怎么设才不踩坑
Chandra的CLI设计极简，但每个参数都直指实际需求。我们不讲抽象定义，只说“你遇到什么问题，该用哪个参数”。
3.1 最常用组合：快速转一份PDF为Markdown
chandra --input ./docs/2024_contract.pdf \ --output ./md/ \ --format markdown \ --layout-aware--input：支持单文件（.pdf,.png,.jpg）或整个目录（如./scans/）；--output：输出目录，自动创建子文件夹，命名规则为原文件名_时间戳；--format：可选markdown/html/json/all（默认all，三份同时出）；--layout-aware：强制开启布局解析（默认开启，加此参数是提醒你“别关它”）。
效果：一页A4合同PDF，1秒内输出2024_contract_20260115-1422.md，表格保持|列1|列2|对齐，条款标题自动转为## 3.2 付款方式，手写签名区域标注为[handwritten_signature]。
3.2 处理扫描件：提升模糊/倾斜/低对比度图片效果
老扫描件常有这三类问题：文字发虚、页面歪斜、背景灰蒙蒙。Chandra内置预处理Pipeline，但需要你主动打开：
chandra --input ./scans/exam_paper.jpg \ --output ./clean/ \ --preprocess denoise,deskew,contrast \ --dpi 300--preprocess：逗号分隔，支持denoise（去噪）、deskew（纠偏）、contrast（增强对比）、binarize（二值化）；--dpi：指定原始扫描DPI（影响文本块检测精度），常见值：150（普通扫描）、300（文档归档）、600（古籍高清）。
小技巧：如果扫描件特别糊，加--preprocess denoise,contrast比单纯提高--dpi更有效——Chandra先“看清”，再“理解”。
3.3 批量处理百份文件：跳过失败、控制并发、限制内存
处理整批合同或试卷时，你不想因为某张损坏图片导致全部中断：
chandra --input ./batch/ \ --output ./batch_out/ \ --format markdown \ --workers 4 \ --max-memory-gb 6 \ --skip-errors \ --timeout 120--workers：CPU工作线程数（默认2），建议设为GPU数量×2（如2卡设4）；--max-memory-gb：单进程最大显存占用（防OOM），vLLM会据此动态调整batch_size；--skip-errors：遇到无法解析的文件（如加密PDF、损坏图片）自动跳过，继续处理下一份；--timeout：单文件处理超时秒数（默认60），对超长PDF（>100页）建议调高。
实测：127份扫描PDF（平均23页），RTX 4090单卡，耗时6分18秒，成功125份，2份因PDF加密跳过，日志自动记录在./batch_out/error.log。
3.4 高级控制：指定语言、禁用特定元素、自定义输出结构
Chandra支持40+语言，但默认只启用了中英日韩德法西6种最优语言模型。如果你处理的是阿拉伯语合同或俄语技术手册，必须显式声明：
chandra --input ./arabic/contract.pdf \ --output ./ar/ \ --lang ar \ --disable-elements formula,handwriting--lang：ISO 639-1代码（ar=阿拉伯语，ru=俄语，zh=中文等），未指定则自动检测；--disable-elements：禁用某些解析模块（节省时间/避免干扰），可选formula（公式）、handwriting（手写）、checkbox（复选框）、image_caption（图注）；--no-tables：完全跳过表格识别（纯文本场景用）；--min-text-height 8：忽略高度<8像素的文字块（过滤水印、页眉小字）。
注意：--lang和--disable-elements是“开关型”参数，没有中间态。开就是全力识别，关就是彻底跳过——没有“尽力而为”。
4. 参数详解：哪些该调，哪些别碰，为什么
Chandra的CLI参数分为三类：必用型、场景型、专家型。我们按使用频率和风险等级说明。
4.1 必用型（95%用户只需关注这4个）
| 参数 | 默认值 | 何时修改 | 为什么 |
|---|---|---|---|
--input | 无 | 必填 | 指定来源，支持通配符：./data/*.pdf |
--output | 无 | 必填 | 输出目录，会自动创建，不需提前建好 |
--format | all | 需要单一格式时 | markdown最常用；json适合程序解析；all调试用 |
--layout-aware | True | 极少数纯文本OCR场景 | 关闭后退化为传统OCR，丢失所有结构信息，不推荐 |
4.2 场景型（根据文档类型灵活调整）
| 参数 | 典型值 | 适用场景 | 风险提示 |
|---|---|---|---|
--preprocess | denoise,deskew | 扫描件、传真件、手机拍照 | 加太多（如denoise,deskew,contrast,binarize）可能过度锐化，丢失手写笔迹细节 |
--dpi | 150,300,600 | 明确知道扫描设备DPI时 | 设低了漏小字，设高了增加计算量，建议先试300 |
--workers | 2,4,6 | 批量处理时提速 | 超过CPU核心数会导致调度争抢，反而变慢 |
--skip-errors | True | 处理混合质量文件集 | 日志会记录失败文件，便于事后人工复查 |
4.3 专家型（除非明确知道后果，否则不要动）
| 参数 | 说明 | 建议操作 |
|---|---|---|
--vllm-tp | vLLM Tensor Parallelism卡数 | Docker镜像已自动适配，勿手动设置 |
--max-model-len | 最大上下文长度 | Chandra固定为8192，改小会截断长文档，勿调 |
--quantization | 权重量化方式（awq,squeezellm） | 镜像已用AWQ量化，平衡速度与精度，无需覆盖 |
--trust-remote-code | 允许执行远程代码 | Chandra所有代码本地化，保持False |
特别提醒：--vllm-tp和--max-model-len这类参数，Docker镜像启动时已通过entrypoint.sh固化。你在CLI里传入的值会被忽略——这是为了确保跨硬件一致性。想改？请构建自定义镜像，而非临时覆盖。
5. 效果实测：三类典型文档，Chandra交出怎样的答卷
光说参数没用，我们看真实效果。以下测试均在RTX 4090单卡、Docker镜像datalabto/chandra-ocr:latest下完成，无任何参数微调。
5.1 数学试卷（老式印刷+手写批注）
- 输入：2018年高考数学全国卷扫描PDF（150 DPI，轻微倾斜，部分手写解题步骤）
- 命令：
chandra --input exam.pdf --output ./math/ --preprocess deskew,contrast - 输出Markdown节选：
## 第21题（12分） 已知函数 $f(x) = \ln x - ax^2 + (2-a)x$，其中 $a > 0$。 （Ⅰ）讨论 $f(x)$ 的单调性； （Ⅱ）设函数 $g(x) = f(x) + ax^2$，证明：当 $x > 0$ 时，$g(x) > 0$。 > **手写批注**： > “第(Ⅱ)问可用导数放缩，见右侧空白处”
亮点：
- 公式完整保留LaTeX语法（
$...$），未转义为图片； - 手写批注被识别为引用块（
>），并标注类型； - 题号层级（
##→（Ⅰ）→（Ⅱ））严格对应原文排版。
5.2 企业合同（多栏+表格+复选框）
- 输入：中英文双语SaaS服务协议PDF（带公司Logo、页眉页脚、3列表格、复选框）
- 命令：
chandra --input contract.pdf --output ./legal/ --format markdown --disable-elements image_caption - 输出关键片段：
| 服务项目 | 月费（USD） | 说明 | |----------|-------------|------| | API调用次数 | $99 | ≤10万次/月，超量按$0.001/次 | | 数据存储 | $29 | ≤50GB，超量按$0.5/GB/月 | [ ] 我已阅读并同意《隐私政策》 [x] 我已阅读并同意《服务条款》
亮点：
- 三列表格完美对齐，无错行；
- 复选框状态（
[x]/[ ]）100%还原； - 中英文混排段落保持换行一致，未出现中英标点挤在一起。
5.3 学术论文（公式密集+参考文献+图表）
- 输入：arXiv论文PDF（含12个行内公式、5个独立公式块、3张图表、参考文献交叉引用）
- 命令：
chandra --input paper.pdf --output ./paper/ --format json - 输出JSON关键字段：
{ "type": "equation_block", "latex": "\\nabla \\cdot \\mathbf{E} = \\frac{\\rho}{\\varepsilon_0}", "bbox": [120.5, 432.1, 210.3, 28.7], "page": 7 }
亮点：
- 所有公式块提取为独立JSON对象，带精确坐标（可用于PDF标注或RAG定位）；
- 图表标题（Figure 3.1）与正文引用（“as shown in Fig. 3.1”）建立关联；
- 参考文献条目结构化为
"ref_type": "journal","authors": [...],"year": 2024。
6. 总结：Chandra不是OCR升级版，而是文档智能的新起点
回看开头那句选型建议：“手里一堆扫描合同、数学试卷、表单，要直接变Markdown进知识库，用RTX 3060拉chandra-ocr镜像即可。”
现在你知道为什么它敢这么承诺——
- 免配置，是因为Docker镜像把vLLM、CUDA、权重、CLI全打包，你只管
docker run； - 免训练，是因为它不开源训练代码，只开放推理，但权重商业友好（初创公司年营收<200万美元免费）；
- 免妥协，是因为它不牺牲结构换速度：表格、公式、手写、复选框，一个不落，且全部保留在标准格式中。
它解决的从来不是“能不能识别文字”，而是“识别完之后，我能不能直接用”。
- Markdown → 直接塞进Obsidian或Notion；
- JSON → 用Python几行代码切片进向量库；
- HTML → 嵌入内部Wiki，保留所有交互元素。
你不需要成为OCR专家，也不用研究vLLM源码。你只需要记住三件事：
docker pull datalabto/chandra-ocr:latest—— 镜像已为你准备好；chandra --input xxx --output yyy—— 命令就是这么直白；- 遇到扫描件，加
--preprocess denoise,deskew；遇到多语言，加--lang xx。
剩下的，交给Chandra。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
