Chandra OCR部署教程：基于vLLM的本地OCR服务搭建，支持HTTP API调用

Chandra OCR部署教程：基于vLLM的本地OCR服务搭建，支持HTTP API调用

1. 为什么你需要一个“布局感知”的OCR？

你有没有遇到过这样的场景：

• 扫描了一堆合同、试卷、带表格的PDF，想直接转成可编辑的Markdown放进知识库，结果传统OCR只给你一堆乱序文字？
• 用GPT-4o或Gemini Flash识别数学公式，结果符号错位、上下标丢失、表格变成段落堆砌？
• 手写笔记拍照后，连笔字识别失败，复选框被当成墨点，图注和坐标信息全丢？

Chandra 就是为解决这些“真痛点”而生的。它不是又一个“把图片变文字”的OCR，而是真正理解页面结构的视觉语言模型——能一眼看懂“这是标题、这是表格第3行第2列、这是手写签名区、这是LaTeX公式块”，然后原样保留逻辑关系输出。

一句话说透它的价值：4 GB显存就能跑，83.1分精度（olmOCR基准），表格/手写/公式/表单一次识别到位，输出直接是结构化Markdown，不用再手动整理排版。

这不是概念演示，而是开箱即用的工程方案。下面我们就从零开始，用vLLM在本地搭起一个稳定、快速、可集成的Chandra OCR服务，支持HTTP API调用，真正嵌入你的工作流。

2. 环境准备：最低配置也能跑起来

Chandra对硬件非常友好。官方明确标注：RTX 3060（12GB显存）或A10（24GB）即可流畅运行；如果你只有RTX 3090（24GB）或4090（24GB），甚至能开多卡并行处理长文档。最关键的是——它不挑卡，不依赖特定驱动版本，也不需要编译CUDA扩展。

我们采用vLLM作为推理后端，原因很实在：

• vLLM的PagedAttention机制大幅降低显存碎片，让Chandra在有限显存下支持更长上下文（单页最高8k token）；
• 原生支持HTTP API服务，无需额外封装Flask/FastAPI；
• 多GPU自动负载均衡，两张卡时吞吐翻倍，但一张卡也能完整启动（网上流传的“两张卡才能起”是旧版误解，已修复）。

2.1 系统与依赖检查

请先确认你的环境满足以下基础条件：

• 操作系统：Ubuntu 22.04 / 24.04（推荐），或WSL2（Windows用户）
• Python版本：3.10 或 3.11（3.12暂未全面验证）
• CUDA驱动：12.1+（对应NVIDIA driver ≥535）
• GPU显存：≥4 GB（测试最低可用为RTX 2060 6GB，但建议≥8GB保障稳定性）

执行以下命令快速验证：

nvidia-smi # 查看GPU型号与驱动版本 python3 --version # 应显示3.10.x或3.11.x nvcc --version # 应显示CUDA 12.1或更高

注意：不要用conda安装vLLM！Chandra官方镜像与vLLM的PyPI包存在CUDA兼容性问题。我们全程使用pip + wheel预编译版本，避免编译失败。

2.2 一键安装vLLM（适配Chandra）

Chandra官方推荐使用vLLM 0.6.3.post1（专为视觉编码器优化的分支）。请严格按以下顺序执行：

# 创建独立虚拟环境（强烈建议） python3 -m venv chandra-env source chandra-env/bin/activate # 升级pip并安装基础依赖 pip install --upgrade pip pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 # 安装vLLM（必须指定wheel链接，否则会装错版本） pip install vllm==0.6.3.post1 \ --extra-index-url https://download.vllm.ai/whl/cu121

安装完成后，验证vLLM是否正常：

python3 -c "from vllm import LLM; print('vLLM ready')"

若无报错，说明底层推理引擎已就绪。

3. 部署Chandra模型：三步完成服务启动

Chandra不提供HuggingFacetransformers原生加载方式（因其视觉编码器与文本解码器耦合紧密），而是通过专用chandra-ocr包封装了vLLM适配层。整个过程无需下载权重、无需修改代码、无需配置YAML——真正的开箱即用。

3.1 安装Chandra CLI与服务包

pip install chandra-ocr==0.2.4

该包内置：

• chandra-cli：命令行批量处理工具
• chandra-streamlit：本地可视化界面（含上传、预览、导出）
• chandra-api：基于vLLM的HTTP服务模块（核心！）

版本锁定为0.2.4：这是首个正式支持vLLM 0.6.3的稳定版，修复了JSON输出字段缺失、多页PDF内存泄漏等关键问题。

3.2 启动HTTP API服务（单卡也稳）

执行以下命令，启动一个监听localhost:8000的OCR服务：

chandra-api \ --model datalab-to/chandra-ocr-base \ --tensor-parallel-size 1 \ --gpu-memory-utilization 0.9 \ --max-model-len 8192 \ --port 8000

参数说明（全部可选，但建议保留）：

• --model：HuggingFace模型ID，自动从HF Hub拉取（首次运行需网络）
• --tensor-parallel-size 1：单卡设为1；双卡则改为2（如--tensor-parallel-size 2 --gpu-memory-utilization 0.8）
• --gpu-memory-utilization 0.9：显存占用上限，避免OOM；显存紧张时可降至0.7
• --max-model-len 8192：最大上下文长度，匹配Chandra处理A4单页能力

启动成功后，终端将显示类似日志：

INFO 01-26 14:22:33 [api_server.py:128] Chandra OCR API server started on http://localhost:8000 INFO 01-26 14:22:33 [engine.py:215] Using device: cuda, dtype: bfloat16 INFO 01-26 14:22:33 [model_runner.py:482] Loading model weights...

此时服务已就绪。你不需要任何额外Web框架，vLLM原生提供OpenAI兼容API接口。

3.3 快速验证API是否可用

新开终端，用curl测试最简请求：

curl -X POST "http://localhost:8000/v1/chat/completions" \ -H "Content-Type: application/json" \ -d '{ "model": "datalab-to/chandra-ocr-base", "messages": [ { "role": "user", "content": [ {"type": "image_url", "image_url": {"url": "https://httpbin.org/image/jpeg"}}, {"type": "text", "text": "请将这张图片转换为Markdown，保留所有标题、段落、表格和公式结构。"} ] } ], "temperature": 0.0, "max_tokens": 2048 }'

注意：实际使用时，image_url需替换为你的本地图片base64编码或内网可访问URL（如file:///home/user/doc.jpg）。vLLM默认支持file://协议，无需上传到公网。

返回结果中，choices[0].message.content字段即为结构化Markdown文本，包含完整排版标记。

4. 实战调用：三种最常用接入方式

服务跑起来只是第一步。真正落地，要看你怎么把它“用进去”。我们提供三种生产级接入方式，覆盖从脚本调用到系统集成的全场景。

4.1 Python脚本调用（适合批量处理）

用openaiPython SDK（v1.0+）调用，代码极简：

# ocr_batch.py from openai import OpenAI import base64 client = OpenAI( base_url="http://localhost:8000/v1", # 指向本地服务 api_key="not-needed" # vLLM无需key ) def image_to_markdown(image_path: str) -> str: # 读取图片并转base64 with open(image_path, "rb") as f: b64 = base64.b64encode(f.read()).decode() response = client.chat.completions.create( model="datalab-to/chandra-ocr-base", messages=[ { "role": "user", "content": [ {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{b64}"}}, {"type": "text", "text": "请输出Markdown，严格保留原文档的标题层级、段落分隔、表格结构、数学公式和图像标题。"} ] } ], temperature=0.0, max_tokens=2048 ) return response.choices[0].message.content # 调用示例 md = image_to_markdown("invoice_scan.jpg") print(md[:200] + "...") # 打印前200字符预览

运行后，你会得到类似这样的Markdown输出：

## 发票信息 **开票日期**：2025年10月15日 **发票号码**：INV-2025-88765 | 项目 | 数量 | 单价（元） | 金额（元） | |------|------|------------|------------| | 服务器租赁 | 1台 | 2,800.00 | 2,800.00 | | 技术支持 | 12小时 | 300.00 | 3,600.00 | | **合计** | | | **6,400.00** | > 图1：机房设备照片（坐标：x=120,y=340,w=480,h=270）

这就是Chandra的“布局感知”能力——表格是真实|语法，标题有##，图注带坐标，无需后期清洗。

4.2 Streamlit交互界面（适合非技术同事）

Chandra自带轻量级Web界面，一行命令启动：

chandra-streamlit --port 8501

打开浏览器访问http://localhost:8501，即可看到：

• 文件拖拽上传区（支持PDF、JPG、PNG、TIFF）
• 实时预览原始图片/PDF页
• 三栏式结果展示：左侧原始图、中间识别区域高亮、右侧Markdown/HTML/JSON切换
• 一键复制、下载为.md/.html/.json文件

这个界面完全离线运行，不上传任何数据，适合法务、财务等对隐私敏感的部门直接使用。

4.3 Docker一键部署（适合团队统一环境）

官方提供预构建Docker镜像，省去环境配置烦恼：

docker run -d \ --gpus all \ --shm-size=2g \ -p 8000:8000 \ -v $(pwd)/models:/root/.cache/huggingface \ -v $(pwd)/data:/data \ --name chandra-ocr \ ghcr.io/datalab-to/chandra-ocr:v0.2.4 \ chandra-api \ --model datalab-to/chandra-ocr-base \ --tensor-parallel-size 1 \ --port 8000

镜像已预装vLLM、Chandra及CUDA依赖，启动即用。-v挂载确保模型缓存与输入数据持久化。

5. 效果实测：它到底有多准？

光说不练假把式。我们用三类典型难例实测Chandra在本地vLLM服务下的表现（RTX 4090单卡，--gpu-memory-utilization 0.85）：

所有输出均同时生成Markdown、HTML、JSON三格式。JSON中包含每个元素的精确坐标（bbox: [x,y,w,h]），可直接用于RAG切片或自动化排版系统。

提示：Chandra对中文排版特别友好。它能区分“标题1”与“正文1号字”，自动识别宋体/黑体/楷体语义，而非仅靠字体大小判断层级。

6. 进阶技巧：让OCR更贴合你的业务

Chandra不是黑盒，它提供多个实用开关，帮你微调输出行为，无需重训模型。

6.1 控制输出格式与粒度

在API请求的messages.content.text中加入指令，即可精准控制：

• 请输出HTML，仅包含<body>内内容，不带DOCTYPE→ 得到纯净HTML片段，可直接插入网页
• 请输出JSON，包含page_number、bbox、type（title/paragraph/table/formula）、text字段→ 获取结构化元数据，用于构建文档知识图谱
• 请忽略页眉页脚，只提取正文区域（x>50,y>100,w<700,h<900）→ 支持坐标裁剪，适配固定模板文档

6.2 批量处理PDF与目录

CLI工具支持递归扫描：

# 将input/下所有PDF/JPG转为Markdown，输出到output/目录 chandra-cli \ --input-dir input/ \ --output-dir output/ \ --output-format markdown \ --workers 4 # 并行进程数，根据CPU核数调整

输出文件命名自动保留原名：invoice_scan.pdf→invoice_scan.md

6.3 内存与速度平衡建议

• 显存<12GB：添加--enforce-eager参数，禁用vLLM的图优化，牺牲少量速度换取稳定性
• 处理超长PDF（>50页）：启用--max-num-seqs 1，强制串行处理，避免显存峰值溢出
• 需要更高精度：将temperature设为0.0（默认），关闭随机采样；如需多样性（如多版本摘要），可设为0.3

7. 总结：一个真正能进生产线的OCR

回顾整个部署过程，你会发现Chandra+vLLM组合打破了OCR落地的几个固有门槛：

• 硬件门槛低：4GB显存起步，RTX 3060即可胜任日常文档处理；
• 集成成本低：OpenAI兼容API，现有RAG/文档系统无需改造即可接入；
• 输出即可用：Markdown/HTML/JSON三格式直出，告别“识别完还要人工整理”的时代；
• 商业友好：Apache 2.0代码 + OpenRAIL-M权重，初创公司年营收200万美元内免费商用。

它不追求“全能”，而是死磕“文档理解”这一件事——把扫描件、PDF、照片里的结构、语义、空间关系全部还给你。当你需要把合同入库、把试卷数字化、把报表喂给分析模型时，Chandra不是备选，而是首选。

现在，就打开终端，敲下那行chandra-api，让你的第一份扫描件，在1秒内变成可搜索、可编辑、可编程的Markdown吧。

--- > **获取更多AI镜像** > > 想探索更多AI镜像和应用场景？访问 [CSDN星图镜像广场](https://ai.csdn.net/?utm_source=mirror_blog_end)，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。