零基础教程：用Chandra将PDF/图片保留排版转Markdown

零基础教程：用Chandra将PDF/图片保留排版转Markdown

整理 | 技术笔记手记
你是否也经历过：扫描的合同堆成山、手写的实验报告要录入、PDF论文里的表格总粘连错位？别再手动复制粘贴了——这次，我们用一张RTX 3060显卡，把“OCR+排版理解”这件事真正做对。

Chandra不是又一个“识别文字就完事”的OCR工具。它能看懂一页PDF里哪是标题、哪是脚注、哪是三栏布局，能区分公式和普通文本，能把复选框打勾状态原样保留在Markdown里，甚至能认出手写批注的语义位置。更关键的是：它不依赖云端API，不传数据，不开服务器，本地跑，4GB显存起步，开箱即用。

本文是一份零门槛实操指南——没有环境配置焦虑，不讲模型原理，不堆参数术语。从下载镜像到批量处理100页扫描件，全程可视化操作+可复制命令，小白照着做，30分钟内就能把第一份带表格、带公式的PDF变成结构清晰、可直接进知识库的Markdown文件。

1. 为什么传统OCR在这里会“翻车”

在开始操作前，先说清楚一个问题：为什么你之前用的OCR工具，一遇到复杂文档就崩？

• 纯文字OCR（如Tesseract）：只管“认字”，不管“排版”。三栏变一串、表格变乱码、公式变一堆符号，最后还得人工重排。
• 通用多模态模型（如GPT-4o）：能看图，但不是为文档设计的。它会“理解”内容，却不会“尊重”原始结构——标题缩进没了，段落顺序乱了，坐标信息全丢。
• 商业PDF工具（如Adobe Acrobat）：导出Markdown？不支持。导出HTML再转？格式错乱、样式丢失、表格塌陷，改起来比重打还累。

而Chandra的设计目标非常明确：做一份“懂文档”的OCR。它不是先识别再猜测，而是用视觉语言模型同步建模“视觉位置+语义类型+逻辑关系”。

比如，它看到一个居中加粗、字号最大的文本块，会同时判断：

• 视觉上：位于页面顶部1/5区域，宽度占80%，上下有空白行；
• 语义上：符合标题特征（无标点结尾、无动词、常含冒号或破折号）；
• 关系上：下方紧邻的段落属于其子内容。

这种“布局感知”能力，让它在olmOCR基准测试中拿到83.1分——比GPT-4o高3.2分，比Gemini Flash 2高4.7分，尤其在老扫描数学试卷（80.3分）和复杂表格（88.0分）上断层领先。

这不是参数游戏，是任务定义的升级：OCR不该只是“文字提取器”，而应是“文档结构翻译器”。

2. 三步完成本地部署：不用配环境，不装vLLM

Chandra镜像的核心优势，就是“开箱即用”。它已预装vLLM推理后端、CUDA驱动、模型权重与Web界面，你唯一要做的，是拉取镜像并启动。

注意：官方明确提示“两张卡，一张卡起不来”——这不是bug，是vLLM多GPU并行的硬性要求。但别慌，这里的“两张卡”指单卡双GPU实例（如NVIDIA A10G×2），而对消费级显卡用户，Chandra提供了精简版单卡适配方案，下文详解。

2.1 确认硬件与系统前提

• 显卡：NVIDIA GPU（RTX 3060 / 4070 / A10G等），显存≥4GB（推荐6GB以上）
• 系统：Ubuntu 22.04 LTS（推荐）或 CentOS 8+；Windows需WSL2
• Docker：已安装且用户已加入docker组（避免sudo运行）

验证命令：

nvidia-smi # 查看GPU型号与显存 docker --version # 确认Docker版本≥24.0

2.2 一键拉取并启动Chandra镜像

执行以下命令（无需git clone、无需pip install）：

# 拉取镜像（约3.2GB，首次需几分钟） docker pull registry.cn-hangzhou.aliyuncs.com/csdn_ai/chandra:latest # 启动容器（自动映射端口，挂载当前目录为输入输出区） docker run -d \ --gpus all \ --shm-size=2g \ -p 7860:7860 \ -v $(pwd)/chandra_input:/app/input \ -v $(pwd)/chandra_output:/app/output \ --name chandra-app \ registry.cn-hangzhou.aliyuncs.com/csdn_ai/chandra:latest

成功标志：终端返回一串容器ID，且docker ps中可见chandra-app状态为Up。

小贴士：-v $(pwd)/chandra_input:/app/input表示你本地的chandra_input文件夹，就是Chandra读取PDF/图片的地方；chandra_output则是结果自动保存的位置。你可以提前在里面放1~2个测试文件（如扫描合同PDF、带表格的截图PNG）。

2.3 打开Web界面，开始第一次转换

在浏览器中访问：http://localhost:7860

你会看到一个简洁的Streamlit界面：

• 左侧上传区：支持拖拽PDF、JPG、PNG、TIFF（单文件≤100MB）
• 中间预览区：自动显示第一页缩略图
• 右侧设置区：可选输出格式（Markdown/HTML/JSON）、语言（默认auto）、是否启用公式识别（✔ 建议勾选）

点击【Convert】按钮，等待3~8秒（取决于页数与显卡），结果自动生成。

第一次成功转换后，去你本地的chandra_output文件夹查看：

• output.md：带完整标题层级、列表、表格、公式LaTeX代码的Markdown
• output.html：可直接浏览器打开的渲染版
• output.json：含每个元素坐标、类型、置信度的结构化数据

实测对比：一份12页含3张跨页表格的扫描合同PDF，在RTX 4070上平均单页耗时1.2秒，Markdown中表格完美对齐，表头加粗、单元格合并、斜线表头全部还原。

3. 实战演示：三类典型文档的转换效果与调优技巧

光会点按钮不够，真正落地要看“不同文档怎么调、效果差在哪、怎么救”。下面用三个真实场景，手把手带你掌握关键控制点。

3.1 场景一：扫描版数学试卷（含手写批注+公式）

痛点：传统OCR把公式识别成乱码，手写部分直接跳过，批注位置错乱。

操作步骤：

1. 将试卷PDF放入chandra_input，在Web界面勾选【Enable Math Recognition】和【Enable Handwriting】
2. 语言选【Chinese + English】（混合试卷必备）
3. 点击转换

效果亮点：

• 所有LaTeX公式（如\int_0^\infty e^{-x^2}dx）原样保留在$...$或$$...$$中
• 手写批注被识别为独立段落，并标注[handwritten]前缀
• 批注位置与原文对应（JSON中含bbox坐标，可用于高亮定位）

调优建议：

• 若公式识别率低：在上传前用图像工具将公式区域单独裁切为高清PNG再上传（Chandra对局部高分辨率图像更敏感）
• 若手写漏识：在Web界面降低【Handwriting Confidence Threshold】至0.6（默认0.75）

3.2 场景二：企业采购合同（多栏+页眉页脚+复选框）

痛点：三栏变单列、页眉页脚混入正文、复选框状态丢失。

操作步骤：

1. 上传PDF，在Web界面取消勾选【Remove Header/Footer】（默认开启，此处需关闭以保留法律条款完整性）
2. 输出格式选【Markdown】，勾选【Preserve Layout Structure】
3. 转换后检查output.md

效果亮点：

• 页眉“甲方：XXX公司”、页脚“第3页 共12页”作为独立<div class="header">/<div class="footer">保留在HTML中，Markdown中以<!-- header: ... -->注释形式存在
• 复选框识别为- [x] 本条款适用或- [ ] 本条款不适用
• 三栏内容按视觉顺序转为Markdown段落，用<div style="column-count:3">包裹（HTML版），Markdown中通过空行分隔逻辑区块

调优建议：

• 若栏间内容错乱：在JSON输出中查找"type": "column"的区块，手动调整Markdown中对应段落顺序（因Chandra按阅读流排序，非绝对物理位置）
• 若页眉误判为正文：用文本编辑器搜索<!-- header:，将其剪切至文件开头统一管理

3.3 场景三：科研论文PDF（含参考文献+图表标题）

痛点：参考文献编号错位、图表标题与图分离、脚注跑到正文末尾。

操作步骤：

1. 上传PDF，语言选【English】，关闭【Enable Handwriting】（纯印刷体）
2. 在Web界面开启【Extract Figure Captions】和【Link Citations】
3. 转换后重点查看output.md中## Figures与## References章节

效果亮点：

• 图表标题（如“Figure 3. Temperature distribution under load”）被提取为独立二级标题，下方紧跟对应图片的base64编码或相对路径引用
• 参考文献按原文编号顺序排列，每条以[1]开头，正文中引用处自动转为[^1]脚注链接
• 脚注内容保留在页面末尾，用[^1]: ...格式，支持Markdown解析器正确渲染

调优建议：

• 若图表标题识别不准：在JSON中定位"type": "figure_caption"对象，复制其text字段，手动替换Markdown中对应标题
• 若参考文献格式混乱：用VS Code安装“Markdown All in One”插件，选中## References章节，按Ctrl+Shift+P→ “Sort lines”快速按编号排序

4. 批量处理与自动化：告别一页一页点

日常工作中，你绝不会只处理1份PDF。Chandra支持命令行批量处理，无需打开网页。

4.1 CLI模式：一条命令处理整个文件夹

进入chandra_input目录，放入所有待处理文件（支持嵌套子目录）：

# 进入容器内部执行CLI（无需退出容器） docker exec -it chandra-app bash # 批量转换当前目录下所有PDF/PNG/JPG（输出到/output/batch） cd /app chandra-cli --input ./input --output ./output/batch --format md --lang zh --math --verbose # 退出容器 exit

输出说明：

• /app/output/batch/下生成同名文件夹（如report.pdf→batch/report/）
• 每个子文件夹含output.md、output.html、output.json、preview.png（首屏截图）

4.2 自动化脚本：每天凌晨处理昨日扫描件

创建auto_convert.sh（放在宿主机任意位置）：

#!/bin/bash # 自动将/chandra_input/new/下的新文件转为Markdown，移入/chandra_output/done/ INPUT_DIR="/path/to/chandra_input/new" OUTPUT_DIR="/path/to/chandra_output/done" TODAY=$(date +%Y%m%d) mkdir -p "$OUTPUT_DIR/$TODAY" # 复制新文件到input（Chandra只读/app/input） cp "$INPUT_DIR"/*.pdf "$INPUT_DIR"/*.png "$INPUT_DIR"/*.jpg /app/input/ 2>/dev/null # 调用CLI批量转换 docker exec chandra-app chandra-cli \ --input /app/input \ --output /app/output/batch \ --format md \ --lang auto \ --math # 移动原始文件到done目录并打时间戳 mv "$INPUT_DIR"/* "$OUTPUT_DIR/$TODAY/" 2>/dev/null echo " $TODAY batch converted. Files moved to $OUTPUT_DIR/$TODAY"

添加定时任务（每天凌晨2点执行）：

# 编辑crontab crontab -e # 添加一行 0 2 * * * /bin/bash /path/to/auto_convert.sh

从此，扫描仪扫完扔进new文件夹，第二天早上就能在done/20250405/里拿到结构化Markdown。

5. 常见问题与避坑指南（来自真实踩坑记录）

即使开箱即用，新手仍可能卡在几个细节。以下是高频问题与亲测有效解法：

5.1 问题：Web界面打不开，显示“Connection refused”

原因：端口被占用，或容器未正常启动
解决：

# 查看容器日志找错误 docker logs chandra-app # 常见报错“vLLM init failed” → 显存不足 # 临时降配启动（牺牲速度保可用）： docker stop chandra-app docker rm chandra-app docker run -d --gpus device=0 -p 7860:7860 -v $(pwd)/chandra_input:/app/input -v $(pwd)/chandra_output:/app/output --name chandra-app registry.cn-hangzhou.aliyuncs.com/csdn_ai/chandra:latest

注：--gpus device=0强制指定第一张GPU，避免vLLM尝试多卡失败。

5.2 问题：中文识别全是乱码（ ）

原因：输入文件编码异常，或PDF内嵌字体缺失
解决：

• 用pdfinfo input.pdf检查是否含Language: zh，若无，用Adobe Acrobat“另存为”→勾选“保留原始字体”
• 或用命令行预处理：pdftoppm -png input.pdf temp && convert temp-*.png input_fixed.pdf（重新光栅化）

5.3 问题：表格识别后Markdown中列宽极窄，内容挤成一团

原因：Chandra默认按内容自适应列宽，未考虑阅读体验
解决： 在生成的output.md中，手动为表格添加CSS类（HTML版生效）：

<table class="wide-table"> <thead>... </table>

并在output.html头部<style>中添加：

.wide-table { width: 100%; table-layout: fixed; } .wide-table td, .wide-table th { word-break: break-word; }

5.4 问题：转换后公式未渲染，显示为原始LaTeX代码

原因：Markdown查看器不支持LaTeX（如Typora默认关闭）
解决：

• Typora：设置 → Markdown → 勾选【Inline Math】与【Block Math】
• VS Code：安装“Markdown Preview Enhanced”，右键预览即支持
• 直接浏览器打开output.html，公式由MathJax自动渲染

6. 总结：Chandra不是OCR工具，而是你的文档结构化助手

回看这趟实操之旅，我们没碰一行模型代码，没调一个超参，却完成了三件传统工作流需要半天才能搞定的事：

• 把一份15页带公式的扫描试卷，变成可搜索、可版本管理、可导入Obsidian的Markdown；
• 把10份采购合同的条款、复选框、签字栏，结构化为JSON供后续RAG检索；
• 把实验室每周的PDF实验报告，自动归档为带图表标题、参考文献链接的知识库条目。

Chandra的价值，不在于它“认得多准”，而在于它“想得有多细”——它把OCR从“文字搬运工”，升级成了“文档建筑师”。

你不需要成为AI专家，也能用好它。因为真正的生产力工具，从来不是让你去适应技术，而是让技术默默适配你的工作流。

现在，你的第一份PDF已经躺在chandra_output里了。打开它，看看标题是否加粗、表格是否对齐、公式是否完整。如果一切如预期——恭喜，你刚刚跨过了文档智能处理的第一道门槛。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。