L
Lumiire/yolos-small
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

hustvl/yolos-small — Ascend NPU 部署说明

1. 简介

YOLOS(You Only Look at One Sequence)是华中科技大学提出的将 Vision Transformer(ViT)直接用于目标检测的框架。本仓库适配的 yolos-small 为在 COCO 2017(118k 训练图)上微调的小尺寸版本,采用 DETR 式二分图匹配损失训练,官方在 COCO 2017 val 上报告 AP 36.1。模型主体由 ViT-small 骨干(12 层、hidden 384)与 100 个目标查询(object queries)构成,输出为固定数量的类别 logits 与归一化包围框。

本次适配在华为昇腾 910 上完成了权重的获取、NPU 推理路径验证、服务化封装与精度一致性评估。由于该模型是目标检测模型而非自回归语言模型,vLLM 的 token 生成链路并不适用,本仓库采用 torch_npu 原生执行路径实现 NPU 加速,并以 FastAPI 提供 OpenAI 风格的服务化接口。

关键规格

项目值
模型 IDhustvl/yolos-small
架构YolosForObjectDetection
参数量30,684,768(约 30.68M)
骨干ViT-small(12 层 / 384 hidden / 6 heads)
输入尺寸预处理后 3×800×1056(保持宽高比)
检测查询数100
类别空间91 个 COCO 类 + N/A
权重体积122.8MB(model.safetensors,fp32,212 个张量)
官方精度COCO 2017 val AP 36.1

2. 验证环境

以下全部数据来自本次任务的真实运行环境。

2.1 硬件环境

项目配置
NPU 型号Ascend 910(aarch64)
SoCascend910_9391
可用 NPU2 片(本任务使用其中 1 片,npu:1)
单卡 HBM64GB
推理稳态占用进程 674MB / 芯片 HBM 增量约 414MB

2.2 软件环境

项目版本
操作系统Linux 5.10.0(aarch64)
Python3.11.14
PyTorch2.9.0
torch_npu2.9.0.post1
CANN8.5.1
transformers4.57.6
vllm-ascend0.18.0(本模型不使用其 LLM 链路)
Pillow11.x

2.3 权重来源与完整性

项目说明
首选源GitCode 镜像(hf_mirrors/hustvl/yolos-small)
结果git clone / ls-remote 被服务端重定向至首页,无法拉取
实际采用ModelScope(hustvl/yolos-small)
完整性model.safetensors 212 个张量读取校验通过,与 pytorch_model.bin 并存

3. 服务启动

仓库内 inference.py 自包含全部加载、前向、后处理逻辑,支持命令行单次推理与 FastAPI 服务化两种模式。默认端口 8320(避开环境中 8000/8001/8002 等其他服务的常用端口)。

3.1 安装依赖

pip install -r requirements.txt

3.2 启动服务化推理

export YOLOS_MODEL_DIR=/path/to/model_dir   # 可选,默认 hustvl/yolos-small
python3 inference.py serve 8320

启动日志(实测):

[SERVER] model loaded: device=npu:1 load_time_s=1.24
[SERVER] listening on http://0.0.0.0:8320
INFO:     Uvicorn running on http://0.0.0.0:8320

3.3 服务接口

方法路径说明
GET/health服务与模型加载状态
GET/v1/models模型元信息
POST/v1/detect目标检测(JSON 内传 base64 图片或图片 URL)
POST/v1/detect/file目标检测(multipart 上传图片)

3.4 命令行单次推理

python3 inference.py run --image demo.jpg --threshold 0.7
python3 inference.py run --image demo.jpg --json

4. Smoke 验证

以下为服务化推理的实测结果。测试图:assets/coco_sample.png(640×480 街景照片)。

4.1 健康检查

curl -s http://127.0.0.1:8320/health
{"status":"ok","model":"hustvl/yolos-small","device":"npu:1","loaded":true,"load_time_s":1.24}

4.2 检测请求

# base64 请求(Python 侧构造)
curl -s http://127.0.0.1:8320/v1/detect -H 'Content-Type: application/json' \
  -d '{"image":"<base64>","threshold":0.7}'

4.3 输出样例(threshold=0.7)

#类别置信度包围框 (x1,y1,x2,y2)
0remote0.9991[331.8, 80.5, 369.9, 188.1]
1remote0.9799[39.5, 69.4, 179.9, 115.9]
2cat0.9977[343.4, 19.8, 638.2, 370.9]
3couch0.9873[0.0, -0.0, 639.9, 475.8]
4cat0.9846[13.1, 55.7, 311.0, 467.1]

单次请求 HTTP 200,服务端推理 18.1ms。阈值 0.5 与 0.9 下检测数量均为 5。

5. 性能参考

数据来自本次任务实测(Ascend 910 单卡,npu:1,输入 640×480 图)。

阶段耗时
模型加载(含权重上卡)1.24s
首次前向(冷启动)176~304ms
稳态单请求推理约 18.1ms
持续负载吞吐945 次 / 58s(约 16 次/s)
NPU 显存占用(进程)674MB

说明:AICore 利用率在单次推理瞬间出现峰值,npu-smi 以约 1s 周期采样时读数多为 0;批量连续请求场景下吞吐约 16 req/s,主要瓶颈为图片编解码与预处理(Python 侧),模型前向占比小。

6. 精度测评

将同一输入在昇腾 NPU 与 CPU 上分别以 fp32 推理,比较输出。

指标结果
logits 最大绝对误差4.88e-1(集中于背景类极端负值 logit)
logits 平均绝对误差2.11e-2
softmax 概率最大误差1.47e-3
pred_boxes 最大绝对误差4.05e-2(<0.5px)
最终检测一致性5/5 标签与置信度完全一致,框偏移 <0.3px

结论:logits 的较大绝对偏差仅出现在低概率背景类(占比约 1.4%),softmax 后概率差被压缩到 1e-3 量级,最终检测结果与 CPU 逐目标一致。差异属于浮点累加次序(融合注意力、gelu 实现差异)导致的正常数值噪声,无算子级精度损失。

7. 注意事项

  • 架构定位:YOLOS 为目标检测模型(非 LLM/VLM),vLLM 的 /v1/chat/completions 接口不适用;本仓库以 torch_npu + FastAPI 提供服务化推理,接口见 3.3。
  • 端口冲突:环境中 8000/8001/8002/8007/8010/8011 等可能被其他任务占用,启动前请确认端口空闲,必要时改用其他端口(如 8320)。
  • 共享资源:多任务共用 NPU 时请勿 kill 他人进程;部署前用 npu-smi info 核对芯片占用,选择显存充裕的芯片。
  • 输入预处理:模型要求 800×1056 保持宽高比输入,宽高比过大的图片会被缩放并补边;测试图建议使用真实 COCO 风格照片。
  • 设备选择:默认使用 npu:1(显存更充裕);可通过 YOLOS_DEVICE 环境变量覆盖。
  • 权重格式:model.safetensors 与 pytorch_model.bin 并存,transformers 优先读取 safetensors。

引用

YOLOS 论文:Yuxin Fang, Bencheng Liao, Xinggang Wang, et al. You Only Look at One Sequence: Rethinking Transformer in Vision through Object Detection. arXiv:2106.00666.