← 개발 로그 목록

LearningCollector: Gemini 일일 한도 초과 시 Claude Pro 폴백 및 AI 학습 초안 분리 기능 구현

/ 9분 분량 / 개발 로그
#개발#PR#코드리뷰

안녕하세요! 이번 PR은 LearningCollector 프로젝트에서 AI 기능을 더욱 강력하고 안정적으로 만들기 위한 개선 사항들을 담고 있습니다. Gemini API의 일일 한도 초과 문제를 해결하고, AI 학습 기록에서 여러 주제가 섞여 있을 때 이를 효과적으로 분리하여 처리하는 기능이 추가되었습니다.

요약

이번 Pull Request는 Gemini API의 일일 사용량 제한을 극복하기 위해 Claude Pro 구독 기반의 Claude CLI를 폴백(Fallback) 방식으로 연동하는 기능과, AI 학습 기록을 분석하여 여러 개의 학습 주제로 분리해 각각 별도의 포스팅으로 생성하는 기능을 구현했습니다. 이를 통해 AI 기반의 초안 생성 과정이 더욱 안정적이고 유연해졌으며, 학습 기록의 활용도를 높일 수 있게 되었습니다. PR은 2026-07-17T15:46:21Z에 master 브랜치로 성공적으로 병합되었습니다.

배경 및 목적

기존에는 Gemini API를 주로 사용하여 학습 기록, 코드 진척 상황, PR 리뷰 요약 등의 초안을 생성했습니다. 하지만 Gemini API의 무료 사용량에는 일일 한도가 존재하여, 한도를 초과할 경우 더 이상 초안 생성이 불가능해지는 문제가 있었습니다. 또한, AI와 나눈 대화 기록을 학습용으로 저장할 때, 하나의 대화 안에 여러 개의 독립적인 학습 주제가 섞여 있을 경우 이를 하나로 뭉뚱그려 처리하게 되어 정보의 분리 및 활용에 어려움이 있었습니다.

이 PR은 이러한 문제들을 해결하기 위해 다음과 같은 목적을 가집니다:

  • Gemini API 한도 초과 문제 해결: 일일 사용량을 초과했을 때, Claude Pro 구독 기반의 Claude CLI를 사용하여 초안 생성을 계속 이어갈 수 있도록 폴백 메커니즘을 구축합니다.
  • AI 학습 기록의 주제별 분리: AI와의 대화 기록에서 여러 학습 주제가 혼재되어 있을 경우, 이를 자동으로 분리하여 각각 별도의 포스팅으로 생성할 수 있도록 합니다.
  • 병렬 처리 성능 향상: 여러 학습/생성 작업을 효율적으로 처리하기 위해 병렬 워커 풀을 도입하고, AI 클라이언트 간의 상태 공유를 강화합니다.

구현 내용

이번 PR에서는 주로 api/ai_client.py, api/claude_code_client.py, core/gemini_draft_generator.py 파일에서 주요 변경이 이루어졌습니다.

1. Gemini API 한도 초과 시 Claude CLI 폴백 (api/ai_client.py, api/claude_code_client.py)

  • api/ai_client.py:

    • AIClient 클래스가 Gemini와 더불어 ClaudeCodeClient 인스턴스를 가지게 되었습니다.
    • gemini_exhausted_flag라는 SharedFlag 객체를 도입하여, 병렬 워커 중 한 곳에서 Gemini의 일일 한도 초과를 감지하면 다른 워커들도 Gemini 사용을 즉시 중단하고 Claude CLI로 폴백하도록 상태를 공유합니다.
    • generate_draft 메서드는 먼저 Gemini를 시도하고, Gemini 사용이 불가능하거나 영구적인 오류가 발생하면 ClaudeCodeClient를 사용하여 초안을 생성합니다.
    • split_topics 메서드 또한 Gemini 우선, 실패 시 Claude CLI로 폴백하도록 수정되었습니다.

  • api/claude_code_client.py:

    • ClaudeCodeClient 클래스가 새로 추가되었습니다. 이 클래스는 claude CLI 명령어를 영속 프로세스로 실행하며, CLAUDE_CODE_OAUTH_TOKEN 환경변수에 설정된 Claude Pro 토큰을 사용하여 인증합니다.
    • 대화 맥락이 섞이지 않도록 /clear 명령어를 사용하여 매 호출마다 세션을 초기화합니다.
    • generate_draft 메서드는 Claude CLI를 통해 초안을 생성하며, 타임아웃, EOF, 사용량 한도 초과 등 다양한 오류 상황을 처리합니다. SYSTEM_PROMPT를 재정의하여 불필요한 도구 호출이나 메모리 접근 시도를 방지합니다.

2. AI 학습 기록 주제 분리 (core/gemini_draft_generator.py, api/ai_client.py)

  • core/gemini_draft_generator.py:

    • generate_drafts 메서드에서 AI 대화 학습 초안 생성 로직(_generate_study_drafts_parallel)이 크게 수정되었습니다.
    • 기존에는 단일 요청으로 초안을 생성했다면, 이제는 _split_into_segments 함수를 통해 대화 내용을 학습 주제별로 분리합니다.
    • 분리된 각 주제는 (연재 N/M) 형식의 제목과 함께 별도의 포스팅으로 생성되며, _mark_as_series_part 함수가 이를 처리합니다.
    • 병렬 워커 풀(DEFAULT_PARALLEL_WORKERS)을 사용하여 여러 항목을 동시에 처리하는 구조로 변경되었습니다.

  • api/ai_client.py:

    • split_topics 메서드가 추가되었습니다. 이 메서드는 대화_주제_분리_프롬프트.md를 사용하여 대화 내용을 분석하고, 각 주제의 시작 줄 번호와 제목을 JSON 형식으로 반환합니다.
    • 이 기능은 Gemini 우선으로 작동하며, Gemini가 실패할 경우 Claude CLI로 폴백하여 주제 분리를 시도합니다.

3. 병렬 처리 및 전반적인 개선 (core/gemini_draft_generator.py, api/gemini_client.py, policies/storage/draft_saver.py)

  • core/gemini_draft_generator.py:

    • GeminiDraftGenerator 클래스에 max_workers 속성과 AIClient 인스턴스 풀(self.ai_clients)이 도입되었습니다.
    • 각 카테고리별 초안 생성 함수(_generate_baekjoon_drafts 등)는 이제 _generate_drafts_parallel 함수를 통해 병렬로 실행됩니다.
    • SharedFlag 객체를 사용하여 Gemini API의 일일 한도 초과 상태를 모든 워커가 공유하게 하여 효율성을 높였습니다.
    • _print 메서드를 추가하여 여러 스레드에서 동시에 출력해도 메시지가 꼬이지 않도록 했습니다.

  • api/gemini_client.py:

    • generate_draft 메서드가 model 및 max_output_tokens 인자를 받도록 수정되었습니다.
    • _estimate_max_output_tokens 함수가 추가되어, 입력 프롬프트 길이에 따라 동적으로 출력 토큰 한도를 설정합니다. 또한, thinking_budget=0으로 설정하여 내부 추론에 사용되는 토큰을 최소화하고 실제 출력에 더 많은 토큰을 할당합니다.

  • policies/storage/draft_saver.py:

    • save_draft 함수에 part 인자가 추가되어, AI 학습 기록처럼 여러 포스팅으로 분리될 경우 _partN 접미사를 파일명에 붙여 저장할 수 있게 되었습니다.
    • is_duplicate_draft 함수도 _partN이 포함된 파일명 패턴을 인식하도록 수정되어, 분리된 포스팅들이 중복으로 간주되지 않도록 개선되었습니다.

배운 점 및 개선점

이번 PR을 통해 OpenAI API처럼 Gemini API에도 일일 한도가 존재하며, 이를 우회하기 위한 폴백 전략의 중요성을 다시 한번 느꼈습니다. 또한, 단순히 API 호출에 성공하는 것뿐만 아니라, AI 모델이 실제로 원하는 결과물(초안, 주제 분리 등)을 제대로 생성하는지에 대한 깊이 있는 이해가 필요함을 깨달았습니다.

특히, AI 대화 주제 분리 기능은 하나의 대화에서 파생될 수 있는 여러 학습 인사이트를 놓치지 않고 개별적으로 관리할 수 있게 해주어 매우 유용하다고 생각합니다.

향후 개선할 점으로는 다음과 같은 것들이 있습니다.

  • Claude CLI의 안정성 강화: 현재 claude CLI는 간혹 프로세스가 죽는 경우가 발생하는데, 이에 대한 보다 견고한 재시도 및 복구 로직을 추가할 수 있습니다.
  • AI 모델 선택 최적화: 현재는 gemini-2.5-flash와 gemini-2.5-flash-lite를 주로 사용하는데, 특정 작업(예: 복잡한 코드 설명)에는 더 고성능 모델이 필요할 수 있습니다. 각 작업에 최적화된 모델을 동적으로 선택하는 로직을 고려해볼 수 있습니다.
  • 오류 로깅 상세화: API 호출 시 발생하는 다양한 오류 메시지를 더 세밀하게 분류하고 로깅하여, 문제 발생 시 근본 원인을 빠르게 파악할 수 있도록 개선할 필요가 있습니다.

태그

LearningCollector, Gemini, ClaudeCLI, AI폴백, 주제분리