图片识别：PaddleOCR-VL-1.6模型部署和访问

背景描述

本文以 NVIDIA L20 环境为例，介绍如何在平台中部署 PaddleOCR-VL-1.6，并通过《模型网关》和《模型体验》完成图片文字识别。

操作包括准备模型文件和推理镜像、创建推理引擎、部署模型、配置 AI 服务提供者及网关路由、验证图片文字识别。

使用 1 张 NVIDIA L20、8 核 CPU、16 GiB 内存，部署 1 个副本。

前提条件

• 已具备目标项目的模型、推理引擎、部署和网关管理权限。
• 已初始化项目命名空间，并分配足够的项目配额。
• 有可调度的 NVIDIA L20 资源；本例每个副本使用 1 张 NVIDIA L20、8 核 CPU 和 16 GiB 内存。
• 环境能够从 ModelScope 导入模型，或已准备好对应的完整模型文件。
• 环境中镜像仓库已上传 hub.ecns.io/engines/vllm-openai:v0.29.0。

本例部署配置

配置项	本例取值
模型来源	ModelScope：PaddlePaddle/PaddleOCR-VL-1.6
平台模型名称	PaddleOCR-VL-1.6
模型文件大小	约 1.80 GiB
推理引擎名称	ocr-vllm，新建时可自定义名称
引擎类型/架构	vLLM/X86（amd64）
推理镜像	hub.ecns.io/engines/vllm-openai:v0.29.0
CPU/内存	8 核/16 GiB
AI 加速卡	NVIDIA-L20 × 1
副本数	1
自定义环境变量	无；部署页面另行填写 SERVED_MODEL_NAME
KV Cache 内存卸载	不启用
模型容器路径	/mnt/models
容器服务端口	8000
服务模型名称	PaddleOCR-VL-1.6
AI 服务提供者类型/API 规范	内部/OpenAI
网关路由名称/域名	all-in-one/ai.beacon.ai，其他环境可自定义
路由模型名称/后端模型名称	PaddleOCR-VL-1.6/PaddleOCR-VL-1.6

操作步骤

1. 准备推理镜像

在《容器镜像服务》中准备推理镜像 hub.ecns.io/engines/vllm-openai:v0.29.0，确认目标项目可以使用该镜像，且运行节点能够拉取。

如果需要转存至其他环境，保持镜像内容和版本一致。在《镜像管理》页面进入镜像详情页按平台要求添加 vllm、nvidia 分类标签，创建引擎时选择 X86 架构、vLLM 类型和 NVIDIA L20。

本例使用的是 vllm-openai 镜像。复现时应使用记录的镜像及后文启动参数。

2. 初始化项目并设置配额

1. 项目管理员进入《模型广场》，按提示完成命名空间初始化；已经初始化的项目可跳过。
2. 在《配额管理》中分配本次部署所需的 CPU、内存和 AI 加速卡配额，容器规格按环境选择安全容器服务对应配置。
3. 确认剩余配额和节点可用资源满足 8 核 CPU、16 GiB 内存、1 张 NVIDIA L20。项目内已有其他模型时，应按剩余资源核对。

3. 导入模型文件

1. 进入《模型仓库》，选择公共仓库后，单击 创建导入任务，选择从 ModelScope 导入。
2. 输入原始链接的内容为https://www.modelscope.cn/models/PaddlePaddle/PaddleOCR-VL-1.6，点击解析链接，按环境带宽限制需求输入限速大小，点击创建导入任务。
3. 等待导入完成，在《模型仓库》核对模型文件状态为 就绪、处理阶段为 成功。

4. 创建推理引擎

1. 进入《推理引擎》，单击 创建推理引擎。

2. 填写引擎名称，例如 ocr-vllm。

3. 引擎可见性选择公有引擎，类型选择 vLLM。

4. CPU 设为 8，内存设为 16，AI 加速卡选择 NVIDIA-L20，数量设为 1，架构选择 X86。

5. 选择镜像 hub.ecns.io/engines/vllm-openai:v0.29.0。

6. 在“启动命令”中按下面的分行形式填写（已默认填充）：

   vllm
   serve
   /mnt/models

7. 在“启动参数”中按下面的分行形式填写：

   --served-model-name
   $(SERVED_MODEL_NAME)
   --port
   8000
   --enable-prompt-tokens-details
   --trust-remote-code

8. 自定义环境变量留空，点击创建，完成创建。

以上两段分别粘贴到页面的“启动命令”和“启动参数”字段，每个参数或参数值独占一行。$(SERVED_MODEL_NAME) 是容器启动参数中的变量引用，按原样填写，不要直接粘贴到本机 Shell 中执行。后续部署页面会提供变量值。

/mnt/models 对应部署时挂载的模型文件路径；8000 是容器服务端口；--trust-remote-code 和其余参数均按已验证配置保留。

5. 创建并部署模型

1. 进入《模型广场》，点击新建模型，填写名称为PaddleOCR-VL-1.6，选择模型可见性为公有模型，模型文件选择绑定已有模型文件，模型文件选择步骤3导入的模型文件，推理引擎选择步骤4创建的推理引擎，点击创建模型。
2. 单击《模型广场》列表中PaddleOCR-VL-1.6卡片中的部署按钮，在新建模型部署的弹框中填写部署名称，例如 PaddleOCR-VL-1.6-deploy，副本数为1。
3. 推理引擎和模型文件会根据新建模型时选择的引擎和模型文件自动填入。
4. 核对模型文件信息与步骤3所导入的模型文件信息一致；核对页面展示的镜像、命令、参数及资源与步骤4 一致。
5. KV Cache 内存卸载 选择 不启用。
6. SERVED_MODEL_NAME 填写 PaddleOCR-VL-1.6，LoRA 微调模型保持为空。
7. 本例配置以继承上述引擎配置为基线，无需另外设置高级覆盖项。如已有部署设置了覆盖项，需展开“高级配置”核对最终命令、参数和环境变量。
8. 单击创建，等待状态变为 就绪。核对副本数为 1，实例运行正常。

SERVED_MODEL_NAME 会由平台注入部署容器，并由引擎中的 --served-model-name 引用。

模型启动或加载异常时，可在部署详情的状态、日志、终端页排查。

6. 创建 AI 服务提供者

1. 进入《AI 服务提供者》，单击 创建AI服务提供者。
2. 填入名称，例如 PaddleOCR-VL-1.6-deploy，服务类型选择 内部。
3. 选择部署选择步骤5创建的模型部署，核对平台生成的访问地址，点击创建，完成创建。
4. 确认提供者状态为 就绪。

7. 配置模型网关

1. 进入《模型网关》，创建路由或编辑已有路由。

2. 本例路由名称为all-in-one，二级域名填写ai，页面与环境域名后缀beacon.ai拼接为ai.beacon.ai。其他环境按实际域名后缀填写；已有该路由时，编辑并添加本模型即可。

3. 添加以下模型与后端映射：

   字段	取值
   对外模型名称	PaddleOCR-VL-1.6
   后端	PaddleOCR-VL-1.6-deploy
   后端模型名称	PaddleOCR-VL-1.6
   优先级	0
   权重	1

4. 保存并确认路由就绪。

8. 准备 API Key

《模型体验》页面需要填写 API Key。已有可用密钥时可直接使用；需要新建时：

1. 进入《套餐管理》，创建套餐，“可访问路由”选择上述路由all-in-one，按需设置调用限制。
2. 进入《API Key》，创建密钥并绑定该套餐。
3. 签发后保存密钥，后续在《模型体验》或 API 请求中使用。

在模型体验中验证图片文字识别

1. 进入《模型体验》，选择 视觉/OCR。

2. 填写有效 API Key。

3. 在 选择图片 中上传待识别图片。本例中图片中内容为文字信息“模型体验”。

4. 路由选择 all-in-one，模型选择 PaddleOCR-VL-1.6。

5. 输入提示词：

   识别图片内容

6. 单击 识别，等待返回识别结果。

7. 核对返回文字与图片内容一致。本例返回结果为：

   模型体验

使用其他图片时，应以该图片中的实际文字作为核对依据。

约束与注意事项

• 镜像与参数保持一致：本例为 vllm-openai:v0.29.0，启动参数包含 --trust-remote-code。更换镜像版本或启动方式后需重新验证。
• 资源配置以本例为基线：8 核 CPU、16 GiB 内存、1 张 NVIDIA L20、1 副本为本例使用的配置。
• 核对最终生效参数：模型部署可以覆盖引擎配置。排查时同时检查引擎和部署的高级配置；本文复现步骤采用继承引擎的配置，如设置过高级覆盖项，应逐项核对。
• 验证范围：本文验证图片文字识别流程；PDF、多页文档、表格或公式等业务场景，应另行准备样本验证。