FastAPI를 활용한 AI 모델 웹 API 서버 코드 구조

AI 모델을 실제 서비스에서 사용하려면 단순히 모델을 실행하는 코드만 작성하는 것이 아니라,
사용자 요청을 받고 모델 추론 결과를 응답하는 API 서버 구조를 만들어야 한다.

FastAPI는 Python 기반의 웹 프레임워크로, AI 모델을 API 형태로 제공할 때 많이 사용된다.
특히 기능별로 코드를 나누면 유지보수와 확장이 쉬워진다.

1. 전체 폴더 구조 예시

FastAPI를 활용한 AI 모델 API 서버는 다음과 같이 구성할 수 있다.

project/
│
├── app/
│   ├── main.py
│   ├── api/
│   │   └── predict.py
│   ├── core/
│   │   └── config.py
│   ├── models/
│   │   └── model_loader.py
│   ├── schemas/
│   │   └── request_response.py
│   └── services/
│       └── predict_service.py
│
├── model/
│   └── sentiment_model.onnx
│
├── requirements.txt
└── README.md

이렇게 기능별로 파일을 분리하면 코드가 길어져도 구조를 이해하기 쉽다.

2. main.py

main.py는 FastAPI 서버가 시작되는 중심 파일이다.
FastAPI 앱을 생성하고, API 라우터를 연결하는 역할을 한다.

예를 들어 /predict 같은 예측 API를 등록하고, 서버가 실행될 수 있도록 구성한다.

from fastapi import FastAPI
from app.api.predict import router as predict_router

app = FastAPI(title="AI Model API")

app.include_router(predict_router)

3. api 폴더

api 폴더는 실제 API 주소를 정의하는 부분이다.
예를 들어 사용자가 /predict 주소로 요청을 보내면 어떤 함수가 실행될지 정한다.

이 파일에서는 요청을 받고, 서비스 로직을 호출한 뒤 결과를 반환한다.

from fastapi import APIRouter
from app.schemas.request_response import PredictRequest, PredictResponse
from app.services.predict_service import predict_text

router = APIRouter()

@router.post("/predict", response_model=PredictResponse)
def predict(request: PredictRequest):
    result = predict_text(request.text)
    return PredictResponse(result=result)

4. schemas 폴더

schemas 폴더는 요청과 응답 데이터의 형태를 정의하는 부분이다.
FastAPI에서는 Pydantic을 사용해 데이터 구조를 명확하게 만들 수 있다.

예를 들어 사용자가 입력해야 하는 값과 서버가 반환할 값을 미리 정해둘 수 있다.

from pydantic import BaseModel

class PredictRequest(BaseModel):
    text: str

class PredictResponse(BaseModel):
    result: str

이렇게 작성하면 잘못된 형식의 요청이 들어왔을 때 오류를 쉽게 확인할 수 있다.

5. models 폴더

models 폴더는 학습된 AI 모델을 불러오는 역할을 한다.
PyTorch, TensorFlow, ONNX 등 어떤 모델을 사용하는지에 따라 로드 방식이 달라질 수 있다.

모델은 요청이 들어올 때마다 새로 불러오면 비효율적이다.
따라서 서버가 시작될 때 한 번만 로드하고, 계속 재사용하는 방식이 좋다.

import onnxruntime as ort

def load_model():
    session = ort.InferenceSession("model/sentiment_model.onnx")
    return session

6. services 폴더

services 폴더는 실제 비즈니스 로직이나 모델 추론 로직을 처리하는 부분이다.
입력 데이터를 전처리하고, 모델에 넣어 예측한 뒤, 결과를 후처리한다.

API 파일에는 요청과 응답 처리만 두고,
실제 예측 로직은 service 파일로 분리하는 것이 좋다.

from app.models.model_loader import load_model

model = load_model()

def predict_text(text: str):
    # 1. 입력 데이터 전처리
    # 2. 모델 추론
    # 3. 결과 후처리

    result = "긍정"
    return result

7. core 폴더

core 폴더는 설정값을 관리하는 부분이다.
예를 들어 모델 경로, 서버 환경, API 설정값 등을 따로 관리할 수 있다.

MODEL_PATH = "model/sentiment_model.onnx"

설정값을 한 곳에서 관리하면 나중에 모델 파일 위치나 서버 환경이 바뀌어도 수정하기 쉽다.

8. 전체 흐름

FastAPI 기반 AI 모델 API 서버의 전체 흐름은 다음과 같다.

1. 사용자가 /predict API로 데이터를 보낸다.
2. API 라우터가 요청 데이터를 받는다.
3. schema를 통해 입력 데이터 형식을 확인한다.
4. service에서 입력 데이터를 전처리한다.
5. model_loader에서 불러온 모델로 추론한다.
6. 예측 결과를 후처리한다.
7. 사용자에게 JSON 형태로 결과를 반환한다.

정리

FastAPI로 AI 모델을 통합한 웹 API를 구현할 때는 기능별로 코드를 나누는 것이 좋다.

• main.py: FastAPI 앱 생성 및 라우터 등록
• api: API 주소와 요청 처리
• schemas: 요청과 응답 데이터 구조 정의
• models: AI 모델 로드
• services: 전처리, 추론, 후처리 로직 처리
• core: 설정값 관리
• model: 학습된 모델 파일 저장

결국 좋은 API 서버 구조는 단순히 코드가 실행되는 것에서 끝나는 것이 아니라,
기능별 역할을 명확히 나누어 유지보수와 확장이 쉬운 형태로 만드는 것이다.