Mage-VL-GGUF-Konvertierung und lokale Inferenz

Lokales MCP-Videoverständnis

Dieses Repository verpackt die gepatchte Mage-VL-GGUF-Laufzeit nun als lokalen MCP-Dienst. Ein MCP-fähiger Agent kann eine Videoaufgabe in die Warteschlange stellen, persistente Ereignisse mit einem Cursor lesen und auf der Grundlage der zurückgegebenen Belege weiter Schlussfolgerungen ziehen, ohne das Video jemals in einen Cloud-Dienst hochzuladen.

Die unterstützte Topologie ist bewusst in zwei Teile geteilt:

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

Die Laufzeit ist die vorhandene gepatchte GGUF-Implementierung; dieses Projekt erstellt Mage-VL-Gewichte nicht neu und quantisiert sie nicht. Das Standardprofil ist für eine 8-GiB-NVIDIA-GPU ausgelegt: Q4_K_M-Sprach-Backbone, Q8-Vision-/StreamMind-Sidecars, F16-DCVC-Sidecars, ein 8192-Token-Kontext und Q4-KV-Cache.

Voraussetzungen

• Windows mit WSL2 und einem NVIDIA-Treiber, der in nvidia-smi innerhalb von WSL sichtbar ist.

• Ubuntu-24.04-WSL-Distribution namens Ubuntu-24.04 (oder -Distro übergeben).

• Mindestens 20 GiB freier Speicher im Docker-WSL-Dateisystem vor dem ersten Image-Build.

• Persistentes Datenverzeichnis E:\mageVL-data; Modellgewichte, Cache, SQLite-Datenbank, Logs und die generierte Laufzeitkonfiguration verbleiben dort.

Der während der Entwicklung verwendete Host besitzt eine RTX 4060 Laptop-GPU mit 8188 MiB; gehen Sie nicht davon aus, dass eine andere Maschine denselben Spielraum hat. Das CUDA-Image 12.8.1 ist die Standardvorgabe. runtime.env stellt CUDA_VERSION=12.6.3 als manuellen Fallback bereit, falls eine kompatible Docker-Laufzeit es nicht starten kann; die Skripte aktualisieren niemals einen Windows-Grafiktreiber.

Installieren und ausführen

Öffnen Sie PowerShell 7 in diesem Repository und führen Sie Folgendes aus:

.\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 ist bewusst interaktiv: Es installiert Docker Engine und NVIDIA Container Toolkit innerhalb von WSL und kann das Linux-sudo-Passwort anfordern. setup-runtime lädt sechs festgelegte GGUF-Artefakte aus JohnTdi/Mage-VL-GGUF in der Revision 63b23eb4707b1907668c57d61845e7d423016b5c herunter, schreibt E:\mageVL-data\models\SHA256SUMS.txt, installiert das MCP-Paket in einer repository-lokalen virtuellen Umgebung und erstellt das CUDA-Image.

start bleibt im Vordergrund. Ein Druck auf Ctrl+C beendet den MCP-Supervisor, hält die warme Docker-Laufzeit jedoch am Laufen. Verwenden Sie diese weiteren Befehle:

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

stop -All beendet sowohl den Supervisor als auch den Laufzeit-Container; es behält alle Daten unterhalb von E:\mageVL-data.

Lokale Dateigrenze

Der MCP-Dienst legt keine URLs, RTSP, Kameras, Bildschirme oder beliebige Container-Pfade offen. Bevor Sie ihn starten, bearbeiten Sie die erzeugte E:\mageVL-data\mcp.env und setzen Sie MAGE_VIDEO_ROOTS auf ein oder mehrere vorhandene WSL-Verzeichnisse, getrennt durch Kommas. Die Standardeinstellung ist /mnt/e/mageVL-data/videos.

Jeder übergebene video_path wird bei Bedarf von einem Windows-Laufwerkspfad konvertiert, über Symlinks aufgelöst und abgelehnt, es sei denn, er verbleibt unterhalb eines erlaubten Wurzelverzeichnisses. Fügen Sie beispielsweise /mnt/e/Videos nur hinzu, wenn dies das Verzeichnis ist, das Agenten untersuchen sollen.

MCP-Client-Endpunkt und Werkzeuge

Verwenden Sie diesen Streamable-HTTP-Endpunkt in einem lokalen MCP-Client:

http://127.0.0.1:8765/mcp

Alle sechs Inferenz-Tools teilen sich einen FIFO-Kanal. Eine Watch-Sitzung blockiert Offline-Analyse und Segment-Inspektion, bis sie beendet oder gestoppt wird. Das ist beabsichtigt: Der native StreamMind-Runner tauscht den gewöhnlichen llama-server aus und hält rekurrenten Zustand. Bei einem Orchestrator-Neustart werden laufende Aufträge als fehlgeschlagen markiert, statt stillschweigend fortgesetzt zu werden.

Offline-Analyse fordert von Mage strukturiertes JSON an. Wenn die Modellausgabe kein gültiges JSON ist, wird die rohe Antwort im Ereignis aufbewahrt, anstatt verworfen oder als erfundene Zeitleiste präsentiert zu werden.

Was CI und Tests belegen

tests/test_mcp_orchestrator.py testet die Pfadgrenze, den SQLite-Ereignis-Cursor und das Abbrechen von Warteschlangenaufträgen. GitHub Actions prüft zusätzlich, dass der festgelegte native Patch anwendbar ist und das CPU-Ziel llama-mage-codec-stream kompiliert. Diese Prüfungen belegen keinen echten CUDA-Container, keinen Modell-Download und keine End-to-End-Videoinferenz; führen Sie für diese Validierung setup-runtime und eine lokale Videoaufgabe aus.

Siehe CONTEXT.md für das Fachvokabular und docs/adr für die beiden Architekturentscheidungen.

Related MCP server: popcorn

Natives StreamMind-Gate

Dieser Fork führt Microsofts proaktiven StreamMind-Pfad vollständig innerhalb von llama.cpp aus: Mage-ViT-Einbettungen werden nach Codec-Zeitstempel gruppiert, über Patches gemittelt, durch das zustandsbehaftete Mamba-1-EPFE geleitet und vom vierschichtigen Qwen3-Gate-Klassifikator bewertet. Er rekonstruiert keine Transformers-Tensoren und hält kein zweites BF16-Modell im 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

Jede JSONL-Zeile enthält das Quellframe, die offiziellen Silent/Speak-Logits, die Speak-Wahrscheinlichkeit und die rohe Entscheidung an Microsofts 0.5-Grenze. Das Gate ist anwendungsneutral: Clients entscheiden, was ein speak-Ereignis bedeutet, und können ihre eigene Richtlinie anwenden. STREAMMIND_CHUNK=N verarbeitet Eingaben inkrementell und bewahrt dabei den rekurrenten Zustand.

MP4-, RTSP- und HLS-Eingabe

streammind_native.py ist ein Transport-/Vorverarbeitungsadapter. Im inkrementellen Modus dekodiert ein persistenter FFmpeg-Prozess den Stream, und der offene Bereitschaftsselektor baut Mage-Canvas, sobald genügend Belege vorhanden sind; keiner von beiden führt ein neuronales Modell aus. Mage-ViT, das Mamba-1-EPFE und der Gate-Klassifikator werden alle in der gepatchten C++-llama.cpp-Laufzeit ausgeführt, sodass kein Transformers-Checkpoint und kein BF16-Duplikat geladen wird.

Installieren Sie nur die Video-Vorverarbeitungsumgebung und lassen Sie sie aktiv, damit codec-video-prep und cv-preinfer im PATH liegen:

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

Lokale 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-Kamera und HLS verwenden denselben Befehl; nur die Quelle ändert sich:

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

Der inkrementelle Live-Modus hat kein festes Transportsegment und schreibt keine temporäre MP4. Bei den standardmäßig 8 abgetasteten FPS kann er nach den mindestens acht Abtastwerten (einer Sekunde) schließen, wenn Bereitschaft und zeitliche Abdeckung erfüllt sind; andernfalls verlängert er sich bis --sampled-frames. Der EPFE-Zustand bleibt über jede adaptive Gruppe hinweg erhalten, bis der Prozess beendet wird. Bei lokalen Dateien bewirkt --realtime, dass FFmpeg Frames mit Wiedergabegeschwindigkeit zuführt. Kleine MAGECV1-Übergabebündel werden sofort nach der Verarbeitung gelöscht. Das Weglassen von --incremental-producer behält den segmentierten Codec-Bitcost-Kompatibilitätspfad für Offline-/Referenzarbeiten bei.

Wiederholbare Konvertierungsdateien und Anleitungen zur lokalen Inferenz für microsoft/Mage-VL. Die veröffentlichten GGUF-Gewichte wurden an Bild-, Video- und Sprach-Benchmarks gemessen und mit Microsofts gemeldeten BF16-Referenzwerten verglichen.

Modellgewichte: JohnTdi/Mage-VL-GGUF auf Hugging Face

Mage-VL Studio: native Q8-GGUF-Analyse mit einem ausgewählten Zeitbereich, dedizierter OCR für statischen Text, RAM/VRAM-Metriken und repräsentativen Vollbild-Highlights.

Entwicklungshinweis: Code-Unterstützung und Review wurden von OpenAI GPT-5.6 Sol bereitgestellt. Die endgültigen Integrations-, Test- und Release-Entscheidungen wurden vom Repository-Maintainer getroffen und verifiziert.

Dieses GitHub-Repository enthält die Docker-Laufzeit, Patches und Startanweisungen. Das Hugging-Face-Repository enthält die Q4/Q8-Backbone- und F16/Q8-Vision-GGUF-Artefakte.

Status

Die Docker-Images wenden einen kleinen nativen Laufzeit-Patch auf das festgelegte llama.cpp an. Sowohl das Sprach-Backbone als auch Mage-ViT bleiben während der Inferenz in ihren GGUF-Speichertypen; kein Transformers-Prozess und keine BF16-Rekonstruktion sind beteiligt.

Veröffentlichte Varianten

Gewichte sind absichtlich nicht in Git gespeichert. Alle acht Laufzeit-Artefakte befinden sich im Modellrepository JohnTdi/Mage-VL-GGUF.

Schnellstart: nativer llama.cpp-Server

Geführte Installation mit einem Befehl

Nach dem Klonen des Repositories erkennt das Installationsprogramm CUDA oder Vulkan, schätzt den VRAM, wählt ein 8/16/24–32-GB-Profil, lädt nur die erforderlichen GGUF-Dateien herunter, leitet die passenden DRM-Knoten/Gruppen ab und startet Docker:

./install.sh

Überschreiben Sie die Erkennung mit MAGE_BACKEND=vulkan|cuda und MAGE_PROFILE=8|16|24|32. Die erzeugte .env bleibt editierbar.

Die enthaltenen Images kompilieren eine festgelegte llama.cpp-Revision, wenden den Mage-ViT-Laufzeit-Patch an und enthalten die Bild-/Video-Abhängigkeiten. Die ungenutzte Upstream-llama.cpp-Web-UI wird zur Build-Zeit deaktiviert; das vermeidet Node/npm und veränderbare UI-Downloads, während das Gateway eine eigene lokale Upload-Seite bereitstellt.

Dieses Repository ist die vollständige Laufzeit-Distribution: Docker klont das festgelegte llama.cpp, wendet den vereinheitlichten nativen Mage-Patch aus patches/ an, kompiliert ihn und startet llama-server mit beiden GGUF-Dateien. Ein separater Checkout eines llama.cpp-Forks ist nicht erforderlich.

Voraussetzungen: Linux, Git, Python 3 mit venv und pip, Docker Engine und Docker Compose 2.30 oder neuer. Beginnen Sie in einem leeren Verzeichnis:

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

Der erste Build kompiliert unser gepatchtes llama.cpp und kann mehrere Minuten dauern. Wenn /health erfolgreich ist, öffnen Sie http://localhost:8080 in einem Browser, wählen Sie eine MP4, geben Sie eine Frage ein und klicken Sie auf Analyze video. Weder eine manuelle Konvertierung noch ein Codec-Befehl ist erforderlich.

Für Skripte laden Sie ein JPEG/PNG-Bild hoch:

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

Oder laden Sie eine gewöhnliche MP4-Datei hoch. H.264 und HEVC gehen direkt an den offiziellen codec-bewussten Vorprozessor; AV1, VP9, MPEG-4 Part 2 und andere FFmpeg-lesbare Videocodecs werden automatisch in hochwertiges H.264 konvertiert. Der Container verpackt dann MAGE CV1 und führt native GGUF-Inferenz aus:

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

Kontinuierliche Live-Überwachung

Öffnen Sie Mage-VL Studio, wählen Sie Live-Stream, fügen Sie eine RTSP/RTMP-, direkte HTTP/HLS-, Localhost- oder unterstützte Seiten-URL wie YouTube ein, konfiguieren Sie die Antwortrichtlinie und wählen Sie Live-Analyse starten. Der native C++-Process führt FFmpeg-Dekodierung, zeitliches Sampling, DCVC-RT-GGUF und Mage-Canvas-Konstruktion durch und bewahrt dann den rekurrenten EPFE-Zustand von StreamMind über Gruppen hinweg. Mage-Vit kodiert eine Gruppe genau einmal; dieselben Embeddings speisen das Gate und jede ausgelöste Qwen-Antwort. Ergebnise mit Zeitstempeln erscheinen sofort unterhalb des Players.

Demonstration mit einem zufällig ausgewählten öffentlichen YouTube-Live-Stream; die Quelle wurde nur gewählt, um den Live-Analyse-Pfad zu testen, und stellt keine Empfehlung dar.

Der kontinuierliche Pfad erzeugt keine Transport-MP4- oder MAGE CV1-Übergabedateien. Beenden Sie die Live-Sitzung, bevor Sie Modelleinstellungen ändern. Quell- und Verarbeitungslatenz hängen von Netzwerk und Bildinhalt ab. Die UI meldet Live-Verzögerung, p95-Echtzeitfaktor (RTF), ausstehende/verworfene Fenster und ob der Stream Schritt hält. Veraltete Fenster verwerfen ist standardmäßig aktiviert, sodass eine überlastete Installation aktuell bleibt, statt eine ständig wachsende Historie zu analyisieren.

Die Live-FPS sind derzeit explizit festgelegt und werden nicht automatisch gemessen oder an die GPU des Benutzers angepast. Das Feld Analysierte FPS ist standardmäßig auf 8 gesetzt; das Hardw areprofil legt einen konservativen Ausgangspunkt fest, ändert die FPS jedoch nicht, während eine Sitzung läuft. Wenn die Pipeline rückfällt, verwirft die begrenzte Warteschlange veraltetete Fenster, wenn Veraltete Fenster verwerfen aktiviert ist, anstatt eine unbegrenzte Verzögerung anzusameln. Nutzen Sie die gemeldete RTF- und Warteschlangentelemeterie zur Feinabstimmung: Halten Sie den p95-RTF unter 0.8, reduzieren Sie zuerst die analyisierten FPS (12 -> 8 -> 6 -> 4 -> 2) und senken Sie dann bei Bedarf MAGE_DCVC_LIVE_MAX_HEIGHT (720 -> 480 -> 360). Erhöhen Sie eine der beiden Einstellungen erst, nachdem der Stream mehrere Minuten lang stabiel geblieben ist.

Gemessene R9700-Kapazitätsergebnise finden Sie in docs/live-performance-r9700.md. Auf dieser GPU akzeptiert die sichere Standardeinstellung eine 1080p/4K-Quelle, skaliert sie jedoch auf 480p herunter und tastet mit 8 fps ab. Nativer DCVC wurde mit 14,30 fps bei 854x480, 6,34 fps bei 720p und 1,55 fps bei 1080p gemessen. Der erste Start mit leeren Cache kann 15–17 Sekunden für die Kompilierung von Vulkan-Graphen benötigen; vorgewärmte Sitzungen müssen diese Kosten nicht wierholen.

Beenden Sie den Dienst mit docker compose --profile vulkan down. Bei späteren Starts können Sie --build weglassen:

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

Eine Quantisierung wählen

Tragen Sie das Paar in .env ein; alle vier Kombinationen werden unterstützt:

# 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

Laden Sie alle Varianten herunter, wenn Sie später ohne erneuten Download wechseln möchten:

.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

Die API bindet standardmäßig an 127.0.0.1, da llama-server in dieser Konfiguration keine Authentifizierung besitzt. Um sie bewusst freizugeben, setzen Sie HOST_BIND in .env und schützen Sie sie mit einer Firewall oder einem authentifizierenden Reverse-Proxy. Leiten Sie den rohen Port niemals direkt ins Internet weiter.

Die Standardkonfiguration setzt nur das passende Paar /dev/dri/renderD128 + /dev/dri/card0 dem Container aus, sodass eine andere Vulkan-GPU nicht sichtbar ist. Überprüfen Sie beide vor der ersten Verwendung gegen /dev/dri/by-path. Wenn Sie sie ändern, leiten Sie auch RENDER_GID und VIDEO_GID von denselben Knoten ab. Ordnen Sie sie nicht innerhalb des Containers auf andere Namen um: RADV folgt ihrer sysfs-Beziehung, und die Authentifizierung kann fehlschlagen, wenn Namen umgeschrieben werden. Ein NVIDIA-Image ist mit --profile cuda verfügbar; es benötigt das NVIDIA Container Toolkit. Siehe docker/README.md.

Das öffentliche Gatway setzt nur die lokale Upload-Seite, /health, /v1/Image/analyze, /v1/video/prepare, /v1/video/analyze-prepared, /v1/video/analyze, die Session-API /v1/ive/sessions sowie schreibgeschützte Codec-Canvas-Vorschauen frei; der interne llama-server lauscht nur innerhalb des Containers. Vorverarbeitete Videos werden anhand des Inhaltshash und aller ausgaberelevanten Vorverarbeitungseinstellungen geapped, sodass ein wierholter Upload sowo hl das Transkodieen als auch die Codec-Vorverarbeitung überspringt. Video-Audiospuren werden bewusst ignoriert: Mage-VL analyisiert visuellen Inhalt, nicht Sprache oder Ton.

Das Live-Stream-Panel akzeptiert RTSP/RTMP, direkte HTTP/HLS-URLs, Localhost-URLs und unterstützte Webseiten wie YouTube (innerhalb des Containers mit yt-dlp aufgelöst). Es bietet vier Antwortrichtlinien an: periodisch, jede erkannte Änderung, nur wichtige Änderungen sowie wichtige Änderungen plus einen periodischen Bericht. Fensterlänge, Mindestabstand zwischen Antworten, Wichtigkeitssensitivität, visuelle Qualität, Antwortlänge, RTSP-Transport und der Benutzerprompt sind konfiguierbar. Geschlossene Transportsegmente und ihre MAGECV1-Arbeitsbereiche werden sofort nach der Inferenz gelöscht; nur die begrenzte Ergebnishistorie im Arbeitsspeicher bleibt erhalten. Beenden Sie eine Sitzung ausdrücklich, bevor Sie Modelleinstellungen ändern.

Die optiierte native Live-Laufzeitumgebung kodiert jedes Videofenster mit Mage-Vit genau einmal. Seine Embeddings speisen sowo hl die EPFE/Klassifizierung von StreamMind als auch, nur nach einem Auslöser, die Qwen-Erzeugung. Das Starten des Live-Modus entladt den gewöhnlichen Upload-llama-server; das Beenden des Live-Modus stellt ihn wier her, sodass nie zwei Sprach-Backbones gleicheitig im Arbeitsspeicher liegen. Jedes Live-Ergebnissagt vission_encode_count=1 und shared_visson_embedings=true als Laufzeitprüfung aus. Das Docker-Release enthält den vollständigen nativen StreamMind-Patch, und beide Q8-EPFE/Klassifizier-Sidecars werden aus dem verlinkten Repository von Hugging Face heruntergeladen.

Das Browser-Panel zeigt die lokale MP4 sofort als Vorschau, zeigt den Fortschrit von Vorverarbeitung und Inferenz, rendert die Modellantwort und PP/TG-Metrien und zeigt die genauen Codec-Canvas an, die an Mage-Vit übergeben werden. Ein Canvas ist ein räumliches Mosai aus ausgewählten Quellbild-Atchen, nicht unbedingt ein herkömmliches vollständiges Einzelbild. Jede Karte meldet daher ihren genauen Zeitstempelbereich der Quellbilder und die vollständige, aus src_patch_position.npy abgeleitete Zeitstempelliste. Der Player enthält einen Auswahlregler mit zwei Griffen für den Analysbereich. Nur das ausgewählte Intervall wird dekodiert und geapped, während jede Vorschau-Zeitstempel in die absolute Zeitleiste des ursprünglichen Viedos rückübersetzt wird. Sein fünfstufiger Geschwindigkeit/Detai-Regler ändert sowo hl das zeitliche Sampling (96–320 Bider) als auch das Pixebudget der Codec-Canvas (90k–180k). Der optionale gründliche Textscan führt bewusst einen separaten, auf OCR fokussierten Inferenzdurchlauf aus: Experimente zeigten, dass ein einziger allgemeiner Ereignisprompt eine lesbare statische Untertitel selbst bei der höchsten Einstellung für visuelle Details übersehen kann.

Erweiterte Einstellungen können das Modell nach einer ausdrücklichen Bestätigung mit einem andern Kontext, Batch, Mikro-Batch und F16/Q8/Q4-KV-Cache neu laden. Wenn die neue Konfiguration nicht starten kann, versucht das Gatway, die vorherige wierherzustellen. Das Ressourcen-Panel meldet den kombinierten Resient-RAM von Gatway+llama auf Linus. Auf NVIDIA verwendet es den prozessbezogenen VRAM über nvidia-smi; bei AMD/Vulkan, wo der Kern keinen verlässlichen prozessbezogenen VRAM bereitstellt, meldet es den Anstieg des ausgewählten DRM-Geräts gegenüber der Baislinie vor dem Laden und kennzeichnet diese Methode ausdrücklich.

Standardwerte für eine 16-GiB-GPU

Das mitgelieferte Profil verwendet einen Anfrage-Sot, F16-KV-Cache und ctx=16384. Auf einer Radeon AI PRO R9700 mit Vulkan erzeugte der im Benchmark-Repositorium beschriebene 50,64 Sekunden lange 1080x1920-H.264-Testclip 8.099 Prompt-Token:

Der Laufzeit-Prefill-Patch kombiniert aufeinanderfolgende Zeitstempel-Text- und visuelle Spans, bis der Decoder-Batch voll ist. Vor diesem Patch erzeugte dieselbe Eingabe viele kleine Vulkan-Übergaben und erreichte nur 1.221 tok/s. Mit dem Patch und ctx=32768 erreichte es 2.718 tok/s und verwendte etwa 10,4 GiB; wenn der voraelligierte Kontext auf 16k reduziert wird, bleiben dieselben F16-KV-Werte erhalten, während rund 2,8 GiB eingespart werden. Genäue Werte hängen von Treiber, Prompt, Canvas-Anzahl und Leistungszustand ab.

Sicherheits-/Ressourcen-Standardwerte stehen in .env: 16.384 Kontext-Token, ein gleicheitiger Vorprozessor, 2 GiB Upload, 60 Minuten Dauer, 3840x2160 Quellvideo, 256 abgetastete Bider, 150.000 Pixel pro Video-Canvas, 256 erzeugte Token und ein 15-minütiges Vorverarbeitungs-Timeout. JPEG/PNG-Bider werden automatisch auf höchstens 1.048.576 Pixel reduziert, um Bild- und Videolasten innerhalb des 16-GiB-Proffils zu halten. Der inhatsadressierte Vorverarbeitungscache ist auf 50 GiB begrenzt und entfernt die am längsten nicht verwendten Einträge. Ändern Sie die entsprechenden MAGE_*- Werte in .env und erzeugen Sie den Dienst dann mit docker compose --profile vulkan up -d --force-recreat vulkan neu.

Die nützlichsten Abstimmvariablen sind LLAMA_ARG_CTX_SIZE (Kontext/VRAM), MAGE_SAMPLED_FRAMES (zeitliche Abdeckung), MAGE_MAX_PIXELS (Token pro Codec-Canvas), MAGE_IMAGE_MAX_PIXELS und MAGE_MAX_NEW_TOKENS. Die Decoder-Übergabe ist ausdrücklich an MAGE_BATCH_SIZE=2048, MAGE_UBATCH_SIZE=512 und F16-KV-Cache gebunden. Wenn eine benutzerdefinierte Bildeinstellung einen visuellen Block erzeugt, der größer als der Decoder-Batch ist, gibt die API einen klaren 422-Fehler zurück, statt einen gekürzten Prompt zu akzeptieren; erhöhen Sie MAGE_BATCH_SIZE oder reduzieren Sie die Bildpixel.

Die Videodauer wird nicht eins-zu-eins auf den Kontext abgebildet: Die Standardinstellung tastet höchstens 256 Bider ab, und die Bereitschaftsgruppierung erzeugte bei getesteten Clips von 15–85 Sekunden 24–52 Canvases (etwa 4.800–10.400 visuelle Token). Mehr abgetastete Bider oder größere Canvases erhöhen die Vorverarbeitungzeit, den Kontextverbrauch und den Arbeitsspeicher. Wenn eine Anfrage nicht passt, senken Sie MAGE_SAMPLED_FRAMES oder MAGE_MAX_PIXELS; erhöhen Sie LLAMA_ARG_CTX_SIZE nur, wenn ausreichend VRAM verfügbar bleibt.

Konvertierung in GGUF

Der Patch zielt auf den llama.cpp-Commit a52077c4cabb4f3c0298329c9d2dd1324d5604cb. Eine andere Revision kann eine manuelle Konfliktlösung erfordern. Führen Sie diesen Block aus dem Wurzelverzeichnis des geklonten mage-vl-gguf-Repositoriums aus; er erzeugt llama.cpp/ darunter.

Verwenden Sie eine separate Konvertierer-venv. Ihre fixierten Anforderungen installieren CPU-PyTorch und dürfen die für die Inferenz verwendte ROCm/CUDA-Umgebung nicht ersetzen.

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

Kompilieren Sie llama.cpp und quantisieren Sie das Sprach-Backbone:

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-Backbone-Leistung

Radeon AI PRO R9700, Vulkan, llama.cpp a52077c, Batch 2048, Ubatch 512, Flash Attention aktiviert:

Diese Zahlen messen das Qwen3-Sprach-Backbone, nicht die Codec-Vorverarbeitung oder Mage-Vit. Unsere veröffentlichten GGUF-Varianten wurden auf dem vollständigen MMBench-EN-Dev-Set (4.329 Datensätze), Vied-MME tc32 ohne Untertitel (2.700 Fragen), WikiText-2 und einem neunbildigen numerischen Vision-Vergleich gemessen. Q8 + Vision Q8 erreichte 84,36 % MMBench CircularEval und 63,33 % Vied-MME. Die von Microsoft berichteten BF16-Referenzwerte betragen 84,19 % beziehungsweise 64,00 %. Die Modellkarte von Hugging Face enthält den vollständigen Vergleich, die Protokollzusamnenfassung und die Prüfsummen.

Native Validierung

Der aktuelle Vulkan-Docker-Build besteht für jede Release-Kombination 10 Bider plus 10 H.264-Videos: Q4+Vision Q8, Q8+Vision Q8, Q4+Vision F16 und Q8+Vision F16 – 80/80 determinstische semantische Prüfungen. Das wieederverwendbare Testgerüst ist tests/native_sanity.sh. Gatway-Tests decken außerdem Bild- und geappte-Video-Inferenz für alle vier Paare, AV1-in-MP4-Konvertierung, Abweihung fehlerhafter MAGECV1-Dateien, Cache-Wiederwendung, Health-Weiterleitung, graziöses Fahren und native Live-Stream-Verarbeitung ab. Diese Ausführungsprüfungen ergänzen MMBench und Vied-MME. Die Release-Patch-Kette wird bei jedem Push von .github/workflows/ci.yml kompiliert; GPU-Qualitäts-/Leistungsprüfungen bleiben Release-Gate-Tests, da gehostetes CI über kein geeignetes Vulkan/CUDA-Gerät und keine Modellgewichte verfügt.

Lizenz und Uppstream-Projekte

Mage-VL ist unter Apache-2.0 lizenziert. llama.cpp ist unter MIT lizenziert. Dieses Repository enthält Integrations-Patches und Dokumentation; die Upstream-Lizenzen gelten weiterhin für den jeweiligen Code und die Modell-Artefakte. Die NOTICE trennt Community-Code, Upstream-Runtime und Modellbedingungen.