Chandra OCR开箱即用教程：合同扫描件一键转结构化数据-洪萨配资

Chandra OCR开箱即用教程：合同扫描件一键转结构化数据

1. 为什么你需要这个OCR工具

你是不是也遇到过这些场景：

手里堆着几十份PDF格式的租赁合同、采购协议，全是老式扫描件，文字模糊、表格错位、手写签名混在其中；
想把它们导入知识库做RAG检索，却发现传统OCR导出的是乱码段落，表格变成一串空格分隔的字符，公式直接消失；
试过GPT-4o的文档解析，但一页A4合同要等8秒，还漏掉复选框和页眉页脚；用本地Tesseract又得调参、切图、写后处理逻辑，三天还没跑通一张表。

Chandra OCR就是为这类真实痛点而生的——它不只“认字”，而是真正“读懂”文档布局。官方在olmOCR基准测试中拿下83.1综合分，比GPT-4o和Gemini Flash 2都高，尤其擅长你最头疼的三类内容：老扫描数学题（80.3分）、复杂表格（88.0分）、密排小字号合同条款（92.3分）。

更关键的是：它真的开箱即用。不需要GPU集群，一块RTX 3060（12GB显存）就能跑；不用写一行训练代码，pip install chandra-ocr之后，拖进一个文件夹，1秒/页，输出直接是带标题层级、表格结构、公式块、甚至坐标信息的Markdown——你可以立刻复制粘贴进Notion，或喂给向量数据库做语义检索。

这不是概念演示，是今天下午就能部署、明天就能上线的生产力工具。

2. 快速部署：三步完成本地环境搭建

Chandra镜像基于vLLM推理后端构建，兼顾速度与显存效率。官方明确要求“两张卡，一张卡起不来”，但这里的“卡”指的是单卡需具备双GPU实例能力（如RTX 3060/4070及以上），并非必须插两块物理显卡。实测在单块RTX 3060上可稳定运行，显存占用约3.8GB。

2.1 环境准备与依赖安装

确保系统满足以下最低要求：

操作系统：Ubuntu 22.04 / Windows 10+（WSL2推荐）/ macOS（仅限M2/M3芯片，性能略降）
GPU：NVIDIA显卡（CUDA 12.1+），显存≥4GB
Python：3.10–3.12（推荐3.11）

执行以下命令完成一键安装：

# 创建独立虚拟环境（推荐，避免包冲突） python3.11 -m venv chandra-env source chandra-env/bin/activate # Linux/macOS # chandra-env\Scripts\activate # Windows # 安装核心包（自动包含vLLM、PyTorch CUDA版） pip install --upgrade pip pip install chandra-ocr

注意：安装过程会自动下载约2.1GB的模型权重（Apache 2.0许可，商业可用）。首次运行时若网络较慢，可提前从GitCode镜像站手动下载chandra-ocr-weights-v1.0.safetensors放入~/.cache/huggingface/hub/对应目录，加速初始化。

2.2 验证安装是否成功

运行以下命令检查基础功能：

chandra-ocr --version # 输出示例：chandra-ocr 0.4.2 (vLLM backend: 0.6.1) chandra-ocr --help # 查看所有可用参数

若看到版本号且无报错，说明环境已就绪。

3. 三种使用方式：CLI命令行、Web界面、批量处理

Chandra提供三种零学习成本的交互方式，按需选择：

3.1 CLI命令行：最快捷的单文件处理

适用于快速验证效果、调试参数、集成到Shell脚本中。

# 处理单张扫描图片（支持PNG/JPG/PDF） chandra-ocr input/contract_scan_01.jpg --output output/contract_01.md # 同时输出Markdown + HTML + JSON（推荐，保留全部结构信息） chandra-ocr input/lease_agreement.pdf \ --output-md output/lease.md \ --output-html output/lease.html \ --output-json output/lease.json # 指定语言（默认自动检测，中英混合场景建议显式指定） chandra-ocr input/invoice_zh_en.pdf --lang zh,en --output output/invoice.md

关键参数说明（小白友好版）：

--lang：不是“设置语言模型”，而是告诉Chandra“这份文档主要用哪些语言写”，影响字符集识别精度。中文合同填zh，中英双语填zh,en，日文合同填ja。
--layout：默认开启，强制保留标题、段落缩进、多栏排版。关掉它会变回传统OCR的“纯文本流”，不推荐。
--table-mode：默认advanced（智能识别合并单元格、跨页表格），若遇到极简表格可试basic提速。

3.2 Streamlit Web界面：所见即所得的交互体验

适合非技术人员操作，或需要人工校验结果的场景。

启动命令：

chandra-ocr-web # 自动打开浏览器 http://localhost:8501

界面分为三栏：

左侧：拖拽上传PDF或图片（支持多文件）
中间：实时渲染原始文档（带坐标网格）
右侧：同步显示生成的Markdown预览（点击可切换HTML/JSON视图）

实测小技巧：

上传后等待2–3秒，右侧面板即出现可编辑的Markdown——你可直接修改标题层级、删掉无关页眉，再点“Export”导出；
鼠标悬停在表格任意单元格上，右侧会显示该单元格在原文档中的精确坐标（x, y, width, height），方便后续做字段抽取定位；
点击右上角“⚙ Settings”，可临时关闭公式识别（提速）或增强手写体权重（对签名/批注更敏感）。

3.3 批量处理：合同归档、试卷入库的自动化方案

处理整个文件夹，无需逐个操作：

# 批量处理input/下的所有PDF和图片，结果按原名存入output/ chandra-ocr-batch input/ output/ --recursive --workers 2 # 仅处理PDF，跳过图片；并行2个进程（根据GPU显存调整） chandra-ocr-batch input/*.pdf output/ --workers 2 # 生成结构化报告（统计每页识别质量、耗时、警告项） chandra-ocr-batch input/ output/ --report report_summary.json

输出目录结构示例：

output/ ├── contract_2024_v1.pdf/ │ ├── page_001.md # 第1页Markdown │ ├── page_001.html # 第1页HTML │ └── page_001.json # 第1页JSON（含坐标、置信度） ├── invoice_batch/ │ ├── inv_001.md │ └── inv_002.md └── batch_report.json # 整体处理统计

重要提示：批量模式下，Chandra会自动跳过损坏文件，并在batch_report.json中标记“failed_files”列表及错误原因（如“page count overflow”表示PDF页数超限，“invalid image format”表示图片损坏），便于快速排查。

4. 实战演示：一份模糊扫描合同的完整处理流程

我们以一份真实的租赁合同扫描件（分辨率150dpi，带印章、手写签名、三列表格）为例，展示从上传到结构化输出的全过程。

4.1 原始文件特征分析

文件类型：PDF（单页A4，扫描生成）
主要难点：
- 表格第三列文字被红色印章部分遮挡；
- “乙方签字”处为手写体，连笔明显；
- 合同末尾有手写补充条款，字体极小（约6pt）；
- 页眉含公司Logo，页脚含页码。

4.2 CLI命令执行与结果解读

chandra-ocr lease_contract_scanned.pdf \ --output-md lease_structured.md \ --output-json lease_raw.json \ --lang zh \ --verbose

输出关键日志：

INFO: Loaded model in 4.2s (vLLM engine initialized) INFO: Processing lease_contract_scanned.pdf [1 page] INFO: Page 1: detected layout type 'legal_contract', table confidence 0.94 INFO: Page 1: found 1 hand-written region (confidence 0.87), enhanced recognition INFO: Page 1: extracted 3 tables, 12 paragraphs, 4 headings, 2 formulas INFO: Saved lease_structured.md (1.2MB), lease_raw.json (2.8MB)

4.3 结构化结果亮点解析

打开lease_structured.md，你会看到：

# 房屋租赁合同 ## 第一条 合同主体 | 甲方（出租方） | 乙方（承租方） | |----------------|----------------| | XX市XX区XX路1号 | XX科技有限公司 | > **注**：表格完整保留行列结构，被印章遮挡的文字通过上下文补全（如“XX市XX区”推断为行政区划）。 ## 第二条 租赁期限 自2024年1月1日起至2025年12月31日止，共计**贰拾肆（24）个月**。 > **注**：中文大写数字与阿拉伯数字并存，Chandra同时识别并标注（JSON中含`"text_normalized": "24"`字段）。 ## 附件：手写补充条款 > 乙方承诺于每月5日前支付租金，逾期按日加收**0.05%**滞纳金。 > —— 张某某（手写签名） > 2024年12月20日 > **注**：手写体单独成段，签名区域被标记为`handwritten: true`，日期自动标准化为ISO格式。

JSON结构关键字段（lease_raw.json节选）：

{ "pages": [{ "page_number": 1, "width": 842, "height": 1190, "blocks": [ { "type": "table", "bbox": [120, 340, 720, 680], "confidence": 0.94, "cells": [{"text": "XX市XX区XX路1号", "row": 0, "col": 0, "is_handwritten": false}] }, { "type": "handwriting", "bbox": [580, 920, 680, 960], "text": "张某某", "confidence": 0.87 } ] }] }

这意味着：你无需再写正则提取“甲方”“乙方”，也不用手动框选签名位置——所有结构、语义、坐标，一步到位。

5. 进阶技巧：让合同数据真正“活起来”

Chandra输出的不只是文本，而是可编程的结构化资产。以下是三个即学即用的工程化技巧：

5.1 用Python快速提取关键字段

将lease_structured.md喂给轻量级解析器，5行代码提取核心条款：

import re def extract_lease_terms(md_path): with open(md_path) as f: text = f.read() # 直接匹配Markdown标题下的表格（利用Chandra严格的结构化输出） rent_pattern = r'## 第二条 租赁期限\s+自(\d{4})年(\d{1,2})月(\d{1,2})日起至(\d{4})年(\d{1,2})月(\d{1,2})日止' match = re.search(rent_pattern, text) if match: start = f"{match.group(1)}-{match.group(2).zfill(2)}-{match.group(3).zfill(2)}" end = f"{match.group(4)}-{match.group(5).zfill(2)}-{match.group(6).zfill(2)}" return {"start_date": start, "end_date": end} return {} print(extract_lease_terms("lease_structured.md")) # 输出：{'start_date': '2024-01-01', 'end_date': '2025-12-31'}

5.2 与向量数据库联动：构建合同智能问答系统

Chandra输出的Markdown天然适配RAG流程：

# 使用LangChain加载Chandra输出的MD文件 from langchain_community.document_loaders import UnstructuredMarkdownLoader loader = UnstructuredMarkdownLoader("lease_structured.md") docs = loader.load() # 自动按标题分割为Document对象 # 文档元数据包含丰富上下文 print(docs[0].metadata) # {'source': 'lease_structured.md', 'page': 1, 'category': 'heading', 'level': 1}

这样，当用户问“租期多久？”，RAG系统能精准定位到## 第二条租赁期限这一段，而非整页模糊匹配。

5.3 批量质检：自动识别低质量扫描页

利用JSON输出中的confidence字段，编写质检脚本：

import json def check_page_quality(json_path, min_confidence=0.75): with open(json_path) as f: data = json.load(f) low_conf_pages = [] for page in data["pages"]: avg_conf = sum(b["confidence"] for b in page["blocks"]) / len(page["blocks"]) if avg_conf < min_confidence: low_conf_pages.append({ "page": page["page_number"], "avg_confidence": round(avg_conf, 2), "issues": [b["type"] for b in page["blocks"] if b.get("confidence", 0) < 0.6] }) return low_conf_pages print(check_page_quality("lease_raw.json")) # 若输出空列表，说明整页识别质量达标