Skip to main content
Glama

Mage-VL GGUF 转换与本地推理

本地 MCP 视频理解

此仓库现在将打过补丁的 Mage-VL GGUF 运行时打包为本地 MCP 服务。支持 MCP 的代理可以排队视频任务、使用游标读取持久事件,并在不将视频上传到云服务的情况下,继续基于返回的证据进行推理。

受支持的拓扑结构有意分为两部分:

Agent / MCP client ──HTTP MCP──> WSL MCP orchestrator (127.0.0.1:8765/mcp)
                                      │ SQLite WAL + one FIFO worker
                                      ▼
                           Docker CUDA Mage runtime (127.0.0.1:8080)
                                      │
                                local video files

运行时是现有的已补丁 GGUF 实现;本项目不会重新创建或量化 Mage-VL 权重。默认配置面向 8 GiB 的 NVIDIA GPU:Q4_K_M 语言主干、Q8 视觉/StreamMind 侧车、F16 DCVC 侧车、8192 token 上下文,以及 Q4 KV 缓存。

先决条件

  • Windows 系统装有 WSL2,并且在 WSL 内的 nvidia-smi 中可见 NVIDIA 驱动程序。

  • 名为 Ubuntu-24.04 的 Ubuntu 24.04 WSL 发行版(或传入 -istro)。

  • 首次构建镜像前,Docker 的 WSL 文件系统至少要有 20 GiB 空闲空间。

  • 持久化数据目录 E:\mageVL-data;模型权重、缓存、SQLite 数据库、日志和生成的运行时配置都保留在那里。

开发时使用的主机配备有 8188 MiB 显存的 RTX 4060 Laptop GPU;不要假设其他机器也有相同的余量。默认使用 12.8.1 CUDA 镜像。runtime.env 暴露 CUDA_VERSION=12.6.3 作为手动回退方案,以防兼容的 Docker 运行时无法启动它;脚本永远不会更新 Windows 显卡驱动程序。

安装并运行

在此仓库中打开 PowerShell 7 并运行:

.\scripts\mage-vl-mcp.ps1 setup-system
# Close/reopen the WSL shell after Docker group membership is applied.
.\scripts\mage-vl-mcp.ps1 setup-runtime
.\scripts\mage-vl-mcp.ps1 start

setup-system 有意设计为交互式:它会在 WSL 内部 安装 Docker Engine 和 NVIDIA Container Toolkit,并且可能会请求 Linux sudo 密码。setup-runtime 从 JohnTdi/Mage-VL-GGUF 修订版 63b23eb4707b1907668c57d61845e7d423016b5c 下载六个固定的 GGUF 工件,写入 E:\mageVL-data\models\SHA256SUMS.txt,在仓库本地虚拟环境中安装 MCP 包,并构建 CUDA 镜像。

start 保持在前台运行。按 Ctrl+C 会停止 MCP 监督进程,但保持已预热好的 Docker 运行时继续运行。可使用以下附加命令:

.\scripts\mage-vl-mcp.ps1 status
.\scripts\mage-vl-mcp.ps1 stop
.\scripts\mage-vl-mcp.ps1 stop -All

stop -All 会同时停止监督进程和运行时容器;它会保留 E:\mageVL-data 下的所有数据。

本地文件边界

MCP 服务不暴露 URL、RTSP、摄像头、屏幕或任意的容器路径。启动前,请编辑生成的 E:\mageVL-data\mcp.env,将 MAGE_VIDEO_ROOTS 设置为一个或多个已存在的 WSL 目录,用逗号分隔。默认值为 /mnt/e/mageVL-data/videos。

每个提交的 video_path 在需要时都会从 Windows 驱动器路径转换,通过符号链接解析,并且除非仍处于允许的根目录之下,否则会被拒绝。例如,只有当你希望代理检查的目录是 /mnt/e/Videos 时,才添加该路径。

MCP 客户端端点与工具

在本地 MCP 客户端中使用此 Streamable HTTP 端点:

http://127.0.0.1:8765/mcp

工具

用途

analyze_video(video_path, language, force)

排队进行全视频分析;兼容的已完成运行可被复用。

start_video_watch(video_path, pacing, language)

在有限的本地视频上运行原生 StreamMind。realtime 遵循源 PTS,并且从不丢弃窗口。

get_job(job_id)

读取已排队/运行中/成功/失败/已取消的状态。

get_video_events(run_id, after_event_id, limit, wait_ms)

基于游标的事件检索,以及可选的本地长轮询。

inspect_video_segment(video_path, start_seconds, end_seconds, question, language)

在一个有界区间上排队直接提问。

stop_video_watch(run_id)

取消已排队或正在运行的本地文件观看会话。

所有六个推理工具共享一个 FIFO 通道。观看会话会阻塞离线分析和片段检查,直到它完成或被停止。这是有意为之:原生 StreamMind 运行器会替换普通的 llama-server 并保持循环状态。在编排器重启时,进行中的作业会被标记为失败,而不是静默恢复。

离线分析会要求 Mage 返回结构化 JSON。如果模型输出不是有效 JSON,原始响应会保留在事件中,而不是被丢弃或呈现为虚构的时间线。

CI 和测试证明了什么

tests/test_mcp_orchestrator.py 演练路径边界、SQLite 事件游标和排队取消行为。GitHub Actions 还会检查固定的原生补丁能够应用,并编译 CPU llama-mage-codec-stream 目标。这些检查不能证明真实的 CUDA 容器、模型下载或端到端的视频推理;要获得此类验证,请运行 setup-runtime 并执行一个本地视频任务。

领域词汇参见 CONTEXT.md,两项架构决策参见 docs/adr。

Related MCP server: popcorn

原生 StreamMind 门控

此分支完全在 llama.cpp 内部执行 Microsoft 的主动式 StreamMind 路径:Mage-ViT 嵌入按编解码器时间戳分组,在 patch 上取平均,通过有状态的 Mamba-1 EPFE,并由四层 Qwen3 门控分类器评分。它不会重建 Transformers 张量,也不会在 VRAM 中保留第二个 BF16 模型。

cmake -S llama.cpp -B llama.cpp/build -DGGML_VULKAN=ON -DLLAMA_BUILD_EXAMPLES=ON
cmake --build llama.cpp/build --target llama-streammind-e2e -j
GGML_VK_VISIBLE_DEVICES=0 llama.cpp/build/bin/llama-streammind-e2e \
  models/mage-vl-backbone-Q8_0.gguf models/mage-vit-mmproj-Q8_0.gguf \
  models/mage-streammind-epfe-Q8_0.gguf models/mage-streammind-cls-Q8_0.gguf \
  video.mcv

每个 JSONL 行都包含源帧、官方的 silent/speak logits、说话概率,以及 Microsoft 的 0.5 边界处的原始决策。该门控与应用无关:客户端自行决定 speak 事件的含义,并可应用自己的策略。STREAMMIND_CHUNK=N 在保留循环状态的同时增量处理输入。

MP4、RTSP 和 HLS 输入

streammind_native.py 是一个传输/预处理适配器。在增量模式下,一个持久化的 FFmpeg 进程解码流,开放式就绪选择器在证据充分时构建 Mage 画布;两者都不执行神经模型。Mage-ViT、Mamba-1 EPFE 和门控分类器都在打过补丁的 C++ llama.cpp 运行时中执行,因此不会加载 Transformers 检查点或 BF16 副本。

只安装视频预处理器环境,然后保持其激活状态,使 codec-video-prep 和 cv-preinfer 位于 PATH 中:

python3.12 -m venv .venv-codec
source .venv-codec/bin/activate
pip install "codec-video-prep>=0.2.5"

本地 MP4:

python tools/streammind_native.py video.mp4 \
  --runner llama.cpp/build/bin/llama-streammind-e2e \
  --backbone models/mage-vl-backbone-Q8_0.gguf \
  --mmproj models/mage-vit-mmproj-Q8_0.gguf \
  --epfe models/mage-streammind-epfe-Q8_0.gguf \
  --classifier models/mage-streammind-cls-Q8_0.gguf \
  --incremental-producer tools/live_codec_stream.py \
  --vulkan-device 0

RTSP 摄像头和 HLS 使用相同的命令;只有源发生变化:

python tools/streammind_native.py 'rtsp://user:password@camera/stream1' ...
python tools/streammind_native.py 'https://host/live/playlist.m3u8' ...

增量实时模式没有固定的传输分段,也不写入临时 MP4。在默认的 8 采样 FPS 下,当满足就绪条件和时间覆盖时,它可以在最少八个样本(一秒)后关闭;否则会延长至 --sampled-frames。EPFE 状态会跨越每个自适应组持续存在,直到进程退出。对于本地文件,--realtime 让 FFmpeg 以播放速度提供帧。小型 MAGECV1 交接包在消费后立即删除。省略 --incremental-producer 会保留分段式 codec-bitcost 兼容路径,用于离线/参考工作。

针对 microsoft/Mage-VL 的可重复转换文件和本地推理说明。已发布的 GGUF 权重已在图像、视频和语言基准上测量,并与 Microsoft 报告的 BF16 参考值进行了比较。

模型权重: Hugging Face 上的 JohnTdi/Mage-VL-GGUF

Mage-VL Studio 分析选定的视频范围,包含 OCR、运行时指标和全帧高亮

Mage-VL Studio:在选定的时间范围内进行原生 Q8 GGUF 分析,配备专用静态文本 OCR、RAM/VRAM 指标和具有代表性的全帧高亮。

开发披露: 代码辅助和审查由 OpenAI GPT-5.6 Sol 提供。最终的集成、测试和发布决策由仓库维护者做出并验证。

此 GitHb 仓库包含 Docker 运行时、补丁和启动说明。Hugging Face 仓库包含 Q4/Q8 主干和 F16/Q8 视觉 GGUF 工件。

状态

组件

状态

打过补丁的 llama.cpp 中的 Qwen3 语言主干 GGUF

可用:Vulkan、CUDA 和 CPU

Mage-ViT mmproj 到 F16/Q8 的转换

可用且已通过质量验证

原生 Mage-ViT 图像/视频推理

在随附的 llama.cpp 补丁中可用

原生有状态 StreamMind 实时推理

与随附的 Q8 侧车配合可用

Docker 镜像会对固定的 llama.cpp 应用一个小的原生运行时补丁。在推理期间,语言主干和 Mage-ViT 都保持其 GGUF 存储类型;不涉及 Transformers 进程或 BF16 重建。

已发布变体

文件

大约大小

推荐用途

mage-vl-backbone-Q8_0.gguf

4.69 GB

最佳质量的 GGUF 主干

mage-vl-backbone-Q4_K_M.gguf

2.72 GB

更小、更快的生成

mage-vit-mmproj-Q8_0.gguf

353 MB

紧凑的视觉权重

mage-vit-mmproj-F16.gguf

661 MB

最高视觉保真度

mage-streammind-epfe-Q8_0.gguf

96.5 MB

有状态的实时流内存

mage-streammind-cls-Q8_0.gguf

512.6 MB

静音/说话门控分类器

mage-dcvc-rt-intra-F16.gguf

91.3 MB

首帧/重置帧编解码器图

mage-dcvc-rt-inter-F16.gguf

41.4 MB

有状态的帧间编解码器图

权重有意不存储在 Git 中。全部八个运行时工件都位于 JohnTdi/Mage-VL-GGUF 模型仓库中。

快速开始:原生 llama.cpp 服务器

一键引导安装

克隆仓库后,安装程序会检测 CUDA 或 Vulkan,估算 VRAM,选择 8/16/24–32 GB 配置,只下载所需的 GGUF 文件,推导匹配的 DRM 节点/组,并启动 Docker:

./install.sh

使用 MAGE_BACKEND=vulkan|cuda 和 MAGE_PROFILE=8|16|24|32 覆盖检测结果。生成的 .env 保持可编辑。

随附的镜像会编译固定的 llama.cpp 修订版,应用 Mage-ViT 运行时补丁,并包含图像/视频依赖。未使用的上游 llama.cpp Web UI 在构时被禁用;这样可以避免 Node/npm 和可变 UI 的下载,而网关会提供自己的本地上传页面。

此仓库是完整的运行时发行版:Docker 克隆固定的 llama.cpp,应用来自 patches/ 的统一原生 Mage 补丁,编译它,并使用两个 GGUF 文件启动 llama-server。不需要单独的 llama.cpp fork 检出。

要求:Linux、Git、带 venv 和 pip 的 Python 3、Docker Engine,以及 Docker Compose 2.30 或更高版本。从一个空目录开始:

git clone https://github.com/JohnTDI-cpu/mage-vl-gguf.git
cd mage-vl-gguf

python3 -m venv .hf-venv
.hf-venv/bin/pip install "huggingface_hub>=0.34"
.hf-venv/bin/hf download JohnTdi/Mage-VL-GGUF \
  mage-vl-backbone-Q8_0.gguf mage-vit-mmproj-Q8_0.gguf \
  mage-streammind-epfe-Q8_0.gguf mage-streammind-cls-Q8_0.gguf \
  mage-dcvc-rt-intra-F16.gguf mage-dcvc-rt-inter-F16.gguf \
  --local-dir models

cp .env.example .env
# RADV needs both DRM nodes from the same GPU. Keep their host names unchanged.
sed -i "s/^RENDER_GID=.*/RENDER_GID=$(stat -c '%g' /dev/dri/renderD128)/" .env
sed -i "s/^VIDEO_GID=.*/VIDEO_GID=$(stat -c '%g' /dev/dri/card0)/" .env
docker compose --profile vulkan up -d --build --wait vulkan
curl --fail http://localhost:8080/health

首次构建会编译我们打过补丁的 llama.cpp,可能需要几分钟。当 /health 返回成功时,在浏览器中打开 http://localhost:8080,选择一个 MP4,输入问题,然后点击 分析视频。无需手动转换或编解码器命令。

对于脚本,上传一张 JPEG/PNG 图像:

curl --fail http://localhost:8080/v1/image/analyze \
  -F image=@./your-image.jpg \
  -F 'prompt=Is there a person in this image? Answer yes or no.' \
  -F max_tokens=32

或者上传一个普通的 MP4 文件。H.264 和 HEVC 会直接进入官方的 编码感知预处理器;AV1、VP9、MPEG-4 Part 2 以及其他 FFmpeg 可读取的 视频编码会自动转换为高质量 H.264。随后容器打包 MAGECV1 并运行原生 GGUF 推理:

curl --fail http://localhost:8080/v1/video/analyze \
  -F video=@./your-video.mp4 \
  -F 'prompt=Describe the important events in temporal order.' \
  -F max_tokens=256

持续实时监控

打开 Mage-VL Studio,选择 实时流,粘贴 RTSP/RTMP、直接 HTTP/HLS、 localhost 或受支持的页面 URL(如 YouTube),配置响应策略, 然后选择 开始实时分析。原生 C++ 进程执行 FFmpeg 解码、时间采样、DCVC-RT GGUF 和 Mage 画布构建,然后 跨组保留 StreamMind 的循环 EPFE 状态。Mage-ViT 对一组编码一次; 相同的嵌入同时供门控和任何触发的 Qwen 响应使用。带时间戳的 结果会立即显示在播放器下方。

Mage-VL Studio 分析带时间戳响应的实时流

演示使用随机选择的公共 YouTube 实时流;选择该源仅用于 测试实时分析路径,不代表任何背书。

持续路径不会创建传输 MP4 或 MAGECV1 交接文件。在更改模型设置之前 停止实时会话。源和处理延迟取决于网络和帧内容。 UI 报告实时延迟、p95 实时因子(RTF)、待处理/丢弃窗口 以及流是否保持同步。丢弃过期窗口 默认启用, 因此过载的安装会保持最新状态,而不是分析不断增长的历史记录。

实时 FPS 目前是显式设置的,不会自动基准测试或适应用户的 GPU。 分析 FPS 字段默认为 8;硬件配置文件 设置了一个保守的起点,但不会在会话运行期间更改 FPS。 如果流水线落后,有界队列会在启用 丢弃过期窗口 时丢弃过期窗口, 而不是累积无限延迟。使用报告的 RTF 和队列遥测来调整它:保持 p95 RTF 低于 0.8, 首先降低分析 FPS(12 -> 8 -> 6 -> 4 -> 2),然后如有必要 降低 MAGE_DCVC_LIVE_MAX_HEIGHT(720 -> 480 -> 360)。只有在流稳定 运行数分钟后才增加任一设置。

测得的 R9700 容量结果位于 docs/live-performance-r9700.md。在这块 GPU 上, 安全默认值接受 1080p/4K 源,但将其缩小到 480p 并以 8 fps 采样。 原生 DCVC 在 854x480 下测得 14.30 fps,720p 下 6.34 fps,1080p 下 1.55 fps。 首次空缓存启动可能需要 15-17 秒编译 Vulkan 图;预热会话不会重复该开销。

使用 docker compose --profile vulkan down 停止服务。后续启动 可以省略 --build:

docker compose --profile vulkan up -d --wait vulkan

选择量化

在 .env 中设置该组合;支持全部四种组合:

# Highest GGUF quality
GGUF_FILE=mage-vl-backbone-Q8_0.gguf
MMPROJ_FILE=mage-vit-mmproj-F16.gguf

# Recommended compact setup
# GGUF_FILE=mage-vl-backbone-Q4_K_M.gguf
# MMPROJ_FILE=mage-vit-mmproj-Q8_0.gguf

下载所有变体,以便以后无需再下载即可切换:

.hf-venv/bin/hf download JohnTdi/Mage-VL-GGUF \
  mage-vl-backbone-Q8_0.gguf mage-vl-backbone-Q4_K_M.gguf \
  mage-vit-mmproj-Q8_0.gguf mage-vit-mmproj-F16.gguf \
  mage-streammind-epfe-Q8_0.gguf mage-streammind-cls-Q8_0.gguf \
  mage-dcvc-rt-intra-F16.gguf mage-dcvc-rt-inter-F16.gguf \
  --local-dir models

API 默认绑定到 127.0.0.1,因为 llama-server 在此配置中 没有身份验证。要故意暴露它,请在 .env 中设置 HOST_BIND,并用防火墙或经过身份验证的反向 代理保护它。切勿将原始端口直接转发到互联网。

默认配置仅向容器暴露匹配的 /dev/dri/renderD128 + /dev/dri/card0 对,因此其他 Vulkan GPU 不可见。首次使用前请对照 /dev/dri/by-path 验证两者。 如果更改它们,还要从相同的节点派生 RENDER_GID 和 VIDEO_GID。 不要在容器内将它们重映射为不同的名称:RADV 遵循 它们的 sysfs 关系,当名称被重写时可能认证失败。 使用 --profile cuda 可获取 NVIDIA 镜像;它需要 NVIDIA Container Toolkit。参见 docker/README.md。

公共网关仅暴露本地上传页面、/health、 /v1/image/analyze、/v1/video/prepare、/v1/video/analyze-prepared、 /v1/video/analyze、/v1/live/sessions 会话 API 和只读的 编码-画布预览;内部 llama-server 仅 在容器内监听。预处理视频按内容哈希和 所有影响输出的预处理设置进行缓存,因此重复上传会跳过 转码和编码预处理。视频音轨被有意 忽略:Mage-VL 分析视觉内容,而非语音或声音。

实时流面板接受 RTSP/RTMP、直接 HTTP/HLS、localhost URL 和 受支持的网页(如 YouTube)(在容器内使用 yt-dlp 解析)。它提供四种响应策略:周期性、每次检测到变化时、 仅重要变化,以及重要变化加周期性报告。窗口 长度、最小响应间隔、重要性敏感度、视觉质量、响应 长度、RTSP 传输和用户提示均可配置。封闭的传输 段及其 MAGECV1 工作区在推理后立即删除; 仅保留有界的内存结果历史。在更改模型设置之前 显式停止会话。

优化的原生实时运行时使用 Mage-ViT 对每个视频窗口 恰好编码一次。其嵌入同时供 StreamMind EPFE/分类使用,并且仅 在触发后才供 Qwen 生成使用。启动实时模式会卸载普通的 上传 llama-server;停止实时模式会恢复它,因此两个语言骨干 永远不会同时驻留。每个实时结果都暴露 vision_encode_count=1 和 shared_vision_embeddings=true 作为运行时检查。 Docker 版本包含完整的原生 StreamMind 补丁,两个 Q8 EPFE/分类器 sidecar 从链接的 Hugging Face 仓库下载。

浏览器面板立即预览本地 MP4,显示预处理和 推理进度,渲染模型答案和 PP/TG 指标,并显示 传入 Mage-ViT 的确切编码画布。画布是 所选源帧补丁的空间马赛克,不一定是传统的完整帧。 因此每张卡片都报告其确切的源帧时间戳范围以及 从 src_patch_position.npy 派生的完整时间戳列表。 播放器包含一个双手柄分析范围选择器。仅 解码和缓存所选区间,而每个预览时间戳都 转换回原始视频的绝对时间线。 其五级 Speed/Detail 控件同时更改时间采样(96–320 帧)和编码画布像素预算(90k–180k)。可选的彻底 文本扫描有意运行单独的 OCR 聚焦推理过程:实验 表明,即使处于最高视觉细节设置,单个通用事件提示也可能遗漏可读的静态字幕。

高级设置可以在明确确认后以不同的上下文、批大小、 微批大小和 F16/Q8/Q4 KV 缓存重新加载模型。如果新配置 无法启动,网关会尝试恢复之前的配置。 资源面板在 Linux 上报告网关+llama 组合常驻 RAM。在 NVIDIA 上使用每进程 nvidia-smi VRAM;在 AMD/Vulkan 上,由于内核 不暴露可靠的每进程 VRAM,它报告所选 DRM 设备 相对于预加载基线的增量,并明确标注该方法。

16 GiB GPU 的默认值

随附的配置文件使用一个请求槽、F16 KV 缓存和 ctx=16384。在 配备 Vulkan 的 Radeon AI PRO R9700 上,基准仓库中描述的 50.64 秒 1080x1920 H.264 测试片段产生了 8,099 个提示词 token:

骨干 + 视觉

峰值 VRAM

视频预填充

解码

请求墙钟

Q8 + Q8

7.56 GiB

2,691 tok/s

80.66 tok/s

4.16 s

运行时预填充补丁将连续的带时间戳文本和视觉跨度合并, 直到解码器批次满。在此补丁之前,相同的输入创建了许多 小的 Vulkan 提交,仅达到 1,221 tok/s。使用该补丁和 ctx=32768 时达到 2,718 tok/s,使用约 10.4 GiB;将 预分配上下文减少到 16k 保留相同的 F16 KV 值,同时节省约 2.8 GiB。确切值取决于驱动程序、提示、画布数量和电源状态。

安全/资源默认值位于 .env 中:16,384 个上下文 token、一个并发 预处理器、2 GiB 上传、60 分钟时长、3840x2160 源视频、256 个采样帧、每个视频画布 150,000 像素、256 个生成 token,以及 15 分钟预处理超时。JPEG/PNG 图像自动缩减到 最多 1,048,576 像素,以保持图像和视频工作负载在 16 GiB 配置文件内。内容寻址预处理缓存上限为 50 GiB, 逐出最近最少使用的条目。更改 .env 中相应的 MAGE_* 值,然后使用 docker compose --profile vulkan up -d --force-recreate vulkan 重新创建服务。

最有用的调优变量是 LLAMA_ARG_CTX_SIZE(上下文/VRAM)、 MAGE_SAMPLED_FRAMES(时间覆盖)、MAGE_MAX_PIXELS(每个编码 画布的 token)、MAGE_IMAGE_MAX_PIXELS 和 MAGE_MAX_NEW_TOKENS。解码器提交 显式固定为 MAGE_BATCH_SIZE=2048、MAGE_UBATCH_SIZE=512 和 F16 KV 缓存。如果自定义图像设置创建的视觉块大于 解码器批次,API 返回明确的 422 错误,而不是接受 截断的提示;增加 MAGE_BATCH_SIZE 或减少图像像素。

视频时长不会一对一映射到上下文:默认最多采样 256 帧,就绪分组在测试的 15–85 秒片段中产生 24–52 个画布(约 4,800–10,400 个视觉 token)。更多采样帧或更大的 画布会增加预处理时间、上下文使用和内存。如果请求 无法容纳,降低 MAGE_SAMPLED_FRAMES 或 MAGE_MAX_PIXELS;仅当 有足够 VRAM 时才增加 LLAMA_ARG_CTX_SIZE。

转换为 GGUF

补丁针对 llama.cpp 提交 a52077c4cabb4f3c0298329c9d2dd1324d5604cb。不同的修订版本可能需要 手动解决冲突。从克隆的 mage-vl-gguf 仓库根目录运行此块;它会在其下创建 llama.cpp/。

使用单独的转换器 venv。其固定要求安装 CPU PyTorch, 不得替换用于推理的 ROCm/CUDA 环境。

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
git checkout a52077c4cabb4f3c0298329c9d2dd1324d5604cb
git apply ../patches/llama.cpp-mage-native-streammind.patch
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements/requirements-convert_hf_to_gguf.txt

python convert_hf_to_gguf.py ../models/Mage-VL \
  --outfile ../mage-vl-backbone-BF16.gguf --outtype bf16
python convert_hf_to_gguf.py ../models/Mage-VL \
  --mmproj --outfile ../mage-vit-mmproj-F16.gguf --outtype f16
python convert_hf_to_gguf.py ../models/Mage-VL \
  --mmproj --outfile ../mage-vit-mmproj-Q8_0.gguf --outtype q8_0

构建 llama.cpp 并量化语言骨干:

cmake -B build -DGGML_VULKAN=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -j
build/bin/llama-quantize ../mage-vl-backbone-BF16.gguf \
  ../mage-vl-backbone-Q8_0.gguf Q8_0
build/bin/llama-quantize ../mage-vl-backbone-BF16.gguf \
  ../mage-vl-backbone-Q4_K_M.gguf Q4_K_M

llama.cpp 骨干性能

Radeon AI PRO R9700、Vulkan、llama.cpp a52077c、批大小 2048、ubatch 512、 启用 Flash Attention:

骨干

pp1024

tg128

BF16

1,380 tok/s

70.84 tok/s

Q8_0

5,751 tok/s

118.03 tok/s

Q4_K_M

5,482 tok/s

178.41 tok/s

这些数据衡量的是 Qwen3 语言骨干,而非编码预处理或 Mage-ViT。我们发布的 GGUF 变体在完整的 MMBench EN 开发集(4,329 条记录)、无字幕的 Video-MME tc32(2,700 个问题)、 WikiText-2 和九图像数值视觉比较上进行了测量。Q8 + 视觉 Q8 在 MMBench CircularEval 上得分 84.36%,在 Video-MME 上得分 63.33%。Microsoft 报告的 BF16 参考值分别为 84.19% 和 64.00%。Hugging Face 模型 卡片包含完整的比较、协议摘要和校验和。

原生验证

当前的 Vulkan Docker 构建为每个发布组合通过 10 张图像加 10 个 H.264 视频: Q4+视觉 Q8、Q8+视觉 Q8、Q4+视觉 F16 和 Q8+视觉 F16 — 80/80 确定性语义检查。可复用的测试框架是 tests/native_sanity.sh。网关测试还涵盖所有四对的图像和缓存视频 推理、AV1-in-MP4 转换、畸形 MAGECV1 拒绝、缓存重用、健康传播、优雅关闭和原生实时 流处理。这些执行检查补充了 MMBench 和 Video-MME。 发布补丁链在每次推送时由 .github/workflows/ci.yml 编译;GPU 质量/性能检查仍然是发布门禁 测试,因为托管 CI 没有合适的 Vulkan/CUDA 设备或模型权重。

许可证和上游项目

Mage-VL 采用 Apache-2.0 许可证。llama.cpp 采用 MIT 许可证。本仓库包含集成补丁和文档;上游许可证继续适用于各自对应的代码和模型工件。NOTICE 区分了社区代码、上游运行时和模型条款。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers