Qwen2.5-VL-7B识图服务：本地图片、像素预算与OCR验收

目标是识图接口，不是上传文件演示

本教程用Qwen2.5-VL-7B-Instruct处理图片问答。建议在独立Linux GPU节点先使用单张24GB以上显存卡、短上下文和单请求验证；真实占用取决于视觉token、图片数量与推理实现。先按官方模型卡检查架构支持和依赖，再扩大容量。本文不是速度跑分，命令应在目标环境复核。

视觉输入会产生额外token。一张高分辨率扫描件可能比短文字请求消耗更多显存，多个图片同时进入又会扩大预处理与编码开销。不能看到7B标签就直接沿用纯文本模型的最大并发。

建立只读权重目录

python3 -m venv .vl-download
source .vl-download/bin/activate
pip install 'huggingface_hub[cli]'
mkdir -p /srv/models/qwen25-vl7b
hf download Qwen/Qwen2.5-VL-7B-Instruct \
  --local-dir /srv/models/qwen25-vl7b
docker run -d --name qwen-vl-test --gpus all --shm-size 8g \
  -p 127.0.0.1:8010:8000 \
  -v /srv/models/qwen25-vl7b:/model:ro \
  vllm/vllm-openai:v0.18.0 /model \
  --served-model-name qwen-vl7b --max-model-len 4096 \
  --max-num-seqs 1 --gpu-memory-utilization 0.85 \
  --limit-mm-per-prompt '{"image":1}'
docker logs -f qwen-vl-test
curl -f http://127.0.0.1:8010/health

下载时补上实际选定的revision，核对完整文件清单。服务端多模态参数随版本变化，若参数不被识别，应查0.18.0命令帮助，不直接删除限制继续上线。模型目录不应在运行中被下载程序修改。

本地图片不依赖外部URL

用Base64数据URL把文件随请求发送，避免服务端访问外网、远程链接失效或对任意URL抓取带来的SSRF风险。先用非敏感图片，文件上限和尺寸上限必须在业务网关再次限制。

import base64, io
from pathlib import Path
from PIL import Image
import requests
raw = Path('sample.jpg').read_bytes()
if len(raw) > 10 * 1024 * 1024:
    raise ValueError('图片超过10MB')
Image.MAX_IMAGE_PIXELS = 20_000_000
im = Image.open(io.BytesIO(raw)).convert('RGB')
im.thumbnail((1600,1600))
buf = io.BytesIO()
im.save(buf, format='JPEG', quality=92)
image_url = 'data:image/jpeg;base64,' + base64.b64encode(buf.getvalue()).decode()
payload = {'model':'qwen-vl7b','max_tokens':512,'temperature':0,
 'messages':[{'role':'user','content':[
  {'type':'text','text':'按阅读顺序提取图中的文字。看不清的部分写[无法确认]，不要猜测。'},
  {'type':'image_url','image_url':{'url':image_url}}
 ]}]}
r = requests.post('http://127.0.0.1:8010/v1/chat/completions',
                  json=payload, timeout=(5,180))
r.raise_for_status()
print(r.json()['choices'][0])

客户端缩图不是越小越好。1600只是试验上限，细字可能因此丢失；应把原图与缩图作为两个条件测试。服务端还可能进行二次缩放，最终视觉token预算以锁定版本处理器设置为准。不能用文件字节数替代像素数量限制。

建立自己的视觉验收集

准备50张有真值图片：清晰文本10张、倾斜10张、细字10张、表格10张、无目标10张。OCR按字符错误率观察，表格按字段与数值匹配，图像描述按事实检查。模型把不存在的内容补出来要单独统计，不与普通拼写错误混成一个平均值。

记录输入尺寸、压缩参数、提示词、输出预算、处理时间和显存峰值。temperature为0也不保证不同硬件逐字一致；验收重点是事实与结构。涉及金额、证件或工业决策的结果交给人工复核，不直接执行。

故障定位顺序

服务拒绝图片先检查请求content数组与data URL格式，再看图片是否损坏、尺寸是否超限、服务端模态限制是否为1。返回空答案检查输出预算与finish_reason。OOM先减少像素、输入张数与并发；不要先降低图片到无法读清，再把识别错误归因于模型。

若纯文本正常而图片异常，重点检查视觉处理器、依赖与模型分片。框架升级后重新跑同一套50张图片，确认预处理没有回归。回滚保留上一版镜像和模型清单，测试完成停止qwen-vl-test，不删除业务原图。参考：Qwen2.5-VL官方模型卡。

文件接收还需要服务端检查

客户端限制不可信，业务网关重新检查文件大小、解码后的宽高与图片数量。扩展名为jpg并不证明内容是JPEG，实际解码失败应在进入GPU前拒绝。对超大像素、损坏文件与动画图片制定明确规则，防止预处理耗尽主机内存。客户端先安装requests与Pillow，文件名和内容类型必须匹配。

主机准备足够内存和临时存储，图片解码、Base64编码与请求复制会增加内存占用。上传十MB文件，进程占用不一定仅十MB。多个请求同时传送时监测网关和推理容器，而不只看GPU显存。保存图片是否允许、保留多久及谁可查看应提前说明，敏感图片不记录到普通访问日志。

细字与表格需要不同提示和真值

OCR任务要求按顺序保留原字符，表格任务要求字段与行列关系，描述任务则可能允许概括。不要让模型先总结再把总结作为OCR真值。数字、日期、单位与否定词单独计错，因为一个字符错误就可能改变业务含义。看不清时应输出无法确认，并将原区域交人工，不要求模型补一个最合理数字。

对于很长扫描页，可尝试按版面分区处理，但每个区域保留原坐标和阅读顺序。重复边界与跨区域句子需要合并规则，不能简单把所有回答相加。原图、裁剪图和压缩图分别留存测试条件，判断质量变化究竟来自模型还是预处理。任何自动旋转或颜色处理都先在样本集上验证。

多图与长任务的扩展顺序

单图接口稳定后，再修改服务端图片上限并核对模型支持。多图请求必须验证图片顺序、引用编号与跨图比较，不能只把两张独立正确答案视为跨图能力。每种输入形态有单独的像素与token预算，越界时给出清楚提示，不等待显存耗尽才报错。

部署监控记录上传、解码、视觉编码、生成和总耗时，质量与速度同时看。新依赖或新模板上线前重复五类样本，重点观察原来可读的细字是否变差。回滚同时恢复模型、处理器配置和代理限制，不仅更换容器镜像。正式应用保留人工复核和原图入口，模型的流畅解释不能替代视觉证据。

客户端上传失败应保留错误类别，不把空图片继续传给模型。图片原件与处理副本使用不同路径，人工复核能查看真正输入。用户删除资料后，临时文件、缩略图与缓存一并按规则清理；同一图片多次任务保留各自模型版本，方便复查差异。