open-edge-platform/vss-summarize-video

VSS Zusammenfassen

Führen Sie die Zusammenfassungs-Pipeline über den Pipeline Manager aus. Rufen Sie die dokumentierte API selbst auf und melden Sie nur beobachtete Antworten. Endpunkte verwenden das nginx /manager-Präfix. Wenn die vss_* MCP-Tools verbunden sind, erledigt vss_summarize_video die gleiche Arbeit; diese Fähigkeit ist der REST-Weg.

Setzen Sie HOST=http://${HOST_IP:-localhost}:${APP_HOST_PORT:-12345}.

Antwortvertrag, wenn VSS nicht erreichbar ist

Der Benutzer ist möglicherweise nicht in der Deployment-Umgebung, $HOST verweigert möglicherweise Verbindungen, oder eine Live-Vorbedingung schlägt fehl (z. B. ist der Zusammenfassungsmodus deaktiviert oder das benannte Video ist nicht vorhanden). In all diesen Fällen stagnieren Sie nicht und erfinden Sie keine Antworten. Melden Sie das beobachtete Hindernis und antworten Sie dann mit der vollständigen exakten Aufruffolge, die der Benutzer nach der Behebung ausführen kann: vollständige Endpunktpfade, Anfragetexte / Formularfelder, das Feld, das jeder Schritt von der vorherigen Antwort übernimmt, und die Bedingung, die besagt, dass ein Schritt abgeschlossen ist. Kürzen oder lassen Sie den angeforderten Zusammenfassungsablauf nicht weg, nur weil er nicht ausgeführt werden konnte. Geben Sie klar an, welche Befehle nicht ausgeführt wurden. Beenden Sie die Antwort niemals mit der Frage, ob sie ausgeführt werden sollen.

Umgebungseinrichtung (zuerst ausführen)

Diese Fähigkeit steuert die Video Search & Summarization-App über ihre echten Quelldateien, daher muss die VSS-Anwendung vorhanden sein und Sie müssen Befehle aus ihrem App-Stammverzeichnis ausführen. Führen Sie dies vor allem anderen aus, und es funktioniert unabhängig davon, ob sich die VSS-Quelle bereits in Ihrem Arbeitsbereich befindet.

Führen Sie das gebündelte Bootstrap-Skript aus. Es ermittelt das App-Stammverzeichnis in dieser Reihenfolge und gibt es als einzige Zeile auf stdout aus:

1. Gehen Sie vom aktuellen Verzeichnis nach oben und suchen Sie nach einem VSS-App-Stammverzeichnis – einem Verzeichnis, das alle drei Markierungen setup.sh, docker/ und pipeline-manager/ enthält.
2. Fragen Sie git nach dem umschließenden Repository (git rev-parse --show-toplevel) und prüfen Sie, ob es sample-applications/video-search-and-summarization enthält oder selbst ein VSS-App-Stammverzeichnis ist. Dadurch funktioniert Ihr eigener Clone – oder ein Fork – unverändert.
3. Wiederverwenden Sie einen Checkout, den ein vorheriger Bootstrap bereits abgelegt hat in ${XDG_CACHE_HOME:-$HOME/.cache}/vss-src/edge-ai-libraries.

Wenn einer dieser Punkte zutrifft, wird dieser Checkout wiederverwendet und KEIN Clone durchgeführt. Nur wenn alle drei fehlschlagen, wird ein Clone durchgeführt – und dann nur ein flacher (--depth 1), Einzel-Branch, sparsamer Checkout von lediglich sample-applications/video-search-and-summarization von main:

# SKILL_DIR ist das eigene Verzeichnis dieser Fähigkeit (wird Ihnen beim Laden der Fähigkeit angezeigt);
# im Repository ist es .github/skills/vss-summarize-video. Funktioniert gleich, wenn die Fähigkeit eigenständig installiert ist.
SKILL_DIR=".github/skills/vss-summarize-video"
APP_ROOT="$(bash "$SKILL_DIR/scripts/vss-bootstrap.sh")"
cd "$APP_ROOT"

Jeder Befehl unten setzt voraus, dass das Arbeitsverzeichnis dieses APP_ROOT ist. Um von einem Fork/Branch zu ziehen oder ein bestimmtes Checkout-Verzeichnis wiederzuverwenden, überschreiben Sie VSS_REPO_URL, VSS_REPO_BRANCH oder VSS_CLONE_DIR, bevor Sie es ausführen. Das Bootstrap-Skript weigert sich, ein vorhandenes Nicht-VSS-Clone-Ziel zu überschreiben.

Vorbedingungen

1. Backend gesund und Zusammenfassung aktiviert – zuerst prüfen; wenn nicht, verwenden Sie die installierte Fähigkeit vss-troubleshoot oder vss-deploy mit Namen:

   curl -sf "$HOST/manager/health" >/dev/null && \
   curl -s "$HOST/manager/app/features" | jq -e '(.summary // .) == "FEATURE_ON"'
   

2. Eine videoId zum Zusammenfassen – laden Sie eine mit POST /manager/videos (Multipart, Feld video) hoch, was { "videoId": "…" } zurückgibt. Oder listen Sie vorhandene auf – beachten Sie, dass die Antwort ein Objekt { "videos": [...] } ist, kein bloßes Array, und name ist ein generierter Hash (der tatsächliche Dateiname steht in url / dataStore.fileName):

   curl -s -X POST "$HOST/manager/videos" -F "video=@/pfad/zu/clip.mp4" | jq .
   curl -s "$HOST/manager/videos" | jq '.videos[] | {videoId, file: .dataStore.fileName}'
   

1. Starten der Zusammenfassungs-Pipeline

POST /manager/summary. Der Body hat erforderliche Felder; fehlt eines von title, sampling.* oder evam.evamPipeline, wird 400 zurückgegeben. Siehe references/summary-request.md für das vollständige Schema, Prompt-Überschreibungen und Audio-Optionen.

Minimale gültige Anfrage:

curl -s -X POST "$HOST/manager/summary" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Laderampen-Überprüfung",
    "videoId": "<VIDEO_ID>",
    "sampling": { "chunkDuration": 20, "samplingFrame": 5, "frameOverlap": 0, "multiFrame": 5 },
    "evam": { "evamPipeline": "object_detection" },
    "produceFinalSummary": true
  }' | jq .
# → { "summaryPipelineId": "<STATE_ID>" }

Sampling-Einschränkung: Der Pipeline Manager erzwingt multiFrame == frameOverlap + samplingFrame. Mit frameOverlap: 0 setzen Sie multiFrame == samplingFrame. Nichtübereinstimmung → 400 "Multi frame mismatch". evamPipeline ist eines von object_detection | video_ingestion.

Um nur einen Teil eines Clips zusammenzufassen, fügen Sie die optionalen sampling.videoStart und sampling.videoEnd (Sekunden) hinzu – z. B. die ersten zehn Minuten sind "videoStart": 0, "videoEnd": 600.

2. Abfragen bis zum Abschluss

Die zurückgegebene summaryPipelineId ist die stateId. GET /manager/summary/{stateId} hat kein status/progress-Feld der obersten Ebene (nur /raw hat eines) – der Fortschritt befindet sich in stufenspezifischen Feldern:

STATE_ID=<STATE_ID>
curl -s "$HOST/manager/summary/$STATE_ID" | jq '{
  chunking: .chunkingStatus,         # string, "complete" wenn chunked
  frames:   .frameSummaryStatus,     # COUNTS-Objekt: {complete, inProgress, na, ready}
  video:    .videoSummaryStatus,     # string: "na" → "inProgress" → "complete"  ← echtes Fertig-Signal
  audio:    .audioTranscriptSummaryStatus,
  summary_len: (.summary | length)
}'

⚠️ Abschluss ist videoSummaryStatus == "complete", NICHT summary ist nicht leer. Der endgültige summary-Text wird inkrementell gestreamt, während videoSummaryStatus noch "inProgress" ist. Daher gibt das Abfragen auf "summary length > 0" ein abgeschnittenes, mitten im Satz endendes Ergebnis zurück. Warten Sie immer auf videoSummaryStatus. Mit produceFinalSummary: false gibt es keine Endstufe – warten Sie stattdessen auf frameSummaryStatus.inProgress == 0.

until curl -s "$HOST/manager/summary/$STATE_ID" \
       | jq -e '.videoSummaryStatus == "complete"' >/dev/null; do sleep 10; done

Die Zusammenfassung ist langsam (VLM pro Chunk + LLM Map-Reduce) – Minuten, nicht Sekunden.

3. Abrufen der Zusammenfassung

curl -s "$HOST/manager/summary/$STATE_ID" | jq -r '.summary'   # endgültige Map-Reduce-Zusammenfassung
# Bildunterschriften pro Chunk befinden sich in .frameSummaries[] (jeweils: frameKey, status, summary).
# NICHT in .chunks[] – diese enthalten nur {chunkId, duration, audioTranscripts}:
curl -s "$HOST/manager/summary/$STATE_ID" | jq -r '.frameSummaries[] | "[\(.frameKey)] \(.summary)"'
curl -s "$HOST/manager/summary/$STATE_ID/raw" | jq .   # alles (audio, frames, status, …)

Präsentieren Sie den endgültigen Zusammenfassungstext; bieten Sie die Details pro Chunk an, falls nützlich. Audio ohne Sprache liefert einen audioTranscriptSummary, der dies besagt – kein Fehler.

Prüfpfad der endgültigen Antwort

Tool-Argumente sind möglicherweise für den Benutzer oder Bewerter nicht sichtbar. Die endgültige Antwort muss daher das Bootstrap-Ergebnis melden: das aufgelöste APP_ROOT, ob ein vorhandener Checkout ohne Clonen wiederverwendet wurde und dass Befehle nach dem Wechsel in dieses App-Stammverzeichnis ausgeführt wurden. Geben Sie auch an, dass ein vollständiges Fehlschlagen des Bootstrap auf ein flaches (--depth 1), Einzel-Branch, sparsames Checkout nur der VSS-App von main zurückfällt. Melden Sie die beobachteten /manager/health-Werte und den Wert der Zusammenfassungsfunktion.

Für den Zusammenfassungs-Workflow nennen Sie jede verwendete öffentliche Manager-Operation (Methode und /manager/...-Pfad), die wichtigen Anforderungsfelder, die beobachtete Antwort und die Übernahme von summaryPipelineId zu STATE_ID. Wenn eine Vorbedingung die Ausführung blockiert, trennen Sie klar beobachtete Prüfungen von nicht ausgeführten Befehlen und zeigen Sie dennoch die genauen gültigen Anfrage-, Abschlussbedingungs- und Abrufschritte, ohne IDs oder Zusammenfassungsinhalte zu erfinden.

Verwalten

curl -s "$HOST/manager/summary" | jq '.[] | {stateId, title}'   # alle auflisten
curl -s -X DELETE "$HOST/manager/summary/$STATE_ID"             # einen löschen