VS Code에서 Python으로 Gemini API 연동하기 – 설치부터 콘솔 챗봇, 멀티턴 대화까지

VS Code + Python으로 Google Gemini API에 연결해, 터미널 기반 챗봇 만들기

1. 전체 흐름 – 무엇을 만들 것인가?

이 글에서는 VS Code와 Python을 사용해 Google Gemini API에 연결하고, 터미널에서 대화할 수 있는 간단한 챗봇을 만드는 과정을 단계별로 설명합니다. 최종 목표는 다음과 같습니다.

• Google AI Studio에서 Gemini API 키 발급
• VS Code + Python 가상환경 구성
• google-genai SDK 설치 및 기본 텍스트 요청 예제
• Gemini 모델과 멀티턴 대화를 유지하는 콘솔 챗봇 구현
• 코드를 확장해서 “역할 프리셋, 로그 저장, 멀티모달 확장” 등으로 발전시키는 아이디어

2. 사전 준비 – 계정, 키, 개발 환경

시작 전에 다음을 준비해야 합니다.

• Google 계정 – Gmail 계정이면 충분.
• Gemini API 키 – Google AI Studio에서 발급.
• VS Code – 최신 버전 설치.
• Python 3.10 이상 – 터미널에서 python --version 또는 python3 --version으로 확인.
• VS Code Python 확장 – Extensions에서 “Python” 검색 후 Microsoft 제공 확장 설치.

2-1. Gemini API 키 발급

1. 브라우저에서 Google AI Studio 접속: https://aistudio.google.com.
2. 로그인 후 상단 메뉴 또는 우측 상단에서 “Get API key” 혹은 “API Keys” 메뉴로 이동.
3. “Create API key”를 선택 후, “Gemini API”용 키를 생성.
4. 발급된 키를 복사해 안전한 곳에 저장 (한 번만 전체가 보이는 경우가 많음).

Google 공식 문서에서는 이 키를 환경 변수 GEMINI_API_KEY로 설정해 사용할 것을 권장합니다.

2-2. VS Code 프로젝트 & 가상환경 구성

1. 원하는 위치에 새 폴더 생성 예: gemini-vscode-chatbot
2. VS Code에서 해당 폴더를 “폴더 열기”로 연다.
3. VS Code 터미널 열기 (단축키: Ctrl + `).
4. Python 가상환경 생성: 
5. python -m venv venv # 또는 환경에 따라 python3 -m venv venv
6. 가상환경 활성화: 
7. # Windows (PowerShell) venv\Scripts\Activate macOS / Linux source venv/bin/activate

이제 이 프로젝트 안에서 설치하는 라이브러리는 다른 프로젝트와 격리됩니다.

3. Gemini Python SDK 설치 & 환경 변수 설정

3-1. Gemini SDK 설치

Gemini API 공식 문서에서는 google-genai 패키지의 genai 모듈을 사용하도록 안내합니다. 터미널에서 다음을 실행합니다.

pip install --upgrade google-genai

일부 예제는 from google import genai를 사용하며, 위 패키지 설치로 해당 모듈이 제공됩니다.

3-2. API 키 환경 변수 설정

키를 코드에 직접 하드코딩하기보다는 환경 변수로 관리하는 것이 안전합니다.

• Windows (PowerShell)

  $env:GEMINI_API_KEY = "여기에_발급받은_키_입력"

• macOS / Linux (bash/zsh)

  export GEMINI_API_KEY="여기에_발급받은_키_입력"

Gemini API 라이브러리는 GEMINI_API_KEY 또는 GOOGLE_API_KEY 환경 변수에 설정된 값을 자동으로 읽어올 수 있습니다. VS Code를 실행할 때는 이 환경 변수가 설정된 쉘에서 VS Code를 켜면, Python 코드에서 바로 인식됩니다.

4. 가장 단순한 Gemini 텍스트 요청 예제

먼저 “한 번 요청 → 한 번 응답” 구조의 가장 기본 예제를 만들어 봅니다. VS Code에서 simple_gemini_test.py 파일을 만들고 아래 코드를 입력합니다.

from google import genai # 환경 변수 GEMINI_API_KEY에서 자동으로 키를 가져옵니다. # (사전에 OS에서 GEMINI_API_KEY 를 설정했다고 가정) client = genai.Client() # 또는 genai.Client(api_key="직접_키_전달") def main(): response = client.models.generate_content( model="gemini-2.0-flash", # 또는 최신 문서의 추천 모델 ID 사용 contents="Python과 VS Code로 Gemini API를 연동하는 방법을 한 문단으로 설명해줘." ) print("=== Gemini 응답 ===") print(response.text) if __name__ == "__main__": main() 

터미널에서 가상환경이 활성화된 상태로 다음을 실행합니다.

python simple_gemini_test.py

정상적으로 설정되어 있다면, Gemini가 한국어로 한 문단 정도의 설명을 반환하며, response.text에 텍스트가 담겨 출력됩니다.

5. 멀티턴 대화를 지원하는 Gemini 콘솔 챗봇 만들기

이제 VS Code에서 여러 차례 질문하면서 맥락을 유지하는 콘솔 챗봇을 구현합니다. 공식 예제와 여러 튜토리얼은 “채팅 세션” 또는 generate_content 호출에 이전 메시지를 함께 넣는 방식으로 멀티턴 대화를 구성합니다. 여기서는 generate_content에 대화 내용을 리스트로 계속 누적하는 구조로 구현하겠습니다.

5-1. 기본 구조 설계

VS Code에서 gemini_chat.py 파일을 만들고, 아래 코드를 입력합니다.

from google import genai import os from datetime import datetime # 1. 클라이언트 생성 # GEMINI_API_KEY 환경 변수에서 키를 자동으로 읽습니다. client = genai.Client() SYSTEM_PROMPT = ( "당신은 한국어로 대화하는 친절한 AI 어시스턴트입니다. " "답변은 너무 장황하지 않게, 핵심을 중심으로 설명해주세요. " "사용자가 코드를 물어보면 Python 예제를 위주로 보여주세요." ) def format_chat_log_path(): """대화 내용을 파일로 저장하기 위한 로그 파일 경로.""" today = datetime.now().strftime("%Y%m%d") return f"chat_log_{today}.txt" def append_log(role: str, content: str): """대화 내용을 간단히 텍스트 파일에 append.""" path = format_chat_log_path() with open(path, "a", encoding="utf-8") as f: ts = datetime.now().strftime("%Y-%m-%d %H:%M:%S") f.write(f"[{ts}] {role}: {content}\n") def chat_loop(): print("💬 Gemini 콘솔 챗봇을 시작합니다.") print(" /quit 로 종료, /clear 로 대화 리셋\n") # 2. 대화 컨텍스트 초기화 history = [ SYSTEM_PROMPT ] # Google docs 예제에서는 contents에 문자열 또는 Part 리스트를 전달할 수 있습니다. while True: user_input = input("나: ").strip() if user_input == "/quit": print("👋 종료합니다.") break if user_input == "/clear": print("🔄 대화 컨텍스트를 초기화합니다.\n") history = [SYSTEM_PROMPT] continue if not user_input: continue # 3. 사용자 발화 로그 기록 append_log("USER", user_input) # 4. Gemini에 보낼 contents 구성 history.append(f"사용자: {user_input}") prompt = "\n".join(history) try: response = client.models.generate_content( model="gemini-2.0-flash", contents=prompt ) except Exception as e: print(f"[에러] API 호출 중 문제가 발생했습니다: {e}") append_log("ERROR", str(e)) continue # 5. 응답 텍스트 추출 bot_text = response.text print("\n봇:", bot_text, "\n") # 6. 어시스턴트 메시지를 히스토리에 추가 history.append(f"어시스턴트: {bot_text}") # 7. 로그 파일에도 기록 append_log("BOT", bot_text) if __name__ == "__main__": chat_loop() 

5-2. 코드 동작 방식 설명

위 코드의 흐름은 다음과 같습니다.

• client 생성 client = genai.Client()는 GEMINI_API_KEY를 환경 변수에서 자동으로 읽어옵니다. 필요하다면 genai.Client(api_key="...") 형태로 직접 전달할 수도 있습니다.
• history 리스트
  - SYSTEM_PROMPT로 시작해서, "사용자: ...", "어시스턴트: ..." 형태로 문자열을 계속 쌓습니다.
  - 공식 예시는 contents=[...Part...] 구조를 권장하지만, 간단한 텍스트 기반 프로토타입에는 이런 문자열 합치기 패턴도 충분히 동작합니다.
• 프롬프트 생성
  - prompt = "\n".join(history)로 지금까지 대화 전체를 하나의 긴 텍스트로 만들어 generate_content에 전달합니다.
• 명령 처리
  - /quit: 프로그램 종료.
  - /clear: history 리스트를 초기화해서 새로운 대화를 시작.
• 로그 파일
  - 날짜별 파일(chat_log_YYYYMMDD.txt)에 USER / BOT 메시지를 타임스탬프와 함께 저장합니다.

6. VS Code에서 실행·디버깅 팁

VS Code 환경을 활용하면 Python 코드를 더 편하게 실행하고 디버깅할 수 있습니다.

• 실행 버튼 활용
  - gemini_chat.py 상단에 “Run Python File” ▶ 아이콘이 보이면 클릭해서 바로 실행할 수 있습니다.
• Run & Debug 구성
  - 좌측 “Run and Debug” 메뉴 → “create a launch.json” → “Python: Current File” 선택 후, 중단점(breakpoint)을 찍고 한 줄씩 코드 흐름을 확인할 수 있습니다.
• 가상환경 자동 인식
  - VS Code 하단 Status Bar의 Python 인터프리터 선택 메뉴에서 ./venv를 선택하면, 터미널·디버거 모두 해당 가상환경을 사용합니다.

7. 한 단계 더: 코드 개선·확장 아이디어

기본 콘솔 챗봇이 동작했다면, 다음과 같은 방향으로 코드를 발전시켜 볼 수 있습니다.

• 역할 프리셋 지원
  - /mode writer, /mode tutor, /mode coder 같은 명령을 추가해, SYSTEM_PROMPT를 동적으로 변경. - 예: 블로그 글 작성 모드, 프로그래밍 도우미 모드, 영어 회화 코치 모드 등.
• 멀티모달 기능
  - Gemini는 이미지·텍스트를 함께 입력하는 멀티모달을 지원합니다.
  - 예: contents=["Tell me about this instrument", image] 형태로 이미지를 함께 보내 “이 이미지에 뭐가 보이는지 설명해줘” 같은 질의를 처리.
• 스트리밍 응답
  - client.models.generate_content_stream()을 사용하면, 긴 답변을 토큰이 생성되는 대로 한 줄씩 받아와 실시간 출력하는 모드를 만들 수 있습니다. - 사용자가 긴 답을 기다릴 때 UX가 훨씬 좋아집니다.
• 에러 처리·쿼터 관리
  - API 호출 실패 시 재시도, 응답 지연 안내, 남은 사용량·쿼터를 체크하는 코드 등을 추가하면 실무용 프로토타입으로 발전시킬 수 있습니다.
• 간단 웹 UI 붙이기
  - Flask/FastAPI로 HTTP API를 만들고, 프론트엔드(HTML/JS)에서 fetch로 요청하는 구조로 바꾸면, 터미널 대신 브라우저에서 Gemini 챗봇을 사용할 수 있습니다. - VS Code의 Live Server 확장과 함께 쓰면 빠르게 UI를 테스트할 수 있습니다.

8. 마무리 – VS Code + Python + Gemini로 시작하기

정리하면, VS Code와 Python만으로도 Google Gemini API에 간단히 연결해 콘솔 기반 챗봇을 만들 수 있고, 이후에는 멀티모달·스트리밍·웹 UI 등으로 확장해 실제 서비스 형태에 가까운 프로토타입을 만드는 것이 가능합니다.
중요한 포인트는 (1) GEMINI_API_KEY 환경 변수 관리, (2) google.genai.Client 사용법, (3) generate_content에 넘길 컨텍스트를 어떻게 설계할지, 이 세 가지를 이해하는 것입니다. 이 글의 코드 구조를 기본 틀로 삼아, 원하는 역할·도메인에 맞는 Gemini 기반 도구를 한 번 만들어 보셔도 좋습니다.