Gemini 웹과 API의 현실: 유튜브 분석 구현 Deep Dive

Gemini 웹과 API의 현실: 유튜브 분석 구현 Deep Dive

1. 기대와 첫 번째 벽 - API와 웹의 차이

Google AI for DevelopersGemini API  |  Google AI for Developers

Gemini API  |  Google AI for Developers

Gemini Developer API 문서 및 API 참조

Google AI for Developers

• 시도: generateContent API에 텍스트 프롬프트와 함께 유튜브 URL을 전달했습니다.

• 결과: 실패. API는 URL을 '링크'로 인식할 뿐, 해당 URL의 비디오 콘텐츠를 능동적으로 가져와 분석하는 기능은 없었습니다.

• → 제미나이 웹에서는 채팅 내용중에 그냥 링크를 넣으면 자동으로 분석해 주던 것과 다르게, Gemini-flash로 동일한 모델을 쓰더라도, 제공하는 결과가 다르단 것을 알게 되었습니다.

• → Gemini 웹의 유튜브 분석은 Google 내부의 별도 프로세스 및 최적화된 기능을 통해 작동하며, 이는 공개 API의 기본 기능이 아님을 알게 되었습니다

2. 작동은 하지만 실패했던 두 번째 시도 - 멀티모달

Google AI for Developers동영상 이해  |  Gemini API  |  Google AI for Developers

동영상 이해  |  Gemini API  |  Google AI for Developers

Gemini API에서 Gemini의 멀티모달 기능을 사용한 빌드 시작하기

Google AI for Developers

// 초기 실패 코드: GeminiService.ts
async analyzeYoutubeVideo(url: string): Promise<YoutubeTrustAnalysis> {
  // ...
  const response = await this.ai.models.generateContent({
    model: "gemini-1.5-flash",
    contents: [{
      role: "user",
      parts: [
        { text: /* ... (분석 프롬프트) ... */ },
        {
          // "요구사항": 영상 자체(프레임, 오디오)를 분석하라!
          fileData: {
             fileUri: url, // 비디오 URL을 파일 URI로 전달
             mimeType: "video/*",
          },
        },
      ],
    }],
    // ...
  });
  // ...
}

1. 치명적인 응답 속도: 20분짜리 영상 분석에 평균 5분이 소요되었습니다.

2. 사용자 경험(UX) 붕괴: '분석' 버튼을 누르고 5분간 로딩 화면을 봐야 하는 서비스는 아무도 사용하지 않을 것이라고 생각하였습니다.

3. 예측 불가능한 비용: 비디오 프레임 전체를 토큰으로 처리하는 비용은 텍스트 대비 수천 배에 달했습니다.

3. 문제의 재정의 - '픽셀'이 아닌 '의미'를 분석

"사용자가 정말 원하는 것은 영상의 '모든 픽셀'에 대한 분석이 아니고, 유튜브 영상의 '논리적 오류, 편향, 광고성' 등 의미론적인 정보다."

• 발화 내용 (What is said?) → 자막 (Transcript)

• 맥락 정보 (What is the context?) → 메타데이터 (Title, Description 등)

4. 공식 API에 없는 자막 추출하기

Google for DevelopersAPI Reference  |  YouTube Data API  |  Google for Developers

API Reference  |  YouTube Data API  |  Google for Developers

YouTube Data API를 사용하면 YouTube 웹사이트에서 일반적으로 실행되는 기능을 자체 웹사이트나 애플리케이션에 통합할 수 있습니다. 다음 섹션에서는 API를 사용하여 가져올 수 있는 다양한 유형의 리소스를 식별합니다. API는 이러한 리소스를 여러 개 삽입, 업데이트 또는 삭제하는 메서드도 지원합니다.

Google for Developers

async extractTranscript(videoId: string): Promise<VideoTranscript> {
    // 1. 비디오 ID 검증 (Command Injection 방지)
    if (!this.validateVideoId(videoId)) {
      throw new Error("유효하지 않은 비디오 ID입니다.");
    }

    console.log(`📝 자막 추출 시작: ${videoId}`);

    // 임시 디렉토리 경로
    const tmpDir = "/tmp";
    const subtitlePath = `${tmpDir}/${videoId}`;

    try {
      // 2. yt-dlp 명령어 구성 (자막을 파일로 저장)
      const args = [
        "--skip-download",
        "--write-auto-subs",
        "--write-subs",
        "--sub-lang",
        "ko",
        "--sub-format",
        "json3",
        "--output",
        subtitlePath,
        "--no-warnings",
        `https://www.youtube.com/watch?v=${videoId}`,
      ];

      console.log("yt-dlp 실행 중...");

      // 3. execFile 사용
      try {
        await execFileAsync(this.ytDlpPath, args, {
          maxBuffer: 1024 * 2048, // 2MB
          timeout: 30000, // 30초 타임아웃
        });
        console.log("yt-dlp 실행 완료");
      } catch (execError: any) {
        // 부분 실패(exit code 1)는 자막 파일이 하나라도 생성되었으면 OK
        console.warn(
          "yt-dlp 부분 실패 (일부 자막은 성공했을 수 있음):",
          execError.message
        );
      }

      // 4. 생성된 자막 파일 찾기
      const possibleFiles = [
        `${subtitlePath}.ko.json3`,
        `${subtitlePath}.en.json3`,
        `${subtitlePath}.ko-KR.json3`,
        `${subtitlePath}.en-US.json3`,
      ];

      let subtitleFile: string | null = null;
      const fs = await import("fs"); // fs는 async import 권장

      for (const file of possibleFiles) {
        if (fs.existsSync(file)) {
          subtitleFile = file;
          console.log(`자막 파일 발견: ${file}`);
          break;
        }
      }

      if (!subtitleFile) {
        // ... (자막 파일 못찾을 시 에러 처리)
        throw new Error(
          "자막 파일을 찾을 수 없습니다. 이 비디오에는 자막이 없을 수 있습니다."
        );
      }

      // 5. 자막 파일 읽기 및 파싱
      const subtitleContent = fs.readFileSync(subtitleFile, "utf-8");
      const transcriptData = JSON.parse(subtitleContent);

      // 6. 파일 정리 (생략)
      // ...

      // 7. 자막 세그먼트 변환
      const segments: TranscriptSegment[] = [];
      let fullText = "";

      if (transcriptData.events) {
        for (const event of transcriptData.events) {
          if (event.segs) {
            const text = event.segs.map((s: any) => s.utf8 || "").join("");
            if (text.trim()) {
              segments.push({
                text: text.trim(),
                start: event.tStartMs / 1000, // 밀리초 -> 초
                duration: (event.dDurationMs || 0) / 1000,
              });
              fullText += text.trim() + " ";
            }
          }
        }
      }
      // ... (에러 처리 및 반환)
      return {
        segments,
        fullText: fullText.trim(),
        language: subtitleFile.includes(".ko") ? "ko" : "en",
      };
    } catch (error) {
      // ... (전체 에러 처리)
      throw error;
    }
}

• -skip-download: 영상/오디오 다운로드 없이 텍스트(자막)만 초고속으로 추출. (3분 -> 1~2초)

• -sub-format json3: 타임스탬프가 포함된 구조적 JSON으로 데이터를 받음

• -output: 결과를 임시 파일로 저장하여 exec의 stdout 버퍼 제한을 피하고 안정적으로 처리

5. 출력 형식 오류 문제 해결

Google AI for Developers구조화된 출력  |  Gemini API  |  Google AI for Developers

구조화된 출력  |  Gemini API  |  Google AI for Developers

Gemini API를 사용하여 구조화된 출력을 생성하는 방법 알아보기

Google AI for Developers

// Gemini의 구조화된 출력 시도
const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: /* ... */,
    config: {
      responseMimeType: "application/json",
      responseSchema: { /* ... (복잡한 Criti.AI 스키마) ... */ },
    },
});

// GeminiService.ts - parseYoutubeAnalysisResult()
import { jsonrepair } from 'jsonrepair'; // 핵심 라이브러리

async parseResult(rawResponse: string): Promise<YoutubeTrustAnalysis> {
  try {
    // AI가 만든 json... 마크다운 제거
    const jsonSlice = this.extractJsonObject(rawResponse);

    // 깨진 JSON을 복구
    // 예: { "key": "value", } (후행 쉼표) -> { "key": "value" }
    const repairedJson = jsonrepair(jsonSlice);

    // 안전하게 파싱
    const parsed = JSON.parse(repairedJson);

    // 후처리 (빈 값 필터링 등)
    return this.postProcessHighlights(parsed);
  } catch (error) {
    // ... (에러 처리 및 로깅)
  }
}

엔지니어링의 가치

1. 현상을 넘어 본질을 묻습니다. "느리다"는 현상에 매몰되지 않고, "사용자가 진짜 원하는 것은 픽셀이 아니라 의미"라는 본질을 파고들어 문제를 정의하고 해결할 수 있었습니다.

2. 막히면, 길을 찾습니다. 공식 API가 벽이라고 생각하고 멈추는 것이 아니라, yt-dlp라는 또 다른 방법을 찾아내어 문제를 돌파하는 집요함이 필요합니다.

3. Edge Case에서 완성도가 결정됩니다. JSON.parse()에서 멈추지 않고, jsonrepair로 AI의 실패까지 방어하는 시스템을 구축했을 때 비로소 기능이 완성되었습니다.