Conversión de GGUF de Mage-VL e inferencia local

Comprensión local de vídeo mediante MCP

Este repositorio ahora empaqueta el runtime GGUF parcheado de Mage-VL como un servicio MCP local. Un agente compatible con MCP puede poner en cola una tarea de vídeo, leer eventos duradros con un cursor y seguir razonando sobre la evidencia devuelta sin subir nunca el vídeo a un servicio en la nube.

La topología admitida se divide deliberadamente en dos:

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

El runtime es la implementación GGUF parcheada existente; este proyecto no recrea ni cuantiza los pesos de Mage-VL. El perfil predeterminado está diseñado para una GPU NVIDIA de 8 GiB: backbone de lenguaje Q4_K_M, sidecars Q8 de visión/StreamMind, sidecars F16 de DCVC, un contexto de 8192 tokens y caché KV Q4.

Requisitos previos

• Windows con WSL2 y un controlador NVIDIA visible en nvidia-smi dentro de WSL.

• Distribución WSL de Ubuntu 24.04 llamada Ubuntu-24.04 (o pasa - Distro).

• Al menos 20 GiB libres en el sistema de archivos WSL de Docker antes de la primera compilación de la imagen.

• Directorio de datos persistente E:\mageVL-data; los pesos del modelo, la caché, la base de datos SQLite, los registros y la configuración generada del runtime permanecen allí.

El host utiliz ado durante el desarrollo tiene una GPU RTX 4060 Laptop con 8188 MiB; no asumas que otra máquina tiene el mismo marge. La imagen CUDA 12.8.1 es la predeterminada. runtime.env expone CUDA_VERSION=12.6.3 como alternativa manual si un runtime de Docker compatible no puede iniciarla; los scripts nunca actualizan un controlador gráfico de Windows.

Instalación y ejecuación

Abre PowerShell 7 en este repositorio y ejecuta:

.\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 es intencionadamente interactivo: instala Docker Engine y NVIDIA Container Toolkit dentro de WSL y puede solicitar la contraseña de sudo de Linux. setup-runtime descarga seis artefactos GGUF fijados de la revisión 63b23eb4707b1907668c57d61845e7d423016b5c de JohnTdi/Mage-VL-GGUF, escribe E:\mageVL-data\models\SHA256SUMS.txt, instala el paquete MCP en un entorno virtual local al repositorio y constr uye la imagen CUDA.

start permanece en primer plano. Pulsar Ctrl+C detiene el supervisor MCP pero mantiene el runtime de Docker en caliente en ejecuación. Usa estos comados adicionales:

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

stop -All detiene tanto el supervisor como el contenedor del runtime; conserva todos los datos bajo E:\mageVL-data.

Límite de archivos locales

El servicio MCP no expone URL, RTSP, cámeras, pantallas ni rutas arbitrarias de contenedores. Antes de iniciarlo, edita el E:\mageVL-data\mcp.env generado y establece MAGE_VIDEO_ROOTS a uno o más directorios WSL existentes, separados por comas. El valor predeterminado es /mnt/e/mageVL-data/videos.

Cada video_path enviado se convierte desde una ruta de unidad de Windows cuando es necesario, se resuelve a través de enlaces simbólicos y se rechaza a menos que permanezca bajo una raíz permitida. Por ejemplo, añade /mnt/e/Videos solo si ese es el directorio que pretendes que los agentes inspeccionen.

Endpoint y herramientas del cliente MCP

Usa este endpoint HTTP Streamable en un cliente MCP local:

http://127.0.0.1:8765/mcp

Las seis herramientas de inferencia comparten un único canal FIFO. Una sesión de observación bloquea el análisis offline y la inspección de segmentos hasta que finaliza o se detiene. Esto es intencional: el ejecutor nativo de StreamMind sustituye al llama-server ordinario y mantiene el estado recurrente. Al reiniciar el orquestador, los trabajos en curso se marcan como fallidos en lugar de reanudarse silenciosamente.

El análisis offline le pide a Mage JSON estructurado. Si la salida del modelo no es JSON válido, la respuesta cruda se conserva en el evento en lugar de descartarse o presentarse como una línea temporal fabricada.

Qué demuestran la CI y las pruebas

tests/test_mcp_orchestrator.py comprueba el límite de rutas, el cursor de eventos SQLite y el comportamiento de cancelación encolada. GitHub Actions además comprueba que el parche nativo fijado se aplica y compila el objetivo llama-mage-codec-stream para CPU. Estas comprobaciones no demuestran un contenedor CUDA real, una descarga de modelo ni inferencia de vídeo de extremo a extremo; ejecuta setup-runtime y una tarea de vídeo local para esa validación.

Consulta CONTEXT.md para el vocabulario del dominio y docs/adr para las dos decisiones arquitectónicas.

Related MCP server: popcorn

Puerta nativa de StreamMind

Este fork ejecuta la ruta proactiva de StreamMind de Microsoft enteramente dentro de llama.cpp: los embeddings de Mage-ViT se agrupan por marca temporal del códec, se promedian sobre los parches, se pasan a través de la Mamba-1 EPFE con estado y los puntúa el clasificador de puerta Qwen3 de cuatro capas. No reconstruye tensores de Transformers ni mantiene un segundo modelo BF16 en la 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

Cada fila JSONL contiene el fotograma de origen, los logits oficiales de silencio/habla, la probabilidad de habla y la decisión cruda en el límite 0.5 de Microsoft. La puerta es neutral respecto a la aplicación: los clientes deciden qué significa un evento speak y pueden aplicar su propia política. STREAMMIND_CHUNK=N procesa la entrada de forma incremental mientras preserva el estado recurrente.

Entrada MP4, RTSP y HLS

streammind_native.py es un adaptador de transporte/preprocesamiento. En el modo incremental, un proceso FFmpeg persistente decodifica el flujo y el selector de disponibilidad abierto construye los lienzos de Mage cuando la evidencia es suficiente; ninguno ejecuta un modelo neuronal. Mage-ViT, la Mamba-1 EPFE y el clasificador de puerta se ejecutan todos en el runtime C++ de llama.cpp parcheado, por lo que no se carga ningún checkpoint de Transformers ni un duplicado BF16.

Instala solo el entorno del preprocesador de vídeo y mantenlo activo para que codec-video-prep y cv-preinfer estén en PATH:

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

MP4 local:

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

La cámara RTSP y HLS usan el mismo comando; solo cambia la fuente:

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

El modo en vivo incremental no tiene un segmento de transporte fijo y no escribe ningún MP4 temporal. Con los 8 FPS muestreados predeterminados puede cerrarse después de las ocho muestras mínimas (un segundo) cuando se cumplen la disponibilidad y la cobertura temporal; de lo contrario, se extiende hasta --sampled-frames. El estado de EPFE continúa a través de cada grupo adaptativo hasta que el proceso termina. Para archivos locales, --realtime hace que FFmpeg alimente los fotogramas a velocidad de reproducción. Los pequeños lotes de traspaso MAGECV1 se eliminan inmediatamente después de consumirse. Omitir --incremental-producer conserva la ruta de compatibilidad segmentada codec-bitcost para trabajo offline/de referencia.

Archivos de conversión reproducibles e instrucciones de inferencia local para microsoft/Mage-VL. Los pesos GGUF publicados se midieron en puntos de referencia de imagen, vídeo y lenguaje y se compararon con los valores de referencia BF16 publicados por Microsoft.

Pesos del modelo: JohnTdi/Mage-VL-GGUF en Hugging Face

Mage-VL Studio: análisis GGUF nativo Q8 con un rango de tiempo seleccionado, OCR dedicado de texto estático, métricas de RAM/VRAM y destacados representativos de fotograma completo.

Divulgación de desarrollo: la asistencia y revisión de código fueron proporcionadas por OpenAI GPT-5.6 Sol. Las decisiones finales de integración, pruebas y publicación fueron tomadas y verificadas por el mantenedor del repositorio.

Este repositorio de GitHub contiene el runtime de Docker, los parches y las instrucciones de lanzamiento. El repositorio de Hugging Face contiene el backbone Q4/Q8 y los artefactos GGUF de visión F16/Q8.

Estado

Las imágenes de Docker aplican un pequeño parche de runtime nativo a llama.cpp fijado. Tanto el backbone de lenguaje como Mage-ViT permanecen en sus tipos de almacenamiento GGUF durante la inferencia; no interviene ningún proceso de Transformers ni reconstrucción BF16.

Variantes publicadas

Los pesos no se almacenan intencionadamente en Git. Los ocho artefactos del runtime están en el repositorio de modelos JohnTdi/Mage-VL-GGUF.

Inicio rápido: servidor nativo de llama.cpp

Instalación guiada con un solo comando

Después de clonar el repositorio, el instalador detecta CUDA o Vulkan, estima la VRAM, selecciona un perfil de 8/16/24–32 GB, descarga solo los archivos GGUF requeridos, deriva los nodos/grupos DRM correspondientes e inicia Docker:

./install.sh

Sobrescribe la detección con MAGE_BACKEND=vulkan|cuda y MAGE_PROFILE=8|16|24|32. El .env generado sigue siendo editable.

Las imágenes incluidas compilan una revisión fijada de llama.cpp, aplican el parche de runtime de Mage-ViT e incluyen las dependencias de imagen/vídeo. La interfaz web upstream no utilizada de llama.cpp se deshabilita en tiempo de compilación; esto evita Node/npm y descargas mutables de la interfaz de usuaro, mientras que la pasarela proporciona su propia página de subida local.

Este repositorio es la distribución completa del runtime: Docker clona llama.cpp fijado, aplica el parche nativo unificado de Mage desde patches/ e inicia llama-server con ambos archivos GGUF. No se requiere una copia de trabajo separada del fork de llama.cpp.

Requisitos: Linux, Git, Python 3 con venv y pip, Docker Engine y Docker Compose 2.30 o superior. Comienza desde un directorio vacío:

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

La primera compilación compila nuestro llama.cpp parcheado y puede tardar varios minutos. Cuando /health tenga éxito, abre http://localhost:8080 en un navegador, elige un MP4, escribe una pregunta y haz clic en Analyze video. No se requiere ninguna conversión manual ni comando de códec.

Para scripts, sube una imagen 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

O sube un MP4 normal. H.264 y HEVC van directamente al preprocesador oficial consciente del códec; AV1, VP9, MPEG-4 Part 2 y otros códecs de vídeo legibles por FFmpeg se convierten automáticamente a H.264 de alta calidad. El contenedor empaqueta MAGECV1 y ejecuta inferencia GGUF nativa:

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

Monitorización continua en directo

Abre Mage-VL Studio, selecciona Live stream, pega una URL RTSP/RTMP, HTTP/HLS directo, localhost o de una página compatible, como YouTube, configura la política de respuesta y selecciona Start live analysis. El proceso nativo en C++ realiza la decodificación FFmpeg, el muestreo temporal, la construcción de canvas de Mage y el GGUF DCVC-RT, y conserva el estado recurrente EPFE de StreamMind entre grupos. Mage-ViT codifica un grupo una sola vez; las mismas incrustaciones alimentan la puerta y cualquier respuesta Qwen activada. Los resultados con marcas de tiempo aparecen inmediatamente debajo del reproductor.

Demostración con una transmisión pública de YouTube seleccionada al azar; la fuente se eligió únicamente para ejercitar la ruta de análisis en directo y no constituye un respaldo.

La ruta continua no crea archivos MP4 de transporte ni de traspaso MAGECV1. Detén la sesión en directo antes de cambiar la configuración del modelo. La latencia de origen y de procesamiento dependen de la red y del contenido de los fotogramas. La interfaz informa del retardo en directo, del factor de tiempo real (RTF) p95, de las ventanas pendientes/descartadas y de si la transmisión mantiene el ritmo. Drop stale windows está activado por defecto, de modo que una instalación sobrecargada se mantiene al día en lugar de analizar un historial cada vez mayor.

El FPS en directo es actualmente explícito, no se evalua ni se adapta automáticamente a la GPU del usuario. El campo Analyzed FPS tiene como valor predeterminado 8; el perfil de hardware establece un punto de partida conservador, pero no cambia los FPS mientras una sesión está en ejecución. Si la canalización se retrasa, la cola acotada descarta las ventanas obsoletas cuando Drop stale windows está activado, en lugar de acumular un retardo ilimitado. Usa el RTF informado y la telemetría de la cola para ajustarlo: mantén el RTF p95 por debajo de 0.8, reduce primero los FPS analizados (12 -> 8 -> 6 -> 4 -> 2) y luego baja MAGE_DCVC_LIVE_MAX_HEIGHT (720 -> 480 -> 360) si es necesario. Aumenta cualquiera de los dos ajustes solo después de que la transmisión permanezca estable durante varios minutos.

Los resultados de capacidad medidos con la R9700 están en docs/live-performance-r9700.md. En esta GPU, el valor predeterminado seguro acepta una fuente 1080p/4K, pero la reduce a 480p y muestrea 8 fps. DCVC nativo midió 14,30 fps a 854x480, 6,34 fps a 720p y 1,55 fps a 1080p. El primer arranque con la caché vacía puede dedicar entre 15 y 17 segundos a compilar gráficos Vulkan; las sesiones ya calentadas no repiten ese coste.

Detén el servicio con docker compose --profile vulkan down. Los arranques posteriores pueden omitir --build:

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

Elegir una cuantización

Establece el par en .env; se admiten las cuatro combinaciones:

# 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

Descarga todas las variantes si quieres cambiar sin tener que descargar más tarde:

.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

La API se vincula a 127.0.0.1 por defecto porque llama-server no tiene autenticación en esta configuración. Para exponerla deliberadamente, configura HOST_BIND en .env y protégela con un cortafuegos o un proxy inverso autenticado. No reenvíes nunca el puerto sin protección directamente a Internet.

La configuración predeterminada expone solo el par correspondiente /dev/dri/renderD128 + /dev/dri/card0 al contenedor, por lo que otra GPU Vulkan no es visible. Verifica ambos contra /dev/dri/by-path antes del primer uso. Si los cambias, deriva también RENDER_GID y VIDEO_GID de los mismos nodos. No los reasignes a nombres diferentes dentro del contenedor: RADV sigue su relación sysfs y puede fallar la autenticación si se reescriben los nombres. Hay una imagen NVIDIA disponible con --profile cuda; necesita NVIDIA Container Toolkit. Ver docker/README.md.

La puerta de enlace pública expone únicamente la página local de subida, /health, /v1/image/analyze, /v1/video/prepare, /v1/video/analyze-prepared, /v1/video/analyze, la API de sesiones /v1/live/sessions y las vistas previas de solo lectura de canvas de códec; el llama-server interno escucha solo dentro del contenedor. Los vídeos preprocesados se almacenan en caché por hash de contenido y por todas las configuraciones de preprocesamiento que afectan a la salida, de modo que una subida repetida omite tanto la transcodificación como el preprocesamiento de códec. Las pistas de audio de los vídeos se ignoran deliberadamente: Mage-VL analiza el contenido visual, no el habla ni el sonido.

El panel Live Stream acepta RTSP/RTMP, HTTP/HLS directo, URLs localhost y páginas web compatibles, como YouTube (resueltas dentro del contenedor con yt-dlp). Ofrece cuatro políticas de respuesta: periódica, cada cambio detectado, solo cambios importantes, y cambios importantes más un informe periódico. La longitud de la ventana, el intervalo mínimo entre respuestas, la sensibilidad a la importancia, la calidad visual, la longitud de la respuesta, el transporte RTSP y el prompt del usuario son configurables. Los segmentos de transporte cerrados y sus espacios de trabajo MAGECV1 se eliminan inmediatamente después de la inferencia; solo permanece el historial acotado de resultados en memoria. Detén una sesión explícitamente antes de cambiar la configuración del modelo.

El runtime nativo optimizado para directo codifica cada ventana de vídeo con Mage-ViT exactamente una vez. Sus incrustaciones alimentan tanto la clasificación StreamMind EPFE como, solo después de un disparador, la generación Qwen. Iniciar el modo en directo descarga el llama-server de subida ordinario; detener el directo lo restaura, de modo que nunca hay dos backbones de lenguaje residentes simultáneamente. Cada resultado en directo expone vision_encode_count=1 y shared_vision_embeddings=true como verificación en tiempo de ejecución. El lanzamiento de Docker incluye el parche nativo completo de StreamMind y ambos sidecars Q8 EPFE/clasificador se descargan del repositorio de Hugging Face enlazado.

El panel del navegador muestra una vista previa del MP4 local inmediatamente, muestra el progreso del preprocesamiento y de la inferencia, renderiza la respuesta del modelo y las métricas PP/TG, y muestra los canvas de códec exactos que se pasan a Mage-ViT. Un canvas es un mosaico espacial de parches seleccionados de fotogramas de origen, no necesariamente un fotograma completo convencional. Por lo tanto, cada tarjeta informa de su rango exacto de marcas de tiempo de los fotogramas de origen y de la lista completa de marcas de tiempo derivada de src_patch_position.npy. El reproductor incluye un selector de rango de análisis con dos asas. Solo se decodifica y almacena en caché el intervalo seleccionado, mientras que cada marca de tiempo de la vista previa se traduce de vuelta a la línea temporal absoluta del vídeo original. Su control de Velocidad/Detalle de cinco pasos cambia tanto el muestreo temporal (96–320 fotogramas) como el presupuesto de píxeles del canvas de códec (90k–180k). El escaneo de texto minucioso opcional ejecuta deliberadamente una pasada de inferencia separada centrada en OCR: los experimentos mostraron que un único prompt de evento general puede omitir un subtítulo estático legible incluso con el ajuste de detalle visual más alto.

Los ajustes avanzados pueden recargar el modelo con un contexto, lote, microlote y caché KV F16/Q8/Q4 diferentes tras una confirmación explícita. Si la nueva configuración no puede iniciarse, la puerta de enlace intenta restaurar la anterior. El panel de recursos informa de la RAM residente combinada de la puerta de enlace y llama en Linux. En NVIDIA usa VRAM por proceso de nvidia-smi; en AMD/Vulkan, donde el kernel no expone una VRAM por proceso fiable, informa del aumento del dispositivo DRM seleccionado con respecto a la línea base previa a la carga y etiqueta ese método explícitamente.

Valores predeterminados para una GPU de 16 GiB

El perfil incluido utiliza una ranura de solicitud, caché KV F16 y ctx=16384. En una Radeon AI PRO R9700 con Vulkan, el clip de prueba H.264 de 1080x1920 y 50,64 segundos descrito en el repositorio de benchmarks generó 8.099 tokens de prompt:

El parche de prefill en tiempo de ejecución combina tramos sucesivos de texto con marcas de tiempo y visuales hasta que el lote del decodificador está lleno. Antes de este parche, la misma entrada creaba muchas sumisiones Vulkan pequeñas y alcanzaba solo 1.221 tok/s. Con el parche y ctx=32768 alcanzó 2.718 tok/s y usó unos 10,4 GiB; reducir el contexto preasignado a 16k conserva los mismos valores KV F16 y ahorra aproximadamente 2,8 GiB. Los valores exactos dependen del controlador, del prompt, del número de canvas y del estado de energía.

Los valores predeterminados de seguridad/recursos están en .env: 16.384 tokens de contexto, un preprocesador concurrente, subida de 2 GiB, duración de 60 minutos, vídeo de origen 3840x2160, 256 fotogramas muestreados, 150.000 píxeles por canvas de vídeo, 256 tokens generados y un tiempo de espera de preprocesamiento de 15 minutos. Las imágenes JPEG/PNG se reducen automáticamente a 1.048.576 píxeles como máximo para mantener las cargas de trabajo de imagen y vídeo dentro del perfil de 16 GiB. La caché de preprocesamiento con direccionamiento por contenido está limitada a 50 GiB y expulsa las entradas menos recientemente usadas. Cambia los valores MAGE_* correspondientes en .env y vuelve a crear el servicio con docker compose --profile vulkan up -d --force-recreate vulkan.

Las variables de ajuste más útiles son LLAMA_ARG_CTX_SIZE (contexto/VRAM), MAGE_SAMPLED_FRAMES (cobertura temporal), MAGE_MAX_PIXELS (tokens por canvas de códec), MAGE_IMAGE_MAX_PIXELS y MAGE_MAX_NEW_TOKENS. El envío al decodificador está fijado explícitamente a MAGE_BATCH_SIZE=2048, MAGE_UBATCH_SIZE=512 y caché KV F16. Si una configuración de imagen personalizada crea un bloque visual mayor que el lote del decodificador, la API devuelve un error 422 claro en lugar de aceptar un prompt truncado; aumenta MAGE_BATCH_SIZE o reduce los píxeles de la imagen.

La duración del vídeo no se mapea uno a uno con el contexto: el valor predeterminado muestrea como máximo 256 fotogramas y la agrupación por preparación produjo de 24 a 52 canvas (entre 4.800 y 10.400 tokens visuales) en los clips de 15 a 85 segundos probados. Cuantos más fotogramas muestreados o canvas más grandes, mayor es el tiempo de preprocesamiento, el uso de contexto y la memoria. Si una solicitud no cabe, baja MAGE_SAMPLED_FRAMES o MAGE_MAX_PIXELS; aumenta LLAMA_ARG_CTX_SIZE solo cuando quede suficiente VRAM.

Convertir a GGUF

El parche apunta al commit a52077c4cabb4f3c0298329c9d2dd1324d5604cb de llama.cpp. Otra revisión puede requerir resolución manual de conflictos. Ejecuta este bloque desde la raíz del repositorio clonado mage-vl-gguf; crea llama.cpp/ en su interior.

Usa un venv de conversión separado. Sus requisitos fijados instalan PyTorch de CPU y no deben reemplazar el entorno ROCm/CUDA utilizado para la inferencia.

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

Compila llama.cpp y cuantiza el backbone de lenguaje:

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

Rendimiento del backbone llama.cpp

Radeon AI PRO R9700, Vulkan, llama.cpp a52077c, batch 2048, ubatch 512, Flash Attention habilitado:

Estas cifras miden el backbone de lenguaje Qwen3, no el preprocesamiento de códec ni Mage-ViT. Nuestras variantes GGUF publicadas se midieron con el conjunto de desarrollo completo de MMBench EN (4.329 registros), Video-MME tc32 sin subtítulos (2.700 preguntas), WikiText-2 y una comparación numérica de visión con nueve imágenes. Q8 + vision Q8 obtuvo un 84,36% en MMBench CircularEval y un 63,33% en Video-MME. Los valores de referencia BF16 informados por Microsoft son 84,19% y 64,00%, respectivamente. La tarjeta del modelo de Hugging Face contiene la comparación completa, el resumen del protocolo y los checksums.

Validación nativa

La compilación Docker actual de Vulkan pasa 10 imágenes más 10 vídeos H.264 para cada combinación de lanzamiento: Q4+vision Q8, Q8+vision Q8, Q4+vision F16 y Q8+vision F16 — 80/80 comprobaciones semánticas deterministas. El banco de pruebas reutilizable es tests/native_sanity.sh. Las pruebas de la puerta de enlace también cubren la inferencia de imágenes y de vídeos en caché para los cuatro pares, la conversión AV1-en-MP4, el rechazo de MAGECV1 malformado, la reutilización de la caché, la propagación del estado de salud, el cierre ordenado y el procesamiento nativo de transmisiones en directo. Estas comprobaciones de ejecución complementan a MMBench y Video-MME. La cadena de parches de lanzamiento se compila en cada push mediante .github/workflows/ci.yml; las comprobaciones de calidad/rendimiento de GPU siguen siendo pruebas de puerta de lanzamiento porque la CI alojada no tiene ningún dispositivo Vulkan/CUDA ni pesos de modelo adecuados.

Licencia y proyectos upstream

Mage-VL está licenciado bajo Apache-2.0. llama.cpp está licenciado bajo MIT. Este repositorio contiene parches de integración y documentación; las licencias upstream continúan aplicándose a sus respectivos artefactos de código y modelo. El NOTICE separa el código de la comunidad, el runtime upstream y los términos de los modelos.