저장소 바로가기
데이터 수집 시점: 약 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 안정성, 추상화 복잡도 |
| LlamaIndex | RAG 시나리오, 인덱스 추상화 | 범용 오케스트레이션은 LangChain에 비해 약함 |
| Haystack | Pipeline 관점 성숙 | 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 호환이다.
참고 자료