# 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 列为 OK
  • Version / 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

脚本自动完成:

  1. 环境检查 — docker / compose / 端口 / 磁盘空间 / 镜像归档完整性 / npu-smi 可用性 / NPU 设备节点 / Ascend 驱动目录
  2. 加载所有镜像(ocr-proxy + PaddleOCR-VL × 2,images/ 合计约 20GB)
  3. 创建日志和数据目录(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 以上),请在启动前启用包内预留的调优命令:

  1. 编辑 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"
    
  2. 去掉行首的 #(保留缩进),保存;

  3. 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

# 修改端口映射

如需修改宿主机端口:

  1. 编辑 .env 文件,修改 OCR_PROXY_PORT 为目标端口(调试端口同理可改 PADDLEOCR_VL_PORT、PADDLEOCR_VLM_PORT)
  2. 停止服务:docker compose down
  3. 重新启动:./start.sh
  4. 将上游系统的 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 设备节点或驱动目录未完整透传进容器。

处理:

  1. 确认使用官方方案:privileged: true + user: root + 三个挂载(/usr/local/Ascend/driver、/usr/local/bin/npu-smi、/usr/local/dcmi,需要时自行加 :ro)。
  2. 确认没有误加 Ascend Docker Runtime 相关的 ASCEND_VISIBLE_DEVICES;选卡统一用 ASCEND_RT_VISIBLE_DEVICES。
  3. 若采用非 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
  4. 先在宿主机确认 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 其它检查清单

部署遇到问题时,按以下顺序自检,通常能快速定位:

  1. uname -m 是否为 aarch64
  2. npu-smi info 是否在宿主机正常输出,Health 是否 OK
  3. 目标卡 HBM-Usage 是否有空闲
  4. df -h /data 是否 ≥ 120GB,free -g 是否 ≥ 64GB
  5. docker compose ps 三个容器是否 running,paddleocr-vlm-server 是否 healthy
  6. docker compose logs paddleocr-vlm-server 是否出现 Uvicorn running
  7. curl http://127.0.0.1:12841/ocr/pic/health 是否 backend: ok
    编撰人:het