🦜
LangChain 치트시트

LangChain 0.3+ 최신 기준: LCEL(LangChain Expression Language) 파이프 연산자, ChatModel(OpenAI/Claude/Ollama), 구조화된 출력(Pydantic), RAG 파이프라인(Chroma/FAISS), Tool Calling 및 LangGraph ReAct 에이전트 실전 완벽 가이드
#langchain#lcel#python#llm#rag#vectorstore#langgraph#agent#tool-calling#chroma#openai#claude#ollama최종 업데이트: 2026-10-06
LangChain 치트시트 핵심 명령어 및 실전 가이드

## 1. 필수 사전 설치 요건 & 개발 환경 구성 (Prerequisites)

LangChain 및 벡터 데이터베이스(Chroma, FAISS), 고성능 토크나이저(`tiktoken`), Pydantic C-Extension을 빌드 오류 없이 구동하기 위해 사전에 준비해야 하는 시스템 필수 요구사항입니다.

### 🐍 1. Python 버전 & 가상환경 (Virtual Environment)
LangChain 0.3+은 **Python 3.9 ~ 3.12+ (권장: Python 3.11 또는 3.12)** 환경을 지원합니다. 전역 패키지 오염 및 버전 충돌을 방지하기 위해 가상환경 생성이 **필수**입니다.

```bash
# 1. 표준 venv 가상환경 생성
python -m venv .venv

# 2. 가상환경 활성화 (Windows PowerShell)
# ※ 최초 1회 스크립트 실행 권한 필요: Set-ExecutionPolicy Unrestricted -Scope Process
.venv\Scripts\Activate.ps1

# 가상환경 활성화 (macOS / Linux / WSL)
source .venv/bin/activate

# 3. 또는 차세대 초고속 패키지 관리자 uv 사용 시 (강력 추천)
pip install uv
uv venv
# Windows: .venv\Scripts\activate / macOS: source .venv/bin/activate
uv pip install langchain langchain-core langchain-openai
```

### 🛠️ 2. OS별 C/C++ 빌드 도구 (Native Compiler)
`chromadb`(HNSWlib C++ 코어), `faiss-cpu`, `tiktoken` 등 C++/Rust 바인딩이 포함된 네이티브 패키지 설치 시 발생할 수 있는 빌드 에러를 사전에 방지하기 위한 도구입니다.

| 운영체제 (OS) | 필요 설치 도구 | 설치 방법 |
| :--- | :--- | :--- |
| **Windows** | Microsoft C++ Build Tools | [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) 설치 시 **"C++를 사용한 데스크톱 개발"** 워크로드 체크 |
| **macOS** | Xcode Command Line Tools | 터미널에서 `xcode-select --install` 실행 |
| **Linux (Ubuntu/Debian)** | `build-essential` & `python3-dev` | `sudo apt update && sudo apt install -y build-essential python3-dev` |

### 🦙 3. 로컬 무료 오프라인 LLM 엔진: Ollama (선택 사항)
OpenAI나 Claude 유료 API 키 없이 내 PC(로컬 GPU/CPU)에서 완전 무료 및 오프라인으로 LLM과 임베딩 모델을 실행하려면 **Ollama**를 사전에 설치합니다.
- **공식 다운로드**: [https://ollama.com](https://ollama.com) (Windows / macOS / Linux 지원)
- **로컬 모델 다운로드 및 백그라운드 서비스 기동**:
  ```bash
  # Llama 3.2 3B 고속 모델 다운로드 & 실행 테스트
  ollama run llama3.2

  # DeepSeek 최신 추론 모델
  ollama run deepseek-r1:8b

  # RAG 검색용 무료 고성능 임베딩 모델
  ollama pull nomic-embed-text
  ```

---

## 2. LangChain 0.3+ 아키텍처 & 패키지 설치

최신 **LangChain 0.3+**은 모놀리식 구조에서 탈피하여 경량 코어(`langchain-core`), 공급자별 패키지(`langchain-openai`, `langchain-anthropic`), 커뮤니티 플러그인(`langchain-community`), 그리고 에이전트 오케스트레이션(`langgraph`)으로 모듈화되었습니다.

```text
[LangChain 0.3+ 생태계 구조]
┌────────────────────────────────────────────────────────┐
│  LangGraph (상태 기반 멀티 에이전트, 루프 및 분기 제어)    │
├────────────────────────────────────────────────────────┤
│  LangChain (고수준 체인, 에이전트, RAG 오케스트레이션)    │
├──────────────────────┬─────────────────────────────────┤
│  langchain-community │  공급자 패키지 (langchain-openai, │
│  (서드파티 도구, 저장소) │  langchain-anthropic, ollama 등)│
├──────────────────────┴─────────────────────────────────┤
│  langchain-core (LCEL, Runnable 인터페이스, 메시지, 스키마) │
└────────────────────────────────────────────────────────┘
```

### 📦 의존성 패키지 일괄 설치 (pip & uv)
```bash
# 1. 핵심 프레임워크 & 주요 공급자 라이브러리
pip install langchain langchain-core langchain-community

# 2. 선호하는 LLM 공급자 패키지 선택 설치
pip install langchain-openai          # OpenAI (GPT-4o, o1, Text Embedding 3)
pip install langchain-anthropic       # Anthropic (Claude 3.5 Sonnet)
pip install langchain-ollama          # Ollama (로컬 무료 오프라인 모델 연동)

# 3. 토크나이저 & 환경변수 관리 & 데이터 검증
pip install tiktoken python-dotenv pydantic

# 4. RAG 벡터 저장소 & 문서 로더
pip install chromadb faiss-cpu pypdf beautifulsoup4

# 5. 차세대 ReAct 에이전트 프레임워크
pip install langgraph
```

### 🔑 환경 변수 설정 (`.env`)
프로젝트 루트 경로에 `.env` 파일을 생성하고 발급받은 API 키를 지정합니다:
```bash
# OpenAI API 키
OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxx"

# Anthropic Claude API 키 (선택)
ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxxxxxx"

# LangSmith 트레이싱 & 모니터링 (선택 사항 - 무료 가입 가능)
LANGCHAIN_TRACING_V2="true"
LANGCHAIN_API_KEY="lsv2_pt_xxxxxxxxxxxxxxxxxxxx"
LANGCHAIN_PROJECT="lucky-langchain-prod"
```

파이썬 코드 첫 줄에서 환경변수를 로드합니다:
```python
from dotenv import load_dotenv
load_dotenv()  # .env 파일 로드
```

---

## 3. LCEL (LangChain Expression Language) 기초

LCEL은 모든 LangChain 컴포넌트를 유닉스 파이프라인(`|`) 스타일로 연결하는 선언적 표준 문법입니다. 스트리밍, 비동기 호출, 병렬 실행이 기본 내장되어 있습니다.

### 🧩 기본 3단계 파이프라인: `Prompt | Model | OutputParser`
```python
import os
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

# 1. Chat 모델 초기화
llm = ChatOpenAI(model="gpt-4o", temperature=0.7)

# 2. 프롬프트 템플릿 정의
prompt = ChatPromptTemplate.from_messages([
    ("system", "당신은 IT 기술 전문 시니어 아키텍트입니다. 간결하고 명확하게 답변하세요."),
    ("human", "{topic} 기술의 핵심 장점 3가지를 불릿 포인트로 설명해줘.")
])

# 3. 문자열 출력 파서
output_parser = StrOutputParser()

# 4. LCEL 체인 조합 (Prompt -> Model -> Parser)
chain = prompt | llm | output_parser

# 5. 실행 (동기 호출)
response = chain.invoke({"topic": "Docker 컨테이너"})
print(response)
```

### ⚡ Runnable 핵심 메서드 치트시트
| 메서드 | 실행 방식 | 설명 |
| :--- | :--- | :--- |
| `chain.invoke(input)` | 동기 (Sync) | 단일 입력을 전달하고 최종 결과를 동기 반환 |
| `await chain.ainvoke(input)` | 비동기 (Async) | `asyncio` 환경에서 비동기 non-blocking 실행 |
| `chain.stream(input)` | 스트리밍 (Generator) | LLM 생성 토큰을 청크 단위로 실시간 yield |
| `chain.batch([in1, in2])` | 병렬 배치 | 여러 입력을 내부 스레드풀로 병렬 일괄 처리 |

---

## 4. ChatModel & 다양한 공급자 연동

LangChain은 동일한 인터페이스(`BaseChatModel`)로 상용 클라우드 LLM과 로컬 온프레미스 LLM을 손쉽게 교체할 수 있습니다.

### 🌐 OpenAI, Claude, 로컬 Ollama 모델 호출
```python
from langchain_core.messages import SystemMessage, HumanMessage, AIMessage

# 1. OpenAI (GPT-4o)
from langchain_openai import ChatOpenAI
gpt = ChatOpenAI(model="gpt-4o", temperature=0.2)

# 2. Anthropic (Claude 3.5 Sonnet)
from langchain_anthropic import ChatAnthropic
claude = ChatAnthropic(model="claude-3-5-sonnet-20241022", temperature=0.2)

# 3. Ollama (로컬 무료 LLM - 오프라인 구동 가능)
from langchain_ollama import ChatOllama
ollama_llama = ChatOllama(model="llama3.2:latest", base_url="http://localhost:11434")

# 공통 메시지 리스트 전달
messages = [
    SystemMessage(content="한국어로 친절하게 답변하는 AI 조수입니다."),
    HumanMessage(content="REST API와 GraphQL의 가장 큰 차이점은 뭐야?")
]

ai_response = gpt.invoke(messages)
print("응답 내용:", ai_response.content)
print("토큰 소비량:", ai_response.response_metadata.get("token_usage"))
```

---

## 5. 프롬프트 템플릿 & 동적 메시지 주입

### 💬 `ChatPromptTemplate` & 대화 히스토리 슬롯 (`MessagesPlaceholder`)
```python
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_core.messages import HumanMessage, AIMessage

chat_prompt = ChatPromptTemplate.from_messages([
    ("system", "당신은 친절한 고객 지원 상담원입니다."),
    # 이전 대화 기록이 동적으로 들어올 자리
    MessagesPlaceholder(variable_name="chat_history"),
    ("human", "{user_input}")
])

# 대화 이력 시뮬레이션
history = [
    HumanMessage(content="안녕하세요, 상품 환불 규정이 어떻게 되나요?"),
    AIMessage(content="구매 후 7일 이내 상품 훼손이 없는 경우 전액 환불 가능합니다.")
]

# 포맷팅 확인
formatted_messages = chat_prompt.format_messages(
    chat_history=history,
    user_input="배송비는 제가 부담해야 하나요?"
)
```

---

## 6. 구조화된 출력 (Structured Output with Pydantic)

최신 LLM 애플리케이션에서는 정규식 대신 **Pydantic 스키마**를 모델에 직접 바인딩하여 100% 보장된 JSON 객체로 응답을 파싱합니다.

### 🎯 `with_structured_output` (공식 권장 최신 방식)
```python
from pydantic import BaseModel, Field
from typing import List
from langchain_openai import ChatOpenAI

# 1. 기대하는 출력 데이터 모델 정의
class TechAnalysis(BaseModel):
    tech_name: str = Field(description="기술 이름")
    difficulty_level: str = Field(description="학습 난이도 (초급/중급/고급)")
    core_features: List[str] = Field(description="핵심 기능 3가지 목록")
    is_recommended_for_beginners: bool = Field(description="초보자 추천 여부")

# 2. 모델에 Pydantic 스키마 직접 바인딩
llm = ChatOpenAI(model="gpt-4o", temperature=0)
structured_llm = llm.with_structured_output(TechAnalysis)

# 3. 호출 시 Pydantic 객체가 즉시 반환됨
result: TechAnalysis = structured_llm.invoke("Kubernetes에 대해 기술 분석을 작성해줘.")

print(type(result)) # <class '__main__.TechAnalysis'>
print(f"기술: {result.tech_name}")
print(f"난이도: {result.difficulty_level}")
print(f"초보자 추천: {result.is_recommended_for_beginners}")
for feat in result.core_features:
    print(f" - {feat}")
```

---

## 7. RAG (검색 증강 생성) 완전 정복 파이프라인

외부 문서(PDF, 텍스트, 웹페이지)를 청킹하여 벡터 DB에 저장하고, 사용자의 질문과 가장 유사한 청크를 검색하여 답변을 생성하는 완성형 RAG 패턴입니다.

```text
[RAG 파이프라인 흐름도]
[Raw Documents] 
      │ (TextLoader / PDFLoader)
      ▼
[Text Chunks] ────► [Embedding Model] ────► [VectorStore (Chroma)]
                                                   │
[User Query] ─────► [Similarity Search] ───────────┘
                           │ (Top-K Chunks)
                           ▼
                  [Context + Prompt] ────► [LLM] ────► [최종 답변]
```

### 🛠️ 엔드투엔드 RAG 예제 (In-Memory Chroma + LCEL)
```python
from langchain_core.documents import Document
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_community.vectorstores import Chroma
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
from langchain_core.output_parsers import StrOutputParser

# 1. 사내 문서 샘플 준비 (실무에서는 PyPDFLoader, TextLoader 사용)
raw_docs = [
    Document(
        page_content="LuckyTech 사내 복지 규정: 모든 임직원은 연간 200만 원의 복지 포인트를 지원받으며, 도서 구매 및 체력 단련비로 사용할 수 있습니다. 재택근무는 주 2회 자율 신청 가능합니다.",
        metadata={"source": "hr_policy_2026.txt"}
    ),
    Document(
        page_content="보안 지침: 회사의 모든 소스코드는 개인 로컬 드라이브에 보관할 수 없으며, 반드시 2FA 인증이 활성화된 사내 GitLab 엔터프라이즈 저장소를 경유해야 합니다.",
        metadata={"source": "security_policy_2026.txt"}
    )
]

# 2. 청킹 (Text Splitting)
text_splitter = RecursiveCharacterTextSplitter(chunk_size=200, chunk_overlap=30)
splits = text_splitter.split_documents(raw_docs)

# 3. 임베딩 모델 & 벡터 스토어 생성
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
vectorstore = Chroma.from_documents(documents=splits, embedding=embeddings)

# 4. 검색기(Retriever) 생성 (상위 유사 청크 2개 검색)
retriever = vectorstore.as_retriever(search_kwargs={"k": 2})

# 5. 검색된 문서 리스트를 단일 문자열로 포맷팅하는 헬퍼 함수
def format_docs(docs):
    return "\n\n".join(f"[{doc.metadata.get('source')}]: {doc.page_content}" for doc in docs)

# 6. RAG 프롬프트 정의
rag_prompt = ChatPromptTemplate.from_template("""
당신은 사내 지식 기반 Q&A 도우미입니다. 아래 제공된 [참고 문서] 내용만을 바탕으로 답변하세요.
만약 문서에 없는 내용이라면 "제공된 문서에서 관련 정보를 찾을 수 없습니다."라고 정직하게 답하세요.

[참고 문서]
{context}

[질문]
{question}
""")

llm = ChatOpenAI(model="gpt-4o", temperature=0)

# 7. LCEL RAG 체인 구축
rag_chain = (
    {"context": retriever | format_docs, "question": RunnablePassthrough()}
    | rag_prompt
    | llm
    | StrOutputParser()
)

# 8. 질문 실행
answer = rag_chain.invoke("복지 포인트 금액이랑 재택근무 규정이 어떻게 돼?")
print("답변:\n", answer)
```

---

## 8. Tool 정의 (`@tool`) & Tool Calling (도구 호출)

LLM이 실시간 계산기, 날씨 API, 데이터베이스 조회 등 외부 시스템을 직접 호출하도록 만드는 핵심 기능입니다.

### 🧰 커스텀 도구 정의 및 바인딩
```python
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI

# 1. @tool 데코레이터로 도구 선언 (타입 힌트와 독스트링이 모델의 도구 설명서가 됨)
@tool
def get_current_stock_price(ticker: str) -> str:
    """주식 종목 티커(예: AAPL, MSFT, 005930)를 받아 현재 주식 가격을 조회합니다."""
    # 실제로는 금융 API 호출
    dummy_prices = {"AAPL": "$235.50", "MSFT": "$420.10", "005930": "72,500원"}
    price = dummy_prices.get(ticker.upper(), "알 수 없음")
    return f"{ticker}의 현재 주가는 {price}입니다."

@tool
def calculate_tax(amount: float, tax_rate: float = 0.1) -> float:
    """금액과 세율(기본 10%)을 입력받아 부가세 금액을 계산합니다."""
    return amount * tax_rate

# 2. 모델에 도구 바인딩
llm = ChatOpenAI(model="gpt-4o", temperature=0)
tools = [get_current_stock_price, calculate_tax]
llm_with_tools = llm.bind_tools(tools)

# 3. 도구 호출 요청 테스트
response = llm_with_tools.invoke("애플(AAPL) 주가가 지금 얼마인지 확인해줘.")

# LLM이 도구 호출 계획(tool_calls)을 수립했는지 확인
if response.tool_calls:
    for call in response.tool_calls:
        print(f"호출할 도구명: {call['name']}")
        print(f"전달할 인자: {call['args']}")
```

---

## 9. LangGraph 기반 ReAct 에이전트 & 대화 메모리

최신 LangChain 생태계에서는 구버전 `AgentExecutor` 대신 **LangGraph**의 `create_react_agent`를 사용하는 것이 공식 표준입니다. 상태 저장(MemorySaver)을 통해 이전 대화를 완벽히 기억합니다.

### 🤖 단 10줄로 완성하는 실전 ReAct 에이전트
```python
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent
from langgraph.checkpoint.memory import MemorySaver

# 1. 에이전트가 활용할 도구 준비
@tool
def add(a: int, b: int) -> int:
    """두 정수를 더합니다."""
    return a + b

@tool
def multiply(a: int, b: int) -> int:
    """두 정수를 곱합니다."""
    return a * b

tools = [add, multiply]
llm = ChatOpenAI(model="gpt-4o", temperature=0)

# 2. 단기 대화 세션 유지를 위한 인메모리 체크포인터
memory = MemorySaver()

# 3. LangGraph ReAct 에이전트 생성
agent_executor = create_react_agent(
    model=llm,
    tools=tools,
    checkpointer=memory
)

# 4. 세션 ID 지정 실행
config = {"configurable": {"thread_id": "session-user-123"}}

# 첫 번째 대화 (도구 다중 호출 수행)
res1 = agent_executor.invoke(
    {"messages": [("user", "15 더하기 27을 계산하고, 그 결과에 3을 곱해줘.")]},
    config=config
)
print("에이전트 답변:", res1["messages"][-1].content)

# 두 번째 대화 (이전 문맥 기억 확인)
res2 = agent_executor.invoke(
    {"messages": [("user", "방금 나온 최종 숫자에 10을 더하면 얼마야?")]},
    config=config
)
print("후속 질문 답변:", res2["messages"][-1].content)
```

---

## 10. 실시간 스트리밍 & 비동기 (SSE / Web API 연동)

FastAPI나 Web 서버 환경에서 토큰이 생성되는 즉시 사용자 화면에 타이핑 효과로 전송하는 스트리밍 패턴입니다.

### 🌊 토큰 청크 단위 스트리밍
```python
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

llm = ChatOpenAI(model="gpt-4o", streaming=True)
prompt = ChatPromptTemplate.from_template("시니어 개발자가 갖추어야 할 마인드셋을 조언해줘: {topic}")
chain = prompt | llm | StrOutputParser()

# stream() 제너레이터로 한 글자씩 실시간 수신
print("스트리밍 시작: ", end="", flush=True)
for chunk in chain.stream({"topic": "코드 리뷰 문화"}):
    print(chunk, end="", flush=True)
print("\n[완료]")
```

### ⚡ FastAPI 비동기 SSE (Server-Sent Events) 스트리밍 연동
```python
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import asyncio

app = FastAPI()

@app.get("/chat/stream")
async def chat_stream_endpoint(query: str):
    async def event_generator():
        async for chunk in chain.astream({"topic": query}):
            # SSE 표준 포맷 (data: <payload>\n\n)
            yield f"data: {chunk}\n\n"
            await asyncio.sleep(0.01)

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

---

## 11. 프로덕션 운영 & 실무 베스트 프랙티스

### 💡 실무 개발자 체크리스트
1. **Pydantic 스키마 필수 적용**: 비정형 텍스트 대신 `with_structured_output`을 사용하여 API 통신 신뢰도를 99.9%로 유지하세요.
2. **청크 사이즈 최적화**: 한국어 텍스트는 토큰 밀도가 높으므로 `chunk_size=300~500`, `chunk_overlap=50` 내외가 검색 정확도에 가장 적합합니다.
3. **LangSmith 트레이싱 활성화**: 복잡한 체인과 에이전트가 어떤 도구를 호출하고 중간 입력/출력이 무엇이었는지 시각적 대시보드로 확인하면 디버깅 시간이 80% 단축됩니다.
4. **AgentExecutor 대신 LangGraph 채택**: 복잡한 조건 분기, 인간 개입(Human-in-the-loop), 멀티 에이전트 협업은 최신 표준인 LangGraph로 작성해야 장기 유지보수가 가능합니다.
5. **토큰 비용 절감**: 단순 분류나 의도 파악은 소형 고속 모델(GPT-4o-mini, Claude 3.5 Haiku)을 거치고, 최종 복잡 답변 생성에만 고급 모델(GPT-4o)을 호출하는 라우팅 체인을 구성하세요.
💬
LangChain 치트시트

의견 및 질문

댓글 수정

댓글 삭제
