Zweck

Den RT-VLM-Mikroservice für Dense Captioning eigenständig bereitstellen und jeden von ihm bereitgestellten Endpunkt testen (Datei-Upload, generate_captions, Stream hinzufügen/löschen, Chat-Vervollständigungen, Kafka-Themen).

Voraussetzungen

Für die eigenständige RT-VLM-Bereitstellung:

• Docker, Docker Compose, NVIDIA Container Toolkit und eine sichtbare GPU.
• Anmeldedaten für die NGC-Registry in $NGC_CLI_API_KEY für die Docker-Anmeldung bei nvcr.io, das Abrufen von Images sowie das Herunterladen lokaler NGC-Modelle und -Artefakte.
• curl, jq und ein beliebiges beschreibbares Arbeitsverzeichnis für die eigenständige Compose-Kopie.

Für API-Aufrufe an einen bestehenden Dienst:

• Laufender RT-VLM-Dienst, erreichbar unter $BASE_URL.
• Bearer-Token in $RTVI_VLM_API_KEY oder $NGC_CLI_API_KEY, je nachdem, wie der Dienst konfiguriert wurde.

Für die vollständige Bereitstellung eines VSS-Profils:

• Verwenden Sie ../vss-deploy-profile/SKILL.md; dieser Skill stellt keine vollständigen VSS-Profile bereit.

Anleitung

Befolgen Sie die unten aufgeführten Routing-Tabellen und Schritt-für-Schritt-Workflows. Jeder Abschnitt, der mit „Workflow“, „Schnellstart“ oder „Ablauf“ endet, ist von oben nach unten auszuführen. Detailliertes Referenzmaterial finden Sie im Verzeichnis „references/“; führen Sie die dokumentierten Workflows direkt aus, sofern in einer zukünftigen Überarbeitung kein konkreter Helfer genannt wird.

Beispiele

Fertig ausgearbeitete End-to-End-Beispiele befinden sich im Verzeichnis „evals/“ (jedes *.json-Manifest enthält ein ausführbares Szenario) sowie inline in den nachstehenden „curl“-Blöcken zu den einzelnen Workflows. Führen Sie eine Tier-3-Bewertung mit „nv-base validate --agent-eval“ durch, um diese abzuspielen.

Einschränkungen

• Erfordert entweder einen eigenständigen RT-VLM-Dienst, der über diesen Skill bereitgestellt wird, oder einen vorhandenen RT-VLM-Dienst, der für den Aufrufer erreichbar ist.
• Von NGC gehostete Modelle und NIMs können Ratenbeschränkungen, Anforderungen an den GPU-Speicher sowie Lizenzbeschränkungen unterliegen.
• Die Grenzen für Parallelität, GPU-Speicher und Speicherplatz hängen von der Host-Hardware und der „compose“-Datei des Profils ab.
• Halten Sie die Dateien ` NGC_CLI_API_KEY`, `RTVI_VLM_API_KEY` und `.env` aus Git und aus den Protokollen heraus; geben Sie Anmeldedaten nicht im Klartext aus und fügen Sie sie nicht in endgültige Antworten ein.
• Der Zugriff auf die Docker-Gruppe und „sudo“ entsprechen faktisch Root-Rechten. Verwenden Sie den nicht-interaktiven „sudo -n “-Schutz in der Deploy-Referenz und stoppen Sie die Aktion des Host-Besitzers, wenn passwortloses „sudo“ nicht verfügbar ist.

Fehlerbehebung

• Fehler: REST-Aufruf gibt „Connection refused“ zurück. Ursache: Ziel-Mikroservice läuft nicht. Lösung: Überprüfen Sie /docs oder /health; führen Sie ein erneutes Deployment über vss-deploy-profile oder die entsprechende vss-deploy-*-Skill durch.
• Fehler: HTTP 401/403 bei NGC-Pulls. Ursache: fehlender/abgelaufener NGC_CLI_API_KEY. Lösung: Führen Sie „docker login nvcr.io“ aus und exportieren Sie den Schlüssel erneut, bevor Sie es erneut versuchen.
• Fehler: Container OOM oder Modell kann nicht geladen werden. Ursache: Unzureichender GPU-Speicher für das ausgewählte Profil. Lösung: Wechseln Sie zu einer kleineren Variante oder geben Sie GPUs mit „docker compose down“ frei.

Bereitstellung und Verwendung von RT-VLM Dense Captioning (VSS 3.2)

RT-VLM ist der Echtzeit-Vision-Language-Mikroservice von NVIDIA: Dekodiere Videos (Datei oder RTSP), segmentiere sie in Chunks, führe ein VLM aus (cosmos-reason1, cosmos-reason2 oder ein beliebiges OpenAI-kompatibles Modell), Dense Captions über SSE/HTTP zurückstreamen und Untertitel, Vorfallwarnungen und Fehler an Kafka veröffentlichen. Verwenden Sie diese Funktion, um den eigenständigen RT-VLM-Dienst bereitzustellen, wenn noch kein vollständiges VSS-Profil ausgeführt wird, und rufen Sie anschließend dessen /v1/... API auf, um Untertitel zu generieren, Dateien hochzuladen, Live-Streams zu verwalten, Zustandsprüfungen durchzuführen, NIM-kompatible Chat-Vervollständigungen zu nutzen oder Prometheus-Metriken abzurufen. API-Referenz: https://docs.nvidia.com/vss/latest/real-time-vlm-api.html.

Bereitstellungs-Routing

Wenn der Nutzer die Bereitstellung eines vollständigen VSS-Profils anfordert, verwenden Sie ../vss-deploy-profile/SKILL.md. Diese Skill ist zuständig für das Profil-Routing, „generated.env“, „resolved.yml“, die Dimensionierung mehrerer Dienste sowie die vollständige Bereitstellung und das Herunterfahren.

Wenn der Benutzer eine eigenständige RT-VLM-Dichteuntertitelung anfordert oder noch kein VSS-Profil läuft, verwenden Sie den eigenständigen RT-VLM-Ablauf in references/deploy-rt-vlm-service.md, bevor Sie die API aufrufen. Dies folgt demselben „Compose“-zentrierten Muster wie vss-deploy-profile: Kontext erfassen, Vorabprüfungen durchführen, mit einer lokalen Kopie arbeiten, Trockenlauf mit der Docker-Compose-Konfiguration durchführen, überprüfen, bereitstellen und anschließend auf den Status warten.

Standalone-Bereitstellungsablauf

Befolgen Sie stets diese Reihenfolge. Überspringen Sie niemals den Testlauf.

# 1. Kopiere deploy/docker/services/rtvi/rtvi-vlm/rtvi-vlm-docker-compose.yml
#    in ein beliebiges beschreibbares eigenständiges Arbeitsverzeichnis.
# 2. Leite RTVI_VLM_IMAGE_TAG aus dieser Compose-Kopie ab.
# 3. Entfernen Sie den nur für die Standalone-Bereitstellung relevanten, überflüssigen `depends_on`-Block aus der Kopie.
# 4. Erstellen Sie eine `.env`-Datei, die von Git ignoriert wird, mit den erforderlichen RT-VLM-Werten.
# 5. Bereiten Sie Host-Bind-Pfade wie $VSS_DATA_DIR/data_log/vst/clip_storage vor.
#    Verwende `sudo -n` für Berechtigkeitskorrekturen; falls passwortloses `sudo` nicht verfügbar ist,
#    halte an und bitte den Host-Besitzer, den angezeigten Befehl manuell auszuführen.
# 6. docker compose --env-file .env -f rtvi-vlm-docker-compose.yml config --quiet
# 7. Laden Sie mit `docker pull` genau den RT-VLM-Image-Tag herunter.
# 8. Führen Sie `docker compose ... up -d rtvi-vlm` aus, warten Sie, bis der Status „ready“ erreicht ist, und führen Sie dann einen Smoke-Test durch.

Führen Sie vor jedem „pull“ oder „up“ Vorabprüfungen durch; beenden Sie den Vorgang hier und beheben Sie Fehler, bevor Sie RT-VLM selbst debuggen:

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

Bei eigenständigen Ein-Datei-Bereitstellungen führen Sie die Datei deploy/docker/services/rtvi/rtvi-vlm/rtvi-vlm-docker-compose.yml nicht direkt aus: Sie enthält „depends_on“-Verweise auf gleichrangige VLM/NIM-Dienste, die nur im vollständigen VSS/met-blueprints-Compose-Projekt definiert sind. Die Referenz für die eigenständige Bereitstellung zeigt, wie man die Compose-Datei kopiert, daraus das aktuelle Image-Tag ableitet, den `depends_on` -Block entfernt und das Ergebnis vor dem Start überprüft.

Bei der agentengesteuerten Validierung darf die sudo- Eingabeaufforderung niemals interaktiv erscheinen. Verwenden Sie vor jedem privilegierten Eigentümerwechsel oder Docker-Vorgang die nicht-interaktive Schutzmaßnahme in references/deploy-rt-vlm-service.md: bevorzuge „plain docker“; verwende andernfalls „sudo -n docker“; falls „sudo -n“ fehlschlägt, breche den Vorgang ab und führe den genauen manuellen Befehl für den Host-Besitzer aus, anstatt es mit interaktivem „sudo“ erneut zu versuchen oder die Berechtigungen zu schwächen.

Wenn „docker pull“ mit einem „containerd snapshotter/unpack“-Fehler unter Docker 28+ fehlschlägt, wenden Sie die Korrektur „containerd-snapshotter=false“ in der Datei „/etc/docker/daemon.json“ aus der Standalone-Referenz an, bevor Sie es erneut versuchen.

Mindestwerte für die standalone -.env -Datei:

Einrichtung

export BASE_URL="http://localhost:${RTVI_VLM_PORT:-8018}"  # RT-VLM-Port auf der Host-Seite
export API_KEY="${NGC_CLI_API_KEY:-${RTVI_VLM_API_KEY:-}}" # Bearer-Token, das von hostseitigen curl-Befehlen verwendet wird
: "${API_KEY:?Legen Sie NGC_CLI_API_KEY oder RTVI_VLM_API_KEY fest, bevor Sie authentifizierte Endpunkte aufrufen}"

Jede der folgenden Anfragen verwendet „Authorization: Bearer $API_KEY“. Health-Endpunkte (/v1/health/*, /v1/ready, /v1/live, /v1/startup) funktionieren in der Regel ohne Authentifizierung.

Test vor der Nutzung:

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-Beispiel-Stream-Guard

Wenn eine Aufgabe oder ein Eval den Namen RTSP_SAMPLE_URL trägt, behandeln Sie genau diese Umgebungsvariable als erforderliche Eingabe. Überprüfen Sie vor dem Abfragen oder der Registrierung eines Streams, ob sie gesetzt und nicht leer ist; falls sie fehlt, brechen Sie den Vorgang mit einer eindeutigen Fehlermeldung ab. Leiten Sie keinen Ersatzwert aus NvStreamer, VIOS, Sample-Data-Bundles oder anderen Fallback-Lösungen ab, da dadurch ein anderer Stream validiert wird als der vom Aufrufer angeforderte.

: „${RTSP_SAMPLE_URL:?Setzen Sie RTSP_SAMPLE_URL vor der RTSP-Validierung auf einen erreichbaren RTSP-Beispiel-Stream}“
case „$RTSP_SAMPLE_URL“ in
  rtsp://*) ;;
  *) echo „RTSP_SAMPLE_URL muss eine rtsp://-URL sein, erhalten: $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 "Installieren Sie ffprobe oder gst-discoverer-1.0 vor der RTSP-Validierung." >&2
  exit 1
fi

Schnellstart – Dense Captions aus einem lokalen Video

# 1. Laden Sie das Video hoch und erfassen Sie dessen Datei-ID
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. Untertitel und Benachrichtigungen generieren (SSE-Stream mit in Blöcken übermittelten Antworten)
curl -N -X POST "$BASE_URL/v1/generate_captions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"id\": \"$FILE_ID\",
    \"prompt\": \"Verfasse für jedes 10-Sekunden-Segment dieses Lagerhausvideos eine prägnante, aussagekräftige Bildunterschrift.\",
    \"model\": \"$MODEL_ID\",
    \"chunk_duration\": 10,
    \"stream\": true
  }"

API-Oberfläche

Verwenden Sie die Live-OpenAPI als maßgebliche Quelle, bevor Sie optionale Endpunkte aufrufen:

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

Die wichtigsten Pfade für VSS 3.2 sind:

• POST /v1/files für den Multipart-Medien-Upload; übergeben Sie die zurückgegebene Datei-ID an die Untertitelgenerierung und löschen Sie die Datei nach Abschluss des Vorgangs.
• POST /v1/generate_captions für die Untertitelung von Dateien oder Streams. Verwenden Sie die exakte Modell-ID, die von GET /v1/models zurückgegeben wird; Aliase wie „cosmos-reason2“ sind Backend-Selektoren und keine Modell-IDs für Anfragen.
• POST /v1/streams/add, GET /v1/streams/get-stream-info und DELETE /v1/streams/delete/{stream_id} für den RTSP-Lebenszyklus. Stream-IDs aus results[0].id auswerten.
• POST /v1/chat/completions für OpenAI-kompatible Text- und multimodale Aufrufe. Aktuelle 26.05-Builds geben für reine Text- /v1/completions einen HTTP-400-Fehler zurück; behandle dies bei der Validierung von Legacy-Verhalten als erwartet.
• GET /v1/health/ready, /v1/models, /v1/assets/stats und /v1/metrics für Service-Probes. Gehen Sie nicht davon aus, dass /v1/license existiert, es sei denn, OpenAPI listet es auf.

Detaillierte Endpunkt-Schemas, Antwortformate, Endpunkte im CV-Stil mit einem einzigen Stream sowie Hinweise zur Kompatibilität mit 26.05 finden Sie in references/api-surface-26.05.md.

Gängige Arbeitsabläufe

• Untertitelung gespeicherter Dateien: Hochladen mit POST /v1/files, Aufruf von /v1/generate_captions mit der zurückgegebenen Datei-ID, Verwendung von stream=true für SSE, anschließendes Löschen der Datei, um Speicherplatz freizugeben.
• RTSP-Live-Untertitelung: Wenn der Aufrufer RTSP_SAMPLE_URL angibt, verwende genau diese URL und führe vor der Registrierung den RTSP Sample Stream Guard aus. Leiten Sie keinen Ersatzstream aus NvStreamer oder VIOS ab, wenn RTSP_SAMPLE_URL leer ist; führen Sie stattdessen einen „Fail-Fast“-Abbruch durch. Verlangen Sie vor der Registrierung einen tatsächlichen Videostream-/Untertitel-Eintrag; fügen Sie den Stream hinzu, untertiteln Sie ihn und heben Sie anschließend die Registrierung auf.
• Warnmeldungen: Fügen Sie eine deterministische Zeile „Anomalie erkannt: Ja/Nein“ ein. Die Kafka-Veröffentlichung erfolgt serverseitig, zusätzlich zu den HTTP-Antworten, und ist in „references/kafka-workflows.md“ dokumentiert.
• Kafka-Validierung: Verlasse dich bei den Themennamen auf die Live-Umgebung von vss-rtvi-vlm. Verwende in einem vollständigen VSS-Echtzeit-Profil für Warnmeldungen den vorhandenen VSS-Kafka-Container „mdx-kafka“ für CLI-Prüfungen und abschließende Befehle des Incident-Consumers. Für die eigenständige Validierung verwenden Sie einen Broker, der ${HOST_IP}:9092 veröffentlicht; beenden oder ersetzen Sie niemals einen bereits vorhandenen Broker ohne Bestätigung durch den Benutzer.

Fehlerreferenz

Häufige Ursachen: 400 bei ungültiger Anfrageform oder Modell-ID, 401/403 bei fehlendem oder falschem Bearer-Token, 404 bei gelöschten Dateien/Streams oder nicht unterstützten Endpunkten, 413 bei zu großen Uploads, 422 bei der Schemavalidierung, 429 bei zu hoher Parallelität, 500 bei Inferenz-/Laufzeitfehlern und 503, während der Start noch im Gange ist. Überprüfen Sie die Docker-Protokolle „vss-rtvi-vlm“ auf serviceseitige Fehler.