구글 제미니(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를 사용하여 음성 및 텍스트 입력을 처리하고, 멀티턴 대화를 구현하는 방법을 설명한다. 기존 챗봇 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 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은 서버리스(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 활성 유지
이러한 설정을 통해 텔레그램 봇은 안정적이고 효율적인 서버리스 환경에서 운영될 수 있다.
텔레그램 봇은 텍스트 및 음성 메시지를 처리하기 위해 두 개의 핸들러(Handler)를 사용한다. 각 핸들러는 메시지 유형에 따라 적절한 동작을 수행하며, 제미니(Gemini) API를 호출하여 응답을 생성한다.
텍스트 핸들러: 텍스트 메시지를 받아 제미니(Gemini) API에 전송, 텍스트 및 음성 응답 전송
음성 핸들러: 음성 메시지를 다운로드하여 제미니(Gemini) API에 전송, 텍스트 및 음성 응답 전송
예외 처리: TTS 실패 시 로깅(Logging)을 통해 문제 발생 시점 파악
이러한 핸들러 구조는 봇의 유연성(Flexibility)과 확장성(Scalability)을 높이며, 다양한 입력 유형에 대응할 수 있도록 한다.