텔레그램 봇, 이제 목소리로 대화하세요! (Gemini API)
구글 제미니(Gemini) API를 활용하여 텔레그램 봇(Telegram Bot)에서 음성 메시지 인식 및 응답 기능 구현
파이썬(Python) 기반으로, 텍스트 및 음성 처리를 위한 python-telegram-bot 라이브러리 사용
멀티턴 대화(Multi-turn Conversation)를 위해 제미니(Gemini) API의 Interactions API 활용
텍스트-음성 변환(TTS)을 위해 Gemini 3.1 Flash TTS 모델 사용, OGG/Opus 형식으로 변환
Cloud Run 배포를 위한 도커파일(Dockerfile) 및 배포 가이드 제공, 서버리스(Serverless) 환경 구축
제미니(Gemini) Interactions API의 핵심 원리
본문에서는 제미니(Gemini)의 Interactions API를 사용하여 음성 및 텍스트 입력을 처리하고, 멀티턴 대화를 구현하는 방법을 설명한다. 기존 챗봇 API와 달리, previous_interaction_id를 활용하여 서버 측에서 대화 내역을 관리하므로, 개발자는 전체 대화 내용을 매번 전송할 필요가 없다.
오디오 입력: Base64 인코딩(Base64 Encoding)된 음성 데이터를 텍스트 프롬프트와 함께 전송
멀티턴 대화: 각 응답의 interaction.id를 저장하고, 다음 요청에 previous_interaction_id로 전달
시스템 인스트럭션(System Instruction): 봇의 역할과 응답 스타일을 정의하여 응답 품질(Response Quality) 향상
이러한 방식을 통해 개발자는 복잡한 대화 관리 로직을 직접 구현할 필요 없이, 간결하고 효율적인 챗봇(Chatbot) 개발이 가능하다.
음성 메시지 처리를 위한 데이터 변환 과정
텔레그램(Telegram) 음성 메시지는 OGG/Opus 형식으로 제공되므로, 제미니(Gemini) API에 직접 전송하여 음성 인식을 수행한다. 텍스트-음성 변환(TTS)의 경우, 제미니(Gemini) TTS 모델은 PCM 오디오를 반환하므로, OGG/Opus 형식으로 변환하는 과정이 필요하다.
PCM 오디오: 24kHz, 16-bit, mono 형식의 raw PCM 데이터
WAV 헤더 추가: pydub 라이브러리를 사용하여 PCM 데이터를 WAV 형식으로 래핑
OGG/Opus 변환: ffmpeg를 사용하여 WAV를 OGG/Opus로 변환
이러한 변환 과정을 통해 텔레그램 봇은 제미니(Gemini) TTS의 음성 응답을 원활하게 재생(Seamless Playback)할 수 있다.
Gemini 3.1 Flash 모델의 장점
본문에서는 챗봇의 성능과 비용 효율성을 위해 Gemini 3.1 Flash Lite 및 Gemini 3.1 Flash TTS 모델을 사용한다. Flash Lite는 텍스트 및 오디오 이해에 사용되며, Flash TTS는 자연스러운 음성 합성을 담당한다.
Flash Lite: 가장 빠르고 저렴한 모델로, 챗봇의 응답 속도(Response Speed) 향상
Flash TTS: 자연스러운 음성(Natural Voice)을 생성하며, 다양한 음성 옵션 제공
모델 분리: 두 개의 모델을 분리하여 각 작업에 최적화된 성능 제공
이러한 모델 분리 아키텍처(Model Separation Architecture)는 챗봇의 전반적인 성능과 사용자 경험을 향상시키는 데 기여한다.
Cloud Run 배포를 위한 설정
본문에서는 텔레그램 봇을 Cloud Run에 배포하기 위한 과정을 상세히 설명한다. Cloud Run은 서버리스(Serverless) 환경을 제공하여, 봇의 자동 확장(Auto-scaling) 및 비용 효율성(Cost-effectiveness)을 보장한다.
도커파일(Dockerfile): ffmpeg 설치 및 봇 실행을 위한 환경 설정
Secret Manager: API 키(API Key)와 텔레그램 토큰(Telegram Token)을 안전하게 관리
IAM 권한 설정: Cloud Build, Cloud Storage, Secret Manager에 대한 서비스 계정 권한 부여
배포 명령어: gcloud CLI를 사용하여 Cloud Run에 배포, --no-cpu-throttling 옵션으로 CPU 활성 유지
이러한 설정을 통해 텔레그램 봇은 안정적이고 효율적인 서버리스 환경에서 운영될 수 있다.
텔레그램 봇(Telegram Bot) 핸들러 구현
텔레그램 봇은 텍스트 및 음성 메시지를 처리하기 위해 두 개의 핸들러(Handler)를 사용한다. 각 핸들러는 메시지 유형에 따라 적절한 동작을 수행하며, 제미니(Gemini) API를 호출하여 응답을 생성한다.
텍스트 핸들러: 텍스트 메시지를 받아 제미니(Gemini) API에 전송, 텍스트 및 음성 응답 전송
음성 핸들러: 음성 메시지를 다운로드하여 제미니(Gemini) API에 전송, 텍스트 및 음성 응답 전송
예외 처리: TTS 실패 시 로깅(Logging)을 통해 문제 발생 시점 파악
이러한 핸들러 구조는 봇의 유연성(Flexibility)과 확장성(Scalability)을 높이며, 다양한 입력 유형에 대응할 수 있도록 한다.
