VSS 비디오 요약은(는) 무엇을 하나요?

파이프라인 매니저를 통해 요약 파이프라인을 실행합니다. 문서화된 API를 직접 호출하고 관찰된 응답만 보고하세요. 엔드포인트는 nginx /manager 접두사를 사용합니다. vss_* MCP 도구가 연결된 경우 vss_summarize_video가 동일한 작업을 수행합니다. 이 스킬은 REST 경로입니다.

다음과 같이 설정하세요: HOST=http://${HOST_IP:-localhost}:${APP_HOST_PORT:-12345}.

VSS에 연결할 수 없는 경우 답변 규칙

사용자가 배포 환경에서 떨어져 있거나, $HOST가 연결을 거부하거나, 실시간 전제 조건이 실패할 수 있습니다(예: 요약 모드가 비활성화되었거나 지정된 비디오가 없는 경우). 이러한 경우 지연을 만들거나 응답을 지어내지 마십시오. 관찰된 장애 요소를 보고한 후, 사용자가 이를 수정한 후 실행할 수 있는 완전하고 정확한 호출 시퀀스를 답변에 포함하세요: 전체 엔드포인트 경로, 요청 본문/양식 필드, 각 단계가 이전 응답에서 전달하는 필드, 단계 완료 조건. 실행할 수 없다고 해서 요청된 요약 흐름을 축약하거나 생략하지 마십시오. 실행되지 않은 명령을 명확히 명시하세요. 실행 여부를 묻는 질문으로 답변을 끝내지 마십시오.

환경 설정 (먼저 실행)

이 스킬은 실제 소스 파일을 통해 Video Search & Summarization 애플리케이션을 구동하므로, VSS 애플리케이션이 존재해야 하며 앱 루트에서 명령을 실행해야 합니다. 다른 모든 작업보다 먼저 이 작업을 수행하세요. VSS 소스가 작업 공간에 이미 있든 없든 작동합니다.

번들로 제공되는 부트스트랩 스크립트를 실행합니다. 이 스크립트는 다음 순서로 앱 루트를 찾아 stdout의 유일한 줄로 출력합니다:

현재 디렉토리에서 위로 이동하여 VSS 앱 루트를 찾습니다. setup.sh, docker/, pipeline-manager/의 세 가지 마커를 모두 가진 디렉토리를 찾습니다.
git에 둘러싸인 저장소를 요청(git rev-parse --show-toplevel)하고 sample-applications/video-search-and-summarization을 포함하는지, 또는 그 자체가 VSS 앱 루트인지 확인합니다. 이렇게 하면 사용자의 클론 또는 포크가 변경 없이 작동합니다.
이전 부트스트랩이 이미 배치한 체크아웃을 재사용합니다. (${XDG_CACHE_HOME:-$HOME/.cache}/vss-src/edge-ai-libraries에 위치)

이 중 하나라도 성공하면 해당 체크아웃이 재사용되며 클론이 수행되지 않습니다. 세 가지 모두 실패한 경우에만 클론이 수행됩니다. 이때는 얕은(--depth 1), 단일 브랜치, 스파스 체크아웃으로 main 브랜치에서 sample-applications/video-search-and-summarization만 가져옵니다:

# SKILL_DIR은 이 스킬의 디렉토리입니다(스킬이 로드될 때 표시됨);
# 저장소 내에서는 .github/skills/vss-summarize-video입니다. 스킬이 독립적으로 설치된 경우에도 동일하게 작동합니다.
SKILL_DIR=".github/skills/vss-summarize-video"
APP_ROOT="$(bash "$SKILL_DIR/scripts/vss-bootstrap.sh")"
cd "$APP_ROOT"

아래의 모든 명령은 작업 디렉토리가 이 APP_ROOT라고 가정합니다. 포크/브랜치에서 가져오거나 특정 체크아웃 디렉토리를 재사용하려면 실행 전에 VSS_REPO_URL, VSS_REPO_BRANCH 또는 VSS_CLONE_DIR을 재정의하세요. 부트스트랩은 기존의 VSS가 아닌 클론 대상을 덮어쓰는 것을 거부합니다.

전제 조건

백엔드가 정상이고 요약이 활성화되었는지 먼저 확인하세요. 그렇지 않은 경우 설치된 vss-troubleshoot 또는 vss-deploy 스킬을 이름으로 사용하세요:
```
curl -sf "$HOST/manager/health" >/dev/null && \
curl -s "$HOST/manager/app/features" | jq -e '(.summary // .) == "FEATURE_ON"'
```
요약할 videoId - POST /manager/videos로 업로드(multipart, 필드 video)하면 { "videoId": "…" }가 반환됩니다. 또는 기존 비디오를 나열합니다 - 응답은 객체 { "videos": [...] }이며, 단순 배열이 아닙니다. name은 생성된 해시입니다(실제 파일 이름은 url / dataStore.fileName에 있음):
```
curl -s -X POST "$HOST/manager/videos" -F "video=@/path/to/clip.mp4" | jq .
curl -s "$HOST/manager/videos" | jq '.videos[] | {videoId, file: .dataStore.fileName}'
```

1. 요약 파이프라인 시작

POST /manager/summary. 본문에는 필수 필드가 있습니다. title, sampling.*, evam.evamPipeline 중 하나라도 누락되면 400 오류가 반환됩니다. 전체 스키마, 프롬프트 재정의 및 오디오 옵션은 references/summary-request.md를 참조하세요.

최소 유효 요청:

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

샘플링 제약 조건: 파이프라인 매니저는 multiFrame == frameOverlap + samplingFrame을 강제합니다. frameOverlap: 0인 경우 multiFrame == samplingFrame으로 설정하세요. 불일치 시 400 "Multi frame mismatch" 오류가 발생합니다. evamPipeline은 object_detection | video_ingestion 중 하나입니다.

클립의 일부만 요약하려면 선택적 sampling.videoStart 및 sampling.videoEnd(초)를 추가하세요. 예: 처음 10분은 "videoStart": 0, "videoEnd": 600.

2. 완료될 때까지 폴링

반환된 summaryPipelineId가 stateId입니다. GET /manager/summary/{stateId}에는 최상위 status/progress 필드가 없습니다(/raw에만 있음). 진행 상태는 각 단계 필드에 있습니다:

STATE_ID=<STATE_ID>
curl -s "$HOST/manager/summary/$STATE_ID" | jq '{
  chunking: .chunkingStatus,         # 문자열, 청크 완료 시 "complete"
  frames:   .frameSummaryStatus,     # 개수 객체: {complete, inProgress, na, ready}
  video:    .videoSummaryStatus,     # 문자열: "na" → "inProgress" → "complete"  ← 실제 완료 신호
  audio:    .audioTranscriptSummaryStatus,
  summary_len: (.summary | length)
}'

⚠️ 완료는 videoSummaryStatus == "complete"이며, summary가 비어 있지 않은 것이 아닙니다. 최종 summary 텍스트는 videoSummaryStatus가 여전히 "inProgress"인 동안 점진적으로 스트리밍되므로, "summary 길이 > 0"으로 폴링하면 잘린 중간 문장 결과를 반환합니다. 항상 videoSummaryStatus로 게이트를 제어하세요. produceFinalSummary: false인 경우 최종 단계가 없습니다. 대신 frameSummaryStatus.inProgress == 0으로 게이트를 제어하세요.

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

요약은 느립니다(청크당 VLM + LLM map-reduce) - 초가 아닌 분 단위입니다.

3. 요약 검색

curl -s "$HOST/manager/summary/$STATE_ID" | jq -r '.summary'   # 최종 map-reduce 요약
# 청크당 캡션은 .frameSummaries[]에 있습니다(각각: frameKey, status, summary).
# .chunks[]에는 {chunkId, duration, audioTranscripts}만 있고 요약은 없습니다:
curl -s "$HOST/manager/summary/$STATE_ID" | jq -r '.frameSummaries[] | "[\(.frameKey)] \(.summary)"'
curl -s "$HOST/manager/summary/$STATE_ID/raw" | jq .   # 모든 정보(오디오, 프레임, 상태, …)

최종 요약 텍스트를 제시하고, 유용한 경우 청크별 세부 정보를 제공하세요. 음성이 없는 오디오의 경우 audioTranscriptSummary에 그 내용이 표시됩니다. 오류가 아닙니다.

최종 답변 감사 추적

도구 인수는 사용자나 평가자에게 표시되지 않을 수 있습니다. 따라서 최종 답변은 부트스트랩 결과를 보고해야 합니다: 확인된 APP_ROOT, 기존 체크아웃이 클론 없이 재사용되었는지 여부, 앱 루트로 변경 후 명령이 실행되었음을 알립니다. 또한 부트스트랩이 완전히 실패하면 main 브랜치에서 VSS 앱만 얕은(--depth 1), 단일 브랜치, 스파스 체크아웃으로 폴백한다는 점을 명시하세요. 관찰된 /manager/health 및 요약 기능 값을 보고하세요.

요약 워크플로의 경우 사용된 모든 공개 Manager 작업(메서드 및 /manager/... 경로), 중요한 요청 필드, 관찰된 응답, summaryPipelineId에서 STATE_ID로의 전이를 명시하세요. 전제 조건이 실행을 차단하는 경우 관찰된 프로브와 실행되지 않은 명령을 명확히 구분하고, ID나 요약 내용을 지어내지 않고 정확한 유효 요청, 완료 조건 및 검색 단계를 계속 표시하세요.

관리

curl -s "$HOST/manager/summary" | jq '.[] | {stateId, title}'   # 모두 나열
curl -s -X DELETE "$HOST/manager/summary/$STATE_ID"             # 하나 삭제

VSS 비디오 요약