DAY 2 · 14교시 · 60분

백엔드 통합: FastAPI 중계 서버 구축

➔
➔

📚1단계: 주요 개념 설명

이번 단원의 목표

Python FastAPI를 사용해 프론트엔드와 로컬 AI 모델들(Qwen3.5·Qwen 0.6B TTS·FLUX)을 하나로 잇는 백엔드 중계 서버를 연동 코딩한다.

🗂️강의 슬라이드
슬라이드 1 / 10

파이썬 FastAPI 중계 라우터 개요

FastAPI 중계 라우터 개요🖥️화면 :3000🐍FastAPI :8000
  • 웹 브라우저 대시보드 화면(3000포트)과 로컬에 흩어진 AI 모듈들(Ollama, TTS, FLUX) 간의 데이터를 교통정리해 주는 백엔드 Uvicorn API 서버를 구축합니다.
  • 구문이 간결하고 성능이 우수한 파이썬 표준 라이브러리인 FastAPI 기반을 학습합니다.

🛠️2단계: 따라하기 실습

🛠 따라 만들기 · AI 바이브 코딩
로컬 AI를 'OpenAI 호환 서버' 하나로 묶고 웹앱 통째로 전환

11·12교시에서 만든 음성·이미지 API에 텍스트(Ollama 프록시)까지 더해, 하나의 OpenAI 호환 로컬 서버(:8000)로 묶습니다. 그러면 웹앱은 base URL 한 줄만 바꿔 텍스트·음성·이미지를 전부 로컬로 돌립니다.

🎯 완성 결과: AI_BASE_URL=http://localhost:8000 한 줄로 Day 1 웹앱 전체가 로컬 모델로 실행되는 상태
1OpenAI 호환 엔드포인트 3종 완성 (CORS 포함)

웹앱이 클라우드처럼 부를 수 있는 로컬 서버 하나로 묶습니다.

🤖 AI에게 이렇게 시켜보세요

FastAPI server.py에 /v1/chat/completions(로컬 Ollama로 프록시)·/v1/audio/speech(로컬 TTS)·/v1/images/generations(로컬 FLUX) 세 엔드포인트를 OpenAI와 같은 형식으로 만들고, CORS 모든 출처 허용, uvicorn 8000포트 실행까지 해줘.

▶ 터미널에서 실행
uvicorn server:app --reload --port 8000
💡 핵심 코드 설명
  • 경로·형식을 OpenAI 규격에 맞추는 게 핵심 — 그래야 웹앱이 '주소만' 바꿔 그대로 호출합니다.
  • CORS 미들웨어가 있어야 배포된 화면이 이 서버를 불러도 브라우저가 막지 않습니다.
2CORS 켜고/끄고 차이 확인

왜 CORS 허용이 필요한지 눈으로 확인합니다.

💡 핵심 코드 설명
  • 오른쪽 CORS 샌드박스에서 미들웨어를 껐다/켰다 하며 차단(빨간 자물쇠)↔200 OK 차이를 확인하세요.
  • 출처(포트)가 다르면 브라우저가 기본 차단하므로, 서버가 '이 출처 허용'을 응답에 붙여야 합니다.
3⭐ 웹앱 통째로 로컬 전환 & 실행

환경변수 한 줄로 Day 1 웹앱 전체를 로컬 모델로 돌립니다.

🤖 AI에게 이렇게 시켜보세요

Day 1 웹앱의 .env.local에 AI_BASE_URL=http://localhost:8000 을 추가하고, 대본·음성·이미지 API 호출이 이 base URL을 쓰도록 맞춰줘. (키 없이도 로컬 서버로 요청되게)

▶ 터미널에서 실행
# .env.local
AI_BASE_URL=http://localhost:8000
💡 핵심 코드 설명
  • 이 한 줄이면 텍스트·음성·이미지 호출이 전부 내 로컬 서버(:8000)로 향합니다 — 코드는 그대로.
  • 주제를 넣어 생성하면 대본·음성·이미지가 모두 내 컴퓨터에서 나옵니다. 클라우드로 되돌리려면 그 줄만 지우면 끝.
  • '클라우드 웹앱 == 온프렘 웹앱, 차이는 주소 한 줄'임을 몸으로 확인하는 단계입니다.
🎯 스스로 해볼 미션
0 / 2 완료
요청에 '내 옵션' 하나 흘려보내기

프론트에서 백엔드까지 값이 전달되는 흐름을, 필드 하나를 추가하며 직접 확인합니다.

출발점(강사와 함께 만든 것): 강사와 함께 FastAPI 중계 서버를 만들고 CORS를 열었다.
✅ 완료 기준: 추가한 필드 값이 백엔드까지 전달되면 성공.
✓실습 미션 체크리스트
1개념 직관

앞의 세 생성기술(텍스트·오디오·이미지)을 하나의 창구로 묶는 단계입니다. 브라우저 화면(포트 3000)에서 전송한 기획 요소를 받아, 내 컴퓨터 로컬에 띄워둔 Ollama(11434, Qwen3.5), Qwen 0.6B TTS, FLUX로 전달 및 지휘하는 파이썬 중계 서버를 작성합니다.

2실습 미션

우측 CORS 연동 샌드박스에서 'CORS Middleware 허용'을 껐을 때와 켰을 때 각각 테스트 요청을 보내 보세요. 미들웨어가 없으면 브라우저가 요청을 차단(빨간 자물쇠)하고, 허용하면 3000↔8000 포트 간 통신이 열려 200 OK가 돌아오는 차이를 직접 확인합니다.

OpenAI 호환 로컬 서버 뼈대 + 한 줄 스왑
# 로컬 서버는 OpenAI와 '같은 경로'를 제공한다
#   /v1/chat/completions · /v1/audio/speech · /v1/images/generations

# 그래서 웹앱은 코드를 안 고치고 주소(base URL)만 바꾸면 끝:
#   .env.local  →  AI_BASE_URL=http://localhost:8000
#
# 클라우드:  https://api.openai.com/v1/...
# 온프렘:    http://localhost:8000/v1/...   (env 한 줄만 교체)

💡 코딩 중 막히나요? 모범 솔루션 코드

🧩3단계: 개념 검증 퀴즈

검증 챌린지 미션

FastAPI 서버에 탑재한 CORS 활성화 기능이 정상 작동하고 교차 출처 테스트를 통과하는지 검증합니다.

📝 객관식 개념 확인 (2문항)

Q1. 브라우저(3000)에서 FastAPI(8000)로 요청할 때 CORS 설정이 없으면?

Q2. CORS 문제를 해결하는 올바른 위치는?

🔬 인터랙티브 체험 (선택)— 개념을 직접 조작하며 확인해 보세요

CORS 정책이 켜져 있어야 브라우저가 FastAPI 백엔드(8000포트)로부터 데이터를 정상 수신할 수 있습니다.

💻 3000포트 (UI)
🔒
⚙️ 8000포트 (API)
다음 교시로 이동하기 (15교시: 영상 합성: moviepy로 이미지+음성 조립) ➡️