FastAPI와 Docker를 활용한 LangGraph 애플리케이션 배포

최근 LangGraph를 활용하여 멀티 에이전트를 구축하는 사례가 증가하고 있다. 이를 어떻게 배포하는 게 좋을까 구글링을 해보면 대부분  streamlit 등을 이용한 방법이 나온다. 그런데 이를 실제 서비스로 제공하기 위해서는 백엔드와 프론트엔드가 분리된 구조에서 배포하는 방법을 이해하는 것이 중요하다. 이번 글에서는 FastAPI를 활용하여 LangGraph 애플리케이션을 서빙하고, Docker를 이용해 손쉽게 배포하는 방법을 다룬다.

1. 프로젝트 구조

프로젝트의 디렉토리 구조는 아래와 같다.

./
├── Dockerfile
├── graph.png
├── main.py
├── requirements.txt
├── graph
│   ├── edges.py
│   ├── graph.py
│   └── nodes.py
└── prompts
    ├── gather.yaml
    └── generate_prompt.yaml

• graph/: LangGraph의 구성 요소(node, edge 등)를 포함
• prompts/: 애플리케이션에 필요한 프롬프트 템플릿을 포함
• main.py: FastAPI 기반의 웹 애플리케이션 정의
• Dockerfile: 컨테이너화하여 배포하기 위한 설정 파일

2. FastAPI를 이용한 스트리밍 응답 구현

FastAPI를 사용하여 LangGraph 기반의 애플리케이션을 서빙하는 API를 구축한다. 핵심 기능은 사용자 입력을 받아 LangGraph를 통해 스트리밍 응답을 제공하는 것이다.

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from langchain_core.messages import HumanMessage
from graph.graph import graph

app = FastAPI()

@app.get("/chat/stream")
async def stream(query: str, thread_id: str = "1"):
    config = {"configurable": {"thread_id": thread_id}}

    async def event_stream():
        try:
            async for chunk in graph.astream(
                input={"messages": [HumanMessage(content=query)]},
                config=config,
                stream_mode=["custom"],
            ):
                yield f"data: {chunk[1]}\n\n"
        except Exception as e:
            yield f"data: {str(e)}\n\n"

    return StreamingResponse(event_stream(), media_type="text/event-stream")

3. 종속성 패키지 관리

애플리케이션 실행에 필요한 패키지는 requirements.txt에 정의한다. 이를 자동으로 생성하려면 아래 명령어를 실행한다.

pip freeze > requirements.txt

4. Dockerfile 작성

이제 Docker를 활용해 컨테이너화한다. 사용한 Python 버전에 맞춰 Base Image를 설정하고, 필요한 파일을 컨테이너 내부로 복사한 후 requirements.txt를 통해 종속성을 설치한다.

# 기본 이미지 설정
FROM python:3.11

WORKDIR /flow

# 애플리케이션 파일을 컨테이너에 복사
COPY ./graph /flow/graph
COPY ./main.py /flow/main.py
COPY ./prompts /flow/prompts
COPY ./.env /flow/.env

# 종속성 설치
COPY ./requirements.txt /flow/requirements.txt
RUN pip install --no-cache-dir --upgrade -r /flow/requirements.txt

# 컨테이너 실행 시 FastAPI 애플리케이션 실행
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

5. Docker 이미지 빌드 및 실행

Docker 이미지를 빌드하고 실행하여 애플리케이션을 테스트할 수 있다.

이미지 빌드

docker build -t my-app:v0.1 .

컨테이너 실행

docker run --rm -p 8000:8000 my-app:v0.1

 

이제 http://localhost:8000/chat/stream?query=안녕하세요?thread_id=abc 같은 URL을 통해 FastAPI 엔드포인트를 테스트할 수 있다.

 

이번 포스트에서는 LangGraph 기반 애플리케이션을 FastAPI로 서빙하고, Docker로 컨테이너화하는 전체 과정을 살펴보았다. 이를 통해 실제 서비스 환경에서 LangGraph를 활용하는 방법을 보다 쉽게 적용할 수 있을 것이다.