파이썬 공부 삼아 로컬 환경에서 생성형 AI를 호출하는 처리를 구현해 보았습니다.
이번에 사용한 것은 Google사의 'Gemini API'입니다.
인터페이스는 2026년 6월 이후에 일반 제공된 'Interactions API'가 권장되고 있어, 이를 사용합니다.
간단히 말해, 기존의 'generateContent API'보다 대화 기록 관리, 툴 호출, 에이전트 실행 등을 일원적으로 다룰 수 있도록 만든 인터페이스가 바로 'Interactions API'입니다.
Interactions API 공식 문서 ▼
| 항목 | 내용 |
|---|
| OS | Windows 11 Home |
| ... | |
| Gemini API는 Google AI Studio에서 사용하는 방법과 Vertex AI를 통해 사용하는 방법이 있습니다. | |
우선 무료 사용 범위 내에서 시도해 보고 싶었기 때문에, Google AI Studio에서 시작하는 절차를 소개합니다.
실제 운영 환경이나 대규모 애플리케이션의 경우, Google Cloud의 운영 기반인 Vertex AI 활용을 권장합니다.
- Google AI Studio에서 API 키를 얻는다
- Python 개발 환경을 구축한다
- Gemini API를 호출하는 함수를 구현하고 동작 확인을 한다
Google AI Studio (https://aistudio.google.com)에 접속하여 Google 계정으로 로그인합니다.
이용 관련 동의 사항에 체크한 후 '계속'을 누르면, 'API 키' 화면이 표시됩니다.
기본적으로 무료 사용 범위가 설정된 프로젝트가 등록되어 있으므로, 'Default Gemini Project'의 '키'를 클릭하면 다음과 같이 API 키를 확인할 수 있습니다.
API 키는 인증 정보이므로 소스 코드에 직접 기재하거나 GitHub 등에 공개하지 않도록 합니다.
다음으로, Python 개발 환경을 준비합니다.
이번에는 다음 구성으로 했습니다.
PowerShell에서 다음 명령어를 실행합니다.
위 명령어는 상위 폴더까지 한 번에 생성하는 명령어입니다.
다음 4줄을 실행했을 때와 동일한 동작을 합니다.
mkdir project
cd project
mkdir backend
...
아래 절차에서 소개하는 명령어는 실행 환경에 맞춰 구문을 적절히 변경해 주십시오.
Python에는 프로젝트별로 라이브러리를 관리할 수 있는 메커니즘이 있습니다.
여러 프로젝트를 개발하다 보면, 프로젝트마다 사용하고 싶은 라이브러리 버전이 충돌하여 프로그램이 작동하지 않게 되는 경우도 있습니다.
이번에는 venv를 사용하여 프로젝트별로 깨끗한 개발 환경을 준비합니다.
생성된 가상 환경을 활성화합니다.
PowerShell에서 가상 환경 활성화가 안 될 경우, 스크립트 실행 정책을 일시적으로 허용하는 다음 명령어를 실행한 후 다시 시도해 보십시오.
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
활성화되면 줄의 시작 부분에 (venv)가 표시됩니다.
이번에 이용할 패키지를 설치합니다.
pip install google-genai python-dotenv
각각의 용도는 다음과 같습니다.
이번에는 첫 API 호출까지만 진행하기 때문에, FastAPI나 Uvicorn은 설치하지 않습니다.
| 패키지 | 용도 |
|---|
| google-genai | Gemini API를 이용하기 위한 공식 Python SDK |
| python-dotenv | .env 파일에서 환경 변수를 읽어오는 기능 |
여기서 최종적인 폴더 구성을 먼저 소개하겠습니다.
에디터나 자동으로 생성되는 환경 의존성 폴더는 신경 쓰지 않아도 되며, 이후 절차에서는 .env 파일을 수정합니다.
AI를 호출하는 처리는 llm.py에 작성합니다.
동작 확인용 프로그램으로 try_llm.py를 만들었지만, 실행만 가능하다면 괜찮습니다.
project/
└── backend/
└── pycache/
...
환경 변수(Environment variable)로, 절차 1에서 확인한 API 키나 사용할 모델명을 .env 파일에 기재합니다.
이번에는 "Gemini 3.8 Flash"를 예시로 진행하지만, 원하는 모델을 사용해도 괜찮습니다.
GEMINI_API_KEY="획득한API키"
MODEL_NAME="gemini-3.8-flash"
API 키가 포함된 .env 파일이나 가상 환경 폴더는 Git 관리 대상에서 제외합니다.
.gitignore에 다음을 기재합니다.
여기부터는 Python으로 Gemini API를 호출하는 처리를 llm.py에 작성합니다. 먼저, 필요한 라이브러리를 임포트(import)합니다.
import os
from dotenv import load_dotenv
from google import genai
다음으로, 환경 변수를 읽어와 Gemini API의 클라이언트(client)를 생성합니다.
load_dotenv()
client = genai.Client()
MODEL = os.environ["MODEL_NAME"]
load_dotenv()는 .env에 기재된 환경 변수를 읽어오는 함수입니다.
genai.Client()에서는 환경 변수에 설정된 GEMINI_API_KEY를 이용하여 클라이언트를 초기화합니다. 기본적인 작성 방식은 공식 문서에 나와 있듯이 간단합니다.
interaction = client.interactions.create(
model="",
input="",
...
이번에는 Python 학습도 겸하고 있기 때문에, 사용자 입력(input)에 더하여 응답 지시를 받는 형태로 만들어 보았습니다.
"OO에 대해 설명해줘"라는 입력과 함께 "몇 글자 이내로", "얼마나 구체적으로", "OO 관점에서"와 같은 응답 관련 방침을 전달할 수 있습니다.
def ask(prompt: str, system: str = "") -> str:
kwargs = {}
if system:
...
system은 초기값을 빈 문자열로 설정했기 때문에 생략할 수도 있습니다.
system이 지정된 경우에만, system_instruction으로 API에 전달하고 있습니다.
여기서 사용한 **kwargs는 딕셔너리에 저장된 키와 값을 키워드 인자(keyword argument)로 전개하는 Python 기능입니다. 다음과 동일하게 작동합니다. kwargs에 저장된 키와 값이 늘어나도 **kwargs라고 작성하여 일괄적으로 전달할 수 있습니다.
interaction = client.interactions.create(
model = MODEL,
input = prompt,
...
실무나 앱 개발에서는, return interaction.output_text로 받은 답변을 후속 처리가 가능하도록 JSON 형태로 변환하는 함수를 정의할 수도 있겠지만, 이번에는 생략합니다.
실제로 Gemini API와 통신할 수 있는지 확인합니다. 동작 확인용으로 try_llm.py를 작성하는 경우, 아래 코드를 참고해 주세요.
from llm import ask
print(ask("안녕하세요. 자기소개를 해 주세요"))
방금 처리한 내용을 작성한 llm.py를 실행할 수 있다면, 다른 방법으로 진행해도 괜찮습니다.
응답이 출력될 때까지 몇 분이 걸렸습니다. 경우에 따라서는 5~10분 이상일 수 있습니다.
실행되고 있는 경우, 인내심을 가지고 기다려 주세요. 무료 사용량(free tier)은 혼잡 시 안정성이 부족할 수 있습니다.
Google AI Studio의 "사용량"에서 요청 자체가 전송되었는지는 확인할 수 있습니다. 이 역시 1분 정도 기다리지 않으면 반영되지 않았습니다.
모델이나 통신 상황에 따라 "503 ServiceUnavailable"이 될 수 있으므로, 시간을 두고 다시 실행해 보세요.
참고로, 터미널을 닫아버리는 등 중단하면 "499"라는 코드로 기록됩니다.
API 오류 목록 ▼
응답이 정상적으로 완료되면 이런 느낌입니다.
지시문(instruction)을 추가하여 실행하면, 응답도 달라집니다.
print(ask("안녕하세요. 자기소개를 해 주세요", "존댓말은 사용하지 말고, 간결하게"))
이번 글에서는 Python 환경 구축부터 Gemini API로부터 응답이 돌아오는까지의 절차를 소개했습니다.
여기서 더 확장해 나갈 경우, 요청을 보내는 화면을 만들거나 FastAPI를 도입하는 것도 좋을 것 같습니다.
Python을 따라잡고 있는 분들, 공식 SDK(Software Development Kit)를 사용해 AI를 호출해 보고 싶은 분들에게 참고가 되기를 바랍니다!
