Цель

Запустить микросервис RT-VLM для плотного субтитрирования в автономном режиме и протестировать все предоставляемые им конечные точки (загрузка файлов, generate_captions, добавление/удаление потоков, автозаполнение в чате, темы Kafka).

Необходимые условия

Для автономного развертывания RT-VLM:

• Docker, Docker Compose, NVIDIA Container Toolkit и доступный графический процессор (GPU).
• Учетные данные реестра NGC в переменной $NGC_CLI_API_KEY для входа в Docker на nvcr.io, загрузки образов и локальной загрузки моделей/артефактов NGC.
• curl, jq и любой рабочий каталог с правами на запись для автономной копии compose.

Для вызовов API в отношении существующего сервиса:

• Запущенный сервис RT-VLM, доступный по адресу $BASE_URL.
• Токен Bearer в $RTVI_VLM_API_KEY или $NGC_CLI_API_KEY, в зависимости от того, как был настроен сервис.

Для развертывания полного профиля VSS:

• Используйте файл ../vss-deploy-profile/SKILL.md; данный скилл не развертывает полные профили VSS.

Инструкции

Следуйте таблицам маршрутизации и пошаговым рабочим процессам, приведённым ниже. Каждый раздел, название которого заканчивается на «workflow», «quick start» или «flow», следует выполнять сверху вниз. Подробные справочные материалы находятся в каталоге references/; выполняйте описанные рабочие процессы напрямую, если в будущих версиях не будет указан конкретный вспомогательный инструмент.

Примеры

Готовые примеры от начала до конца хранятся в папке evals/ (каждый манифест *.json содержит запускаемый сценарий) и встроены в блоки curl для каждого рабочего процесса ниже. Запустите оценку уровня 3 с помощью nv-base validate --agent-eval, чтобы воспроизвести их.

Ограничения

• Требуется либо автономный сервис RT-VLM, развернутый с помощью данного навыка, либо существующий сервис RT-VLM, доступный для вызывающего пользователя.
• На модели и NIM, размещённые в NGC, могут распространяться ограничения по скорости, требования к памяти GPU и лицензионные ограничения.
• Ограничения на параллелизм, память GPU и хранилище зависят от аппаратного обеспечения хоста и файла compose профиля.
• Не включайте файлы NGC_CLI_API_KEY, RTVI_VLM_API_KEY и .env в репозиторий git и в журналы; не выводите значения учетных данных и не включайте их в итоговые ответы.
• Доступ к группе Docker и команда sudo фактически предоставляют привилегии уровня root. Используйте неинтерактивный защитный механизм sudo -n при развертывании и останавливайте процесс, чтобы владелец хоста мог выполнить действие, если sudo без ввода пароля недоступен.

Устранение неполадок

• Ошибка: REST-вызов возвращает отказ в подключении. Причина: целевой микросервис не запущен. Решение: проверьте /docs или /health; выполните повторное развертывание с помощью vss-deploy-profile или соответствующего навыка vss-deploy- *.
• Ошибка: HTTP 401/403 при запросах к NGC. Причина: отсутствует или истек срок действия NGC_CLI_API_KEY. Решение: выполните команду ` docker login nvcr.io ` и повторно экспортируйте ключ перед повторной попыткой.
• Ошибка: не хватает памяти в контейнере (OOM) или не удаётся загрузить модель. Причина: недостаточно памяти GPU для выбранного профиля. Решение: перейдите на вариант меньшего размера или освободите ресурсы GPU с помощью команды `docker compose down`.

Развертывание и использование RT-VLM Dense Captioning (VSS 3.2)

RT-VLM — это микросервис NVIDIA для обработки изображений и языка в реальном времени: декодирует видео (файл или RTSP), сегментирует его на фрагменты, запускает VLM (cosmos-reason1, cosmos-reason2 или любую совместимой с OpenAI модели), передает плотные субтитры обратно по SSE/HTTP и публикует субтитры, оповещения об инцидентах и ошибки в Kafka. Используйте этот навык для развертывания автономного сервиса RT-VLM, если полный профиль VSS ещё не запущен, а затем вызывайте его API /v1/... для генерации подписей, загрузки файлов, управления прямыми трансляциями, проверок работоспособности , автозаполнения в чате, совместимого с NIM, или метрик Prometheus. Справочник API: https://docs.nvidia.com/vss/latest/real-time-vlm-api.html.

Маршрутизация развертывания

Если пользователь запрашивает развертывание полного профиля VSS, используйте ../vss-deploy-profile/SKILL.md. Этот навык отвечает за маршрутизацию профилей, файлы generated.env и resolved.yml, определение размера нескольких сервисов и развертывание/сборку полного стека.

Если пользователь запрашивает автономную плотную субтитризацию RT-VLM или профиль VSS еще не запущен, используйте автономный поток RT-VLM в файле references/deploy-rt-vlm-service.md перед вызовом API. Он следует тому же шаблону, ориентированному на Compose, что и vss-deploy-profile: сбор контекста, запуск предварительных проверок, работа с локальной копией, пробный запуск с конфигурацией Docker Compose, проверка, развертывание, а затем ожидание подтверждения работоспособности.

Поток автономного развертывания

Всегда следуйте этой последовательности. Никогда не пропускайте пробный запуск.

# 1. Скопируйте файл deploy/docker/services/rtvi/rtvi-vlm/rtvi-vlm-docker-compose.yml
#    в любой доступный для записи автономный рабочий каталог.
# 2. Получите значение RTVI_VLM_IMAGE_TAG из этой копии compose.
# 3. Удалите из копии блок depends_on, предназначенный только для автономного режима.
# 4. Создайте файл .env, игнорируемый git, с необходимыми значениями RT-VLM.
# 5. Подготовьте пути привязки хоста, такие как $VSS_DATA_DIR/data_log/vst/clip_storage.
#    Используйте `sudo -n` для исправления прав владения; если sudo без ввода пароля недоступно,
#    остановитесь и попросите владельца хоста запустить выведенную команду вручную.
# 6. docker compose --env-file .env -f rtvi-vlm-docker-compose.yml config --quiet
# 7. Загрузите с помощью `docker pull` образ RT-VLM с точным тегом.
# 8. Запустите `docker compose ... up -d rtvi-vlm`, дождитесь, пока система будет готова, затем проведите тест работоспособности.

Перед любой операцией pull или up запустите предварительную проверку; остановитесь и устраните сбои на этом этапе, прежде чем приступать к отладке самого RT-VLM:

nvidia-smi --query-gpu=index,name --format=csv,noheader
nvidia-container-cli info
docker compose version
docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

При автономном развертывании с одним файлом не запускайте файл deploy/docker/services/rtvi/rtvi-vlm/rtvi-vlm-docker-compose.yml напрямую: он содержит ссылки depends_on на родственные службы VLM/NIM, которые определены в полном проекте compose VSS/met-blueprints. В отдельном примере показано, как скопировать файл compose, получить из него текущий тег образа, удалить блок `depends_on ` и проверить результат перед запуском.

Для проверки с помощью агента никогда не допускайте интерактивного запроса sudo. Перед любой операцией, требующей привилегий владельца или операцией Docker, используйте неинтерактивную защиту, описанную в references/deploy-rt-vlm-service.md: предпочтительный вариант — простой docker; в противном случае используйте sudo -n docker; если sudo -n завершится с ошибкой, остановитесь и выполните точную ручную команду для владельца хоста вместо повторной попытки с интерактивным sudo или ослаблением прав доступа.

Если команда `docker pull` завершается с ошибкой containerd snapshotter/unpack в Docker 28+ версии, перед повторной попыткой примените исправление ` /etc/docker/daemon.json containerd-snapshotter=false ` из справочника по автономной установке.

Минимальные значения переменных .env для автономного режима:

Настройка

export BASE_URL="http://localhost:${RTVI_VLM_PORT:-8018}"  # порт RT-VLM на стороне хоста
export API_KEY="${NGC_CLI_API_KEY:-${RTVI_VLM_API_KEY:-}}" # токен bearer, используемый командами curl на стороне хоста
: "${API_KEY:?Установите NGC_CLI_API_KEY или RTVI_VLM_API_KEY перед вызовом конечных точек, требующих аутентификации}"

Каждый из приведённых ниже запросов использует Authorization: Bearer $API_KEY. Конечные точки проверки работоспособности (/v1/health/*, /v1/ready, /v1/live, /v1/startup) обычно работают без авторизации.

Проверка работоспособности перед использованием:

curl -fsS "$BASE_URL/v1/health/ready"
MODEL_ID="$(curl -fsS "$BASE_URL/v1/models" -H "Authorization: Bearer $API_KEY" | jq -r '.data[0].id // .id')"
curl -fsS "$BASE_URL/openapi.json" | jq -r '.paths | keys[]' | sort

RTSP Sample Stream Guard

Если в задаче или eval указано RTSP_SAMPLE_URL, рассматривайте именно эту переменную среды как обязательный входной параметр. Перед проверкой или регистрацией любого потока убедитесь, что она установлена и не пуста; если она отсутствует, остановитесь с чётким сообщением об ошибке. Не используйте замену из NvStreamer, VIOS, пакетов sample-data или каких-либо других резервных источников, поскольку это приведёт к проверке потока, отличного от того, который запросил вызывающий.

: "${RTSP_SAMPLE_URL:?Установите RTSP_SAMPLE_URL в значение доступного образец потока RTSP перед проверкой RTSP}"
case "$RTSP_SAMPLE_URL" in
  rtsp://*) ;;
  *) echo "RTSP_SAMPLE_URL должен быть URL-адресом в формате rtsp://, получено: $RTSP_SAMPLE_URL" >&2; exit 1 ;;
esac

if command -v ffprobe >/dev/null 2>&1; then
  ffprobe -v error -rtsp_transport tcp \
    -select_streams v:0 -show_entries stream=codec_type \
    -of csv=p=0 "$RTSP_SAMPLE_URL" | grep -qx video
elif command -v gst-discoverer-1.0 >/dev/null 2>&1; then
  gst-discoverer-1.0 "$RTSP_SAMPLE_URL" | grep -qi 'video'
else
  echo "Установите ffprobe или gst-discoverer-1.0 перед проверкой RTSP." >&2
  exit 1
fi

Быстрый старт — плотные субтитры из локального видео

# 1. Загрузите видео, получите его идентификатор файла
FILE_ID=$(curl -fsS -X POST "$BASE_URL/v1/files" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@/path/to/warehouse.mp4" \
  -F "purpose=vision" \
  -F "media_type=video" | jq -r '.id')

# 2. Сгенерировать субтитры и оповещения (поток SSE с фрагментированными ответами)
curl -N -X POST "$BASE_URL/v1/generate_captions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"id\": \"$FILE_ID\",
    \"prompt\": \"Напишите краткую и емкую подпись для каждого 10-секундного фрагмента этого видео с склада.\",
    \"model\": \"$MODEL_ID\",
    \"chunk_duration\": 10,
    \"stream\": true
  }"

API-интерфейс

Перед вызовом дополнительных конечных точек используйте актуальный OpenAPI в качестве достоверного источника информации:

curl -fsS "$BASE_URL/openapi.json" | jq -r '.paths | keys[]' | sort

Основные пути для VSS 3.2:

• POST /v1/files для многочастной загрузки медиафайлов; передайте возвращаемый идентификатор файла в функцию генерации субтитров и удалите файл по завершении.
• POST /v1/generate_captions для создания субтитров к файлу или потоку. Используйте точный идентификатор модели, возвращаемый запросом GET /v1/models; псевдонимы, такие как cosmos-reason2, являются селекторами бэкенда, а не идентификаторами модели в запросе.
• POST /v1/streams/add, GET /v1/streams/get-stream-info и DELETE /v1/streams/delete/{stream_id} для жизненного цикла RTSP. Извлекайте идентификаторы потоков из results[0].id.
• POST /v1/chat/completions для текстовых и мультимодальных вызовов, совместимых с OpenAI. Текущие сборки версии 26.05 возвращают HTTP 400 для текстовых запросов /v1/completions; рассматривайте это как ожидаемое поведение при проверке совместимости с устаревшими версиями.
• GET /v1/health/ready, /v1/models, /v1/assets/stats и /v1/metrics для проверки работоспособности сервиса. Не следует предполагать наличие /v1/license, если он не указан в OpenAPI.

Подробные схемы конечных точек, формы ответов, конечные точки с единственным потоком в стиле CV, а также примечания по совместимости с версией 26.05 находятся в файле references/api-surface-26.05.md.

Типичные рабочие процессы

• Создание субтитров для сохраненных файлов: загрузите файл с помощью POST /v1/files, вызовите /v1/generate_captions с возвращенным идентификатором файла, используйте stream=true для SSE, затем удалите файл, чтобы освободить место на хранилище.
• Субтитры в реальном времени по RTSP: если вызывающая сторона предоставляет RTSP_SAMPLE_URL, используйте именно этот URL и запустите RTSP Sample Stream Guard перед регистрацией. Не создавайте замещающий поток из NvStreamer или VIOS, если RTSP_SAMPLE_URL пуст; вместо этого сразу завершайте операцию с ошибкой. Требуйте наличие фактической записи видеопотока/субтитров перед регистрацией; добавьте поток, добавьте к нему субтитры, а затем отмените его регистрацию.
• Подсказки оповещений: включайте детерминированную строку «Обнаружена аномалия: Да/Нет ». Публикация в Kafka настраивается на стороне сервера, добавляется к HTTP-ответам и описана в файле references/kafka-workflows.md.
• Проверка Kafka: полагайтесь на рабочую среду vss-rtvi-vlm при определении имён тем. В полном профиле оповещений VSS в режиме реального времени используйте существующий контейнер VSS Kafka mdx-kafka для проверок через командную строку и окончательных команд потребителя инцидентов. Для автономной проверки используйте брокер, объявляющий ${HOST_IP}:9092; никогда не останавливайте и не заменяйте уже существующий брокер без подтверждения пользователя.

Справочник ошибок

Распространённые причины: 400 — неверный формат запроса или идентификатор модели, 401/403 — отсутствующий или неверный токен bearer, 404 — удалённые файлы/потоки или неподдерживаемые конечные точки, 413 — для загрузок превышающих допустимый размер, 422 — для проверки схемы, 429 — из-за слишком высокой параллельности, 500 — для сбоев при выводе/во время выполнения, и 503 — пока запуск ещё происходит. Проверьте журналы Docker vss-rtvi-vlm на наличие сбоев со стороны службы.