TwelveLabs가 몇 번의 API 호출만으로 수시간에 달하는 수동 비디오 주석 작업을 줄이는 방법

소개

비디오 데이터 라벨링은 머신러닝 분야에서 가장 비용이 많이 드는 병목 현상 중 하나입니다. 단 1시간 분량의 영상을 처리하는 데도 4시간의 수동 주석 작업 시간이 필요하며, 도메인 전문가(방사선 전문의, 안전 감사원, 스포츠 분석가 등)의 인건비가 시간당 100달러에 달하는 상황에서는 보관 중인 기존 비디오 자산에 손을 대기도 전에 예산 장벽에 부딪히게 마련입니다.

영상 데이터는 이미 충분히 존재합니다. 대시캠, 매장 내 보안 카메라, 물류창고 피드, 수술 녹화본, 스포츠 경기 중계 등 기업들은 모델 학습에 필요한 핵심 정답 신호가 담긴 수천 시간 분량의 비디오를 보유하고 있습니다. 그러나 원본 영상에서 구조화된 라벨을 도출하기까지의 과정은 여전히 작업자가 프레임별로 일일이 확인하는 라벨ing 플랫폼에 의존하고 있습니다.

이 튜토리얼에서는 전혀 새로운 파이프라인을 구축합니다. 미디어 데이터를 사람에게 직접 전송하는 대신, TwelveLabs의 멀티모달 파운데이션 모델에 즉시 전송합니다. Marengo 모델은 각 비디오를 시각, 오디오 및 문맥적 정보를 포괄하는 512차원의 정밀하고 시간 축이 반영된 임베딩(temporal embeddings)으로 인코딩합니다. 이후 Pegasus 모델이 이 임베딩을 분석 및 추론하여, 엄격한 JSON 스키마 규격에 맞춰 씬 분류, 객체 감지 및 신뢰도 점수가 완벽하게 포함된 구조화되고 타임스탬프가 적용된 주석(annotation) 결과를 반환합니다.

이 튜토리얼을 마칠 때쯤이면 비디오를 인덱싱하고, 커스텀 분류 체계에 따라 학습용 라벨을 자동 생성하며, 데이터셋을 2D 임베딩 공간에서 시각화할 뿐만 아니라 PyTorch나 표준 ML 파이프라인으로 직접 가져갈 수 있도록 COCO, JSON 또는 CSV 형식으로 내보내는 기능까지 갖춘 유기적인 Next.js 애플리케이션을 확보하게 됩니다.

완성된 애플리케이션의 작동 모습은 다음과 같습니다:

아키텍처 개요

코드를 작성하기 전에, 실전용 비디오 주석 작업의 주요 제약 조건을 해결하기 위해 각 레이어별로 신중히 설계된 전체 파이프라인의 아키텍처를 소개합니다.

Next.js 16 + React 19 사양이 프론트엔드 대시보드와 백엔드 API 라우트를 모두 처리합니다. 서버리스 함수를 활용하면 상시 가동되는 서버 없이도 전체 주석 파이프라인을 조율할 수 있으므로, ISV 파트너나 사내 팀이 vercel deploy 단 한 줄의 명령어로 손쉽게 배포를 구성해야 하는 환경에서 매우 유용합니다.

Vercel Blob은 임시 비디오 스토리지를 제공합니다. 서버리스 환경은 업로드 페이로드 크기 제약(Vercel의 경우 4.5 MB 제한)이 엄격하므로, 클라이언트가 비디오 파일을 Blob 스토리지로 직접 업로드한 뒤 생성된 공용 URL만 API 라우트로 전달합니다. 이를 통해 웹 기능 구현 시 파일 용량 제한으로부터 자유로워집니다.

TwelveLabs Marengo는 각 비디오에서 512차원 벡터 임베딩을 추출합니다. 이 데이터는 단순한 프레임 수준의 정적 특징이 아닙니다. Marengo는 시각, 청각 및 시간 경과에 따른 정보들을 유기적인 멀티모달 신호로 연결 처리하여 개별 픽셀 수준이 아닌 실제적인 '의미적 맥락'이 고스란히 담긴 세그먼트 수준의 연속적인 임베딩을 생성합니다. 덕분에 수동 피처 엔지니어링 없이도 다운스트림 군집화 및 시각화를 완벽하게 구현할 수 있습니다.

TwelveLabs Pegasus (Analyze API)는 고성능 추론 엔진의 역할을 수행합니다. 추출된 임베딩과 사용자가 정의한 라벨 분류 체계를 기반으로 Pegasus는 타임스탬프, 씬 분류 데이터, 검출된 객체 정보가 정교하게 포함되어 기계 판독이 가능한 주석을 자동 생성하며, 이는 ML 학습 포맷으로 즉시 매핑할 수 있는 구조화된 JSON 데이터로 제공됩니다.

데이터 프레임의 전체 흐름과 세부 사항은 다음 LucidChart 아키텍처 다이어그램에서 더욱 깊이 있게 확인하실 수 있습니다: [TwelveLabs] - automated Video Data Labeling Solution

1단계: 준비 사항 및 환경 설정

이 프로젝트를 로컬 시스템에서 가동하려면 다음 세 가지가 필요합니다:

• Node.js 18 이상 (20 이상 권장)

• TwelveLabs 대시보드에서 발급받은 TwelveLabs API 키

• 임시 비디오 업로드용 Vercel Blob 토큰

레포지토리를 클론하고 종속성 패키지를 설치합니다:

>> git clone https://github.com/nathanchess/tl-automated-video-data-labeler.git
>> cd tl-automated-video-data-labeler
>> npm

.env.local 파일을 생성하고 환경변수를 설정합니다:

TL_API_KEY=your_twelvelabs_api_key_here
TL_INDEX_NAME=your_default_index_name_here
BLOB_READ_WRITE_TOKEN

npm run dev 명령어로 로컬 개발 서버를 실행하십시오. 이제 대시보드는 http://localhost:3000/indexes 주소에서 사용 가능합니다.

2단계: 비디오 인제스천 및 인덱싱

비디오 인제스천 흐름은 사용자가 대시보드 UI에 비디오 파일을 드롭하면 시작됩니다. 클라이언트는 각 파일을 Vercel Blob에 업로드한 다음, 생성된 공용 URL들을 Next.js API 라우트로 전송하여 TwelveLabs 인덱싱 작업을 요청합니다.

src/app/api/videos/route.js 파일에 구현된 서버 사이드 핵심 로직은 다음과 같습니다:

import { TwelveLabs } from 'twelvelabs-js';
import { NextResponse } from 'next/server';

const tl_client = new TwelveLabs({ apiKey: process.env.TL_API_KEY });

export async function POST(request) {
  const { videoURLs, metadata } = await request.json();

  // 1. 대상 인덱스 탐색
  const indexPager = await tl_client.indexes.list();
  let indexId = null;
  for await (const index of indexPager) {
    if (index.indexName === process.env.TL_INDEX_NAME) indexId = index.id;
  }

  if (!indexId) return NextResponse.json({ error: 'Index not found' }, { status: 404 });

  // 2. 태스크 생성 후 완료 대기
  for (const videoURL of videoURLs) {
    const task = await tl_client.tasks.create({
      indexId,
      videoUrl: videoURL,
      userMetadata: JSON.stringify(metadata),
    });

    const completedTask = await tl_client.tasks.waitForDone(task.id, {
      sleepInterval: 5,
    });

    if (completedTask.status !== 'ready') {
      throw new Error(`Task ${completedTask.id} failed`);
    }
  }

  return new Response('ok');

운영 시 팁: 비디오 처리는 본질적으로 비동기로 작동해야 합니다. 위의 코드 예시에서는 waitForDone 호출을 통해 인덱싱이 끝날 때까지 HTTP 요청을 홀딩하게 되며, 이는 몇 개의 소형 클립만 가동하는 테스트 단계에서는 무방합니다. 대규모 또는 시간 분량이 큰 비디오를 지속해서 가동해야 하는 프로덕션 파이프라인의 경우에는 가볍게 TwelveLabs 웹훅을 연동하고, 인덱싱 백그라운드 큐(Inngest, Upstash 등)를 결합하여 처리 완료 소식을 수신하도록 구현하는 것이 좋습니다. SDK는 해당 개발 패턴을 완벽히 지원합니다.

3단계: 임베딩 추출 및 풀링(Pooling)

비디오 인덱싱 처리가 끝나면, 이제 Marengo 임베딩이 포함된 비디오 정보들을 조회합니다. 이 고차원 벡터 데이터는 뒤에서 구현할 데이터 그룹화 및 2D 시각화 구성을 위한 직접적인 토대가 됩니다.

const videoPager = await tl_client.indexes.videos.list(indexId);
  const videos = [];

  for await (const video of videoPager) {
    let embeddings = [];
    try {
      const videoData = await tl_client.indexes.videos.retrieve(indexId, video.id, {
        embeddingOption: ['visual'],
      });

      const segments = videoData.embedding?.videoEmbedding?.segments || [];
      if (segments.length > 0) {
        const dim = segments[0].float?.length;
        if (dim) {
          const sum = new Array(dim).fill(0);
          let count = 0;

          // 전체 시간 정보 세그먼트에 대해 임베딩의 평균치 계산 (Mean Pooling)
          for (const seg of segments) {
            if (seg.float && seg.float.length === dim) {
              for (let i = 0; i < dim; i++) sum[i] += seg.float[i];
              count++;
            }
          }
          if (count > 0) embeddings = sum.map((val) => val / count);
        }
      }
    } catch (embErr) {
      console.warn(`Failed to get embeddings for ${video.id}`);
    }
    videos.push({ ...video, embeddings });
  }

왜 평균 풀링(Mean Pooling)을 적용할까요? Marengo는 시간에 흐름에 따라 매핑된 시간 기반 세그먼트 임베딩 시퀀스를 출력합니다 (예: 0~5초 세그먼트용 임베딩, 5~10초용 임베딩 등). 이 정밀한 시간대별 정보는 '특정 구역에 지게차가 진입하는 순간'과 같이 아주 세세한 비디오 타겟 검색 시 매우 유용합니다. 하지만 한 편의 전체 비디오를 2D 산점도 위의 단일 점으로 표현해 시각화하려면 하나의 대표 벡터가 필요합니다.

평균 풀링(전체 세그먼트 임베딩들의 Float 어레이 값 평균 계산)을 실행하면, 전체 영상의 포괄적인 맥락을 대표하는 고도화된 하나의 벡터가 완성됩니다. 원본 비디오가 주로 창고 내 지게차 운행을 찍은 영상이라면, 특정한 5초 구간에서 어떤 행동이 일어났든 상관없이 평균값 벡터는 임베딩 공간 내의 "지게차 작업" 영역 군집으로 완벽히 수렴하게 됩니다.

4단계: Pegasus 기반의 제로샷(Zero-Shot) 자동 라벨링

다목적 초거대언어모델(LLM)을 비디오 주석 작업에 연동할 때 직면하는 구조적 난제는 일관성 없는 '출력 포맷'입니다. 범용 언어모델은 수필처럼 긴 줄글 텍스트를 내놓기 때문에, 개발자들은 이 텍스트 단편 속에서 타임스탬프, 라벨, 정확도 수치를 파싱하기 위해 매우 비효율적이고 깨지기 쉬운 정규 표현식 모듈을 설계해야 합니다. 형식 포맷이 단 한 곳이라도 어긋나면 파서 전체가 충돌을 일으키기 마련입니다.

TwelveLabs Analyze API는 Pegasus가 응답할 JSON 출력 형식을 엄격하고 정확하게 사전 규정함으로써 이 핵심 고충을 완전히 상쇄합니다. ML 학습 파이프라인 규격에 부합하는 출력 키 값을 설정하고, 유저가 지정한 커스텀 분류 체계(예: shoplifting, forklift_violation, surgical_clamp)를 프롬프트 구조에 담아 호출하면, 사후 번거로운 파싱 작업이 일절 필요 없는 깔끔한 구조의 JSON 주석 데이터를 수령하게 됩니다.

const response_format = {
    type: 'json_schema',
    json_schema: {
      type: 'object',
      properties: {
        annotations: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              start_timestamp: { type: 'string' },
              end_timestamp: { type: 'string' },
              description: { type: 'string' },
              scene_classification: { type: 'string' },
              detected_objects: {
                type: 'array',
                items: {
                  type: 'object',
                  properties: {
                    label: { type: 'string' },
                    confidence_score: { type: 'number' },
                    start_timestamp: { type: 'string' },
                    end_timestamp: { type: 'string' },
                  },
                },
              },
            },
            required: ['start_timestamp', 'end_timestamp', 'description', 'scene_classification', 'detected_objects'],
          },
        },
      },
    },
  };

이 가이드대로 스키마를 구성하면, 모든 결과물의 출력 형식이 정확한 타임스탬프 범위, 정교한 맥락 서술, 정밀하게 식별된 씬 분류 라벨, 그리고 각각의 자체 신뢰성 스코어 값이 달린 감지 객체들이 완전한 결합 구조의 JSON으로 보증됩니다. 우수한 제로샷(Zero-shot) 추론 능력을 지닌 Pegasus이기에, 미세조정(Fine-Tuning) 단계를 건너뛰고도 오직 스키마 설계와 분류 체계 정의만으로 실시간 시맨틱 분석 결과를 초 단위의 학습용 라벨로 고스란히 이끌어낼 수 있습니다.

5단계: PCA 분석을 적용한 인터랙티브 임베딩 시각화

정렬된 원시 수치들과 라벨 정보 목록은 머신러닝 프로세스 자체에 필수적이지만, 이를 기획 및 정제하는 핵심 프로세스 단에서는 데이터 자체를 직접 비주얼로 확인하는 일이 필요합니다. 본 애플리케이션은 Marengo가 연산해낸 512차원 밀집 임베딩들을 PCA(주성분 분석, Principal Component Analysis) 원리를 이용하여 브라우저 내에서 즉각 2차원 평면의 차트 형태로 시각화하는 모듈을 내포하고 있습니다.

이용자의 브라우저 성능에 알맞게 최적화된 PCA 연산 기법

고차원 전자기 공간 내 벡터 데이터를 직접 투영해 PCA 연산을 완전하게 실행하는 일은 막대한 컴퓨팅 파워를 요구합니다. 가장 고전적인 접근 방식(512 × 512 크기 공분산 행렬 생성 후 Singularity Value Decomposition 방식을 돌려 고윳값을 구하는 과정)을 자바스크립트 프론트 단에서 돌려버리면 즉각 브라우저가 응답 실패 상태로 정지해버릴 수 있습니다. 사용자가 수십 편의 비디오를 정량 제어하고 있는 실무 상황에서는 즉각적인 피드백이 보장되어야만 하며 로딩 화면 뒤에 멈춰있어서는 곤란합니다.

이를 위해 Gram 행렬 기반 연산 기법을 사용합니다. 512차원의 고차원 변수를 직접 다루는 D × D 행렬 가공을 우회하는 대신, 현재 탑재된 비디오 데이터 개수 크기를 기반으로 데이터 간 유사 관계만 활용하여 N × N 차원으로 연산의 크기를 즉각 축소합니다. 50여 편의 비디오들을 관리하는 상태라면 50 × 50 행렬의 eigenvectors를 연산하는 속도가 512 차원의 전체 영역을 연산하는 것보다 수배 가량 고속으로 완수됩니다. 이는 시간 복잡도를 혁신적으로 낮추며 브라우저의 기본 쓰레드 흐름에 무리 없이 조화로운 인터렉티브 대시보드를 유지시켜 줍니다.

이 시각화 결과가 실제 레이블 작업 품질에 기여하는 차별점: 조밀하고 명확히 분리 분포된 포인트들의 패턴은 설정한 라벨 항목들이 세부 맥락 관점에서 얼마나 일관성 있게 분산 및 정제되었는지를 직관적으로 보여줍니다. 중심 군집 영역에서 멀리 벗어난 위치의 데이터들은 '일반적인 흐름에서 탈피한 변동 사건'(물류 창고 프로세스 중 우발적이고 특이한 사고 발생 상황 등)을 명확하게 드러내 주거나, 혹은 라벨 분류 과정에서 맥락이 혼재되어 정제해야 하는 노이즈 파트임을 사전 예고해 줍니다. 데이터 관리자와 실무팀은 대단위 학습 프로세스라는 고액의 컴퓨터 리소스를 낭비하기 전에 데이터셋의 물리적 건전성을 즉각 교정할 수 있게 됩니다.

6단계: 머신러닝 학습 모델 포맷으로의 원클릭 내보내기

완벽히 정제된 고품질 비디오 데이터라 할지라도 학습 인프라와의 연동 호환성이 확보되지 않는다면 무용지물입니다. 본 대시보드 시스템은 아래의 3가지 범용 학습용 데이터 내보내기 포맷을 준비하고 있습니다:

1. JSON: 기업 또는 개발팀이 개별적으로 빌드한 타겟 데이터 로더를 통해 즉각 기계 파싱할 수 있게 구조화된 로우 데이터를 전달합니다. 신뢰 수치 및 세부 세그먼트 타임스탬프 정보 등 Pegasus로부터 획득한 모든 메타데이터들의 계층 관계가 선명하게 완존 보존됩니다.

2. CSV: 다차원 데이터셋을 정량 관점이나 수동 검수 목적, 혹은 pandas 라이브러리로 제어하는 가공 스크립트에 곧장 인계할 수 있게 행렬 레이아웃 형태로 일목요연해진 텍스트 테이블 데이터를 제공합니다.

3. COCO (Common Objects in Context): AI 컴퓨터 비전 영역의 전 세계적 표준인 COCO 표준에 부합하도록 videos, annotations, categories 영역의 고유 속성 구조를 자동으로 갖춰 제공합니다. PyTorch 라이브러리가 직접 소화 가능한 사양일 뿐 아니라 Label Studio나 CVAT 등의 어노테이션 전문 툴로 옮겨 사람이 직접 검토하는 최종 단계(Human-in-the-loop)의 입력 데이터로 완벽하게 대입됩니다.

COCO 형식을 기본 지원하는 기능은 큰 부가가치를 내포합니다. 파이프라인에서 수동 레이블 처리를 마친 영상들을 수십 번에 걸쳐 재포맷 코딩을 수정하며 파편화되는 비효율을 완벽히 제거하기 때문입니다. 비디오 원본 수급부터 벡터 임베딩 수집, 고속 라벨 구성, 학습 적용용 파트로 향하는 선순환 데이터 처리가 이 하나의 툴 안에서 모두 매끄럽게 연결됩니다.

달라진 비즈니스 임팩트 가치

일반 머신러닝 개발 및 비전 연구 조직의 이점

새롭게 개편된 혁신 파이프라인 덕분에 더는 물리적 수동 노동 비중이 학습 비용의 절대치를 채우지 않습니다:

• 기존의 고전적 매뉴얼 파이프라인: 비디오 1시간 분량을 검수하는데 도메인 전문가 등 숙련 노동력이 2~4시간 투입되며, 시간당 50~100달러 선의 높은 비용이 지출되었습니다. 대략 500시간의 미가공 저장 비디오들을 가공하려면 최고 2,000시간 상당의 장기적 라벨 작업과 막대한 인건비에 더해 최소 반년 이상의 전임 투입 기간이 요구됩니다.

• TwelveLabs 자동화 파이프라인: TwelveLabs 인덱싱과 자동 해석 프로세스를 가동하면 비디오당 단 수분 내외의 고속 클라우드 작동만으로 완전하게 구조화된 타임스탬프 주석 및 라벨 틀을 완성해 내며 작업자는 최적의 교정 검토 작업만 집중 전념하면 됩니다. 500시간 분량의 영상 자산 축적 데이터셋 파이프를 수개월이 아닌 단 며칠 이내에 빌드할 수 있습니다.

전문 인력은 핵심 최종 퀄리티 통제 영역(QA)에 집중 투입되며, 가장 소모적이고 비싼 과정인 '장시간의 비디오 러닝 타임 중에서 의미가 유효한 단 수초 가량의 조각을 색출해 내는 과정'은 TwelveLabs 비전 모델들이 고속으로 대신 보조하게 됩니다. 이전에는 처리 비용 압박으로 버려지던 아카이브 속의 레거시 영상 자산들을 극도로 저성능 저비용 상태에서 온전히 학습에 활용하기 좋아집니다.

데이터 어노테이션 전문 SaaS 서비스 및 ISV 도메인의 이점

본 예시 애플리케이션 프레임워크는 확실한 성공을 향하는 서비스 모델의 선구안입니다. 고객용 서비스 플랫폼 제품군 내에 비디오 중심의 AI 오토 어노테이션을 장착함으로써, 실제 투입되는 어노테이션 공수를 최대 80~90% 이상으로 감소시키는 고효율 시너지를 창출해 내기 때문입니다. 이는 비즈니스의 부가가치를 단순 인간 노동 시간 기반의 하청 형태에서 고부가가치의 하이 밸류 서비스 지능형 소프트웨어 모델로 전환시킬 수 있습니다. 레이블링 노동의 형태가 범용화(Commoditized)되는 추세 내에서 유일한 경쟁력을 만들어가는 비결입니다.

마치며

본 오픈 레퍼런스 애플리케이션은 TwelveLabs 비디오 이해 API의 진면모를 활용해 날것의 미공개 비디오 데이터를 인공지능용 학습 준비 상태의 정제된 골격 데이터셋으로 파이프라인화하는 풀 스택 모형을 실증합니다. Marengo 엔진이 영상 신호를 다차원 시간대 임베딩으로 인코딩하고, Pegasus 모델이 타임스탬프와 정교한 스키마 기반의 라벨 정보로 탈바꿈해 냅니다. 브라우저 기반으로 고안된 대시보드를 통하면 복잡한 항시 가동 백엔드 구조 없이도 데이터 확보, 추출 및 내보내기를 막힘없이 통제하기 편합니다.

이 튜토리얼을 통해 얻을 수 있는 실제적인 결과물: 당장 여러분 조직의 자체 비디오들을 끌어와 타겟 라벨 구조를 설계하고 인덱싱 완료 시간을 누림과 동시에 곧장 쓰일 수 있는 고도화된 머신러닝용 데이터셋 완성본을 확보할 수 있는 활성화된 애플리케이션입니다.

모든 전체 가이드 소스 코드는 GitHub 상에 오픈소스로 공개 중입니다. 가볍게 복사 인스턴스를 빌드하고 TwelveLabs 계정 인덱스를 입력하여 세상에 가치를 더할 차세대 학습 시스템을 가동해보십시오.

소스 코드 확보하러 가기 →

실시간 작동 데모 경험하기 →

TwelveLabs 컴퓨터 비전 엔진 API를 사용해 구현해 볼 수 있는 다채로운 혁신 가능성을 한층 깊이 확인해보시려면, 언제든 공식 개발자 가이드 문서를 상세 검토해보시거나 저희 개발 자문 전문 팀을 찾아 문의주시기 바랍니다.

관련 추천 리소스

• TwelveLabs 기술 연동 가이드

• GitHub 리포지토리 (프로젝트 소스 코드)

• 전체 구현 튜토리얼 가이드 영상 (YouTube 채널)

• 전체 작동 설계 아키텍처 다이어그램 (LucidChart)