Mage-VL GGUF 変換とローカル推論

ローカル MCP ビデオ理解

このリポジトリは、パッチ適用済みの Mage-VL GGUF ランタイムをローカル MCP サービスとしてパッケージ化しています。MCP 対応エージェントは、ビデオタスクをキューに入れ、カーソルで永続イベントを読み取り、ビデオをクラウドサービスにアップロードすることなく、返された証拠に基づいて推論を続けることができます。

サポートされるトポロジーは、意図的に2つに分かれています。

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 トークンのコンテキスト、Q4 KV キャッシュ。

前提条件

• WSL2 を備えた Windows と、WSL 内で nvidia-smi に表示される NVIDIA ドライバー。

• Ubuntu-24.04 という名前の Ubuntu 24.04 WSL ディストリビューション（または -Distro を渡す）。

• 最初のイメージビルドの前に、Docker の WSL ファイルシステムに少なくとも 20 GiB の空き容量が必要です。

• 永続データディレクトリ E:\mageVL-data。モデルの重み、キャッシュ、SQLite データベース、ログ、生成されたランタイム設定はそこに残ります。

開発中に使用したホストには 8188 MiB の RTX 4060 Laptop GPU が搭載されています。別のマシンが同じ余裕を持っているとは想定しないでください。12.8.1 CUDA イメージがデフォルトです。runtime.env は、互換性のある Docker ランタイムが起動できない場合の手動フォールバックとして CUDA_VERSION=12.6.3 を公開しています。スクリプトは 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 は意図的にインタラクティブです。Docker Engine と NVIDIA Container Toolkit を WSL 内にインストールし、Linux の sudo パスワードを要求する場合があります。setup-runtime は、JohnTdi/Mage-VL-GGUF リビジョン 63b23eb4707b1907668c57d61845e7d423016b5c から6つの固定された 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

6つの推論ツールすべてが1つの 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 を、2つのアーキテクチャ決定については docs/adr を参照してください。

Related MCP server: popcorn

ネイティブ StreamMind ゲート

このフォークは、Microsoft のプロアクティブ StreamMind パスを llama.cpp 内で完全に実行します。Mage-ViT 埋め込みはコーデックタイムスタンプでグループ化され、パッチ全体で平均化され、ステートフルな Mamba-1 EPFE を通過し、4層の Qwen3 ゲート分類器によってスコアリングされます。Transformers テンソルを再構築したり、2つ目の BF16 モデルを VRAM に保持したりしません。

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 行には、ソースフレーム、公式のサイレント/スピークロジット、スピーク確率、および Microsoft の 0.5 境界での生の決定が含まれます。ゲートはアプリケーションに依存しません。クライアントは speak イベントの意味を決定し、独自のポリシーを適用できます。STREAMMIND_CHUNK=N は、リカレント状態を保持しながら入力をインクリメンタルに処理します。

MP4、RTSP、HLS 入力

streammind_native.py はトランスポート/前処理アダプターです。インクリメンタルモードでは、1つの永続的な 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 では、レディネスと時間的カバレッジが満たされた場合、最小8サンプル（1秒）後に閉じることができます。それ以外の場合は --sampled-frames まで拡張されます。EPFE 状態はプロセスが終了するまで、すべての適応グループにわたって継続します。ローカルファイルの場合、--realtime により FFmpeg は再生速度でフレームを供給します。小さな MAGECV1 ハンドオフバンドルは消費後すぐに削除されます。--incremental-producer を省略すると、オフライン/参照作業用のセグメント化されたコーデックビットコスト互換パスが保持されます。

再現可能な変換ファイルと、microsoft/Mage-VL のローカル推論手順。リリースされた GGUF の重みは、画像、ビデオ、言語ベンチマークで測定され、Microsoft が報告した BF16 参照値と比較されました。

モデルの重み: JohnTdi/Mage-VL-GGUF on Hugging Face

Mage-VL Studio: 選択した時間範囲でのネイティブ Q8 GGUF 分析、専用の静的テキスト OCR、RAM/VRAM メトリクス、代表的なフルフレームハイライト。

開発開示: コード支援とレビューは OpenAI GPT-5.6 Sol によって提供されました。最終的な統合、テスト、リリースの決定は、リポジトリメンテナーによって行われ、検証されました。

この GitHub リポジトリには、Docker ランタイム、パッチ、起動手順が含まれています。Hugging Face リポジトリには、Q4/Q8 バックボーンと F16/Q8 ビジョン GGUF アーティファクトが含まれています。

ステータス

Docker イメージは、固定された llama.cpp に小さなネイティブランタイムパッチを適用します。言語バックボーンと Mage-ViT はどちらも推論中に GGUF ストレージタイプのままです。Transformers プロセスや BF16 の再構築は関与しません。

リリース済みバリアント

重みは意図的に Git に保存されていません。8つのランタイムアーティファクトはすべて 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 フォークのチェックアウトは必要ありません。

要件: 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、またはYouTubeなどの対応ページURLを貼り付け、応答ポリシーを設定して、ライブ分析を開始を選択します。ネイティブC++プロセスはFFmpegデコード、時間的サンプリング、DCVC-RT GGUF、Mageキャンバス構築を実行し、グループ間でStreamMindのリカレントEPFE状態を保持します。Mage-ViTはグループを一度エンコードし、同じ埋め込みがゲートと、トリガーされたQwen応答の両方に供給されます。タイムスタンプ付きの結果がプレイヤーの直下に表示されます。

デモは無作為に選択した公開YouTubeライブストリームを使用しています。ソースはライブ分析パスを実行するためにのみ選ばれたものであり、推奨を意味するものではありません。

連続パスは転送用MP4やMAGECV1ハンドオフファイルを作成しません。モデル設定を変更する前にライブセッションを停止してください。ソースと処理のレイテンシはネットワークとフレーム内容に依存します。UIはライブ遅延、p95リアルタイムファクター（RTF）、保留中/ドロップされたウィンドウ、ストリームが追いついているかどうかを報告します。古いウィンドウをドロップはデフォルトで有効になっており、過負荷のインストール環境でも、増え続ける履歴を分析する代わりに最新の状態を維持します。

ライブFPSは現在明示的であり、自動的にベンチマークされたり、ユーザーのGPUに適応したりすることはありません。分析FPSフィールドはデフォルトで8です。ハードウェアプロファイルは控えめな開始点を設定しますが、セッション実行中にFPSを変更することはありません。パイプラインが遅れた場合、古いウィンドウをドロップが有効のとき、境界付きキューは無制限に遅延を蓄積する代わりに古いウィンドウをドロップします。報告されるRTFとキューテレメトリーを使って調整します：p95 RTFを0.8未満に保ち、まず分析FPS（12 -> 8 -> 6 -> 4 -> 2）を減らし、必要に応じてMAGE_DCVC_LIVЕ_MAХ_НЕIGНТ（720 -> 480 -> 360）を下げます。どちらの設定も、ストリームが数分間安定してから増やしてください。

R9700の実測容量結果はdocs/live-performanc-r9700.mdにあります。このGPUでは、安全なデフォルトは1080p/4Kソースを受け付けますが、480pに縮小し、8fpsでサンプリングします。ネイティブDCVCは、854x480で14.30 fps、720pで6.34 fps、1080pで1.55 fpsを記録しました。最初の空キャッシュ起動では、Vulkanグラフのコンパイルに15〜17秒かかる場合があります。ウォームアップ済みセッションではそのコストは発生しません。

docker compose --profile vulkan downでサービスを停止します。以降の起動では--buildを省略できます:

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

量子化の選択

.envでペアを設定します。4つの組み合わせすべてがサポートされています:

# 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

この構成ではllama-serverに認証がないため、APIはデフォルトで127.0.0.1にバインドします。意図的に公開するには、.envでHOST_BINDを設定し、ファイアウォールまたは認証付きリバースプロキシで保護してください。生のポートをインターネットに直接転送しないでください。

デフォルト構成では、一致する/dev/dri/renderD128 + /dev/dri/card0のペアのみがコンテナに公開されるため、別のVulkan GPUは見えません。最初に使用する前に、両方を/dev/dri/by-pathと照合して確認してください。それらを変更する場合は、同じノードからRENDER_GIDとVIDEO_GIDも導出してください。コンテナ内でそれらを別の名前にリマップしないでください。RADVはそれらのsysfsの関係に従うため、名前を書換えると認証に失敗することがあります。NVIDIAイメージは--profile cudaで利用できます。これにはNVIDIA Container Toolkitが必要です。docker/README.mdを参照してください。

パブリックゲートウェイは、ローカルのアップロードページ、/health、/vi/image/analyze、/vi/video/prepare、/vi/video/analyze-pared、/vi/video/analyze、/vi/live/sessionsセッションAPI、読み取り専用のコーデック・キャンバス・プレビューのみを公開します。内部のllama-serverはコンテナ内でのみリッスンします。プリプロセス済みビデオは、コンテンツハッシュと、出力に影響するすべてのプリプロセッシング設定によってキャッシュされるため、再アップロード時はトランスコーディングとコーデックプリプロセッシングの両方がスキップされます。ビデオのオーディオトラックは意図的に無視されます。Mage-VLは音声やサウンドではなく、視覚コンテンツを分析します。

ライブストリームパネルは、RTSP/RTMP、ダイレクトHTTP/HLS、localhost URL、およびYouTubeなどの対応ウェブペーじ（コンテナ内でyt-dlpによって解決）を受け付けます。応答ポリシーは4つあります：定期、検出された変更ごと、重要変更のみ、重要変更+定期レポート。ウィンドウ長、最小応答間隔、重要度感度、画質、応答長、RTSPトランスポート、ユーザープロンプトは設定可能です。閉じられたトランスポート・セグメントとそのMAGECV1ワークスぺースは、推論の直後に削除されます。残るのは、境界付きのメモリ内結果履歴だけです。モデル設定を変更する前に、セッションを明示的に停止してください。

最適化されたネイティブ・ライブ・ランタイムは、すべてのビデオウィンドウをMage-ViTで正確に1回エンコードします。その埋め込みは、StreamMindのEPFE/分類と、トリガーの後でのみQwen生成の両方に供給されます。ライブモードを開始すると、通常のアップロード用llama-serverがアンロードされ、ライブを停止すると復元されます。したがって、2つの言語バックボーンが同時に常駐することはありません。各ライブ結果は、実行時チェックとしてvision_encode_count=1とshared_vision_embeddings=trueを公開します。Dockerリリースには完全なネイティブStreamMindパッチが含まれており、両方のQ8 EPFE/クラシファイア・サイドカーは、リンクされたHugging Faceリポジトリからダウンロードされます。

ブラウザパネルは、ローカルMP4を即座にプレビューし、プリプロセッシングと推論の進捗を表示し、モデルの回答とPP/TGメトリクスをレンダリングし、Mage-ViTに渡される正確なコーデック・キャンバスを表示します。キャンバスは、選択されたソース・フレーム・パッチの空間的モザイクであり、必ずしも従来のフル・フレームではありません。したがっテ、各カードは、正確なソース・フレームのタイムスタンプ範囲と、src_patch_position.npyから導出された完全なタイムスタンプ・リスとを報告します。プレイヤには、2つのハンドルの分析範囲セレクタが含まれます。選択された間隔のみがデコード・キャッシュされ、すべてのプレビュー・タイムスタンプは元のビデオの絶対タイムラインに変換されて戻されます。5段階の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のデフォルト

出荷時プロファイルは、1つのリクエスト・スロット、F16 KVキャッシュ、ctx=16384を使用します。Vulkanを搭載したRadeon AI PRO R9700では、ベンチマーク・リポジトリで説明されている50.64秒の1080x1920 H.264テスト・クリップが8,099個のプロンプト・トークンを生成しました:

ランタイム・プリフィル・パッチは、デコーダ・バッチが満たされるまで、連続するタイムスタンプ・テキストと視覚スパンを結合します。このパッチの前は、同じ入力が多数の小さなVulkanサブミッションを生成し、1,221 tok/sしか達成できませんでした。パッチ適用後、ctx=32768では2,718 tok/sに達し、約10.4 GiBを使用しました。プリアロケートされたコンテキストを16kに減らすと、同じF16 KV値が維持され、約2.8 GiBを節約できます。正確な値は、ドライバ、プロンプト、キャンバス数、電力状態によって異なります。

セーフティ/リソースのデフォルトは.envにあります：16,384コンテキストトークン、1つの同時プリプロセッサ、2 GiBアップロード、60分の時間、3840x2160ソースビデオ、256サンプリングフレーム、ビデオキャンバスあたり150,000ピクセル、256生成トークン、15分のプリプロセッシングタイムアウト。JPEG/PNG画像は、画像およびビデオのワークロードを16 GiBプロファイル内に保つため、自動的に最大1,048,576ピクセルに縮小されます。コンテンツアドレス型プリプロセッシングキャッシュは50 GiBに制限され、最も長く使用されていないエントリを退避します。対応するMAGE_*の値を.envで変更し、docker compose --profile vulkan up -d --force-recreate vulkanでサービスを再作成します。

最も有用なチューニング変数は、LLAMA_ARG_CTX_SIZE（コンテキスト/VRAM）、MAGE_SAMPLED_FRAMES（時間的カバレッジ）、MAGE_MAX_PIXELS（コーデックキャンバスあたりのトークン）、MAGE_IMAGE_MAX_PIXELS、MAGE_MAX_NEW_TOKENSです。デコーダのサブミッションは、MAGE_BATCH_SIZE=2048、MAGE_UBATCH_SIZE=512、およびF16 KVキャッシュに明示的に固定されています。カスタム画像設定がデコーダバッチより大きい視覚チャンクを生成した場合、APIは切り詰められたプロンプトを受け入れる代わりに、明確な422エラーを返します。MAGE_BATCH_SIZEを増やすか、画像ピクセルを減らしてください。

ビデオの再生時間はコンテキストに1対1で対応するわけではありません。デフォルトでは最大256フレームをサンプリングし、レディネスグループ化により、テストした15〜85秒のクリップ全体で24〜52個のキャンバス（約4,800〜10,400ビジュアル・トークン）が生成されました。サンプリング・フレームを増やしたり、キャンバスを大きくしたりすると、プリプロセスング時間、コンテキスト使用量、メモリが増加します。リクエストが収まらない場合は、MAGE_SAMPLED_FRAMESまたはMAGE_MAX_PIXELSを減らしてください。十分なVRAMが残っている場合にのみLLAMA_ARG_CTX_SIZEを増やしてください。

GGUFへの変換

パッチはllama.cppのコミットa52077c4cabb4f3c0298329c9d2dd1324d5604cbを対象としています。異なるリビジョンでは、手動のコンフリクト解決が必要になる場合があります。このブロックを、クローンしたmage-vl-ggufリポジトリのルートから実行してください。その下にllama.cpp/が作成されます。

専用のconverter 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、ubatch512、Flash Attention有効：

これらの数値は、コーデックプリプロセッシングやMage-ViTではなく、Qwen3言語バックボーンを測定したものです。リリースしたGGUFバリアントは、完全なMMBench EN開発セット（4,329レコード）、字幕なしのVideo-MME tc32（2,700質問）、WikiText-2、および9枚の画像による数値視覚比較で測定されました。Q8 + vision Q8は、MMBench CircularEvalで84.36%、Video-MMEで63.33%を記録しました。Microsoftが報告したBF16参照値は、それぞれ84.19%と64.00%です。Hugging Faceモデルカードには、完全な比較、プロトコル概要、チェックサムが含まれています。

ネイティブ検証

現在のVulkan Dockerビルドは、各リリース組み合わせについて、10枚の画像と10本のH.264ビデオに合格します：Q4+vision Q8、Q8+vision Q8、Q4+vision F16、Q8+vision F16 — 80/80の決定論的セマンティックチェック。再利用可能なハーネスはtests/native_sanity.shです。ゲートウェイテストは、4つのペアすべてに対する画像およびキャッシュ済みビデオ推論、AV1-in-MP4変換、不正なMAGECV1の拒否、キャッシュ再利用、ヘルスプロパゲーション、グレースフルシャットダウン、ネイティブライブストリーム処理もカバーしています。これらの実行チェックは、MMBenchとVideo-MMEを補完します。リリースパッチチェーンは、.github/workflows/ci.ymlによってプッシュのたびにコンパイルされます。GPU品質/パフォーマンスチェックは、ホスト型CIには適切なVulkan/CUDAデバイスやモデル重みがないため、リリースゲートテストのままです。

ライセンスと上流プロジェクト

Mage-VLはApache-2.0ライセンスです。llama.cppはMITライセンスです。このリポジトリには統合パッチとドキュメントが含まれており、上流ライセンスはそれぞれのコードとモデル成果物に引き続き適用されます。NOTICEは、コミュニティコード、上流ランタイム、モデル条件を区別しています。