LightOnOCR-2-1B-ocr-soup on vLLM-Ascend 0.18.0rc1

1. 简介

本文档记录 LightOnOCR-2-1B-ocr-soup 在 vLLM-Ascend 0.18.0rc1 环境的快速部署与验证结果。

LightOnOCR-2-1B-ocr-soup 是由 LightOn 发布的 OCR/VLM 多模态模型，文本部分基于 Qwen3ForCausalLM 架构，视觉编码器采用 pixtral。本次验证聚焦文本生成能力（单模态），确认其在昇腾 NPU 上的适配状态。

相关获取地址：

• 原始 HF 权重下载地址（ModelScope）：https://modelscope.cn/models/lightonai/LightOnOCR-2-1B-ocr-soup
• GGUF 量化权重下载地址（ModelScope）：https://modelscope.cn/models/noctrex/LightOnOCR-2-1B-ocr-soup-GGUF
• Docker Image（vLLM-Ascend 0.18.0rc1）：quay.io/ascend/vllm-ascend:v0.18.0rc1

参考文档：

• https://docs.vllm.ai/projects/ascend/zh-cn/v0.18.0/tutorials/models/Qwen3-Dense.html
• https://docs.vllm.ai/projects/ascend/zh-cn/v0.18.0/user_guide/support_matrix/supported_models.html

2. 验证环境

• NPU：2 逻辑卡（Atlas 800 A2）
• 模型路径：/tmp/weight/LightOnOCR-2-1B-ocr-soup
• 服务端口：8000

3. 服务启动

启动前可先检查端口：

ss -lntp | grep ':8000 ' || true

已验证通过的启动命令：

export ASCEND_RT_VISIBLE_DEVICES=0,1
export VLLM_USE_MODELSCOPE=true
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export HCCL_BUFFSIZE=512
export OMP_PROC_BIND=false
export OMP_NUM_THREADS=1
export TASK_QUEUE_ENABLE=1

vllm serve /tmp/weight/LightOnOCR-2-1B-ocr-soup \
  --host 0.0.0.0 \
  --port 8000 \
  --data-parallel-size 1 \
  --tensor-parallel-size 1 \
  --seed 1024 \
  --served-model-name lightonocr-2-1b \
  --max-num-seqs 32 \
  --max-model-len 8192 \
  --max-num-batched-tokens 4096 \
  --trust-remote-code \
  --gpu-memory-utilization 0.85 \
  --no-enable-prefix-caching \
  --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}'

关键参数说明：

• --trust-remote-code：建议携带，vLLM 0.18.0 已原生支持 LightOnOCRForConditionalGeneration 架构，但携带此参数可兼容潜在自定义代码
• --tensor-parallel-size 1：2B 模型单卡即可运行
• --max-model-len 8192：模型支持的最大上下文长度
• --gpu-memory-utilization 0.85：HBM 利用率
• --compilation-config FULL_DECODE_ONLY：ACL Graph 加速编译

4. Smoke 验证

基础检查：

curl -sf http://127.0.0.1:8000/v1/models
curl -sf http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lightonocr-2-1b",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "用一句中文说明 TCP 和 UDP 的核心区别。"}
    ],
    "temperature": 0,
    "max_tokens": 128
  }'

验证结果：

• /v1/models 返回 200
• /v1/chat/completions 返回 200
• 文本生成正常，无乱码

5. 性能参考

测试条件：128 input / 128 output，API 级压测（vllm bench latency 在本模型上会触发 vision encoder 的 profile_run 导致 OOM，故采用 API 级基准测试脚本 scripts/bench_perf.py）。

注：测试并发度为 2，总请求数 10。实际性能受输入长度、并发度及编译参数影响，以上数据仅供参考。

压测命令：

# 需先确保 vLLM 服务已在 8000 端口运行
python scripts/bench_perf.py \
  --url http://localhost:8000/v1/completions \
  --model lightonocr-2-1b \
  --max-tokens 128 \
  --latency-iters 5 \
  --throughput-requests 10 \
  --throughput-concurrency 2

6. 精度评测

6.1 验证方法

采用 NPU 与 CPU 基线对比的方式，对模型输出的 Logits 和 Hidden States 进行精度评估。验证指标包括：

• max_abs_error: 最大绝对误差
• mean_abs_error: 平均绝对误差
• relative_error: 相对误差
• cosine_similarity: 余弦相似度
• threshold: 通过阈值

6.2 验证结果

结论：NPU 与 CPU 基线高度一致，验证通过。

说明：

• 绝对误差（max_abs_error < 1.0）与余弦相似度（> 0.999）均满足通过标准。
• 相对误差受 bfloat16 近零值影响偏大，仅作参考，不作为硬性判定依据。

运行精度评测：

python scripts/eval_accuracy.py \
  --model /tmp/weight/LightOnOCR-2-1B-ocr-soup \
  --output accuracy_result.json

7. 推理脚本

项目提供 inference.py 一键推理脚本，支持本地 LLM 与 API 服务两种模式：

# 本地 LLM 模式（直接调用 vllm.LLM）
python inference.py --mode local \
  --model /tmp/weight/LightOnOCR-2-1B-ocr-soup \
  --prompt "The future of AI is"

# API 服务模式（调用已部署的 vLLM 服务）
python inference.py --mode api \
  --url http://localhost:8000/v1/chat/completions \
  --model-name lightonocr-2-1b \
  --prompt "Hello, how are you?"

8. 注意事项

1. vLLM 原生支持

   • LightOnOCRForConditionalGeneration 已在 vLLM 0.18.0 中注册，无需额外适配代码
   • 建议仍携带 --trust-remote-code，以兼容潜在自定义配置

2. 多模态能力未验证

   • 本文档仅验证文本生成能力（单模态）
   • OCR/图像理解能力需要额外的 vision encoder 适配，不在本次验证范围内

3. 显存占用

   • 2B 参数模型 BF16 精度下约占用 4-5 GB HBM
   • 单卡 64 GB Atlas 910 可轻松承载，无需张量并行

4. GGUF 权重说明

   • 本验证使用原始 HF 格式权重（lightonai/LightOnOCR-2-1B-ocr-soup）
   • 若需使用 GGUF 量化版本，请参考 llama.cpp / ollama 生态，vLLM-Ascend 对 GGUF 的原生支持有限

9. 参考信息