Преобразование 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. Профиль по умолчанию рассчитан на NVIDIA GPU с 8 ГиБ: языковой бэкбон Q4_K_M, боковые модели Q8 для vision/StreamMind, боковые модели F16 для DCVC, контекст на 8192 токена и KV-кэш Q4.

Предварительные требования

• Windows с WSL2 и драйвером NVIDIA, видимым в nvidia-smi внутри WSL.

• Дистрибутив WSL Ubuntu 24.04 с именем Ubuntu-24.04 (или передайте -Distro).

• Не менее 20 ГиБ свободного места в WSL-файловой системе Docker до первой сборки образа.

• Постоянный каталог данных E:\mageVL-data; веса моделей, кэш, база данных SQLite, журналы и сгенерированная конфигурация рантайма остаются там.

Хост, использовавшийся при разработке, имеет ноутбучный GPU RTX 4060 с 8188 МиБ; не предполагайте, что другая машина имеет такой же запас. Образ CUDA 12.8.1 используется по умолчанию. 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 намеренно интерактивен: он устанавливает Docker Engine и NVIDIA Container Toolkit внутри WSL и может запросить пароль sudo Linux. setup-runtime загружает шесть закреплённых GGUF-артефактов из ревизии 63b23eb4707b1907668c57d61845e7d423016b5c репозитория JohnTdi/Mage-VL-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-клиента и инструменты

Используйте эту конечную точку Streamable HTTP в локальном MCP-клиенте:

http://127.0.0.1:8765/mcp

Все шесть инструментов инференса используют один общий FIFO-канал. Сессия наблюдения блокирует офлайн-анализ и проверку сегментов, пока не завершится или не будет остановлена. Это намеренно: нативный раннер StreamMind заменяет обычный llama-server и удерживает рекуррентное состояние. При перезапуске оркестратора выполняемые задания помечаются как failed, а не молчаливо возобновляются.

Офлайн-анализ запрашивает у 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

Этот форк выполняет проактивный путь StreamMind от Microsoft полностью внутри llama.cpp: эмбеддинги Mage-ViT группируются по временным меткам кодекa, усредняются по патчам, проходят через состоятельную Mamba-1 EPFE и оцениваются четырёхслойным классификатором-шлюзом Qwen3. Он не воссоздаёт тензоры Transformers и не держит втоую модель 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 содежит исходный кадр, официальные логиты silent/speak, вероятность speak и сырое решение на границе Microsoft 0.5. Шлюз нейтрален к приложению: клиенты сами решают, что означает событие speak, и могут применять собственную политику. STREAMMIND_CHUNK=N обрабатывает входные данные инкрементально, сохранзя рекуррентное состояние.

Вход MP4, RTSP и HLS

streammind_native.py — это адаптер транспорта/преобработки. В инкрементальном режиме один постоянный процес FFmpeg декодирует поток, а селектор готовности о ткрытых соединениях строит канвасы Mage по мере достаточности даннных; ни один из них не выполняет нейронную модель. Mage-ViT, EPFE Mamba-1 и классификатор-шлюз выполняются в пропатченном 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 сэмплированных кадров в секуну по умолчанию он может завериться после минимльны восьми сэмплов (одной секунды), когд удовлетворены готовность и временное покрытие; в противном слчае он расширяется до --sampled-frames. Состояние EPFE сохраняется во всех адаптивных группах до выхода процесса. Для локальных файлов --realtime заставляет FFmpeg подавать кадры со скоростью воспроизведения. Небольшие пакеты передачи MAGECV1 удаляются сразу после потребления. Опускание --incremental-producer сохранет сегментированный путь совместимости codec-bitcost для офлайн/референсной работы.

Повторяемые файлы конверсии и локальные инсрукции по инференсу для microsoft/Mage-VL. Выпущенные веса GGUF были измерены на бенчмарках изобржений, видео и языка и сравнены с заявленными эталонными значениями BF16 от Microsoft.

Веса модели: JohnTdi/Mage-VL-GGUF на Hugging Face

Mage-VL Studio: нативный анализ Q8 GGUF с выбранным временным диапазоном, выделенным статическим OCR, метриками RAM/VRAM и репрезентативными полнокадровыми Highlights.

Раскрытие информации о разработке: помощь в написании кода и его рецензирование были предоставлены OpenAI GPT-5.6 Sol. Окончательная интграция, тестирование и рещения о выпуске были приняты и проверены сопровождающим репозитория.

Этот репозиторий GitHub содерит Docker-рантайм, патчи и инструкции по запуску. Репозиторий Hugging Face содерит артефакты GGUF: бекбон Q4/Q8 и vision F16/Q8.

Статус

Docker-обрзы применяют небольшой нативный патч рантайма к закреплённому llama.cpp. И языковой бекбон, и Mage-ViT остаются в своих типах хранения GGUF во время инференса; никакой процес Transformers или воссоздание BF16 не вклчены.

Выпущенные вариаты

Веса намеренно не хранятся в Git. Все восем артефактов рантайма находятся в модельном репозитории JohnTdi/Mage-VL-GGUF.

Быстрый старт: нативный сервер llama.cpp

Одиокомандная направляемая установа

После клонирования репозитория устанавщик обнаруживает CUDA или Vulkan, оценивает VRAM, выбирает профil 8/16/24–32 ГБ, загружает только требуемые GGUF-файлы, выводит соответствующие узлы/группы DRM и запускает Doker:

./install.sh

Переопределите обнаружение с помощью MAGE_BACKEND=vulkan|cuda и MAGE_PROFILE=8|16|24|32. Сгенерированный .env остается редактируемым.

Вклченные обрзы компилируют закреплённую ревизию llama.cpp, применяют патч рантайма Mage-ViT и вклчают зависимсти для изобржений/видео. Неиспользуемый веб-интерфейс вышестоящего llama.cpp отклчен на этапе сбрки; это избегает Node/npm и изменяемых загрзок веб-интерфейса, а шлюз предоставляет собственную локальную страницу загрзки.

Этот репозиторий является полным дистрибутивом рантайма: Docker клонирует закреплённый llama.cpp, применяет единый нативный патч Mage из patches/ и запускает llama-server с обоми файлами GGUF. Отдельный чекаут форка llama.cpp не требуется.

Требования: Linux, Git, Python 3 с venv и pip, 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, введите вопрос и нажмите Analyze video. Никакой ручной конверсии или команды кодекa не требуется.

Для скриптов загрузите изобржение 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, выберите Live stream, вставьте RTSP/RTMP, прямой HTTP/HLS, localhost или URL поддерживаемой страницы, например YouTube, настройте политику ответов и выберите Start live analysis. Нативный процесс на C++ выпоняет декодирование FFmpeg, временную выборку, построение DCVC-RT GGUF и canvas-изображений Mage, затем сохраняет рекуррентное состояние EPFE StreamMind между группами. Mage-ViT кодирует группу один раз; одни и те же эмбеддинги подаются в затвор и в любой запущенный ответ Qwen. Результаты с временными метками сразу поя вляются под плеером.

Демонстрация на случайно выбранном публичном YouTube-прямом эфире; источник был выбран только для проверки пути анализа в реальном времени и не я вляется одобрением.

Непрерывный путь не создаёт транспортных MP4 или передаваемых MAGECV1-файлов. Остановите сеанс прямого эфира перед изменением настроек модели. Задержка источника и обработки зависит от сети и содержимого кадров. Интерфейс сообщает задержку прямого эфира, p95 коэфициент реального времени (RTF), ожидающие/отброшенные окна и успевает ли поток. Drop stale windows включено по умолчанию, поэтому перегруженная установка остаётся актуальной, а не анализирует постоянно растущую историю.

Live FPS в настояще е время задаётся явно, а не автоматически измеряется и не подстраивается под GPU пользователя. Поле Analyzed FPS по умолчанию рав но 8; апаратный профиль задаёт консервативную отправную точку, но не изменяет FPS во время работы сеанса. Если конвейер не успевает, ограниченная очередь отбрасывает устаревшие окна, когда включено Drop stale windows, вме сто накопления неограниченной задержки. Используйте сообщаемые RTF и телеметрию очереди для настройки: держите p95 RTF ниже 0.8, сначала уменшайте analyzed 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 показал 14.30 fps при 854x480, 6.34 fps при 720p и 1.55 fps при 1080p. Первый запуск с пустым кэшем может потратить 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 в этой конфигурации не имеет аутентификации. Чтобы намеренно открыть к нему доступ, задайте HOST_BIND в .env и защитите его брандмауэром или аутентифицирующим обратным прокси. Никогда не пробрасывайте исходный порт напрямую в Интернет.

Конфигурация по умолчанию предоставлят контейнеру только соответствующую пару /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, /v1/image/analyze, /v1/video/prepare, /v1/video/analyze-prepared, /v1/video/analyze, API сеансов /v1/live/sessions и предпросмotры codec-canvas только для чтения; внутрений llama-server слушает только внутри контейнера. Предобработанные видео кэшируются по хэшу содержимого и всем настройкам предобработки, влияющим на результат, поэтому повторная загрузка пропускает и транскодирование, и предобработку кодеков. Дорожки аудио в видео намеренно игнорируются: Mage-VL анализирует визуальный контент, а не речь или звук.

Панель Live Stream принимает RTSP/RTMP, прямые HTTP/HLS, URL localhost и поддерживаемые веб-страницы, такие как YouTube (разрешаются внутри контейнера с помощью yt-dlp). Она предлагает четыре политики ответов: периодические ответы, при каждом обнаруженном изменении, только важные изменения, а также важные изменения плюс периодический отчёт. Длина окна, минимальный интервал между ответами, чувствительность к важности, визуальное качество, длина ответа, транспорт RTSP и пользовательский промпт настраиваются. Закрытые транспортные сегменты и их рабочие области MAGECV1 удаляются сразу после инференса; остаётся только ограниченная история результатов в памяти. Остановите сеанс явно перед изменением настроек модели.

Оптимизированный нативный runtime прямого эфира кодирует каждое видеоокно с помощью Mage-ViT ровно один раз. Его эмбеддинги питают и StreamMind EPFE/классификацию, и — только после триггера — генерацию Qwen. Запуск режима прямого эфира выгружает обычный загрузочный llama-server; остановка прямого эфира восстанавливает его, поэтому два языковых бэкбона никогда не находятся в памяти одновременно. Каждый результат прямого эфира содержит vision_encode_count=1 и shared_vision_embeddings=true в качестве проверки времени выполнения. В состав Docker-релиза входит полный нативный патч StreamMind, а оба сайдкара Q8 EPFE/классификатор загружаются из указанного репозитория Hugging Face.

Панель браузера сразу показывает локальный MP4, отображает ход предобработки и инференса, выводит ответ модели и метрики PP/TG, а также показывает точные codec-canvas, передаваемые в Mage-ViT. Canvas — это пространственная мозаика выбранных патчей исходных кадров, а не обязательно обычный полный кадр. Поэтому каждая карточка сообщает точный диапазон временных меток исходных кадров и полный список временных меток, полученный из src_patch_position.npy. Плеер включает селектор диапазона анализа с двумя ползунками. Декодируется и кэшируется только выбранный интервал, а каждая временная метка предпросмотра переводится обратно в абсолютную шкалу времени исходного видео. Его пятиступенчатый регулятор Speed/Detail изменяет и временную выборку (96–320 кадров), и бюджет пикселей codec-canvas (90k–180k). Дополнительное тщательное сканирование текста намеренно выполняет отдельный проход инференса, ориентированный на OCR: эксперименты показали, что один общий промпт о событии может пропустить читаемую статическую подпись даже при максимальной настройке визуальной детализации.

Расширенные настройки позволяют перезагрузить модель с другим контекстом, batch, micro-batch и KV-кэшем F16/Q8/Q4 после явного подтверждения. Если новая конфигурация не запускается, шлюз пытается восстановить предыдущую. Панель ресурсов сообщает суммарную резидентную RAM шлюза и llama-server в Linux. На NVIDIA используется VRAM на процесс через nvidia-smi; на AMD/Vulkan, где ядро не предоставляет надёжную VRAM на процесс, сообщается прирост выбранного DRM-устройства относительно базового уровня до загрузки, и этот метод явно помечен.

Значения по умолчанию для GPU с 16 GiB

Поставляемый профиль использует один слот запросов, F16 KV-кэш и ctx=16384. На Radeon AI PRO R9700 с Vulkan тестовый фрагмент H.264 1080x1920 длительностью 50.64 секунды, описанный в репозитории бенчмарков, создал 8 099 токенов промпта:

Патч префилла в runtime объединяет последовательные текстовые фрагменты временных меток и визуальные фрагменты, пока пакет декодера не заполнится. До этого патча те же входные данные создавали много мелких Vulkan-подвызовов и достигали лишь 1 221 tok/s. С патчем и ctx=32768 скорость достигла 2 718 tok/s при использовании около 10.4 GiB; уменьшение предварительно выделенного контекста до 16k сохраняет те же значения F16 KV, экономя примерно 2.8 GiB. Точные значения зависят от драйвера, промпта, количества canvas и состояния питания.

Значения по умолчанию для безопасности и ресурсов находятся в .env: 16 384 токена контекста, один одновременный препроцессор, загрузка 2 GiB, длительность 60 минут, исходное видео 3840x2160, 256 выборочных кадров, 150 000 пикселей на видео-canvas, 256 генерируемых токенов и таймаут предобработки 15 минут. Изображения JPEG/PNG автоматически уменшаются до не более 1 048 576 пикселей, чтобы держать рабочие нагрузки изображений и видео в пределах профиля 16 GiB. Кэш предобработки с адресацией по содержимому ограничен 50 GiB и вытесняет наименее недавно используемые записи. Измените соответствующие значения MAGE_* в .env, затем пересоздайте сервис командой docker compose --profile vulkan up -d --force-recreate vulkan.

Наиболее полезные переменные для настройки: LLAMA_ARG_CTX_SIZE (контекст/VRAM), MAGE_SAMPLED_FRAMES (временное покрытие), MAGE_MAX_PIXELS (токены на codec canvas), MAGE_IMAGE_MAX_PIXELS и MAGE_MAX_NEW_TOKENS. Подвызов декодера явно привязан к MAGE_BATCH_SIZE=2048, MAGE_UBATCH_SIZE=512 и F16 KV-кэшу. Если пользовательская настройка изображения создаёт визуальный фрагмент больше пакета декодера, API возвращает понятную ошибку 422 вместо приёма усечённого промпта; увеличьте MAGE_BATCH_SIZE или уменьшите количество пикселей изображения.

Длительность видео не сопоставляется один-к-одному с контекстом: по умолчанию выбирается не более 256 кадров, а группировка по готовности дала 24–52 canvas-изображения (примерно 4 800–10 400 визуальных токенов) на протестированных клипах длительностью 15–85 секунд. Большее количество выборочных кадров или более крупные canvas увеличивают время предобработки, использование контекста и память. Если запрос не помещается, уменьшите MAGE_SAMPLED_FRAMES или MAGE_MAX_PIXELS; увеличивайте LLAMA_ARG_CTX_SIZE только при достаточном остатке VRAM.

Преобразование в 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, batch 2048, ubatch 512, Flash Attention включена:

Эти цифры измеряют языковой бэкбон Qwen3, а не предобработку кодеков или Mage-ViT. Наши выпущенные варианты GGUF измерялись на полном dev-наборе MMBench EN (4 329 записей), Video-MME tc32 без субтитров (2 700 вопросов), WikiText-2 и численном визуальном сравнении с девятью изображениями. Q8 + vision Q8 набрал 84.36% в MMBench CircularEval и 63.33% в Video-MME. Заявленные Microsoft эталонные значения BF16 составляют соответственно 84.19% и 64.00%. Карточка модели Hugging Face содержит полное сравнение, сводку протокола и контрольные суммы.

Нативная проверка

Текущая сборка Docker с Vulkan проходит 10 изображений плюс 10 видео H.264 для каждой релизной комбинации: Q4+vision Q8, Q8+vision Q8, Q4+vision F16 и Q8+vision F16 — 80/80 детерминированных семантических проверок. Многоразовый каркас — tests/native_sanity.sh. Тесты шлюза также покрывают инференс изображений и кэшированных видео для всех четырёх пар, конвертацию AV1-в-MP4, отклонение некорректных MAGECV1, повторное использование кэша, распространение состояния здоровья, корректное завершение работы и обработку нативного прямого эфира. Эти исполнительные проверки дополняют MMBench и Video-MME. Цепочка релизных патчей компилируется при каждой пуше с помощью .github/workflows/ci.yml; проверки качества/производительности GPU остаются тестами релизного шлюза, потому что размещённому CI не хватает подходящего устройства Vulkan/CUDA или весов модели.

Лицензия и вышестоящие проекты

Mage-VL распространяется по лицензии Apache-2.0. llama.cpp распространяется по лицензии MIT. Этот репозиторий содержит интеграционные патчи и документацию; лицензии вышестоящих проектов по-прежнему применяются к соответствующему коду и артефактам моделей. Файл NOTICE разграничивает код сообщества, вышестоящую среду выполнения и условия использования моделей.