Mattral/production-vlm-engineering

大多数“CV 最佳实践”代码库都是静态的 markdown —— 具有教育意义，但没有任何可以运行、进行基准测试或作为基础进行构建的内容。这个代码库采取了相反的立场：**五个可运行的 pipeline**，它们实现了当前（2026 年 6 月）的前沿技术，并从一开始就内置了生产环境的约束。 每个示例都提供了： - 一条 **仅限 CPU 的降级运行路径**，让你可以在消耗 GPU 算力之前验证运行机制 - **诚实的基准测试表**，清楚地标明了 CPU 冒烟测试与真实 GPU 数据的区别 - 带有可运行代码的**前后指标对比**，而不是演示幻灯片 - 每项技术背后特定 2025–2026 年论文的**内联引用** ## 基准测试结果（CPU 冒烟测试路径） 五个示例在 CPU 上端到端运行不到 25 秒。标记为 ⚠️ 的是冒烟测试 代理指标；GPU 路径的说明在最右侧列。 | 示例 | 核心指标 | 数值 | 说明 | |---|---|---|---| | `vlm_chart_finetune` | 忠实度 Δ（LoRA vs zero-shot） | **+0.71** | ⚠️ 代理指标；真实的 LoRA 在 GPU 上训练 | | `vlm_chart_finetune` | 结构化提取 MAPE（微调后） | **0%** | ⚠️ 使用 ground-truth JSON 作为代理 | | `embedding_drift_active_learning` | 检测延迟（批次） | **0** | ✅ 真实的 KS-test，numpy/scipy | | `embedding_drift_active_learning` | 触发的重训次数 | **2** | ✅ 真实的基于阈值的反馈循环 | | `vlm_edge_inference` | INT8 相比 fp32 的加速比 | **3.99×** | ⚠️ 合成的 backbone；真实的 ONNX 需要 `[onnx]` 额外依赖 | | `vlm_edge_inference` | GQA KV-cache 内存相比 MHA | **14.3%**（小 7×） | ✅ 闭式算术，无需模型 | | `vlm_edge_inference` | KV-cache 内存（GQA vs MHA 基线） | **14.3%** | ✅ 闭式算术，无需模型 | | `vlm_robustness_guard` | 幻觉防御 precision / recall | **1.0 / 1.0** | ✅ 真实的忠实度测试套件 | | `vlm_robustness_guard` | OOD 检测 TP 率 | **85–100%** | ✅ 真实的 kNN 校准 | | `vlm_video_temporal` | 帧采样忠实度 | **0.70** | ✅ 真实的时序定位指标 | 完整表格（按严重程度划分的扰动明细、OOD ROC 扫描、基准测试时间戳）： [`benchmarks/reports/benchmark_report.md`](benchmarks/reports/benchmark_report.md) — 使用 `python benchmarks/run_all.py` 重新生成。 ## 架构 ``` production_vlm/ Shared library — CPU-only, zero hard ML deps ├── config.py Fail-fast dataclass config schemas (stdlib dataclasses, no pydantic) ├── drift/ KS-test CosineDriftDetector + frozen-baseline EWMA SPC ├── eval/ Numeric accuracy, grounding, faithfulness (RAGAS-inspired) ├── robustness/ ImageNet-C perturbations, kNN OOD detection, hallucination guard └── utils/ Synthetic charts, vision encoder, batching queue, observability (JSONL + Prometheus), retraining trigger examples/pipelines/ ├── vlm_chart_finetune/ LoRA (vision tower + LM) + structured JSON extraction ├── embedding_drift_active_learning/ KS-test + EWMA drift, AL triage, retraining loop ├── vlm_edge_inference/ ONNX export, INT8 quantization, FastAPI dynamic batching ├── vlm_robustness_guard/ Perturbation sweep, OOD, hallucination guard └── vlm_video_temporal/ Frame sampling, temporal grounding, scene-change detection notebooks/ 3 interactive notebooks with pre-executed output cells benchmarks/run_all.py Unified runner → Markdown + JSON comparative report tests/ pytest suite (56 checks via verify_no_pytest.py) scripts/verify_no_pytest.py stdlib-only verifier (no pytest needed, runs in CI) ``` ## 快速开始 ``` git clone https://github.com/Mattral/production-vlm-engineering cd production-vlm-engineering make setup # ~15s, CPU-only install production-vlm list-examples # see all five examples ``` 运行所有示例并生成统一的基准测试报告： ``` python benchmarks/run_all.py # → benchmarks/reports/benchmark_report.md (Markdown，可粘贴到 PRs / docs 中) # → benchmarks/reports/benchmark_report.json（机器可读） ``` 进行真实的 GPU 微调和 ONNX 导出： ``` make setup-gpu # adds torch / transformers / peft / onnxruntime production-vlm run-example vlm_chart_finetune production-vlm run-example vlm_edge_inference ``` ## 五个示例 ### 1 · VLM 图表微调 ([`vlm_chart_finetune`](examples/pipelines/vlm_chart_finetune/)) LoRA **同时**适配视觉塔和语言模型投影层（这是 2025–2026 年多模态 LoRA 的惯例 —— 纯语言 adapter 会保持视觉表征不变，这限制了在需要从图表中读取数值的任务上的提升）。默认 checkpoint：`Qwen2-VL-2B-Instruct`，可通过配置 YAML 进行替换。 评估使用了专为图表/文档 QA 设计的三项指标，而不是 BLEU 或精确匹配： - **数值准确率** —— 对提取的数值 token 进行相对容差匹配（2% 的容差，符合 ChartQA 评估惯例） - **定位得分** —— 预测中出现在源证据中的内容词比例 - **忠实度得分** —— 加权综合指标（60% 数值，40% 定位），受 RAGAS 启发并针对图像证据进行了调整 参考文献：Hu et al. (2021) LoRA · Wang et al. (2024) Qwen2-VL · Es et al. (2023) RAGAS ### 2 · Embedding 漂移检测与主动学习 ([`embedding_drift_active_learning`](examples/pipelines/embedding_drift_active_learning/)) 解决了 2026 年企业部署报告中**被引用最多的生产环境 CV 静默失败原因**：在输入分布发生变化（新摄像头、新渲染 pipeline、新文档格式）且准确率在没有错误信号的情况下衰退时，模型仍在继续提供服务。 两个具有不同语义的互补检测器： - **`CosineDriftDetector`** —— 对余弦相似度分布进行双样本 KS-test。持续型：在存在漂移的每个批次中触发。适合用于监控仪表盘。 - **`EWMADriftDetector`** —— 使用*冻结的基线标准差*的 EWMA-SPC。突发检测型：在偏移开始时触发，然后重新校准中心。适合用于警报系统。 当漂移被标记时，`select_for_active_learning()` 会根据批次与参考质心的距离对其进行排序 —— 这是一种免费、无需标签的新颖性代理 —— 并将最具新颖性的样本优先排入人工标注队列。 参考文献：Massey (1951) KS-test · Montgomery (2020) SPC · Settles (2009) 主动学习综述 ### 3 · 边缘推理与服务 ([`vlm_edge_inference`](examples/pipelines/vlm_edge_inference/)) ONNX 导出 → 动态 INT8 量化 → 前后基准测试对比表（延迟 p50/p95、吞吐量、峰值内存、准确率保持度），涵盖多种图像尺寸和批次大小。目标：实现 3–5 倍的加速，且准确率下降 <2%。 FastAPI 服务存根实现了 Triton Inference Server 和 TorchServe 使用的**动态批处理模式**：请求进入队列并在达到 `max_batch_size` 或 `max_batch_wait_ms` 时（以先到者为准）进行刷新。批处理队列（`production_vlm.utils.batching_queue.BatchingQueue`）无依赖且经过了独立的单元测试 —— 可以直接接入任何 asyncio 服务层。 一个独立的次要组件（`production_vlm.utils.kv_cache`）解决了*语言模型解码器的*内存占用问题 —— 这是与上述视觉编码器吞吐量不同的瓶颈。现代 VLM 在生成单个词之前，通常会对每张图像编码 500–1500 多个视觉 token，因此通常限制长上下文解码的是 KV-cache 大小，而不是 FLOPs。通过闭式内存算术比较了四种注意力/缓存策略（MHA、GQA、MQA、滑动窗口）—— 无需模型权重，在任何机器上运行结果都一致。GQA 可减少约 7 倍的内存，MQA 约 28 倍，而滑动窗口只有在真实序列超过窗口大小时才显示出其真正的价值（绝对内存有上限，而 MHA 则是无界的线性增长）。 参考文献：Jacob et al. (2018) 仅整数算术推理 · Ainslie et al. (2023) GQA · Dao (2023) FlashAttention-2 · Kwon et al. (2023) PagedAttention ### 4 · 鲁棒性与安全防御 ([`vlm_robustness_guard`](examples/pipelines/vlm_robustness_guard/)) 三种生产环境的失败模式，每种都有具体的检测或缓解措施： **扰动鲁棒性**：在五个严重级别下的六种 ImageNet-C 风格的损坏（亮度、对比度、噪声、模糊、旋转、遮挡）。通过自适应背景色估计，亮度和对比度具有完全的鲁棒性。模糊和旋转在高严重程度下确实会使阅读器性能下降 —— 这是破坏性扰动的真实结果。 **OOD 检测**：`KNNOODDetector` 从参考集自身的留一法相似度分布中校准其阈值（目标是特定的假阳性率，而不是任意的余弦截断值）。经验证的工作点：在风格迁移场景下，12.5% FP 时的 TP 率为 100%。 **幻觉防御**：`HallucinationGuard` 将 `faithfulness_score` 转换为三层决策（通过/标记/拒绝），在拒绝时返回安全的后备消息，而不是向用户展示无根据的答案。 参考文献：Hendrycks & Dietterich (2019) ImageNet-C ### 5 · 视频 / 时序推理 ([`vlm_video_temporal`](examples/pipelines/vlm_video_temporal/)) 用于多帧 VLM 推理的精简但可真正运行的模板 (P1-04)。在合成剪辑数据集上比较了三种帧采样策略，提供了一个将 `faithfulness_score` 扩展到多帧证据的时序定位指标，以及匹配版本化 schema 的结构化 JSON 答案输出。 关键的架构联系：示例 2 中的同一个 `CosineDriftDetector` 通过标记 embedding 偏离前一窗口的帧来检测场景变化 —— 无需特定于场景变化的训练。这意味着生产环境的视频 pipeline 可以重用与批处理监控系统相同的漂移监控基础设施。 将 `_synthetic_frame_sequence()` 替换为真实的视频加载器（decord/torchvision），并将 `_mock_vlm_temporal()` 替换为你的 VLM 调用（Video-LLaVA、VITA、InternVL2-Video）。采样、定位和场景检测代码保持不变。 参考文献：Lin et al. (2023) Video-LLaVA · Fu et al. (2024) VITA · CVPR 2026 时序 VLM 赛道 ## 关于降级路径的诚实说明 每个示例都会在运行时检测是否安装了真实的 ML 技术栈（torch/transformers/peft/bitsandbytes，或 onnx/onnxruntime）以及 CUDA 设备是否可用。如果没有，它将运行仅限 CPU 的路径，该路径会测试真实的数据生成、真实的配置验证和真实的评估套件 —— 但使用的是模拟的模型输出或计算等效的代理 backbone，而不是实际的模型权重。 这种区别记录在每个 `results.json` 中： ``` { "ran_with_real_ml_stack": false, ... } ``` 并且在控制台输出中明确打印。CPU 冒烟测试数据和真实 GPU 数据绝不会互换展示 —— 无论是在此代码库还是在生成的基准测试报告中。 ## 📓 Notebook （在 Google Colab 中打开） 核心技术的交互式演练 —— **无需 GPU，无需本地配置**。点击任意徽章即可直接在 Colab 中启动；包会在每个 notebook 的顶部自动安装。 | # | Notebook | 涵盖内容 | 启动 | |---|---|---|---| | 01 | 评估指标 | `numeric_accuracy`, `grounding_score`, `faithfulness_score` — 为什么 BLEU 在图表回答上会失效 | [](https://colab.research.google.com/github/Mattral/production-vlm-engineering/blob/main/notebooks/colab/01_evaluation_metrics_colab.ipynb) | | 02 | 漂移检测与主动学习 | `CosineDriftDetector`, `EWMADriftDetector` (冻结基线 SPC)，无标签的主动学习分诊 | [](https://colab.research.google.com/github/Mattral/production-vlm-engineering/blob/main/notebooks/colab/02_drift_detection_colab.ipynb) | | 03 | 鲁棒性与安全防御 | 扰动扫描，`KNNOODDetector`，`HallucinationGuard`，生产环境包装器模式 | [](https://colab.research.google.com/github/Mattral/production-vlm-engineering/blob/main/notebooks/colab/03_robustness_guard_colab.ipynb) | 每个 Colab notebook 端到端运行只需 1–3 分钟，并在末尾包含一个“自己动手尝试”的单元格，方便你使用自己的输入进行实验。完整索引请参见 [`notebooks/colab/README.md`](notebooks/colab/README.md)。 **不想运行只想阅读？** 包含所有已填充输出单元格的预执行可以直接在 GitHub 上渲染： [`01_evaluation_metrics.ipynb`](notebooks/01_evaluation_metrics.ipynb) · [`02_drift_detection_active_learning.ipynb`](notebooks/02_drift_detection_active_learning.ipynb) · [`03_robustness_safety_guard.ipynb`](notebooks/03_robustness_safety_guard.ipynb) ## 测试 ``` make test # pytest, 40 tests, requires pip install -e ".[dev]" python scripts/verify_no_pytest.py # stdlib-only fallback, no pytest needed ``` ## 相关工作 此代码库是一组生产级 ML 工程资源的一部分： - **[GuardRail-Studio](https://github.com/Mattral/GuardRail-Studio)** — LLM/VLM 安全和护栏模式（此处的幻觉防御遵循 GuardRail-Studio 的惯例） - **[FlashSpec](https://github.com/Mattral/FlashSpec)** — 内存高效的投机解码（是对边缘推理示例的补充） - **[Multimodal RAG](https://github.com/Mattral)** — 视觉 + 检索 pipeline（此处的图表 QA 微调是自然的上游补充） 这里提到的模式 —— 高效适配、embedding 空间监控、忠实度评估、推理优化 —— 在设计上是为了与这些代码库组合使用，而不是重复它们。 ## 为什么这对 2027 年很重要 从 2026 → 2027 年的发展轨迹很明确：VLM 将成为 Agentic 系统的默认感知层，设备端高效模型将变得可用于实时场景，并且 **MLOps 和鲁棒性模式将成为任何严肃的 VLM 部署的标准化要求** —— 类似于 LLMOps 在 2024-2025 年的成熟过程。 目前的采用差距在于，从业者理解高层次的理念（VLM、LoRA、漂移检测、护栏），但在构建能够处理真实数据变化并集成安全/可观测性的可重现端到端实现时却面临困难。此代码库专门填补了视觉/多模态技术栈中的这一空白。 具体来说： - **LoRA pipeline** 让你为下一代图表/文档 VLM 以及需要视觉定位的 Agentic 系统所依赖的结构化视觉推理任务做好准备 - **漂移检测器** 是每个生产级 VLM 部署在模型服务于真实流量时都需要的监控基础组件 - **边缘推理模式** 直接适用于 2027 年将在 Jetson 级及类似硬件上激增的设备端高效 VLM - **鲁棒性防御** 符合多模态模型安全层日益标准化的趋势 ## 引用与参考文献 每一项技术都在实现该技术的函数/类的文档字符串中进行了内联引用。 consolidated 的参考文献目录（LoRA、RAGAS、ChartQA、KS-test、SPC、PGD、ImageNet-C、ONNX quantization、Triton batching、Video-LLaVA/VITA）位于 [`docs/citations.md`](docs/citations.md) 中。 ## 许可证 MIT。详见 [LICENSE](LICENSE)。

标签：MLOps, 人工智能, 凭据扫描, 多模态模型, 模型微调, 用户模式Hook绕过, 系统调用监控, 自定义请求头, 视觉大模型, 边缘计算, 逆向工具