LangChain 기초 (0) - Introduction
LangChain 기초 시리즈 소개와 진행 순서, 실습 환경과 시리즈 내내 쓸 예제 문서 준비를 다룹니다.
손으로 짠 LLM 파이프라인을 프레임워크 부품으로 다시 조립하는 LangChain 기초 시리즈의 0편입니다. 시리즈 소개와 진행 순서를 다루며, 개념 정리가 1편, 실습은 2편부터 시작합니다.
무엇을 다루나
RAG 기초 시리즈와 LLM 에이전트 기초 시리즈는 “프레임워크로 세 줄에 끝내는 대신 직접 짠다”는 방향이었습니다. 이 시리즈는 그 반대 방향입니다. 손으로 짜 둔 그 코드를 LangChain 부품으로 하나씩 바꿔 끼우면서, 프레임워크가 무엇을 대신해 주고 무엇을 감추는지 봅니다.
범위는 부품 규격을 이해하는 일, 부품을 |로 이어 붙이는 일, 프롬프트와 출력을 문자열이 아니라 구조로 다루는 일, 검색 부품으로 RAG 파이프라인을 다시 세우는 일, 도구를 모델에 물리는 일, 그리고 체인을 띄워 놓고 스트리밍과 추적과 비용을 다루는 일까지입니다.
대조가 목적이라 예제는 새로 만들지 않습니다. RAG 시리즈에서 쓴 쇼핑몰 정책 문서 세 개와 같은 질문을 그대로 쓰고, 도구는 에이전트 시리즈의 주문 도구를 가져옵니다. 손으로 짠 결과와 부품으로 조립한 결과를 나란히 놓고 봅니다.
LangChain 1.x 기준입니다. 0.x에서 1.0으로 넘어오면서 네임스페이스가 크게 정리되어 LLMChain, AgentExecutor, ConversationBufferMemory 같은 이름은 더 이상 권장되지 않습니다. 인터넷에 남아 있는 예제 상당수가 0.x 문법이므로, 이 시리즈는 임포트 경로부터 1.x 기준으로 씁니다.
누구를 위한 시리즈인가
- LangChain 예제를 복사해 돌리기는 했는데
prompt | llm | parser의|가 정확히 무엇을 하는지 설명하지 못하는 사람 - 0.x 시절에 짠 코드를 들고 있는데 1.x에서 무엇을 바꿔야 하는지 모르는 사람
- 프레임워크를 쓸지 SDK를 직접 호출할지 정하지 못한 사람
Python 기본 문법을 전제로 합니다. LLM API 호출은 프롬프트 엔지니어링 기초 시리즈 1편 수준이면 충분합니다. RAG 시리즈와 에이전트 시리즈를 먼저 읽으면 대조가 선명해지지만, 읽지 않아도 따라올 수 있게 필요한 코드는 다시 싣습니다.
개념 요약만 필요하면 LangChain 기초 단편에 압축본이 있습니다. 이 시리즈는 그 한 편을 실습과 대조 중심으로 풀어 쓴 확장판입니다.
어떻게 진행하는가
여덟 편으로 진행합니다. 각 편은 앞 편의 방식이 버거워지는 지점에서 시작합니다.
| 편 | 주제 | 이 편이 끝나면 |
|---|---|---|
| (1) | Why LangChain: 손으로 짠 파이프라인이 무너지는 지점 | 이 작업에 프레임워크가 필요한지 판단할 수 있다 |
| (2) | Runnable and LCEL: 부품 규격과 파이프 합성 | 부품을 잇고 데이터가 어디로 흐르는지 읽는다 |
| (3) | Prompts and Output Parsers: 템플릿과 구조화 출력 | 프롬프트와 출력을 문자열이 아니라 구조로 다룬다 |
| (4) | Retrieval Components: 로더, 스플리터, 벡터스토어, 리트리버 | 손으로 짠 검색 코드를 부품으로 바꿔 끼운다 |
| (5) | RAG Chain: 검색과 생성을 한 표현식으로 | RAG 파이프라인이 하나의 표현식이 된다 |
| (6) | Tools and State: 도구 바인딩과 한 방향 흐름의 한계 | 체인으로 되는 것과 안 되는 것의 경계가 보인다 |
| (7) | Operations: 스트리밍, 추적, 재시도, 비용 | 돌아가는 체인 안에서 무슨 일이 일어나는지 본다 |
세 부로 묶입니다.
1부, 부품 익히기 (1편에서 3편). 1편에서 RAG 시리즈 5편의 생성 코드를 놓고 요구를 세 개 얹습니다. 제공자를 바꿔 봐라, 답을 스트리밍해라, 질문 100건을 배치로 돌려라. 손으로 짠 코드에서는 셋 다 다른 곳을 고쳐야 하고, 여기서 공통 인터페이스라는 발상이 나옵니다. 2편이 그 인터페이스인 Runnable과 합성 문법 LCEL입니다. 이 시리즈에서 가장 중요한 편이고, 나머지 전부가 여기서 파생됩니다. 3편에서 프롬프트 템플릿과 출력 파서를 붙여 입력과 출력의 양끝을 정리합니다.
2부, 다시 세우기 (4편과 5편). RAG 시리즈에서 numpy로 코사인 유사도를 계산하고 Chroma 클라이언트를 직접 다뤘던 코드를 부품으로 교체합니다. 4편에서 로더, 스플리터, 벡터스토어, 리트리버를 하나씩 바꿔 끼우고 손 코드와 chunk 경계를 비교합니다. 5편에서 그 리트리버를 LCEL로 엮어 출처가 붙은 답까지 만들고, 질문 재작성을 넣어 대화형으로 확장합니다.
3부, 경계와 운영 (6편과 7편). 6편에서 도구를 모델에 물립니다. 도구 하나를 부르는 것까지는 체인으로 되지만, 결과를 보고 또 부를지 정하는 순환은 한 방향 파이프로 표현하기 어렵습니다. LangChain 1.x가 이 지점에서 내놓은 답이 create_agent이고, 그것이 LangGraph 위에 올라가 있다는 사실이 다음 시리즈로 가는 이유가 됩니다. 7편은 운영입니다. 스트리밍, 추적, 캐싱, 재시도와 폴백, 토큰 집계를 다룹니다.
2편에서 만든 체인을 7편까지 이어 씁니다. 편이 넘어갈 때 코드를 버리고 새로 시작하지 않습니다.
실습 환경
Python 3.12 기준입니다. LangChain 1.x는 Python 3.10 이상을 요구합니다.
1
2
3
python3 -m venv .venv
source .venv/bin/activate
pip install -U "langchain[anthropic]" langchain-text-splitters langchain-chroma langchain-huggingface
| 패키지 | 쓰는 곳 |
|---|---|
langchain[anthropic] | 체인 조립과 Claude 호출 전 구간 |
langchain-text-splitters | 문서 분할 (4편) |
langchain-chroma | 벡터 스토어 (4편, 5편) |
langchain-huggingface | 한국어 embedding 모델 (4편) |
langchain[anthropic]은 본체인 langchain과 Claude용 통합 패키지를 함께 설치합니다. 부품의 기반 클래스가 들어 있는 langchain-core는 의존성으로 따라옵니다.
설치된 버전을 확인해 둡니다. 1.0 미만이면 이 시리즈의 임포트 경로가 맞지 않습니다.
1
python -c "import langchain; print(langchain.__version__)"
API key는 환경변수로 둡니다.
1
export ANTHROPIC_API_KEY="sk-ant-..."
모델은 claude-sonnet-5를 씁니다. 이 시리즈의 주제는 조립 방식이지 모델의 판단력이 아니라서, 같은 입력에 같은 부품을 통과시켰을 때 결과가 어떻게 흐르는지만 보면 충분합니다. embedding은 RAG 기초 3편에서 고른 한국어 모델을 그대로 씁니다.
예제 문서 만들기
시리즈 내내 쓸 문서 세 개를 만듭니다. RAG 기초 시리즈에서 쓴 온라인 쇼핑몰의 정책 문서와 같은 내용입니다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
mkdir -p docs
cat > docs/refund.md <<'EOF'
# 환불 및 반품 정책
## 단순 변심
상품 수령일로부터 7일 이내에 반품을 신청할 수 있습니다.
왕복 배송비 5,000원은 고객이 부담합니다.
상품을 사용했거나 포장을 훼손한 경우 단순 변심 반품은 불가합니다.
## 상품 하자
상품에 하자가 있거나 주문과 다른 상품이 배송된 경우,
수령일로부터 30일 이내에 무료로 반품 또는 교환할 수 있습니다.
이 경우 왕복 배송비는 회사가 부담합니다.
## 환불 처리 기간
반품 상품이 물류센터에 도착한 뒤 3영업일 이내에 환불을 처리합니다.
카드 결제는 환불 처리 후 카드사에 따라 3일에서 5일이 추가로 소요됩니다.
EOF
cat > docs/shipping.md <<'EOF'
# 배송 정책
## 배송비
기본 배송비는 3,000원입니다.
주문 금액이 30,000원 이상이면 배송비가 무료입니다.
제주 및 도서산간 지역은 3,000원이 추가됩니다.
## 출고와 도착
평일 오후 2시 이전에 결제된 주문은 당일 출고됩니다.
출고 후 영업일 기준 2일에서 3일 이내에 도착합니다.
주말과 공휴일에는 출고하지 않습니다.
## 송장 조회
송장번호는 출고 다음 날 오전부터 조회할 수 있습니다.
출고 당일에는 택배사 시스템에 등록되지 않아 조회되지 않습니다.
EOF
cat > docs/membership.md <<'EOF'
# 회원 등급 정책
## 등급 기준
최근 6개월 구매 금액을 기준으로 실버, 골드, 플래티넘 등급을 부여합니다.
실버는 30만원 미만, 골드는 30만원 이상, 플래티넘은 100만원 이상입니다.
## 등급별 혜택
적립률은 실버 1%, 골드 2%, 플래티넘 3%입니다.
골드 등급부터는 주문 금액과 관계없이 배송비가 무료입니다.
플래티넘 등급은 전용 상담 창구를 이용할 수 있습니다.
## 등급 산정 시점
등급은 매월 1일에 다시 계산되며, 계산된 등급은 한 달간 유지됩니다.
EOF
문서를 같게 쓰는 이유는 결과를 비교하기 위해서입니다. RAG 시리즈에서 이 세 문서를 400자에 overlap 50으로 잘라 chunk 7개를 얻었고, “골드 등급이면 배송비가 무료인가요?” 같은 질문으로 검색을 확인했습니다. 4편에서 같은 문서를 LangChain 스플리터에 넣고 chunk가 몇 개로 어떻게 갈리는지 나란히 놓습니다.
첫 호출이 되는지만 확인하고 넘어갑니다.
1
2
3
4
from langchain.chat_models import init_chat_model
model = init_chat_model("anthropic:claude-sonnet-5")
print(model.invoke("한 문장으로 자기소개 해줘.").text)
다음 글: LangChain 기초 (1) - Why LangChain: 손으로 짠 파이프라인이 무너지는 지점