-
背景：在智能机器狗巡检任务中，尝试引入参数量有限，易于本地部署的多模态大模型，提高机器狗在不特定场景下的感知与决策能力。需要在本地快速部署 Qwen3‑VL‑4B 这类 VLM，并验证推理链路（单次推理、交互式 REPL、vLLM 加速、HTTP 服务化、批量推理）。
-
目标：
- 选取可能合适的大模型，验证本地部署方法
- 评估大模型的智力与推理速度
- 调研并应用高性能推理框架和模型优化技术提升推理速度；微调、蒸馏模型，提升处理部分任务时的智力
- 融合更多传感器数据
- 系统集成，打通运动与控制 - 底层导航与自主移动 - 实时小模型 - 复杂大模型 - 人工干预的感知决策链路
- 初步技术调研
- Transformers 直接推理：单次推理脚本与交互式 REPL（支持图片输入、上下文模式、性能统计与日志）。
- vLLM Python API 推理：在 2 的基础上启用 vLLM，加速推理与吞吐。
- vLLM HTTP 服务化：服务端常驻、客户端分离，支持会话与批量接口。
- 批量推理与 Evaluation：JSONL 生成、批量调用、结果对比与统计报告。
- 模型格式：原始 BF16 模型与 AWQ 8bit/4bit 量化模型目录结构（vLLM 不支持 GGUF，大部分消费级 GPU 不支持 FP8）。
- 核心依赖：
torch、modelscope/transformers、vllm、qwen-vl-utils、fastapi、uvicorn、requests、nvidia-ml-py（pynvml）。
pip list 见文末
网站：Hugging Face, Modelscope
https://www.modelscope.cn/models/Qwen/Qwen3-VL-4B-Instruct/summary
下载(ubuntu,python)： pip install modelscope modelscope download --model [model_name] [--cache_dir [cache_dir]]
- 脚本：
test.py/test2.py - 用途：验证模型是否能推理、GPU 是否可用、输出是否正常。
- 示例：
python test.py ./images/frame_000000.jpg "描述这张图片" - 输出：包含预处理/传输/生成/解码耗时、token 统计、显存占用。
- 脚本：
client.py - 功能：交互式验证（支持图片与上下文），性能报告，对话日志记录。
- 启动：
python client.py /start ./models/Qwen/Qwen3-VL-4B-Instruct /image ./images/frame_000000.jpg 识别车牌
- 脚本：
vllm-test.py（最小例子） /vllm-client.py（REPL） - 用途：验证 vLLM 推理链路、性能。
- 注意：需在脚本中改
checkpoint_path为本地模型目录。
- 服务端：
vllm_server.py - 启动：
uvicorn vllm_server:app --host 0.0.0.0 --port 8001
- 客户端：
- 交互 REPL：
python vllm_client1.py - 批量 JSONL：
python vllm_client2.py --infile batch_input.jsonl --outfile batch_output.jsonl - 管道模式：
cat batch_input.jsonl | python vllm_client3.py > batch_output.jsonl
- 交互 REPL：
说明：以下每个脚本均包含 1) 代码摘要 2) 关键函数/模块 3) 用法与参数 4) 示例，便于后续协作开发与对接。
- 代码摘要：基于 ModelScope 的
Qwen3VLForConditionalGeneration做单次图文推理，统计预处理/数据转移/推理/解码耗时与吞吐。 - 关键函数/模块：
load_model()（加载模型与处理器）、inference_image()（推理与性能统计）、model.generate()（核心生成）。 - 用法与参数：
- 运行：
python test.py <image_path> <prompt> - image_path：本地图片路径（相对或绝对）。
- prompt：文本指令，含空格需加引号。
- 模型路径：脚本内
model_path变量需改为你的本地模型目录。 - 可调参数：
max_new_tokens=256、temperature=0.7、top_p=0.9可按需求调整。
- 运行：
- 示例：
python test.py ./images/frame_000000.jpg "描述这张图片"
- 代码摘要：最精简的单次推理示例，直接在脚本内写死模型与输入。
- 关键函数/模块：
AutoProcessor.apply_chat_template()（构造输入）、model.generate()（生成）。 - 用法与参数：
- 运行：
python test2.py - 需手动编辑：
model路径、image路径、text提示词都在脚本中写死。
- 运行：
- 示例：
python test2.py
- 代码摘要：Transformers/ModelScope 直连推理的交互式 REPL，支持图片输入、上下文模式、性能统计与日志。
- 关键函数/模块：
infer_once()（一次推理）、cmd_start()（加载模型）、cmd_mode()（模式切换）、write_chat_log()（日志写入）。 - 用法与参数：
- 运行：
python client.py - 命令说明：
/start <model_path>：加载模型（必须先执行）。/stop：卸载模型并释放显存。/status：查看当前状态与显存。/mode [independent|contextual]：切换独立/上下文模式。/image <path>：绑定下一轮图片路径。/clear：清空当前上下文（仅 contextual）。/new：新建上下文会话并生成新日志。/performance [on|off]：开启/关闭性能统计输出。/set max_new_tokens <N>：设置生成长度上限（脚本内生效）。/help、/exit、/quit：帮助与退出。
- 日志：写入
log/independent.log或log/contextual_*.log。
- 运行：
- 示例：
python client.py /start ./models/Qwen/Qwen3-VL-4B-Instruct /image ./images/frame_000000.jpg /mode contextual 识别车牌
- 代码摘要：最小 vLLM 推理脚本，构造多模态输入并单次生成。
- 关键函数/模块：
prepare_inputs_for_vllm()（多模态输入构造）、LLM.generate()（vLLM 生成）。 - 用法与参数：
- 运行：
python vllm-test.py - 需手动编辑：
checkpoint_path（模型目录）、messages（图片与文本）、max_model_len（上下文长度）。 - 启动速度：
FAST_STARTUP=True时启用enforce_eager加快冷启动。
- 运行：
- 示例：
python vllm-test.py
- 代码摘要：使用 vLLM Python API 的交互式 REPL，模型常驻 GPU，支持单轮/上下文与性能统计。
- 关键函数/模块：
prepare_vllm_input()（vLLM 多模态输入）、cmd_start()（加载 vLLM）、infer_once()（推理）。 - 用法与参数：
- 运行：
python vllm-client.py - 命令说明：
/start <model_path>：加载模型。/stop：释放显存。/status：状态与显存。/mode [single|contextual]：切换模式。/image <path>：绑定下一轮图片。/clear、/new：清空或新建上下文会话。/performance [on|off]：性能统计开关。
- 可调参数（代码中）：
max_model_len=4096、enforce_eager=True、SamplingParams(max_tokens=512, temperature=0.0)。
- 运行：
- 示例：
python vllm-client.py /start ./models/Qwen/Qwen3-VL-4B-Instruct /image ./images/frame_000000.jpg 识别车牌
- 代码摘要：基于 FastAPI 的 vLLM 服务端，提供单次、会话与批量推理 API。
- 关键函数/模块：
prepare_vllm_input()（多模态输入）、/start（加载模型）、/single（单次推理）、/chat（上下文会话）。 - 用法与参数：
- 启动：
uvicorn vllm_server:app --host 0.0.0.0 --port 8001 - 环境变量：
VLM_MODEL_PATH：默认模型路径。VLM_MAX_MODEL_LEN：默认最大上下文长度。VLM_ENFORCE_EAGER：1/0，控制启动速度与吞吐。VLM_LOG_DIR：日志目录。
- 接口与参数：
POST /start：model_path、max_model_len、enforce_eagerPOST /stop：无参数GET /status：无参数POST /single：text、image、max_tokens、temperature、return_perfPOST /single_batch：items（id/text/image）、max_tokens、temperature、return_perfPOST /session/new：无参数，返回session_idPOST /session/clear：session_idPOST /chat：session_id、text、image、max_tokens、temperature、return_perf
- 启动：
- 示例：
uvicorn vllm_server:app --host 0.0.0.0 --port 8001 curl -X POST http://127.0.0.1:8001/single -H "Content-Type: application/json" \ -d '{"text":"描述这张图片","image":"./images/frame_000000.jpg","max_tokens":256,"temperature":0.0}'
- 代码摘要：面向
vllm_server.py的交互式客户端，支持单轮/上下文与性能统计。 - 关键函数/模块：
post()/get()（HTTP 调用）、/mode contextual（自动创建 session）。 - 用法与参数：
- 运行：
python vllm_client1.py - 命令说明：
/start [model_path]：让 server 加载模型（不传使用 server 默认）。/stop、/status：停止或查看状态。/mode [single|contextual]：上下文模式会自动创建 session。/new、/clear：新建或清空 session。/image <path>：绑定下一轮图片。/performance [on|off]：让 server 返回 perf 并打印。
- 运行：
- 示例：
python vllm_client1.py /start ./models/Qwen/Qwen3-VL-4B-Instruct /mode contextual /image ./images/frame_000000.jpg 识别车牌
- 代码摘要：读取 JSONL，分块调用
/single_batch，写出 JSONL 结果。 - 关键函数/模块：
read_jsonl()（读入）、/single_batch（批量推理）。 - 用法与参数：
--model：模型目录（默认./models/Qwen/Qwen3-VL-4B-Instruct）。--infile：输入 JSONL（必填）。--outfile：输出 JSONL（默认batch_output.jsonl）。--chunk：批量大小（默认 16）。--max-tokens：每条生成 token 上限（默认 2048）。--perf：返回并写入性能统计。
- 示例：
python vllm_client2.py --infile batch_input.jsonl --outfile batch_output.jsonl \ --model ./models/Qwen/Qwen3-VL-4B-Instruct --chunk 8 --max-tokens 512 --perf
- 代码摘要：stdin JSONL → stdout JSONL 的流式推理客户端，便于 shell 管道组合。
- 关键函数/模块：
requests.post("/single")（单次推理）、stdout 流式输出。 - 用法与参数：
- 输入 JSONL 每行字段：
id、image、text、max_tokens、temperature、return_perf。 - 输出：
id、image、text、output_text、perf。
- 输入 JSONL 每行字段：
- 示例：
cat batch_input.jsonl | python vllm_client3.py > batch_output.jsonl
- 代码摘要：将图片列表文本转换为 JSONL 输入，便于批量推理。
- 关键函数/模块：
PROMPT（默认提示词）、main()（逐行生成）。 - 用法与参数：
--infile：图片列表文件（默认in.txt，每行一条路径）。--outfile：输出 JSONL（默认batch_input.jsonl）。--root：可选根目录前缀。
- 示例：
python convert.py --infile val_in.txt --outfile batch_input.jsonl --root ./images
- 代码摘要：对比识别结果与参考文本，生成 ANSI/Markdown 误差报告与统计。
- 关键函数/模块：
extract_text_content_from_output()（解析结果）、highlight_pair_*()（差异高亮）。 - 用法与参数：
--jsonl：模型输出 JSONL（必填）。--ref：参考文本（必填，一行一条）。--out：输出文件基名（默认results）。--show-all：输出全部条目统计与详情。
- 示例：
python statistic.py --jsonl output.jsonl --ref val_in.txt --out results --show-all
{"id":"1","image":"/abs/path/a.jpg","text":"Describe this image","max_tokens":256,"temperature":0.0,"return_perf":true}POST /start：加载模型（可指定model_path、max_model_len、enforce_eager）GET /status：查看加载状态与显存POST /single：单次推理POST /single_batch：批量推理POST /session/new/POST /session/clear/POST /chat：上下文会话
- 日志目录：默认
log/，REPL/Server 会写入single或contextual_*。 - 批量输出：JSONL 文件，可配合
statistic.py生成错误分析报告。
| 模型版本 | 条目错误率 | 中文错误率 | 字母错误率 | 数字错误率 | 生成速度 (tokens/s) | 来源文件 |
|---|---|---|---|---|---|---|
| Qwen3‑VL‑4B | 239/992 (24.0927%) | 157/1103 14.2339% | 215/3384 6.3534% | 314/2926 10.7314% | 539 | results_4B.md |
| Qwen3‑VL‑4B AWQ 8bit | 249/992 (25.1008%) | 168 15.23% | 231 6.83% | 344 11.76% | 506 | results_4BAWQ8b.md |
| Qwen3‑VL‑4B AWQ 4bit | 254/992 (25.6048%) | 192 17.41% | 92 2.72% | 146 4.99% | 514 | results_4BAWQ4b.md |
| Qwen3‑VL‑2B | 236 (23.79%) | 183 (16.59%) | 106 (3.13%) | 90 (2.73%) | 1033 | results_2B.md |
| Qwen3‑VL‑8B AWQ 4bit | 195 (19.66%) | 122 (11.06%) | 171 (5.05%) | 243 (8.30%) | 453 | results_8BAWQ4b.md |
$ pip list
Package Version
--------------------------------- -------------
accelerate 1.12.0
aiohappyeyeballs 2.6.1
aiohttp 3.13.3
aiosignal 1.4.0
annotated-doc 0.0.4
annotated-types 0.7.0
anthropic 0.71.0
anyio 4.12.1
apache-tvm-ffi 0.1.8.post1
astor 0.8.1
async-timeout 5.0.1
attrs 25.4.0
av 16.1.0
blake3 1.0.8
cachetools 6.2.4
cbor2 5.8.0
certifi 2026.1.4
cffi 2.0.0
charset-normalizer 3.4.4
click 8.3.1
cloudpickle 3.1.2
compressed-tensors 0.12.2
cryptography 46.0.3
cuda-bindings 13.1.1
cuda-pathfinder 1.3.3
cuda-python 13.1.1
cupy-cuda12x 13.6.0
depyf 0.20.0
dill 0.4.0
diskcache 5.6.3
distro 1.9.0
dnspython 2.8.0
docstring_parser 0.17.0
einops 0.8.1
email-validator 2.3.0
exceptiongroup 1.3.1
fastapi 0.128.0
fastapi-cli 0.0.20
fastapi-cloud-cli 0.9.0
fastar 0.8.0
fastrlock 0.8.3
filelock 3.20.2
flash_attn 2.8.3
flashinfer-python 0.5.3
frozenlist 1.8.0
fsspec 2025.12.0
gguf 0.17.1
h11 0.16.0
hf-xet 1.2.0
httpcore 1.0.9
httptools 0.7.1
httpx 0.28.1
httpx-sse 0.4.3
huggingface-hub 0.36.0
idna 3.11
ijson 3.4.0.post0
interegular 0.3.3
Jinja2 3.1.6
jiter 0.12.0
jmespath 1.0.1
jsonschema 4.26.0
jsonschema-specifications 2025.9.1
lark 1.2.2
llguidance 1.3.0
llvmlite 0.44.0
lm-format-enforcer 0.11.3
loguru 0.7.3
markdown-it-py 4.0.0
MarkupSafe 2.1.5
mcp 1.25.0
mdurl 0.1.2
mistral_common 1.8.8
model-hosting-container-standards 0.1.13
modelscope 1.33.0
mpmath 1.3.0
msgpack 1.1.2
msgspec 0.20.0
multidict 6.7.0
networkx 3.4.2
ninja 1.13.0
numba 0.61.2
numpy 2.2.6
nvidia-cublas-cu12 12.8.4.1
nvidia-cuda-cupti-cu12 12.8.90
nvidia-cuda-nvrtc-cu12 12.8.93
nvidia-cuda-runtime-cu12 12.8.90
nvidia-cudnn-cu12 9.10.2.21
nvidia-cudnn-frontend 1.17.0
nvidia-cufft-cu12 11.3.3.83
nvidia-cufile-cu12 1.13.1.3
nvidia-curand-cu12 10.3.9.90
nvidia-cusolver-cu12 11.7.3.90
nvidia-cusparse-cu12 12.5.8.93
nvidia-cusparselt-cu12 0.7.1
nvidia-cutlass-dsl 4.3.5
nvidia-ml-py 13.590.44
nvidia-nccl-cu12 2.27.5
nvidia-nvjitlink-cu12 12.8.93
nvidia-nvshmem-cu12 3.3.20
nvidia-nvtx-cu12 12.8.90
openai 2.15.0
openai-harmony 0.0.8
opencv-python-headless 4.12.0.88
outlines_core 0.2.11
packaging 25.0
partial-json-parser 0.2.1.1.post7
pillow 12.0.0
pip 25.3
prometheus_client 0.24.0
prometheus-fastapi-instrumentator 7.1.0
prompt_toolkit 3.0.52
propcache 0.4.1
protobuf 6.33.4
psutil 7.2.1
py-cpuinfo 9.0.0
pybase64 1.4.3
pycountry 24.6.1
pycparser 2.23
pydantic 2.12.5
pydantic_core 2.41.5
pydantic-extra-types 2.11.0
pydantic-settings 2.12.0
Pygments 2.19.2
PyJWT 2.10.1
python-dotenv 1.2.1
python-json-logger 4.0.0
python-multipart 0.0.21
PyYAML 6.0.3
pyzmq 27.1.0
qwen-vl-utils 0.0.14
ray 2.53.0
referencing 0.37.0
regex 2025.11.3
requests 2.32.5
rich 14.2.0
rich-toolkit 0.17.1
rignore 0.7.6
rpds-py 0.30.0
safetensors 0.7.0
scipy 1.15.3
sentencepiece 0.2.1
sentry-sdk 2.49.0
setproctitle 1.3.7
setuptools 80.9.0
shellingham 1.5.4
sniffio 1.3.1
sse-starlette 3.1.2
starlette 0.50.0
supervisor 4.3.0
sympy 1.14.0
tabulate 0.9.0
tiktoken 0.12.0
tokenizers 0.22.2
tomli 2.4.0
torch 2.9.0
torchaudio 2.9.0
torchvision 0.24.0
tqdm 4.67.1
transformers 4.57.3
triton 3.5.0
typer 0.21.1
typer-slim 0.21.1
typing_extensions 4.15.0
typing-inspection 0.4.2
urllib3 2.6.3
uvicorn 0.40.0
uvloop 0.22.1
vllm 0.13.0
watchfiles 1.1.1
wcwidth 0.2.14
websockets 16.0
wheel 0.45.1
xgrammar 0.1.27
yarl 1.22.0