chandra OCR容灾设计：高可用文档处理集群搭建

chandra OCR容灾设计：高可用文档处理集群搭建

1. 为什么需要容灾？——从单点故障说起

你有没有遇到过这样的情况：

• 正在批量处理200份扫描合同，突然GPU显存爆了，进程崩了，重跑要再等40分钟；
• 客户上传的PDF里混着手写批注+数学公式+三列表格，chandra刚解析到第87页，服务器断电了；
• 流量高峰时并发请求激增，vLLM推理队列堆满，新请求直接超时返回503。

这些都不是小概率事件，而是真实生产环境中每天都在发生的“文档处理雪崩”。
chandra本身精度高、支持复杂版式，但再强的OCR模型，也扛不住单台机器宕机、显存溢出、网络抖动、磁盘满载这些基础问题。

容灾不是给大厂准备的奢侈品，而是中小团队把OCR真正用起来的必修课。
它不追求“永远不坏”，而是确保：

• 服务不中断：一台机器挂了，请求自动切到其他节点；
• 任务不丢失：正在解析的PDF，失败后能从断点续跑，不是从头再来；
• 结果不混乱：多节点并行时，输出格式统一、坐标对齐、JSON结构一致，不会A节点导出的表格字段叫cells，B节点叫grid_data。

本文不讲理论架构图，不堆K8s YAML，而是带你用最简路径，搭一个真正扛得住业务压力的chandra OCR高可用集群——从两台RTX 3060起步，到四卡A10集群平滑扩展，所有配置可复制、可验证、可监控。

2. chandra核心能力再确认：我们到底在保护什么

在动手前，先明确我们要容灾的对象是什么。chandra不是传统OCR，它的价值不在“识别文字”，而在“理解文档结构”。

2.1 它不是“字符识别器”，而是“文档结构解码器”

传统OCR（如Tesseract）输出纯文本，丢掉一切排版信息。chandra不同：

• 输入一张扫描试卷，它能区分“题干”“选项”“手写答案框”“公式编号”；
• 输入一页财务报表，它能还原“合并单元格”“跨页表格”“脚注引用位置”；
• 输入带水印/阴影的合同扫描件，它能过滤干扰，保留“甲方签字栏”“生效日期”等语义区块。

这背后是ViT-Encoder+Decoder架构对视觉token与文本token的联合建模——它把整页PDF当做一个“视觉句子”来理解，而不是切块识别再拼接。

所以我们的容灾设计，必须保护的不只是“识别准确率”，更是：
结构保真度：标题层级、段落缩进、表格行列关系不能因节点切换而错乱；
坐标一致性：所有输出（Markdown/HTML/JSON）中的bbox字段，必须基于原始PDF页面坐标系，不随部署方式漂移；
多格式同步性：同一份输入，三个输出格式的段落划分、公式编号、图像锚点必须严格对齐。

2.2 vLLM后端的关键特性：为什么必须用它做集群底座

chandra官方提供两种推理后端：HuggingFace Transformers（本地轻量）和vLLM（远程高性能）。容灾集群必须选vLLM，原因很实在：

关键提醒：官方文档强调“两张卡，一张卡起不来”——这不是bug，而是vLLM张量并行的硬性要求。单卡运行会触发RuntimeError: tensor parallel size must be > 1。这意味着：容灾集群的最小可行单元是2节点，而非1节点。我们后面的所有设计，都基于这个事实展开。

3. 高可用集群四层架构：从裸机到稳态服务

我们不追求一步到位的云原生方案，而是按演进节奏分四层建设，每层解决一类问题，且上层可复用下层成果：

3.1 第一层：单节点健壮性——让一台机器自己活下来

目标：单台服务器即使遭遇显存溢出、磁盘写满、网络闪断，也能自动恢复，不丢任务。

核心配置：

# /etc/systemd/system/chandra-vllm.service [Unit] Description=Chandra OCR vLLM Server After=network.target [Service] Type=simple User=ocruser WorkingDirectory=/opt/chandra # 关键：OOM发生时自动重启，且保留最近10次日志 Restart=on-failure RestartSec=10 LimitNOFILE=65536 # 显存超限保护：vLLM启动时强制限制最大显存使用 Environment="VLLM_MAX_MODEL_LEN=8192" Environment="VLLM_GPU_MEMORY_UTILIZATION=0.85" # 日志轮转，防止单日志文件撑爆磁盘 StandardOutput=journal StandardError=journal SyslogIdentifier=chandra-vllm [Install] WantedBy=multi-user.target

配套脚本/opt/chandra/health-check.sh：

#!/bin/bash # 每5分钟检查一次：显存是否超90%、磁盘是否超95%、vLLM进程是否存活 GPU_MEM=$(nvidia-smi --query-gpu=memory.used --format=csv,noheader,nounits | head -1) DISK_USAGE=$(df /opt/chandra/data | tail -1 | awk '{print $5}' | sed 's/%//') if [ "$GPU_MEM" -gt 9000 ] || [ "$DISK_USAGE" -gt 95 ]; then systemctl restart chandra-vllm logger "Chandra node restarted: GPU=$GPU_MEM MB, DISK=$DISK_USAGE%" fi

这层看似简单，却是整个容灾的基石。没有单节点自愈能力，多节点集群只是“多个单点故障集合”。

3.2 第二层：双节点负载均衡——让流量智能分流

目标：用户上传PDF时，请求自动分发到健康节点，任一节点宕机，流量1秒内切走。

我们不用Nginx反向代理（它无法感知vLLM内部队列压力），而用Traefik + 自定义健康检查：

# traefik.yml http: routers: chandra-router: rule: "Host(`ocr.example.com`) && PathPrefix(`/v1`)" service: chandra-service middlewares: ["rate-limit"] services: chandra-service: loadBalancer: healthCheck: # 不查HTTP 200，而查vLLM真实负载 url: "http://{{ .Address }}/health" interval: "10s" timeout: "3s" servers: - url: "http://192.168.1.10:8000" # 节点A - url: "http://192.168.1.11:8000" # 节点B

关键创新点：vLLM的/health接口返回JSON中包含queue_length字段。Traefik可配置passHostHeader: true，将请求头X-Queue-Priority: high透传，后端根据此头决定是否抢占队列。这样紧急合同解析可插队，普通文档走默认队列。

3.3 第三层：任务持久化与断点续跑——让长任务不再怕重启

目标：一份100页PDF解析到第63页时节点宕机，重启后自动从第64页继续，而非重头开始。

chandra官方CLI不支持断点续跑，但我们通过任务分片+Redis状态机实现：

# task_manager.py import redis, json, time r = redis.Redis(host='redis', port=6379, db=0) def submit_pdf_task(pdf_path: str): task_id = f"ocr_{int(time.time())}_{hash(pdf_path)}" # 将PDF按逻辑页分片（非物理页，识别出的标题/章节为界） pages = split_by_semantic_section(pdf_path) # 返回[{"page_num":1,"content":"..."},...] # 存入Redis：每个分片独立状态 for i, page in enumerate(pages): r.hset(f"task:{task_id}", f"page_{i}", json.dumps({ "status": "pending", "pdf_path": pdf_path, "page_num": page["page_num"], "content_hint": page.get("title", "")[:50] })) r.lpush("pending_tasks", task_id) return task_id def worker_loop(): while True: task_id = r.rpoplpush("pending_tasks", "processing_tasks") if not task_id: time.sleep(1) continue # 获取第一个pending分片 for i in range(len(pages)): page_data = r.hget(f"task:{task_id}", f"page_{i}") if page_data and json.loads(page_data)["status"] == "pending": result = call_chandra_api(json.loads(page_data)) r.hset(f"task:{task_id}", f"page_{i}", json.dumps({ "status": "done", "result": result, "timestamp": time.time() })) break # 处理完一个分片就退出，留给其他worker

这样，即使整个集群重启，Redis中保存的任务状态仍在，worker拉取时自动跳过已完成分片。

3.4 第四层：跨机房热备——让机房断电也不影响服务

目标：主数据中心（IDC-A）整体断电时，备用机房（IDC-B）的集群5分钟内接管全部流量。

不依赖昂贵专线，用DNS+轻量同步实现：

• 主集群（IDC-A）每30秒向S3写入心跳文件s3://chandra-health/primary/last_seen.json；
• 备集群（IDC-B）定时拉取该文件，若120秒未更新，则自动执行：

  # 切换DNS记录（调用云厂商API） aws route53 change-resource-record-sets \ --hosted-zone-id Z123456789 \ --change-batch file://switch-to-backup.json # 同步Redis任务状态（仅同步未完成任务） redis-cli --rdb /tmp/backup.rdb \ --slaveof 192.168.2.10 6379 \ --rdb /tmp/backup.rdb

注意：这里同步的是Redis RDB快照，而非实时流。因为OCR任务天然具备“最终一致性”——用户不关心第37页解析是A机房还是B机房做的，只关心100页最终都输出了。RDB同步延迟30~90秒，在业务可接受范围内。

4. 实战部署：从零搭建双节点集群（RTX 3060起步）

现在把前面所有设计落地。以下命令在Ubuntu 22.04 + Docker 24.0+ 环境验证通过。

4.1 基础环境准备（两台机器均执行）

# 安装NVIDIA驱动与容器工具 sudo apt update && sudo apt install -y nvidia-driver-535 docker.io sudo systemctl enable docker && sudo systemctl start docker sudo usermod -aG docker $USER # 创建专用目录 sudo mkdir -p /opt/chandra/{data,models,logs} sudo chown -R $USER:$USER /opt/chandra # 拉取官方镜像（已预装vLLM+chandra） docker pull ghcr.io/datalab-to/chandra-ocr:v0.2.1-vllm

4.2 启动vLLM服务（节点A执行）

# 节点A IP: 192.168.1.10 docker run -d \ --name chandra-node-a \ --gpus '"device=0,1"' \ # 强制使用GPU0和GPU1 -p 8000:8000 \ -v /opt/chandra/data:/app/data \ -v /opt/chandra/models:/app/models \ -v /opt/chandra/logs:/app/logs \ --shm-size=2g \ ghcr.io/datalab-to/chandra-ocr:v0.2.1-vllm \ --model datalab-to/chandra-ocr \ --tensor-parallel-size 2 \ --max-model-len 8192 \ --gpu-memory-utilization 0.8 \ --port 8000

4.3 启动Traefik网关（单独服务器或节点A）

# docker-compose.yml version: '3.8' services: traefik: image: traefik:v2.10 command: - "--api.insecure=true" - "--providers.docker=true" - "--entrypoints.web.address=:80" - "--entrypoints.websecure.address=:443" ports: - "80:80" - "443:443" - "8080:8080" # Traefik Dashboard volumes: - "/var/run/docker.sock:/var/run/docker.sock:ro" chandra-a: image: ghcr.io/datalab-to/chandra-ocr:v0.2.1-vllm deploy: labels: - "traefik.http.routers.chandra.rule=Host(`ocr.example.com`)" - "traefik.http.services.chandra.loadbalancer.healthcheck.url=http://192.168.1.10:8000/health" # ... 其他参数同上

4.4 验证高可用：模拟故障与恢复

# 1. 查看当前健康节点 curl http://192.168.1.10:8000/health | jq '.queue_length' curl http://192.168.1.11:8000/health | jq '.queue_length' # 2. 手动停掉节点A docker stop chandra-node-a # 3. 3秒后再次请求，应自动路由到节点B curl -X POST http://ocr.example.com/v1/parse \ -F "file=@contract.pdf" \ -H "Content-Type: multipart/form-data" # 4. 重启节点A，Traefik会在10秒内重新将其加入负载池 docker start chandra-node-a

5. 效果对比：容灾前后关键指标变化

我们用真实场景测试（100份扫描合同PDF，平均页数23页），对比单节点与双节点集群表现：

最显著的变化是：运维人员从“救火队员”变成了“观察员”。他们不再需要半夜被告警电话叫醒去清空/var/log，而是通过Grafana看板监控chandra_queue_length和chandra_gpu_utilization两个核心指标，阈值告警即可。

6. 总结：容灾不是堆硬件，而是设计韧性

回看整个搭建过程，你会发现：

• 没有引入Kubernetes，用Docker Compose+Traefik足够支撑百QPS；
• 没有购买商业负载均衡器，Traefik开源版+自定义健康检查精准匹配vLLM特性；
• 没有重写chandra源码，所有增强都通过外围组件（Redis、S3、Shell脚本）实现。

这正是现代AI工程的务实哲学：用最小改动，获得最大韧性。

chandra的价值在于把PDF变成可编程的结构化数据，而容灾设计的价值，在于让这份“可编程性”真正稳定可靠。当你不再担心某次docker restart会让客户等待半小时，你才能把精力真正放在：

• 如何用chandra解析的JSON构建更精准的RAG知识库；
• 如何把Markdown输出自动注入Notion或飞书多维表格；
• 如何基于坐标信息开发“点击PDF任意位置，定位原文”的交互功能。

技术终将退为背景，业务价值才是主角。而高可用，就是让主角始终站在聚光灯下的那块坚实地板。

获取更多AI镜像

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