dev

파이썬 Flask와 Google Gemini API 연동 개발 가이드: 초보자도 쉽게 따라하기

quinton84 2025. 7. 6. 02:28
반응형

안녕하세요,

 

오늘은 파이썬(Python)의 경량 웹 프레임워크인 Flask를 사용하여 간단한 웹 애플리케이션을 만들고,

여기에 Google의 강력한 AI 모델인 Gemini API를 연동하여 AI 기반의 질문-답변 기능을 구현하는 방법을 단계별로 알려드릴게요. 코딩 초보자분들도 쉽게 따라오실 수 있도록 상세하게 설명해 드리니, 차근차근 함께 만들어 봐요!

 

반응형

1. 개요 (Overview)

이 가이드를 통해 여러분은 다음을 배우고 직접 구현하게 됩니다.

  • 목표: 파이썬 Flask 웹 애플리케이션을 구축하고, Google Gemini AI 모델을 연동하여 사용자의 질문에 AI가 답변하는 기능을 구현합니다.
  • 결과물: 웹 브라우저에서 질문을 입력하면 Gemini 모델이 실시간으로 답변을 제공하는 간단한 웹 애플리케이션.

2. 준비물 (Prerequisites)

시작하기 전에 다음 도구들이 컴퓨터에 설치되어 있어야 합니다.

  • Visual Studio Code (VS Code): 코드 편집 및 터미널 사용을 위한 통합 개발 환경 (IDE).
  • Python 3.x: 파이썬 언어 및 패키지 관리를 위한 런타임.
  • Google Gemini API 키: Google AI Studio 또는 Google Cloud Platform에서 발급받은 API 키.

3. 프로젝트 설정 (Project Setup)

3.1. 프로젝트 폴더 생성 및 VS Code 열기

  1. 컴퓨터의 원하는 위치에 새 폴더를 생성합니다 (예: gemini-flask-app).
  2. VS Code를 열고 파일(File) > 폴더 열기(Open Folder...)를 클릭하여 방금 만든 폴더를 선택합니다.

3.2. 가상 환경 설정 및 활성화 (권장)

프로젝트별로 독립적인 파이썬 환경을 구축하여 라이브러리 충돌을 방지하고 프로젝트를 깔끔하게 관리할 수 있습니다.

  1. VS Code 터미널을 엽니다: 터미널(Terminal) > 새 터미널(New Terminal) 또는 Ctrl + ` (백틱).
  2. 터미널에 다음 명령어를 입력하여 가상 환경을 생성합니다:
  3. python -m venv venv
  4. 가상 환경을 활성화합니다:
    • Windows (PowerShell):
    • .\venv\Scripts\activate
    • macOS/Linux (Bash/Zsh):
    • source venv/bin/activate
    • 터미널 프롬프트 앞에 (venv)가 표시되면 가상 환경이 성공적으로 활성화된 것입니다.

3.3. 필수 라이브러리 설치

활성화된 가상 환경에서 다음 라이브러리들을 설치합니다.

pip install Flask google-generativeai python-dotenv
  • Flask: 웹 애플리케이션을 만들기 위한 핵심 프레임워크입니다.
  • google-generativeai: Google Gemini API를 파이썬에서 쉽게 사용할 수 있도록 돕는 공식 라이브러리입니다.
  • python-dotenv: .env 파일에 저장된 환경 변수(API 키 등)를 파이썬 코드에서 안전하게 불러오기 위한 라이브러리입니다.

3.4. .env 파일 생성 및 API 키 저장 (보안 필수!)

API 키는 절대 코드에 직접 노출하거나 GitHub와 같은 공개 저장소에 올리면 안 됩니다. 유출될 경우 악의적으로 사용될 수 있습니다. .env 파일을 사용하여 환경 변수로 관리하는 것이 가장 안전한 방법입니다.

  1. VS Code 탐색기에서 프로젝트 폴더를 마우스 오른쪽 버튼으로 클릭하고 새 파일(New File)을 선택합니다.
  2. 파일 이름을 .env로 입력하고 Enter 키를 누릅니다.
  3. .env 파일에 발급받은 Gemini API 키를 다음과 같이 저장합니다 (따옴표를 포함해야 합니다).
  4. GOOGLE_API_KEY=" 실제 발급받은 당신의 Gemini API 키 "

4. 코드 구현 (Code Implementation)

이제 웹 애플리케이션의 핵심 로직을 구현할 차례입니다.

4.1. app.py 파일 작성 (Flask 애플리케이션 로직)

프로젝트 폴더에 app.py 파일을 생성하고 아래 코드를 복사하여 붙여넣습니다.

from flask import Flask, render_template, request # Flask 웹 애플리케이션 관련 모듈 임포트
import google.generativeai as genai # Google Gemini API 라이브러리 임포트
import os # 환경 변수를 사용하기 위해 os 모듈 임포트
from dotenv import load_dotenv # .env 파일에서 환경 변수를 로드하기 위한 라이브러리 임포트

# .env 파일에서 환경 변수를 로드합니다.
load_dotenv() 

# 환경 변수에서 Gemini API 키를 불러옵니다.
# GOOGLE_API_KEY는 .env 파일에 설정한 변수 이름과 동일해야 합니다.
GOOGLE_API_KEY = os.getenv("GOOGLE_API_KEY") 

# API 키가 제대로 로드되었는지 확인하는 로직 (필수)
if not GOOGLE_API_KEY:
    raise ValueError("Google API Key가 설정되지 않았습니다. .env 파일을 확인하거나 환경 변수를 설정해주세요.")

# Gemini API를 구성합니다.
genai.configure(api_key=GOOGLE_API_KEY)

# Flask 애플리케이션 인스턴스를 생성합니다.
app = Flask(__name__)

@app.route('/')
def index():
    """
    웹페이지의 루트 경로('/')에 대한 GET 요청을 처리합니다.
    초기 웹페이지 로드 시 질문과 결과는 비어 있는 상태로 템플릿을 렌더링합니다.
    """
    return render_template('index.html', question=None, result=None)

@app.route('/', methods=['POST'])
def submit():
    """
    웹페이지의 루트 경로('/')에 대한 POST 요청을 처리합니다.
    사용자가 폼을 통해 질문을 제출했을 때 실행됩니다.
    """
    # 웹 폼에서 'prompt'라는 이름으로 전송된 사용자 질문을 가져옵니다.
    user_prompt = request.form['prompt']
    
    # Gemini 모델을 사용하여 사용자 질문에 대한 응답을 생성합니다.
    gemini_response = access_gemini(user_prompt)
    
    # 사용자 질문과 Gemini 응답을 HTML 템플릿에 전달하여 렌더링합니다.
    # 이를 통해 웹페이지에 질문과 답변이 표시됩니다.
    return render_template('index.html', question=user_prompt, result=gemini_response)

def access_gemini(prompt_value):
    """
    Google Gemini 모델에 프롬프트를 전송하고 응답 텍스트를 반환하는 함수입니다.
    API 호출 중 오류가 발생하면 오류 메시지를 반환합니다.
    """
    try:
        # 사용할 Gemini 모델을 지정합니다.
        # 'models/gemini-2.0-flash'는 현재 시점에서 텍스트 생성에 권장되는 모델입니다.
        # Google Generative AI 라이브러리에서는 'models/' 접두사를 붙여 명시하는 것이 안정적입니다.
        model = genai.GenerativeModel('models/gemini-2.0-flash') 
        
        # 모델에 프롬프트를 전송하고 응답을 생성합니다.
        # generate_content 메서드는 텍스트 외에 이미지 등 다양한 콘텐츠 유형을 처리할 수 있습니다.
        response = model.generate_content(prompt_value)
        
        # 생성된 응답 텍스트를 반환합니다.
        return response.text
    except Exception as e:
        # API 호출 중 발생한 예외(네트워크 오류, API 키 오류, 할당량 초과 등)를 잡아서
        # 사용자에게 친화적인 오류 메시지를 반환합니다.
        return f"Gemini API 호출 중 오류가 발생했습니다: {e}"

if __name__ == '__main__':
    # Flask 애플리케이션을 실행합니다.
    # debug=True는 개발 모드로, 코드 변경 시 자동으로 서버를 재시작해주는 편리한 기능입니다.
    # 실제 운영 환경에 배포할 때는 보안과 성능을 위해 debug=False로 설정해야 합니다.
    app.run(debug=True)

4.2. templates/index.html 파일 작성 (프런트엔드 UI)

app.py 파일과 같은 레벨에 templates 폴더를 생성하고, 그 안에 index.html 파일을 다음과 같이 작성합니다.

<!DOCTYPE html>
<html lang="ko">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8">
    <title>Gemini Flask Example</title>
    <!-- Bootstrap CSS를 CDN으로 포함하여 기본적인 스타일을 제공합니다. -->
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/css/bootstrap.min.css" rel="stylesheet" crossorigin="anonymous">
</head>
<body class="container">
    <h1 class="display-6 py-2">Gemini Flask Example</h1>
    
    <!-- 사용자 입력을 받는 폼 -->
    <form method="POST" action="/">
        <div>
            <label for="prompt">프롬프트:</label>
            <textarea id="prompt" name="prompt" class="form-control" rows="5" placeholder="여기에 질문을 입력하세요."></textarea>
        </div>
        <center class="py-3">
            <input type="submit" value="질문하기" class="btn btn-primary">
        </center>
    </form>

    <!-- 질문과 답변 결과를 표시하는 영역 -->
    {# Jinja2 템플릿 문법: question 변수가 None이 아닐 때만 표시 #}
    {% if question is not none %} 
        <div class="mt-4">
            <h5 class="text-primary">당신의 질문:</h5>
            <p class="border border-2 p-3 h6 bg-light">{{ question }}</p>
        </div>
    {% endif %}

    {# Jinja2 템플릿 문법: result 변수가 None이 아닐 때만 표시 #}
    {% if result is not none %} 
        <div class="mt-2">
            <h5 class="text-success">Gemini의 답변:</h5>
            <p class="border border-2 p-3 h6 bg-light">{{ result }}</p>
        </div>
    {% endif %}

</body>
</html>

 

 

5. 애플리케이션 실행 및 테스트 (Execution & Testing)

모든 파일 준비가 완료되었다면, 다음 단계에 따라 Flask 애플리케이션을 실행하고 웹 브라우저에서 테스트합니다.

  1. VS Code 터미널 열기: 터미널(Terminal) > 새 터미널(New Terminal) 또는 Ctrl + `.
  2. 가상 환경 활성화 확인: 터미널 프롬프트 앞에 (venv)가 표시되어 있는지 확인합니다. (만약 표시되지 않으면 .\venv\Scripts\activate 또는 source venv/bin/activate 명령어로 활성화합니다.)
  3. FLASK_APP 환경 변수 설정:
    • 이 명령어를 입력하고 Enter 키를 눌러 명령을 확정합니다.
  4. $env:FLASK_APP="app.py"
  5. Flask 애플리케이션 실행:
    • 이 명령어를 입력하고 Enter 키를 눌러 명령을 확정합니다.
    • 터미널에 * Running on http://127.0.0.1:5000와 같은 메시지가 표시되면 서버가 정상적으로 실행된 것입니다.
  6. flask run
  7. 웹 브라우저 접속: 웹 브라우저를 열고 주소창에 http://127.0.0.1:5000 또는 http://localhost:5000을 입력하고 접속합니다.
  8. 기능 테스트: 웹페이지의 프롬프트: 입력창에 질문을 입력하고 "질문하기" 버튼을 클릭합니다. Gemini 모델의 답변이 웹페이지 하단에 표시되는 것을 확인합니다.
  9. 서버 종료: 터미널에서 Ctrl + C를 눌러 Flask 서버를 중지할 수 있습니다.

6. 주요 문제 해결 (Troubleshooting)

개발 과정에서 발생할 수 있는 일반적인 문제들과 그 해결 방법을 안내합니다.

  • 문제: .\venv\Scripts\activate 명령 실행 시 "이 시스템에서 스크립트를 실행할 수 없으므로" 오류 발생.
    • 원인: Windows PowerShell의 기본 보안 설정(실행 정책)이 서명되지 않은 스크립트 실행을 막기 때문입니다.
    • 해결: 관리자 권한으로 PowerShell을 열어 Set-ExecutionPolicy RemoteSigned 명령을 실행하고 Y를 입력하여 정책을 변경합니다. (이 작업은 한 번만 수행하면 됩니다.)
  • 문제: flask run 명령 실행 시 "Failed to find Flask application or factory in module 'app'." 오류 발생.
    • 원인: Flask가 app.py 파일 내의 앱 인스턴스를 찾지 못했거나, FLASK_APP 환경 변수 설정이 즉시 적용되지 않는 PowerShell의 특성 때문일 수 있습니다.
    • 해결: FLASK_APP 환경 변수 설정($env:FLASK_APP="app.py")과 flask run 명령을 각각 다른 줄에서 실행합니다. 즉, $env:FLASK_APP="app.py" 입력 후 Enter, 다음 줄에서 flask run 입력 후 Enter.
  • 문제: 웹 앱에서 질문 시 "Gemini API 호출 중 오류가 발생했습니다: 404 models/gemini-pro is not found" 또는 유사한 404 오류 발생.
    • 원인: gemini-pro 모델이 현재 Gemini API 환경에서 인식되지 않거나, 다른 모델을 사용해야 할 수 있습니다. curl 명령을 통해 gemini-2.0-flash 모델이 사용되는 것을 확인한 경우, 모델 이름 불일치가 원인일 수 있습니다.
    • 해결: app.py 파일의 access_gemini 함수에서 모델 이름을 genai.GenerativeModel('models/gemini-2.0-flash')로 변경합니다. models/ 접두사를 붙여 명시적으로 모델 경로를 지정하는 것이 더 안정적입니다. 변경 후에는 Flask 서버를 Ctrl + C로 종료하고 flask run으로 재시작해야 합니다.

 

마무리하며:

이 가이드가 여러분의 블로그에 잘 활용되기를 바라며, 파이썬 Flask와 Gemini API를 활용한 멋진 프로젝트를 계속 만들어 나가시길 응원합니다! 궁금한 점이 있다면 언제든지 다시 찾아주세요.

 

🏷️ 태그: Flask, 파이썬, 웹개발, Python, 웹애플리케이션, AI, Gemini, API, 프로그래밍, 코딩, 초보개발, 백엔드, 개발가이드, 입문, GeminiAPI

반응형

'dev' 카테고리의 다른 글

AI와 함께 보고용 PPT 제작기: Gemini와 skywork.ai 활용법  (0) 2025.07.09
🎾 테니스 NTRP 레벨 테스트  (0) 2025.07.06
🎾 누구나 따라 할 수 있는 테니스 NTRP 레벨 테스트 웹 앱 만들기 가이드  (1) 2025.07.06
Gemini API를 활용한 슬랙 챗봇 제작 가이드  (7) 2025.07.06
코딩 초보도 OK! Flask로 시작하는 파이썬 웹 애플리케이션 개발 (feat. Gemini AI)  (0) 2025.07.06

'dev'의 다른글

  • 현재글파이썬 Flask와 Google Gemini API 연동 개발 가이드: 초보자도 쉽게 따라하기

관련글

티스토리툴바