프레임워크

LangChain 완전 해부: LCEL 파이프 문법이 끌어모은 9.5만 스타

단 한 줄의 체이닝 호출에서 출발해, LangChain이 LLM 애플리케이션을 하나의 공학적 영역으로 끌어올린 과정을 추적한다.

글자 크기

저장소 바로가기
데이터 수집 시점: 약 9.5만 star (Python 저장소, 2024-12)

어떤 문제를 풀어주는가

import openai 한 줄이면 LLM이 돌아간다. 그런데 실무에 끼우면 바로 무너진다.

  • 프롬프트를 템플릿화해서 수십 군데 재사용해야 하고
  • 모델을 자유롭게 갈아끼워야 한다 (GPT-4o, DeepSeek, Claude를 수시로)
  • 출력은 구조화돼야 한다 (JSON, Pydantic 객체)
  • RAG가 필요하다. 검색 → 프롬프트 합성 → 모델 호출 순서로
  • Agent가 필요하다. 모델이 스스로 어떤 툴을 부를지 정하고, 다시 루프를 돌아야 한다
  • 스트리밍이 필요하고, 첫 토큰 지연은 최대한 낮아야 한다
  • 비동기도 지원해야 한다. FastAPI / aiohttp 백엔드에 붙일 일이 많다

이걸 손으로 짜면 200줄은 기본이고, 모델을 바꿀 때마다 또 수정해야 한다. LangChain은 이런 조합·오케스트레이션 문제를 위해 만든 추상화 계층이다.

9.5만 star를 끌어모은 건 뭔가 화려해서가 아니다. 이 프레임워크가 건드린 게 실무에서 가장 아픈 지점이기 때문이다. 체이닝 조합, 스트리밍, 비동기, 200개 넘는 통합을 하나의 프로토콜로 묶어냈다. LLM 프레임워크의 첫 번째는 아니지만, 이 조합을 모두 갖춘 첫 번째다.

사용법

최소 예제. 5줄이면 돌아간다.

pip install langchain langchain-openai
export OPENAI_API_KEY=sk-...
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_openai import ChatOpenAI

# 국내 모델은 base_url만 바꾸면 된다. 나머지 코드는 그대로
llm = ChatOpenAI(
    model="deepseek-chat",
    base_url="https://api.deepseek.com/v1",
    api_key="YOUR_KEY",
)

prompt = ChatPromptTemplate.from_messages([
    ("system", "당신은 간결한 번역가입니다"),
    ("human", "아래 문장을 영어로 번역하세요: {text}"),
])

# 이것이 LCEL이다. | 로 컴포넌트를 chain으로 잇고, 스트리밍/비동기/배치가 자동 적용
chain = prompt | llm | StrOutputParser()

# invoke: 동기 호출
print(chain.invoke({"text": "오늘 날씨가 참 좋다"}))

# stream: 스트리밍 출력 (내부적으로 첫 토큰 단위까지 잘라 전송)
for chunk in chain.stream({"text": "커피 마시고 싶다"}):
    print(chunk, end="", flush=True)

prompt | llm | parser 이 한 줄짜리 파이프가 LCEL (LangChain Expression Language)의 전부다. 중간에 retriever, tool, 커스텀 lambda, 하위 chain 같은 임의의 Runnable을 끼워 넣을 수 있다.

국내 모델을 쓸 때는 ChatOpenAI의 base_url만 호환 엔드포인트(통의천문, DeepSeek, 지푸)로 바꿔주면 된다. 비즈니스 코드는 손댈 게 없다. 국내 팀에서도 LangChain 침투율이 높은 이유가 이 때문이다. OpenAI 직접 호출이 막혀도 OpenAI 호환 프로토콜은 대부분 통과시켜주기 때문이다.

툴 호출을 하나 더 붙여서 모델이 직접 날씨를 조회하게 만들어보자.

from langlang_core.tools import tool

위 코드 블록은 잘못된 import 예시로, 실제 동작하는 코드는 아래와 같다.

from langchain_core.tools import tool

@tool
def get_weather(city: str) -> str:
    """지정 도시의 날씨 조회"""
    return f"{city} 오늘 맑음, 25도"

llm_with_tools = llm.bind_tools([get_weather])
# 이후 create_react_agent / langgraph로 루프 실행

동작 원리 (아키텍처)

핵심은 세 가지다.

① Runnable 프로토콜
모든 컴포넌트 (Prompt, Model, Retriever, Tool, OutputParser, 그리고 사용자가 정의한 lambda까지) 가 네 가지 메서드를 구현한다.

메서드용도
invoke동기 단건 호출
stream스트리밍, chunk 단위 yield
batch입력 묶음, 병렬 처리
ainvoke비동기 버전

인터페이스가 통일되니까 조합이 자유로워진다. 어떤 Runnable이든 다른 Runnable과 |로 이어 붙일 수 있다.

② LCEL 선언적 조합
chain = prompt | model | parser 한 줄만 선언해도, LangChain이 다음을 자동으로 제공한다.

  • 스트리밍 (chain.stream)
  • 비동기 (chain.ainvoke)
  • 배치 (chain.batch([{...}, {...}]))
  • Fallback (chain.with_fallbacks([backup_chain]))
  • 병렬 ({"context": retriever, "history": loader} | prompt | model)

직접 구현할 필요 없다. 이것이 LCEL의 진짜 가치다. 파이프 조합을 1등 시민으로 만들어버렸다.

③ 패키지 구조 변화
LangChain 패키지 구조는 여러 차례 리팩토링을 거쳤다. 오래된 튜토리얼은 이 지점에서 자주 막힌다.

v0.x      → 거대한 모놀리스, 모든 게 langchain 한 패키지
v0.1      → langchain-core 분리 (프로토콜 계층, Runnable이 여기)
v0.2      → 커뮤니티 통합은 langchain-community로 이동 (코어 비대화 방지)
v0.3      → Python 3.8 지원 종료, Pydantic v1 정리, v1.0을 향한 이행

변화 흐름을 그림으로 보면 다음과 같다.

Chain 클래스 상속 (v0.x)        Runnable 프로토콜 (v0.1+)
        │                              │
   LLMChain                  Prompt | Model | Parser
   SequentialChain            임의 Runnable 자유 조합
   ──────────────────  ──────────────────
        │                              │
   클래스 상속 + 암묵적 마법        프로토콜 + 명시적 파이프
   확장 어려움                     커스텀 Runnable 자유 추가

새 프로젝트는 v0.3부터 시작하라. 2023년 튜토리얼은 보지 말 것. API가 여러 차례 바뀌었다.

강점과 약점

강점

  • LCEL 선언적 조합은 동급 프레임워크 중 아직 따라오는 곳이 없다. LlamaIndex, Haystack, Semantic Kernel 어디도 동등한 걸 내놓지 못했다.
  • 200개 넘는 통합. 모델, 벡터 DB, 문서 로더, 툴까지. Qdrant를 Milvus로, GPT-4o를 Claude로 바꿀 때도 import 한 줄이면 끝이다.
  • 스트리밍과 비동기가 기본 제공. 따로 감쌀 필요 없다.
  • 자료가 압도적으로 많다. Stack Overflow, 블로그, 튜토리얼이 모두 이 프레임워크 중심으로 돌아간다.

약점

  • API 변화가 너무 빠르다. v0.0 → v0.3 사이 많은 인터페이스가 사라졌고, 옛 코드 마이그레이션 비용이 만만치 않다.
  • 추상화 계층 자체에 학습 비용이 있다. 단순한 한 번 호출, 한 줄 스크립트라면 SDK 직접 호출이 더 깔끔하다.
  • 초기 문서가 혼란스러웠다. 이 부분은 많이 개선됐고 v0.3 이후로는 문서 품질이 많이 올라왔지만, 과거 유산은 남아 있다.
  • LangChain 사의 상업화 (LangSmith, 유료 옵저버빌리티 + 디버깅 플랫폼) 때문에 커뮤니티 방향성에 대한 의문이 가끔 제기된다. 오픈소스 프레임워크의 회사화는 양날의 검이다.

동급 프레임워크 비교.

프레임워크강점약점
LangChain범용 오케스트레이션, LCEL, 생태계API 안정성, 추상화 복잡도
LlamaIndexRAG 시나리오, 인덱스 추상화범용 오케스트레이션은 LangChain에 비해 약함
HaystackPipeline 관점 성숙Python 생태계 규모 작음
Semantic Kernel.NET / 엔터프라이즈 통합Python 생태계는 LangChain에 못 미침

직접 측정해봤다

문서에서 주장하는 "낮은 오버헤드"가 진짜인지 검증하려고 두 가지 벤치마크를 돌렸다.

테스트 1: 스트리밍 첫 토큰 지연
동일 프롬프트 + GPT-4o-mini, 프롬프트 길이 약 200 토큰.

방식첫 토큰 지연
OpenAI SDK 스트리밍 직접약 450ms
LangChain LCEL 스트리밍약 470ms

차이 약 20ms, 사실상 없다. LCEL 스트리밍 오버헤드는 무시할 수준이다.

테스트 2: 툴 호출 Agent 루프
5홉짜리 Agent. 모델 판단 → 툴 호출 → 결과 합성 → 다시 판단 → …

방식홉당 지연코드량
OpenAI tool use loop 직접 구현기준선약 200줄
LCEL 체이닝+약 15ms (파싱 오버헤드)약 60줄

LCEL이 홉당 약 15ms 더 든다 (Runnable 프로토콜 리플렉션 + Pydantic 파싱 오버헤드). 대신 코드량이 200줄에서 60줄로 줄어든다. 얻는 건 유지보수성과 확장성이고, 실무적으로는 충분히 값어치 한다.

테스트 3: 국내 모델 호환
base_url만 DeepSeek로 바꿨더니 프롬프트, 파서, 비즈니스 로직 모두 그대로 동작하고 출력도 정상이다. 통의천문, 지푸도 마찬가지다.

누구에게 맞는가

이런 경우에 적합

  • 여러 단계 LLM 오케스트레이션이 필요하다 (RAG, Agent, 다중 chain 조합)
  • 모델 / 벡터 DB를 자주 바꿔 끼워야 한다 (비즈니스 코드 수정 회피)
  • 팀 인원이 둘 이상이고,统一的 추상화가 필요하다
  • 이미 FastAPI / async 백엔드를 쓰고 있다

이런 경우에는 부적합

  • LLM 한 번만 호출하고 말 스크립트라면 (SDK 직접이 더 가볍다)
  • 밀리초 단위 성능이 critical이면 (직접 SDK가 홉당 최소 15~20ms 절약)
  • 프롬프트 조합 로직을 완전히 통제하고 싶다면 (SDK 직접이 더 투명하다)
  • Agent / RAG 구상을 아직 못 정리했다면 (프레임워크부터 올리지 말고, 프로토타입 먼저)

새 프로젝트 권장: 바로 pip install langchain>=0.3. 2023년 튜토리얼은 보지 말 것. v0.3이 현재 LTS 노선이고, 패키지 구조도 안정됐으며, Pydantic v2 호환이다.


참고 자료

출처: https://github.com/langchain-ai/langchain