本地 VLM 的六个预设：量化、显存与加载路径

VLM_MODEL_OPTIONS 把六个预设定义成模型规模、量化方式和最低显存的组合。下载量由 repo 决定，量化方式不改变权重文件大小：

• A1：3B / BF16 / 8GB / 下载 6–8GB
• A2：3B / NF4 / 4GB / 下载 6–8GB
• B1：7B / BF16 / 16GB / 下载 14–16GB
• B2：7B / NF4 / 8GB / 下载 14–16GB（默认）
• C1：32B / BF16 / 72GB / 下载 64–70GB
• C2：32B / NF4 / 24GB / 下载 64–70GB

getVlmModelOption 只做 ID 匹配。平台兼容性和显存判断在 feature-installer.ts，不在模型表里。

推荐逻辑

recommendCompatibleVlmOption(vramGb, platform) 按 C1 → C2 → B1 → B2 → A1 → A2 遍历，先排除 getModelPlatformIssue 命中的组合。NF4 只允许 Windows/Linux 的 NVIDIA CUDA；Apple MPS 和 AMD ROCm 只能选 BF16。Apple 的可用显存按 max(0, vramGb - 4) 计算，返回第一个满足 usableVram >= minVramGb 的选项。

显存读不到时没有推荐项。--yes 且没有推荐项会抛 MODEL_INITIALIZATION_FAILED，要求显式传入 --vlm-option。显式指定的选项超出建议显存时，confirmVlmModelOption 打印风险：交互模式要求 y/n，--yes 直接继续安装。

量化与加载

load_vlm 按设备选择 dtype：CUDA 用 bfloat16，Apple MPS 用 float16，CPU 用 float32。GPU 模式设置 device_map={"": device}，模型完整放在加速设备上，不允许静默卸载到 CPU。NF4 在非 CUDA 平台直接返回 MODEL_INITIALIZATION_FAILED。

NF4 的量化配置是：

BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_use_double_quant=True,
    bnb_4bit_compute_dtype=torch.bfloat16,
)

权重仍是 BF16 下载，加载时量化。models/vlm/.vcli-model-option 和 .vcli-model-quantization 记录当前选择；两者与目标不一致时，download_vlm 会先 rmtree(VLM_DIR) 再重新下载。没有安装标记的目录被视为未完成下载，保留续传。

Mix 的显存生命周期

Mix 的 OCR 和 VLM 顺序执行。run_vlm_inference 先跑 OCR（--web 时还有 YOLO），调用 strip_internal_item_fields 移除 confidence/source，再执行 release_ocr()：

1. 将 _ppocr_engine、_ppocr_backend、_yolo_model 置为 None；
2. gc.collect()；
3. CUDA 可用时 torch.cuda.empty_cache()；
4. MPS 可用时 torch.mps.empty_cache()。

之后才加载 VLM。因此 Mix 的峰值接近 max(OCR, VLM) 加分配器残留，而不是两个模型显存相加。RapidOCR 或 Ultralytics 如果仍持有 tensor 引用，release_ocr() 无法替这些引用释放显存，残留会高于理论值。

超时与输出

VLM 请求的默认超时是 300_000ms，在 Mix 中覆盖 OCR、模型加载和解码整段流程；OCR-only 没有默认超时。CLI 的 --timeout <seconds> 会换算成毫秒并覆盖默认值。

生成参数固定为 max_new_tokens=4096、do_sample=False，elements 最多保留 30 个。输出里的 vlm 诊断记录 parsed、partial、outputTokens、maxOutputTokens、hitOutputLimit、responseChars 和各字段的恢复数量；_parse_vlm_json 在 JSON 截断时会恢复已闭合的顶层字段，而不是丢弃整次输出。

已知限制

minVramGb 是建议值，不是实测下限；24GB 上跑 C2 仍可能因为图片分辨率和上下文长度 OOM。NF4 不支持 MPS/ROCm。下载量是估算值，NF4 不会减少下载体积。device_map 固定为单设备，显存不足时直接失败，不会回退到 CPU。