# OCR图片理解模型服务Docker部署手册(NPU版)
# 1、服务信息
**服务名称:**OCR识别服务
- **服务功能:**可识别图片、PDF扫描件,生成文字,常用于CoMi知识库上传扫描件后进行OCR识别解析成文字
- **服务端口:**12841
- **NPU支持:**是(必须),华为昇腾 Ascend 910B3
- **架构支持:**仅支持 aarch64(ARM64),x86_64(amd64)服务器不适用
- **依赖CoMi版本:**CoMi V2.0.2及以上
- 支持产品线: V5产品线A6、A8、G6、A8-N、G6-N (注:V8新一代产品线不适用,V8暂不支持此OCR)
硬件与验证范围说明
- 目标硬件为华为昇腾 Ascend 910B3(单卡 64GB HBM),典型形态为 Atlas 800T A2 整机(鲲鹏 920 + 昇腾 910,aarch64/ARM64 架构),也可以是单卡/多卡 910B3 昇腾服务器。
- 官方 PaddleOCR-VL 部署方案仅在 910B 上完成过验证,其他昇腾 NPU 型号的兼容性未经官方验证,现场如需使用请先做小范围验证。
- 本部署包为离线安装包,镜像已内置模型权重,部署全程无需联网。镜像包由交付人员提供。
什么时候需要部署OCR图片理解模型服务?
用户有大量重要的扫描件、图片需要导入CoMi知识库,此时如果没有OCR服务,会提示:ocr请求失败。
# 二、环境要求
# 硬件要求
- CPU: 鲲鹏 920(aarch64)4核+
- 内存: 64G+(三容器方案,其中两个容器各配置
shm_size: 64g共享内存,内存不足会直接启动失败) - 磁盘: 120G+(镜像归档约 20G,
docker load后镜像实际占用约 45-50G,另需预留日志与数据空间) - NPU: 华为昇腾 Ascend 910B3(单卡 64GB HBM)× N,示例为 8 卡整机 Atlas 800T A2
# 软件要求
重要兼容性声明:当前 PaddleOCR-VL 昇腾部署方案及随包提供的 Docker 镜像仅支持 aarch64(ARM64)Linux + 华为昇腾 NPU。提供的两个 PaddleOCR 镜像均为
linux/arm64,x86_64 服务器无法运行(docker load可能成功,但启动会报exec format error),修改 Docker Compose 配置也无法解决镜像架构不兼容问题。部署前必须先确认uname -m输出为aarch64。
- 操作系统: Ubuntu 20.04 / 22.04(aarch64)。官方镜像基于 Ubuntu 20.04 构建,宿主机使用 20.04 或 22.04 均可
- NPU 驱动与固件: 已安装且
npu-smi info可正常输出(具体驱动/CANN 版本以现场npu-smi输出为准,本手册不做硬性版本约束) - Docker Engine: 19.03+(建议 24+),且
docker compose version可用(Compose V2) - Ascend Docker Runtime: 不需要安装。官方方案通过容器
privileged: true直接透传 NPU 设备,无需额外的容器运行时插件
说明: 昇腾 CANN、驱动库、vllm-ascend 等运行时组件均已在镜像内集成,宿主机只需具备可用的 NPU 驱动与设备节点。请勿自行升级镜像内的 vllm-ascend(见第七章)。
# 部署架构
采用 docker compose 三容器编排:
| 容器名 | 镜像 | 作用 | 容器内端口 |
|---|---|---|---|
ocr-proxy | ocr-proxy:latest | 自研 OCR 代理,对外提供 12841 服务,转发请求给 PaddleOCR-VL | 8000 |
paddleocr-vl-api | paddleocr-vl:latest-huawei-npu-offline | PaddleOCR-VL 流水线服务(paddlex serve),负责版面分析、OCR 调度 | 8080 |
paddleocr-vlm-server | paddleocr-genai-vllm-server:latest-huawei-npu-offline | VLM 推理服务(paddleocr genai_server),底层为 vllm-ascend | 8080 |
调用链:CoMi → ocr-proxy:12841 → paddleocr-vl-api → paddleocr-vlm-server(NPU 推理)
推理后端固定为
VLM_BACKEND=vllm:昇腾 NPU 目前只支持 vllm 后端,不要改成 sglang 等其他后端。
# 镜像清单
| 镜像 | 大小 | 架构 | 说明 |
|---|---|---|---|
ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-huawei-npu-offline | 约 30GB | linux/arm64 | 已内置模型权重,加载后占用更大 |
ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest-huawei-npu-offline | 约 20GB | linux/arm64 | vllm-ascend 推理服务 |
ocr-proxy:latest | 约数百 MB | 与宿主一致 | 自研代理镜像 |
归档文件
images/目录下 3 个镜像归档(合计约 20GB,压缩后),docker load完成后镜像实际占用约 45-50GB。镜像 tag/digest/架构清单见部署包内image-digests.txt,可用于校验镜像完整性。
# 容器访问 NPU 的前提条件(重要)
官方 PaddleOCR compose 方案要求每个 NPU 容器具备以下条件:
user: root(容器内以 root 运行,避免设备文件权限不足)privileged: true(依靠特权模式透传 NPU 设备,这是官方方案,不需要 Ascend Docker Runtime)shm_size: 64g(共享内存,不是 HBM 显存;但宿主内存不足同样会导致启动失败)- 挂载以下宿主机路径:
/usr/local/Ascend/driver→ 驱动与算子库/usr/local/bin/npu-smi→ 容器内可用的 npu-smi 工具/usr/local/dcmi→ DCMI 接口库
官方 compose 中对应片段示例(paddleocr-vl-api 与 paddleocr-vlm-server 两个服务都需要;本部署包的 compose 已按此写好,可直接使用):
user: root
privileged: true
shm_size: 64g
volumes:
- /usr/local/Ascend/driver:/usr/local/Ascend/driver
- /usr/local/bin/npu-smi:/usr/local/bin/npu-smi
- /usr/local/dcmi:/usr/local/dcmi
注意:官方 compose 没有手写
/dev/davinci0之类的devices:映射,也不需要ASCEND_VISIBLE_DEVICES环境变量(那是 Ascend Docker Runtime 插件使用的变量)。如需改用非 privileged 的显式设备方案(例如客户安全规范禁止 privileged),必须一次性补齐以下全部设备与挂载,缺任意一项都会导致
npu-smi报错或算子加载失败:
- 设备节点:
/dev/davinciN(N 为卡号)、/dev/davinci_manager、/dev/devmm_svm、/dev/hisi_hdc- 驱动挂载:
/usr/local/Ascend/driver(含driver/lib64、driver/version.info)- 配置文件:
/etc/ascend_install.info- 工具与接口:
/usr/local/dcmi、/usr/local/bin/npu-smi
选卡方式:使用 ASCEND_RT_VISIBLE_DEVICES(CANN 逻辑编号,取值 0-7,多卡用英文逗号分隔,如 0,1)。不要使用 ASCEND_VISIBLE_DEVICES,该变量仅对 Ascend Docker Runtime 插件生效。
# 三、环境检查与准备(客户)
需要客户完成如下环境准备。以下命令块可直接复制执行,每一项都给出了预期输出,任一项不符合请先处理再继续部署。
# 3.1 检查CPU架构与操作系统
OCR识别服务对 CPU 架构要求严格:当前部署包仅适配 aarch64(ARM64),x86_64 服务器无法运行 NPU 镜像:
# 检查CPU架构,必须输出 aarch64
uname -m
# 查看详细内核与架构信息
uname -a
# 检查操作系统版本,输出 Ubuntu 20.04.x 或 22.04.x
lsb_release -a
预期输出示例:
$ uname -m
aarch64
$ lsb_release -a
Distributor ID: Ubuntu
Description: Ubuntu 22.04.4 LTS
Release: 22.04
Codename: jammy
若
uname -m输出x86_64,说明当前服务器是 x86 架构,请立即停止部署:本套镜像为 linux/arm64,无法在此机器上运行,需更换为鲲鹏/昇腾 ARM 服务器。
# 3.2 检查NPU驱动与设备
npu-smi info 是唯一必须能跑通的 NPU 检查,它能正常输出就说明驱动、设备节点、权限都正常:
# 查看 NPU 基本信息(型号、健康状态、HBM 占用)
npu-smi info
# 查看芯片详细信息(可选)
npu-smi info -t board -i 0
# 检查设备节点是否存在
ls -l /dev/davinci* /dev/davinci_manager /dev/devmm_svm /dev/hisi_hdc
# 检查驱动与工具目录是否存在
ls -d /usr/local/Ascend/driver /usr/local/dcmi /usr/local/bin/npu-smi
预期输出示例(8 卡 910B3 整机):
$ npu-smi info
+------------------------------------------------------------------------------------------------+
| npu-smi 25.3.rc1 Version: 25.3.rc1 |
+---------------------------+---------------+----------------------------------------------------+
| NPU Name | Health | Power(W) Temp(C) Hugepages-Usage(page)|
| Chip | Bus-Id | AICore(%) Memory-Usage(MB) HBM-Usage(MB) |
+===========================+===============+====================================================+
| 0 910B3 | OK | 92.3 34 0 / 0 |
| 0 | 0000:C1:00.0 | 0 0 / 0 1234 / 65536 |
+===========================+===============+====================================================+
| 1 910B3 | OK | 90.1 35 0 / 0 |
| 0 | 0000:C2:00.0 | 0 0 / 0 0 / 65536 |
+===========================+===============+====================================================+
...(共 8 卡,逐卡列出)
关键判读点:
Name列显示910B3,与目标硬件一致Health列为OKVersion/npu-smi版本为现场实际驱动版本(示例为25.3.rc1),以现场 npu-smi / 驱动版本为准,本手册不强制某个版本号HBM-Usage(MB)形如0 / 65536,说明该卡 HBM 完全空闲;部署前必须确认目标卡有足够空闲 HBM
若
npu-smi info报command not found,说明宿主机未安装 NPU 驱动或未加入 PATH;若报Failed to get device/device not found,说明驱动与设备节点异常。这两种情况都需要现场先修复 NPU 驱动,再继续部署。
# 3.3 安装/确认 Docker Engine
# 检查 docker 是否已安装,要求 >= 19.03(建议 24+)
docker -v
# 检查 docker compose(V2)是否可用
docker compose version
# 查看 docker 服务状态
sudo systemctl status docker
预期输出示例:
$ docker -v
Docker version 24.0.7, build afdd53b
$ docker compose version
Docker Compose version v2.20.2
如未安装,使用国内镜像源安装(注意 aarch64 架构):
# 导入Docker官方签名密钥
sudo curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | \
sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
# 添加 Docker apt 源(阿里云镜像,arm64)
echo "deb [arch=arm64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# 安装Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
# 设置开机启动
sudo systemctl start docker
sudo systemctl enable docker
# 验证
docker -v
docker compose version
# 3.4 检查内存与磁盘
# 内存:建议 >= 64GB(两个 PaddleOCR 容器各需 64g 共享内存)
free -g
# 磁盘:部署目录所在分区建议 >= 120GB
df -h /data
预期输出示例:
$ free -g
total used free shared buff/cache available
Mem: 755 8 700 0 46 740
Swap: 0 0 0
$ df -h /data
Filesystem Size Used Avail Use% Mounted on
/dev/sda1 1.8T 120G 1.6T 7% /data
# 3.5 检查端口占用
# 检查 12841(对外服务)、8800、8808(宿主机调试端口)是否被占用
ss -tlnp | grep -E '12841|8800|8808' || echo "端口全部空闲"
预期输出:端口全部空闲。若已有进程占用,需先停止该进程或修改 .env 中的端口。
# 3.6 验证容器内可以访问 NPU(可选,离线环境在 4.4 加载镜像后执行)
在镜像加载完成后,可先单独验证 NPU 能否透传进容器:
docker run --rm --privileged \
-v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
-v /usr/local/dcmi:/usr/local/dcmi \
ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-huawei-npu-offline \
npu-smi info
预期输出与宿主机 npu-smi info 一致。若容器内报错而宿主机正常,请对照第七章 7.2。
# 四、部署步骤
# 4.1 创建部署目录
sudo mkdir -p /data/Seeyon/Comi/ocr/
# 4.2 获取部署包
镜像包由交付人员提供(ocr_npu_arm64.tar.gz),上传到服务器 /data/Seeyon/Comi/ocr/ 目录后解压:
cd /data/Seeyon/Comi/ocr/
# 解压部署包
tar xzf ocr_npu_arm64.tar.gz
# 进入部署目录
cd ocr_npu
部署包目录结构:
ocr_npu/
├── docker-compose.yml ← 容器编排文件
├── .env.example ← 配置模板(复制为 .env 后编辑)
├── install.sh ← 安装脚本
├── start.sh ← 启动脚本
├── images/ ← 镜像归档目录(3 个 .tar.gz,合计约 20GB)
│ ├── ocr-proxy.tar.gz
│ ├── paddleocr-vl.tar.gz
│ └── paddleocr-genai-vllm-server.tar.gz
├── image-digests.txt ← 镜像 tag/digest/架构清单,用于校验
├── ocr_test.png ← 健康检查测试图片
├── 部署手册-NPU版.md ← 本文档
└── docker/config/ ← vLLM 调优配置(vllm_backend.json,默认不加载,见 4.5 说明)
上传前可在源端执行
sha256sum ocr_npu_arm64.tar.gz,现场解压前用同一条命令核对,避免传输损坏。每个
.tar.gz在install.sh中都会先gzip -t校验完整性,再逐个docker load -i加载;也可按image-digests.txt核对镜像 tag 与架构是否为linux/arm64。拆成 3 个文件的原因:单文件约 20GB,传输中断需要整体重传;分开后可逐个
rsync --partial续传,加载也可以分步执行。
# 4.3 配置环境变量
# 从模板创建配置文件
cp .env.example .env
# 按需编辑配置(可选)
vi .env
主要可配参数:
| 参数 | 默认值 | 说明 |
|---|---|---|
CONTAINER_SUFFIX | (空) | 容器名后缀,空=生产,-test=测试实例 |
OCR_PROXY_PORT | 12841 | ocr-proxy 对外服务端口 |
PADDLEOCR_VL_PORT | 8800 | PaddleOCR-VL API 的宿主机调试端口(容器内服务监听 8080) |
PADDLEOCR_VLM_PORT | 8808 | VLM 推理服务的宿主机调试端口(容器内服务监听 8080) |
ASCEND_RT_VISIBLE_DEVICES | 0 | 选择使用的 NPU 卡号(CANN 逻辑编号 0-7,多卡用逗号分隔) |
VLM_BACKEND | vllm | 推理后端,NPU 仅支持 vllm |
OCR_PROXY_FILE_SIZE_LIMIT_MB | 20 | 上传文件大小上限(MB) |
OCR_PROXY_PADDLEOCR_VL_USE_CHART_RECOGNITION | true | 图表识别开关 |
OCR_PROXY_PADDLEOCR_VL_USE_OCR_FOR_IMAGE_BLOCK | true | 图片块文字提取开关 |
OCR_PROXY_PADDLEOCR_VL_MAX_NEW_TOKENS | 1024 | 单次生成最大 token 数 |
OCR_PROXY_CACHE_ENABLED | true | OCR 结果缓存开关 |
端口说明:
PADDLEOCR_VL_PORT=8800、PADDLEOCR_VLM_PORT=8808只是宿主机上的调试端口,用于浏览器或 curl 直连排查。容器内 PaddleOCR 服务实际监听 8080,映射关系为宿主机 8800/8808 → 容器 8080,不要写成「容器端口 8800/8808」。选卡说明:本离线包内
docker-compose.yml已使用ASCEND_RT_VISIBLE_DEVICES(CANN 逻辑编号),无需改动;改卡只需改.env中的该变量后docker compose up -d重建容器。
# 4.4 首次安装
# 普通用户
./install.sh
# 如无docker权限
sudo bash install.sh
脚本自动完成:
- 环境检查 — docker / compose / 端口 / 磁盘空间 / 镜像归档完整性 /
npu-smi可用性 / NPU 设备节点 / Ascend 驱动目录 - 加载所有镜像(ocr-proxy + PaddleOCR-VL × 2,
images/合计约 20GB) - 创建日志和数据目录(
logs/、data/)
镜像已内置模型文件,无需联网下载。
docker load约需数分钟,加载后镜像实际占用约 45-50GB,请确保磁盘充足。
# 4.5 启动服务
# 普通用户
./start.sh
# 如无docker权限
sudo bash start.sh
start.sh 会再次检查 docker 环境、compose 文件与镜像是否已全部加载,然后执行 docker compose up -d。
共享卡场景(重要):默认启动命令使用镜像内置参数,会按 vLLM 默认策略占用 HBM。如果现场
npu-smi info显示目标卡已被其它推理进程占用较多显存(例如 8 张卡 HBM-Usage 都已在 40GB 以上),请在启动前启用包内预留的调优命令:
编辑
docker-compose.yml,找到paddleocr-vlm-server段中这行:# command: /bin/bash -c "paddleocr genai_server --model_name PaddleOCR-VL-1.6-0.9B --host 0.0.0.0 --port 8080 --backend ${VLM_BACKEND:-vllm} --backend_config /config/vllm_backend.json"去掉行首的
#(保留缩进),保存;
docker compose down后重新./start.sh。该命令会加载
docker/config/vllm_backend.json,其中gpu-memory-utilization已保守设为0.2(约 12.8GB)、max-model-len设为 16384。若目标卡完全空闲、希望更高吞吐,可把该值调大(如0.4)或去回默认命令。
# 4.6 验证部署
# 查看所有容器状态(三个容器都应为 running/healthy)
docker compose ps
# 查看代理日志
docker compose logs -f ocr-proxy
# 查看 VLM 推理服务日志(首次启动重点看这个)
docker compose logs -f paddleocr-vlm-server
# 测试服务是否正常
curl http://127.0.0.1:12841/ocr/pic/health
预期返回:
{"code":"200","message":"Success","data":{"text_content":[...],"backend":"ok"}}
只要 code 为 "200" 且 data.backend 为 "ok",即表示代理与下游 PaddleOCR-VL 全链路连通。
首次启动时,PaddleOCR-VL 需要把 0.9B 模型加载到 NPU,启动较慢(约 5-10 分钟)。 请通过
docker compose logs -f paddleocr-vlm-server持续观察,直到日志出现Uvicorn running on http://0.0.0.0:8080,或容器 healthcheck 转为 healthy,再进行健康检查。容器start_period已设置为 600s,首次启动阶段 healthcheck 失败属正常现象。
# 4.7 上游系统对接
CoMi 或其他上游系统配置 OCR 服务地址为:
http://<服务器IP>:12841/ocr/pic/get_all_text
# 五、常用运维操作
# 停止服务
docker compose down
# 重启服务
docker compose restart
# 查看日志
docker compose logs -f
# 更新镜像(替换 images/ 下的归档后重新加载)
./install.sh
./start.sh
# 修改端口映射
如需修改宿主机端口:
- 编辑
.env文件,修改OCR_PROXY_PORT为目标端口(调试端口同理可改PADDLEOCR_VL_PORT、PADDLEOCR_VLM_PORT) - 停止服务:
docker compose down - 重新启动:
./start.sh - 将上游系统的 OCR 地址更新为新端口
# 更换使用的 NPU 卡
# 1. 查看各卡 HBM 占用,挑一张空闲卡
npu-smi info
# 2. 修改 .env 中的卡号(逻辑编号 0-7)
vi .env # ASCEND_RT_VISIBLE_DEVICES=1
# 3. 重建容器使环境变量生效
docker compose down
./start.sh
# 查看运行状态与资源占用
# 容器状态与健康检查
docker compose ps
# 各容器资源占用
docker stats
# NPU 侧 HBM 与算力占用(确认模型已加载到目标卡)
npu-smi info
模型加载完成后,目标卡的
HBM-Usage(MB)应有明显增长(0.9B 模型通常占用 8-12GB 级别,具体以现场为准)。若目标卡 HBM 仍为 0,说明模型没有加载成功,请查看paddleocr-vlm-server日志。
# 六、CoMi配置测试
# 场景一:智能部署工具配置OCR
如果项目上采用智能部署工具部署的CoMi,则通过一体化工具管理控制台修改AI-Manager的配置:
V5产品线仅需修改"OA OCR服务地址"这个配置,将其改成OCR真实地址。
格式为 http://OCR服务地址:OCR端口/ocr/pic/get_all_text
修改配置后,需要重新发布修改后的应用才能生效,具体操作方法详见《智能部署工具手册》 → 修改CoMi配置 章节。
# 场景二:Docker部署CoMi场景配置OCR
如果项目上采用Docker部署的CoMi,则修改 comi-install/config/ai-manager/application.yaml 文件:
cd /data/Seeyon/Comi/comi-install
vim config/ai-manager/application.yaml
# 找到 oaOcrUrl: 后面设置成OCR服务正确的地址
# 格式为 http://OCR服务地址:OCR端口/ocr/pic/get_all_text
# 修改保存后重启AI-Manager服务
docker restart comi-builder
# 验证方法
到CoMiBuilder本地知识库上传一个扫描件,解析策略勾选"文档图片解析",等待执行完成。如果扫描件执行完成并且正常切片,则说明OCR服务部署配置成功。
知识库OCR解析进度可通过AI-Manager日志查看:
tail -f volumes/ai-manager/logs/log-info.log
# 七、常见问题排查
# 7.1 镜像加载失败 / 提示架构不匹配
现象:docker load -i images/*.tar.gz 报错;或容器启动即退出,日志出现 exec format error、no matching manifest for linux/arm64、standard_init_linux.go: exec user process caused: exec format error。
原因:当前服务器是 x86_64,而镜像为 linux/arm64。
处理:
# 确认架构,必须为 aarch64
uname -m
# 确认镜像架构
docker inspect --format '{{.Architecture}}' \
ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-huawei-npu-offline
# 校验归档文件完整性
gzip -t images/*.tar.gz
# 对照部署包内清单核对 tag 与 digest
cat image-digests.txt
- 若
uname -m为x86_64:本套 NPU 镜像无法使用,必须更换为 aarch64 昇腾服务器。 - 若架构正确但仍报错:多为
images/下的归档传输损坏,重新拷贝归档文件后再次docker load,并用image-digests.txt核对 digest。
# 7.2 容器内 npu-smi 不可用 / 找不到 NPU 设备
现象:容器内执行 npu-smi info 报 command not found;或报 Failed to get device、device not found、no such device;服务日志报算子加载失败、libascend* 缺失。
原因:NPU 设备节点或驱动目录未完整透传进容器。
处理:
- 确认使用官方方案:
privileged: true+user: root+ 三个挂载(/usr/local/Ascend/driver、/usr/local/bin/npu-smi、/usr/local/dcmi,需要时自行加:ro)。 - 确认没有误加 Ascend Docker Runtime 相关的
ASCEND_VISIBLE_DEVICES;选卡统一用ASCEND_RT_VISIBLE_DEVICES。 - 若采用非 privileged 的显式设备方案,必须补齐全部项,缺一项即失败:
/dev/davinciN、/dev/davinci_manager、/dev/devmm_svm、/dev/hisi_hdc/usr/local/Ascend/driver(含driver/lib64、driver/version.info)/etc/ascend_install.info/usr/local/dcmi、/usr/local/bin/npu-smi
- 先在宿主机确认
npu-smi info正常,再验证容器内是否正常(见 3.6)。宿主机异常时,先修复驱动。
# 7.3 启动卡在加载模型阶段
现象:docker compose ps 显示 paddleocr-vlm-server 长时间 starting / unhealthy,健康检查一直失败。
原因:首次启动需要把模型权重加载到 NPU,耗时 5-10 分钟属正常;若超过 15 分钟仍未就绪,则需排查。
处理:
# 持续观察初始化进度,直到出现 Uvicorn running / 服务就绪
docker compose logs -f paddleocr-vlm-server
# 同时观察 NPU 侧是否有 HBM 占用增长
watch -n 5 npu-smi info
- 日志出现
Uvicorn running on http://0.0.0.0:8080后,再执行curl http://127.0.0.1:12841/ocr/pic/health。 - 若日志长时间停在模型加载且 HBM 不增长,优先检查 7.4(HBM 不足)与 7.2(设备不可见)。
- 不要因为健康检查暂时失败就反复
docker compose restart,会打断模型加载、使耗时更长。
# 7.4 HBM 显存不足 / OOM
现象:paddleocr-vlm-server 启动失败或推理时报 OOM、out of memory、NPU memory is not enough,容器反复重启。
原因:宿主机上已有其它 vLLM / 训练任务占用目标 NPU 卡的 HBM。0.9B 模型本身只需 8-12GB,但目标卡剩余 HBM 不足时仍会 OOM。
处理:
# 1. 查看每张卡的 HBM-Usage,确认目标卡是否有空闲
npu-smi info
# 2. 换一张空闲卡(逻辑编号 0-7)
vi .env # 改为 ASCEND_RT_VISIBLE_DEVICES=2
docker compose down
./start.sh
- 优先停掉占用该卡的其它任务;无法停止时直接换卡。
shm_size: 64g是共享内存不是 HBM 显存,但它同样会占用宿主机内存;宿主内存不足时容器也会启动失败(表现为 exit code 137 或no space left on device),可用free -g与docker stats确认。- 默认启动命令不加载
docker/config/vllm_backend.json,vLLM 按内置默认策略申请 HBM。若卡上已有其它推理进程,默认策略可能申请过多导致 OOM,请按 4.5 节「共享卡场景」 启用调优命令:去掉docker-compose.yml中paddleocr-vlm-server段# command: ...行首的#,再docker compose down && ./start.sh。 - 调优文件
docker/config/vllm_backend.json中gpu-memory-utilization=0.2(约 12.8GB)、max-model-len=16384、max-num-batched-tokens=32768。gpu-memory-utilization是 vLLM 通用参数,在 NPU 后端下是否精确生效官方未明确说明,但限制上限、避免占满共享卡是安全方向;卡完全空闲时可调大到0.4。
# 7.5 端口被占用
现象:docker compose up -d 报 bind: address already in use;或 install.sh 直接提示「端口 12841 已被占用」。
处理:
# 查看占用进程
ss -tlnp | grep -E '12841|8800|8808'
# 或
lsof -i:12841
# 停掉占用进程,或改用其他端口
vi .env # OCR_PROXY_PORT=12842
docker compose down
./start.sh
修改端口后,务必同步更新 CoMi 侧配置的 OCR 地址。
# 7.6 健康检查失败
现象:curl http://127.0.0.1:12841/ocr/pic/health 返回非 200,或返回 {"code":...,"data":{"backend":"error"}};docker compose ps 中 ocr-proxy 一直 unhealthy。
排查顺序(自下而上逐层确认):
# 1. 三个容器是否都在运行
docker compose ps
# 2. VLM 推理服务是否就绪(容器内 8080)
docker exec -it paddleocr-vlm-server curl -f http://127.0.0.1:8080/health
# 3. PaddleOCR-VL API 是否就绪(宿主机 8800 → 容器 8080)
curl -f http://127.0.0.1:8800/health
# 4. 代理日志中的具体报错
docker compose logs --tail=200 ocr-proxy
- 若第 2 步失败:回到 7.3 / 7.4,先让 VLM 服务就绪。
ocr-proxy依赖paddleocr-vl-api健康,paddleocr-vl-api又依赖paddleocr-vlm-server健康,上游未就绪时代理健康检查必然失败。 - 若第 3 步失败但第 2 步正常:检查 compose 中
PADDLEOCR_VL_PORT的映射是否为宿主机端口:8080,而不是:8800。 - 若第 2、3 步都正常但代理仍失败:检查
.env中VLM_BACKEND是否为vllm,以及OCR_PROXY_BACKEND_BASE_URL是否指向http://paddleocr-vl-api:8080。
# 7.7 不要升级 vllm-ascend 到 0.30 及以上
说明:vllm-ascend >= 0.30 已移除对 PaddleOCR-VL 的支持,升级后 VLM 服务将无法加载模型或直接报错。
要求:使用部署包镜像内置的 vllm-ascend 版本,不要在容器内执行 pip install -U vllm-ascend,也不要通过自定义 Dockerfile 升级该组件。如确需调整,先与研发确认兼容版本;现场仅需保证镜像未被改动(可用 image-digests.txt 校验)。
# 7.8 其它检查清单
部署遇到问题时,按以下顺序自检,通常能快速定位:
uname -m是否为aarch64npu-smi info是否在宿主机正常输出,Health是否OK- 目标卡
HBM-Usage是否有空闲 df -h /data是否 ≥ 120GB,free -g是否 ≥ 64GBdocker compose ps三个容器是否running,paddleocr-vlm-server是否healthydocker compose logs paddleocr-vlm-server是否出现Uvicorn runningcurl http://127.0.0.1:12841/ocr/pic/health是否backend: ok编撰人:het