LangServe 사용해보기

랭체인(LangChain) 프레임워크는 LLM 애플리케이션 개발에 도움이 되는 여러 구성 요소로 이루어져 있다.

 

랭체인의 주요 구성 요소는 다음과 같다.

 

 

랭체인 라이브러리(LangChain Libraries): 파이썬과 자바스크립트 라이브러리를 포함하며, 다양한 컴포넌트의 인터페이스와 통합, 이 컴포넌트들을 체인과 에이전트로 결합할 수 있는 기본 런타임, 그리고 체인과 에이전트의 사용 가능한 구현이 가능.

 

랭체인 템플릿(LangChain Templates): 다양한 작업을 위한 쉽게 배포할 수 있는 참조 아키텍처 모음. 개발자들이 특정 작업에 맞춰 빠르게 애플리케이션을 구축할 수 있도록 돕는다.

 

랭서브(LangServe): 랭체인 체인을 REST API로 배포할 수 있게 하는 라이브러리. 이를 통해 개발자들은 자신의 애플리케이션을 외부 시스템과 쉽게 통합할 수 있다.

 

랭스미스(LangSmith): 개발자 플랫폼으로, LLM 프레임워크에서 구축된 체인을 디버깅, 테스트, 평가, 모니터링할 수 있으며, 랭체인과의 원활한 통합을 지원.

 

 

 

 

 

 

 

 

지난번에는 LangChain Libraries를 이용하여 RAG를 이용한 질의응답 시스템을 만들었다.

 

https://develoyummer.tistory.com/168

[RAG] 민법 챗봇 만들기 (with LangChain)

 

 

 

 

 

이제 이 로직을 LangServe를 이용해 API화 해보겠다.

 

 

 

 

 

🔎LangServe

LangChain의 runnable/chain을 FastAPI 기반 REST API로 배포할 수 있게 해주는 라이브러리.
내부적으로는 FastAPI + Pydantic을 사용해 입력·출력 스키마 자동 추론과 검증 기능, API 문서(Swagger + JSON Schema), 스트리밍, 배치 처리 등을 지원한다.

 

 

 

 

 

 

주요 기능

• 자동 스키마 추론: LangChain 객체의 입출력 타입을 자동 추출해 API 호출 시 유효성 검사와 풍부한 에러 메시지 제공 mlops2024.jeju.ai.
• 문서 자동 생성: Swagger UI를 통해 API 문서화.
• 효율적인 엔드포인트:
  • /invoke, /batch: 동시 요청에 최적화
  • /stream, /stream_log, /stream_events: 토큰 스트리밍과 중간 로그 제공 mlops2024.jeju.aiblog.langchain.com+2python.langchain.com+2mlops2024.jeju.ai+2.
• 플레이그라운드 페이지: 웹 UI에서 직접 API 요청을 실험 가능.
• LangSmith 연동: API 키만 등록하면 호출 추적 가능.
• 기반 라이브러리: FastAPI, Pydantic, uvloop, asyncio 등 안정적 오픈소스 사용\

 

 

 

 

 

 

 

주의사항

• 서버 생성 이벤트에 대해 클라이언트 콜백을 아직 지원하지 않음.
• Pydantic v2와의 호환성 문제: Pydantic v2 사용 시 OpenAPI 문서 자동 생성이 제대로 동작하지 않을 수 있으며, FastAPI와 혼용 시 이슈 발생. 이 경우 Pydantic v1 사용 또는 LangServe 0.3.0 이상 권장

 

 

 

 

 

 

사용 목적

LangServe는 LangChain 기반 서비스를 빠르게 API화할 수 있다는 점에서 선택했다.

초기에는 LangChain 로직을 Python 환경에서 LangServe로 간단히 배포하고,
장기적으로는 보안, 인증, 세션 관리, 웹소켓 등은 Spring 서버에서 처리하며,

LLM inference 로직은 독립된 MCP 서버에서 관리할 계획이다.

즉, 서비스 구조를 확장할 수 있는 기반을 마련하려는 목적이다.

 

 

 

 

 

 

 

 

 

사전 준비

pip install langserve fastapi uvicorn

pip install sse_starlette ( langserve의 실시간 응답 스트리밍 기능을 위해 필요)

 

 

 

 

 

 

 

 

 

환경변수 설정

노출되면 안되는 api_key 등은 환경변수로 설정해두어야 한다.

 

1. .env파일에 환경변수 등록

2. .gitignore 파일에 .env파일 등록

 

3. setting.py 작성

# app/settings.py
from pydantic_settings import BaseSettings, SettingsConfigDict
from functools import lru_cache

class Settings(BaseSettings):
    gpt_api_key:str

    model_config = SettingsConfigDict(env_file=".env")

@lru_cache()
def get_settings():
    return Settings()

 

해당 파일에서는 .env 정의 후 효율적으로 재사용하기 위해  get_settings() 함수를 작성하였다.

이는 공식문서에서 추천하는 방식이다.

FASTAPI 공식문서

 

 

이제 사용하는 곳에서 setting.py를 import 후  settings.환경변수명 으로 사용하면 된다. 

ex) from app.settings import get_settings, Settings  

 

 

 

 

 

 

 

 

 

 

 

등록

langserve 라이브러리에서 제공하는 add_routes함수를 통해 

LangChain에서 만든 Runnable (예: LLM, Chain 등)을 FastAPI의 REST API로 등록해보자

 

 

 

예시

add_routes(
    app: FastAPI,
    runnable: Runnable,        # LangChain 객체
    path: str = "/invoke",     # 라우트 경로 (예: "/chat")
    enable_batch: bool = True,
    enable_streaming: bool = True,
    ...                        # 기타 옵션들
)

 

 

실제 코드

app = FastAPI()


# LangServe로 API 자동 등록 (UI 포함)
add_routes(app, chain, path="/ask")  # http://localhost:8000/ask 에서 POST 요청 처리 및 Web UI 제공

 

나는 저번에 만들었던 chain을 등록하였다.

다음과 같이 등록하면

path="/ask"이라면 아래 라우트가 자동 생성된다.

 

/ask/invoke	일반 POST 요청 처리
/ ask/batch	여러 요청 동시에 처리
/ ask /stream	스트리밍 응답 (token-by-token)
/ ask/docs	Swagger API 문서
/ ask/playground	입력값 실험할 수 있는 웹 UI

 

 

 

 

 

 

 

 

서버실행

uvicorn main:app --reload --port 8000

 

 

 

 

 

다만 앞서말한 주의사항처럼 스웨거로 접속 시 다음과 같은 에러가 발생했다.

 

pydantic.errors.PydanticUserError:
TypeAdapter[...] is not fully defined ...

 

LangServe 내부에서 FastAPI 문서(openapi.json)를 만들려고 할 때, 사용하는 Pydantic 모델이 완전히 정의되지 않은 상태여서 발생하는 것이라 했다. 이건 LangServe가 아직 Pydantic v2랑 100% 호환되지 않아서 그런것이다.

그러나 지금 사용하는 LangChain과 LangServe는 Pydantic 2.x 이상을 필요로 한다.

따라서 pydantic 1.x로 바꾸면 Swagger 오류는 해결되지만 langchain, langserve, langsmith가 정상 작동하지 않는다.

 

LangServe 안 쓰고 직접 FastAPI 라우터 짜는 방법도 있었으나, langServe의 기능을 포기하고 싶지 않아 Swagger 문서 포기하고 Playground로 사용하기로 했다.

 

LangServe는 Swagger /docs 대신 자체 Playground UI를 제공하기 떄문에 swagger와 별도로 사용 가능하다.

 

 

 

 

 

 

 

 

 

 

접속 화면

이제  http://localhost:8000/ask/playground/ 경로로 접속하면

자동 화면을 구성하고 api 응답도 보내준다