Configuration¶

캡션 생성 설정 관리

개요¶

동일한 모델, 동일한 비디오라도 config 설정에 따라 완전히 다른 결과가 생성됩니다.

Config가 영향을 주는 요소:

사용할 엔진/모델
Scene detection 방식 (fine-grained vs coarse-grained)
Summarization 설정
기타 사용자 정의 파라미터

Config의 유연성

Config 파일은 사용자가 자유롭게 정의할 수 있습니다.
복잡한 파라미터가 필요하지 않으며, 핵심 설정만 간단히 작성 가능합니다.

VSS 프레임워크 설정 예시¶

VSS 프레임워크 이용 시 아래와 같이 상세한 설정이 가능합니다. 하지만 모든 항목을 복잡하게 구성할 필요는 없으며, 필요한 항목만 선택적으로 사용할 수 있습니다.

Config	Description
prompt	캡션 생성에 사용할 기본 prompt
caption_summarization_prompt	세그먼트별 캡션/ASR 결과를 입력으로 받아 캡션 요약을 만들 때 쓰는 prompt
max_tokens	캡션의 최대 토큰 수 (1-1024)
temperature	캡션의 샘플링 temperature (0-1)
top_p	캡션의 top-p 샘플링 질량 (0-1)
top_k	캡션의 top-k 후보 토큰 수 (1-1000)
summarize_top_p	요약 단계에서의 top-p (0-1)
summarize_temperature	요약 단계에서의 temperature (0-1)
summarize_max_tokens	요약 단계의 최대 토큰 수
enable_audio	오디오 스트림 ASR 활성화 여부
enable_reasoning	추론 모드 활성화 여부
chunk_duration	비디오를 N초 단위로 chunking
chunk_overlap_duration	chunk 간 겹치는 구간(초)
summarize_batch_size	요약 LLM에 한 번에 입력할 batch 크기 (caption_summary 단위)
segment_source	세그먼트 생성 기준 (start/end을 외부에서 지정)

[!TIP] Gemini 예시와 같이 실제로는 매우 간단하게 구성하여 사용할 수 있습니다.

Config 파일 관리¶

저장 위치¶

/gpfs/public/artifacts/feature_store/vss_feature_store/config/
├── gemini_coarse.yaml
├── gemini_fine.yaml
└── custom_config.yaml

Feature Store 연동¶

register_captions 호출 시 config 파라미터로 절대 경로를 입력합니다. 시스템은 해당 파일을 관리 경로(/gpfs/public/artifacts/feature_store/vss_feature_store/config)로 자동 복사하며, Feature Store에는 파일명만 저장됩니다.

# 1. 등록 시: 절대 경로 입력 (자동 복사 발생)
api.register_captions(
    uuid='...',
    model='gemini-2.5-pro',
    config='/gpfs/public/my_configs/gemini_fine.yaml',  # ← 절대 경로 입력
    ...
)

# 2. 조회 시: 저장된 파일명으로 조회
captions = api.get_captions(
    uuid='...',
    model='gemini-2.5-pro',
    config='gemini_fine.yaml'  # ← 파일명만으로 조회
)

자동 복사 메커니즘

입력된 절대 경로의 파일이 관리 디렉토리에 없으면 자동으로 복사됩니다. 이미 존재하는 경우 기존 파일을 사용합니다. 이를 통해 모든 설정 파일이 중앙에서 체계적으로 관리됩니다.

Config 예시¶

gemini_fine.yaml (Fine-grained)¶

세밀한 scene detection

main_engine:
  name: gemini

scene_detection:
  type: fine-grained
  method: gemini-2.5-pro

summarization:
  llm: gemini-2.5-pro

특징: - Fine-grained scene detection - 더 많은 세그먼트 생성 - 세밀한 분석

gemini_coarse.yaml (Coarse-grained)¶

넓은 범위 scene detection

main_engine:
  name: gemini

scene_detection:
  type: coarse-grained
  method: gemini-2.5-pro

summarization:
  llm: gemini-2.5-pro

특징: - Coarse-grained scene detection - 적은 수의 세그먼트 - 고수준 요약

gpt4_custom.yaml (커스텀 설정)¶

사용자 정의 설정 예시

main_engine:
  name: openai
  model: gpt-4o

scene_detection:
  type: fine-grained
  fps: 1

processing:
  max_segments: 50
  overlap: true

output:
  format: detailed

특징: - 사용자가 필요한 파라미터만 정의 - 간단하게 또는 복잡하게 작성 가능

Config 비교 예시¶

동일한 비디오(uuid=abc123), 동일한 모델(gemini-2.5-pro)로 처리했을 때:

Config	Scene Detection	세그먼트 수	특징
gemini_fine	fine-grained	45개	세밀한 분석
gemini_coarse	coarse-grained	15개	고수준 요약

동일 시점, 서로 다른 결과¶

# 2024-12-01 10:00:00에 등록된 2가지 버전
metadata = api.search_metadata(
    uuid='abc123',
    model='gemini-2.5-pro',
    time_after='2024-12-01T09:00:00',
    time_before='2024-12-01T11:00:00'
)

# 출력:
#   config                segment_count
#   gemini_fine.yaml      45
#   gemini_coarse.yaml    15

Config 선택 가이드¶

Fine-grained¶

사용 사례: - 상세한 행동 분석 - 프레임별 변화 추적 - 교육용 콘텐츠

장점: 높은 정밀도
단점: 많은 세그먼트, 긴 처리 시간

Coarse-grained¶

사용 사례: - 영상 전체 요약 - 빠른 프리뷰 - 장면 전환 중심 분석

장점: 빠른 처리, 적은 세그먼트
단점: 세부 정보 손실 가능

Config 등록 및 조회¶

등록 시¶

# Fine config로 등록
result = api.register_captions(
    feature_view='caption_summary',
    uuid='abc123',
    model='gemini-2.5-pro',
    config='gemini_fine.yaml',  # ← 명시
    segments=[...]
)

# Coarse config로 등록 (동일 비디오)
result = api.register_captions(
    feature_view='caption_summary',
    uuid='abc123',
    model='gemini-2.5-pro',
    config='gemini_coarse.yaml',  # ← 다른 config
    segments=[...]
)

조회 시¶

# Fine 버전 조회
captions_fine = api.get_captions(
    feature_view='caption_summary',
    uuid='abc123',
    model='gemini-2.5-pro',
    config='gemini_fine.yaml'
)

# Coarse 버전 조회
captions_coarse = api.get_captions(
    feature_view='caption_summary',
    uuid='abc123',
    model='gemini-2.5-pro',
    config='gemini_coarse.yaml'
)

# 비교
print(f"Fine segments: {len(captions_fine)}")      # 45
print(f"Coarse segments: {len(captions_coarse)}")  # 15

Best Practices¶

1. 명확한 네이밍¶

# 좋은 예
gemini_fine_v2.yaml
gpt4_coarse_2024-12.yaml

# 나쁜 예
config1.yaml
test.yaml

2. Config 버전 관리¶

# Git으로 config 파일 관리
cd /gpfs/public/artifacts/feature_store/vss_feature_store/config/
git init
git add *.yaml
git commit -m "Initial configs"

3. 주석 추가¶

# Gemini Fine-grained Config
# Created: 2024-12-01
# Purpose: Detailed scene-by-scene analysis

main_engine:
  name: gemini
  # 세밀한 분석을 위한 fine-grained 설정

scene_detection:
  type: fine-grained
  method: gemini-2.5-pro

4. Config 문서화¶

각 config 파일에 대한 설명을 별도 README로 관리:

config/
├── gemini_fine.yaml
├── gemini_coarse.yaml
└── README.md  # ← 각 config 설명 및 사용 가이드

주요 포인트¶

중요

Config는 사용자가 자유롭게 정의
간단한 구조도 충분 (3-5개 필드만으로도 가능)
동일 비디오 + 동일 모델이라도 config에 따라 완전히 다른 결과

다음 단계¶

API 레퍼런스 - Config 파라미터 사용법
아키텍처 - Config 저장 구조
시작하기 - Config 적용 예시