Qwen3-VL OnDemand：按需加载的多模态模型代理

Qwen3-VL OnDemand是一个轻量级代理服务，旨在解决本地运行多模态视觉语言模型（如Qwen3-VL）的显存管理难题。它通过代理中继架构，实现空闲时零显存占用、请求到达时自动加载模型，平衡了快速响应与GPU资源释放的需求，让用户在有限显存环境下也能灵活使用多模态模型。

对于本地运行大语言模型的用户，显存管理是一大痛点，尤其是多模态视觉语言模型（VLM）如Qwen3-VL，加载后通常占用数GB显存。存在两种两难选择：

常驻显存模式：模型一直加载，响应快但占用GPU资源，无法同时进行其他GPU任务；

手动启停模式：使用前启动、用完关闭，节省显存但操作繁琐且加载耗时。

qwen3-vl-ondemand项目正是为解决这一困境而设计，实现“零显存空闲、按需自动加载”的平衡。

项目采用代理中继架构，核心组件包括：

vl-relay.py（中继代理）：纯Python编写的轻量级服务，仅占几MB内存，监听端口接收请求、管理后端模型生命周期、透明转发请求；

llama-server（后端服务）：llama.cpp提供的推理服务，运行Qwen3-VL模型，占用约3.8GB显存，仅在有请求时启动，空闲超时时自动关闭。

该架构将“服务入口”与“模型推理”解耦，中继代理始终运行，后端服务按需启停。

完整请求处理流程如下：

空闲状态：中继代理监听端口，llama-server未运行，显存占用0MB；

请求到达：中继代理检测到后端未运行，自动启动llama-server（约1.5秒加载），转发请求；

服务中状态：llama-server保持运行，后续请求直接转发，响应延迟低（约100 tokens/秒）；

空闲超时：超过配置闲置时间（默认5分钟）无新请求，自动终止llama-server释放显存。

此设计兼顾本地模型低延迟与显存不长期占用的需求。

项目在工程实现上的健壮性设计亮点：

1. PDEATHSIG机制：使用Linux系统调用确保父进程（中继代理）退出时，子进程（llama-server）自动终止，避免孤儿进程；

2. Exec启动模式：start.sh用exec启动中继代理，替换shell进程，关闭终端时中继代理退出，触发子进程终止；

3. 透明代理转发：支持所有HTTP方法透明转发，无需针对API协议细节处理，兼容文本、视觉等请求；

4. 纯标准库实现：vl-relay.py仅用Python标准库，零第三方依赖，降低部署复杂度与安全风险。

在Ryzen7 9700X + RTX3060 12GB配置上，使用Qwen3-VL-4B Q4_K_M量化模型的实测数据：

指标	数值
模型显存占用	约2.4GB
KV缓存显存（8K上下文）	约1.2GB
计算缓冲区	约0.3GB
总显存占用	约3.8GB
冷启动时间	约1.5秒
文本生成速度	约100 tokens/秒
空闲显存占用	0MB

该方案在消费级显卡上可行，冷启动延迟可接受，空闲零显存释放GPU资源。

与现有方案对比：

方案	显存占用	部署复杂度	灵活性
本中继方案	按需占用✅	一条命令	完全控制
Ollama常驻	始终占用	简单	参数受限
手动llama-server	始终占用	手动启停	完全控制
vLLM	始终占用+额外开销	复杂	生产级

相比Ollama，本方案空闲释放显存；相比手动管理，自动化启停；相比vLLM，部署简单，适合个人和小团队。

qwen3-vl-ondemand通过代理中继架构解决本地多模态模型显存管理难题，实现空闲零显存、请求自动加载，兼顾便利性与资源释放。适用于：

• 个人AI工作站（显存有限，需灵活切换GPU任务）；
• 开发测试环境（偶尔测试多模态功能）；
• 多模型共存（时间复用GPU资源）。

项目兼容主流AI客户端，且可扩展至任何支持llama.cpp的多模态GGUF模型，是显存有限用户体验本地多模态AI的实用方案。