Chiko IT
AI & Machine Learning

Gemini 2.0 프로토타입 가이드 — Google AI Studio에서 데모 빠르게 만들기

Chiko
13min read

목차

google.genai.errors.ClientError: 400 API key not valid. Please pass a valid API key.

Gemini 2.0 API를 처음 호출하면 높은 확률로 이 에러를 만난다. API 키를 환경변수에 등록해놨는데 왜 안 되는지 한참 헤맸다. 결국 AI Studio에서 키를 재발급하니 바로 해결됐다. 프로젝트 제한이 걸린 키를 복사한 게 원인이었다.

GPU 서버 없이, OpenAI 크레딧도 빠듯한 상황에서 문서 요약 데모를 빠르게 만들어야 했다. 빠르게 쓸 수 있는 대안을 찾다가 Google AI Studio 무료 티어와 Gemini 2.0 Flash 조합이 이 기준을 가장 잘 충족했다. Streamlit 데모까지 하루면 충분하다.

왜 Google AI Studio에서 시작하는가

프로토타입용 LLM API 선택 기준은 단순하다. 무료 티어가 넉넉한지, 셋업이 빠른지, 유료 전환 경로가 명확한지.

Google AI Studio는 이 기준을 대체로 충족한다. 웹 브라우저에서 바로 프롬프트를 테스트할 수 있고, API 키 발급에 신용카드가 필요 없다. OpenAI 플레이그라운드도 프롬프트 테스트는 가능하지만, 무료 크레딧 소진 후에는 결제 수단 등록이 필수다. 프로토타입 단계에서 비용 승인을 받느라 하루 이틀 날리는 경험을 해본 적이 있을 것이다. 그 시간이 아깝다.

Gemini 2.0 Flash의 무료 티어는 분당 15회 요청(RPM), 일 1,500회 요청(RPD) 수준이다 (2026년 4월 기준, Google AI for Developers 요금 페이지 참고). 3일간 개발하면서 rate limit에 한 번도 걸리지 않았다. 프로토타입과 사내 데모 용도라면 무료 범위 안에서 해결 가능하다는 게 직접 확인한 결론이다.

짚어둘 점은, AI Studio API 키는 프로토타이핑용이지 프로덕션용이 아니라는 것이다. SLA도 없고 rate limit도 낮다. 실서비스로 넘어가려면 Vertex AI로 전환해야 하는데, 이건 마지막 섹션에서 다룬다.

API 키 발급과 SDK 설치

이건 간단하다. Google AI Studio에 Google 계정으로 로그인하고, 좌측 "Get API key" → "Create API key"를 누르면 끝이다.

# google-genai SDK 설치 (구 google-generativeai와 다른 패키지)
pip install google-genai

# 환경변수에 API 키 등록
export GEMINI_API_KEY="발급받은_키_값"

Google의 Gemini Python SDK가 두 개 존재한다는 점만 주의하면 된다. 예전 SDK인 google-generativeai와 현재 권장되는 google-genai다. 2025년 하반기부터 공식 문서가 google-genai로 통일됐으니, 새 프로젝트는 이쪽을 쓰자. 둘 다 설치돼 있으면 import 경로가 겹쳐서 혼동이 생길 수 있다. pip uninstall google-generativeai로 구버전을 정리해두는 게 안전하다.

AI Studio 플레이그라운드에서 프롬프트 다듬기

코드부터 짜는 것보다 AI Studio 플레이그라운드에서 프롬프트를 먼저 잡는 게 시간을 크게 아낀다. 코드 레벨에서 프롬프트를 수정하면 스크립트 재실행 → 응답 대기 → 결과 확인 사이클이 반복되지만, 플레이그라운드는 웹에서 바로 결과가 나온다. 체감상 반복 테스트 속도가 3배 이상 빨랐다.

모델 선택

플레이그라운드 우측 패널에서 모델을 고른다. 프로토타입이라면 Gemini 2.0 Flash가 무난하다.

모델 응답 속도 (체감) 무료 RPM 적합한 용도
Gemini 2.0 Flash 1~2초 15 범용 프로토타입
Gemini 2.0 Flash Lite 1초 미만 30 단순 분류, 키워드 추출
Gemini 2.0 Pro 3~5초 2 복잡한 추론, 긴 문맥 처리

Flash Lite는 가볍고 빠르지만, 긴 문서 요약에서 품질이 눈에 띄게 떨어졌다. 핵심 포인트를 2개 정도 빠뜨리는 식이다. Pro는 품질은 좋은데 무료 RPM이 2라서 데모 시연 중 여러 사람이 동시에 요청을 보내면 곧바로 429가 뜬다. 결국 Flash가 속도와 품질의 균형점이었다.

시스템 프롬프트 세팅

"System instructions" 칸에 역할과 출력 형식을 명시한다. 내가 문서 요약 프로토타입에서 사용한 시스템 프롬프트는 이렇다:

당신은 사내 기술 문서 요약 도우미입니다.
- 입력: 기술 문서 원문 (한국어 또는 영어)
- 출력 형식: JSON
  - summary: 3문장 이내 요약
  - key_points: 핵심 포인트 3~5개 (배열)
  - action_items: 후속 조치 항목 (배열, 없으면 빈 배열)
마크다운 래핑이나 부가 설명 없이 JSON만 출력하세요.

이 프롬프트로 실제 사내 문서 10건을 테스트했다. 처음에는 JSON 앞에 "다음은 요약 결과입니다:" 같은 문구를 붙이는 경우가 있었다. 마지막 줄에 "JSON만 출력하세요"를 추가하니 거의 사라졌다. 이런 미세 조정이 플레이그라운드에서는 30초면 끝나지만, 코드에서 하면 매번 파일 저장하고 다시 실행해야 돼서 리듬이 끊긴다.

temperature도 여기서 잡아두는 게 좋다. 요약처럼 사실 기반 태스크는 0.2~0.4로 낮추면 출력 일관성이 올라간다. 기본값(1.0)으로 두면 같은 문서를 넣어도 매번 다른 구조의 JSON이 나와서 프론트엔드 파싱이 불안정해진다.

"Get code"로 코드 추출

프롬프트가 확정되면 우측 상단 "Get code"를 누른다. Python, JavaScript, REST curl 중 원하는 형태로 변환된 코드를 바로 받을 수 있다. 복사해서 프로젝트에 붙여넣기만 하면 되니 SDK 문서를 처음부터 읽을 필요가 줄어든다. 이 기능 덕에 첫 셋업에서 체감상 30분은 줄였다.

Python SDK로 Gemini 2.0 호출하기

기본 호출

플레이그라운드에서 "Get code"로 뽑은 코드를 기반으로 시작한다. 기본 구조는 이렇게 생겼다:

import os
from google import genai

# 환경변수에서 API 키 로드
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

# 텍스트 생성 요청
response = client.models.generate_content(
    model="gemini-2.0-flash",  # 모델명 지정
    contents="이 문장을 한 줄로 요약해줘: [문서 내용]"
)
print(response.text)

여기까지는 5분이면 끝난다. 별다른 설정 없이 API 키와 모델명만 맞추면 응답이 온다.

구조화된 출력 — JSON 모드

실제로 시간을 잡아먹은 건 JSON 응답을 안정적으로 받는 부분이었다. 프롬프트에 "JSON으로 출력해"라고만 쓰면, 모델이 ```json ``` 마크다운 블록으로 감싸거나 앞뒤에 설명 텍스트를 붙인다. json.loads()가 터지는 거다.

처음에는 정규식으로 JSON 부분만 잘라내려고 했다. 방향이 잘못됐다는 걸 깨닫는 데 20분쯤 걸렸다. GenerateContentConfig에 response_mime_type을 지정하면 깔끔하게 해결된다.

import os, json
from google import genai
from google.genai import types

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="다음 문서를 요약해줘: [문서 내용]",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",  # JSON 출력 강제
        temperature=0.3,  # 요약은 낮은 temperature가 안정적
        system_instruction="summary, key_points, action_items 키로 JSON 반환"
    )
)

result = json.loads(response.text)  # 파싱 실패 없음
print(result["summary"])

response_mime_type="application/json"을 넣으면 마크다운 래핑 없이 순수 JSON만 내려온다. 공식 문서에 설명은 있지만 실제 코드 예제가 부실해서 처음 찾기가 어려웠다 (출처: Gemini API Structured Output 문서, 2026년 3월 기준).

response_schema 파라미터에 Pydantic 모델이나 JSON 스키마를 넘기면 필드 구조를 더 엄격하게 강제할 수 있다. 다만 스키마가 복잡해지면 모델이 필드를 누락하는 경우가 간헐적으로 발생했다. 프로토타입에서는 response_mime_type만으로 충분하고, 스키마 검증은 실서비스 전환 시점에 도입하는 게 현실적이다.

스트리밍 응답

데모에서 사용자 경험을 신경 쓴다면 스트리밍을 고려할 만하다. generate_content 대신 generate_content_stream으로 바꾸면 토큰 단위로 응답이 내려온다. 첫 글자가 화면에 뜨기까지의 체감 대기 시간이 크게 줄어든다. Streamlit에서 st.write_stream과 연동했더니 PM 반응이 "이거 실시간 느낌 나네"였다. 코드 변경은 메서드명 하나 바꾸는 수준이라 비용 대비 효과가 좋다.

Gemini 2.0 API에서 자주 만나는 에러

3일간 프로토타입을 만들면서 반복적으로 만난 에러 세 가지를 정리한다. 검색하면 나오는 정보이긴 한데, 어떤 상황에서 발생하는지까지는 잘 안 나와 있어서 적어둔다.

첫 번째, API 키 관련 400/403 에러. 가장 흔하다. AI Studio에서 키를 발급할 때 "기존 Google Cloud 프로젝트에 연결"과 "새 프로젝트 생성" 두 가지 옵션이 나온다. 기존 프로젝트에 Generative Language API가 활성화되어 있지 않으면, 키는 정상 발급되지만 호출 시 403이 뜬다. 새 프로젝트로 키를 발급하면 API가 자동으로 활성화되니 프로토타입 단계에서는 이쪽이 안전하다.

두 번째, 429 Resource Exhausted. 무료 티어 RPM 한도에 도달하면 나타난다. Flash 기준 분당 15회인데, for문 안에서 API를 연속 호출하면 10초 만에 닿는다. 가장 간단한 우회법은 요청 사이에 time.sleep(4)를 넣는 것이다. 지수 백오프(exponential backoff)를 구현해도 되지만, 프로토타입 수준에서 거기까지는 과하다고 본다. 배치 처리가 필요하다면 요청 큐를 만들어 RPM 범위 안에서 돌리는 편이 낫다.

세 번째, 응답이 빈 문자열로 돌아오는 경우. response.text가 빈 스트링이라 json.loads()에서 에러가 터지는데, 이건 안전 필터(safety filter)에 걸린 거다. response.candidates[0].finish_reason을 확인하면 SAFETY로 찍혀 있다. 사내 문서에 보안 관련 키워드가 포함됐을 때 이런 일이 생겼다. safety_settings로 필터 수준을 조정할 수 있는데, 이 부분은 아직 깊게 테스트해보지 못해서 확실한 가이드를 주기 어렵다.

실서비스 전환 시 확인할 것

프로토타입 데모가 통과하면 "이거 서비스에 넣자"는 이야기가 나온다. 그 전에 확인해야 할 항목이 있다.

AI Studio의 무료 API 키는 프로덕션용이 아니다. rate limit이 낮고 SLA가 없어서, 트래픽이 조금만 몰려도 429가 발생한다. 실서비스에서는 Google Cloud의 Vertex AI를 통해 Gemini API를 호출하는 구조로 전환해야 한다. SDK는 google-genai를 그대로 쓸 수 있고, 클라이언트 초기화 부분만 바뀐다. genai.Client(api_key=...) 대신 genai.Client(project="프로젝트ID", location="us-central1")로 변경하는 수준이라 코드 수정 범위는 크지 않다.

비용 추정도 미리 해둬야 한다. Vertex AI는 입력·출력 토큰 단위로 과금된다. 프로토타입 단계에서 문서별 평균 토큰 수를 로깅해두면 비용 산정이 편해진다. 내 경우 문서 1건당 평균 입력 2,000토큰, 출력 300토큰 정도였고, 이걸 기준으로 월간 처리량을 곱해서 예산을 잡았다.

다만 데이터 저장 위치(data residency)도 확인이 필요하다. AI Studio는 데이터가 미국 서버를 경유하기 때문에, 개인정보나 민감 정보가 포함된 문서를 처리한다면 사내 보안 정책과 맞는지 검토해야 한다. Vertex AI에서는 리전을 지정할 수 있으니, 이 부분이 요구사항이라면 전환 시 반영하면 된다.

당장 실행할 수 있는 액션 세 가지를 남겨둔다:

  1. AI Studio에서 API 키 발급 — 5분이면 된다. 오늘 바로 할 수 있다.
  2. 플레이그라운드에서 프롬프트를 최소 10회 반복 테스트 — 코드 작성 전에 프롬프트를 확정하는 게 전체 시간을 가장 많이 줄인다.
  3. JSON 응답이 필요하면 처음부터 response_mime_type="application/json" 사용 — 나중에 정규식 파서를 만드는 건 돌아가는 길이다.

개인적으로는 프로토타입 단계에 한정하면 Gemini 2.0 Flash의 무료 티어 가성비가 현재 나와 있는 선택지 중 가장 나은 것 같다.

관련 글

Chiko
Chiko

Platform Engineer. Python, AI, Infra에 관심이 많습니다.

Buy me a coffee

More posts