TL;DR — LangChain은 1.0(2025-10-22 GA)부터 단일 패키지가 아니라
langchain-core · langchain · langchain-community · 파트너 패키지
4계층 + 레거시 langchain-classic으로 나뉩니다. 옛 튜토리얼의 LLMChain · RetrievalQA · ConversationBufferMemory · AgentExecutor는 대부분 폐기되어 classic으로 옮겨졌습니다. 새 코드는 init_chat_model · with_structured_output · create_agent를 씁니다. 그래서 옛 코드를 최신 설치에서 그대로 돌리면 ImportError가 납니다.
이 글은 옛 LangChain 자료(0.1~0.2)로 입문했거나 1.0을 처음 보는 개발자가 1.0이 무엇을 바꿨는지(패키지·버전·폐기)를 이해하도록 돕습니다. 나아가 새 코드의 진입점(init_chat_model · 메시지 · 구조화 출력)으로 갈아탈 기준을 얻도록 돕습니다.
이 글에서 다루는 것
- 패키지 4계층 + langchain-classic 분리 구조
- 버전 진화 타임라인과 1.0 안정성(LTS) 정책
- 코어 진입점: init_chat_model · 메시지 · with_structured_output
- 레거시 → 현행 마이그레이션 지도
이 글에서 다루지 않는 것
- LCEL·LangGraph·에이전트·RAG 상세 (2~5편에서)
- 관측·평가(LangSmith) (6편에서)
1. 왜 LangChain 1.0이 분기점인가
LangChain으로 검색해서 나온 블로그 글을 따라 쳤는데 ImportError가 났다면, 코드를 잘못 친 게 아닐 가능성이 큽니다. 그 글이 0.1~0.2 시절에 쓰였기 때문입니다. 지금 설치되는 LangChain은 1.0(2025-10-22 GA) 이후입니다.
이 시리즈는 Chapters_RAG/LangChain의 1.x 기준 통합 정리를 6편으로 나눠, LangChain을 지금 버전 기준으로 다시 익히는 과정입니다. 첫 편의 목표는 단 하나, "내가 보는 코드가 현행인지 레거시인지" 구분하는 눈을 갖는 것입니다. 그 기준이 서면 나머지 편(LCEL · LangGraph · 에이전트 · RAG · LangSmith)이 훨씬 빠르게 읽힙니다.
비유하면 LangChain 1.0은 이사를 끝낸 집과 같습니다. 가구(클래스)는 대부분 그대로지만, 방 배치(패키지)가 바뀌었습니다. 짐을 못 찾는 이유는 짐이 사라져서가 아니라 다른 방으로 옮겨졌기 때문입니다. 그래서 먼저 집 구조부터 봅니다.
2. 흔한 오해 — "langchain 하나만 설치하면 끝"
가장 흔한 오해는 "pip install langchain 하나면 모든 게 들어온다"는 생각입니다. 0.0.x 모놀리식 시절에는 어느 정도 맞았지만, 지금은 다릅니다.
즉 1.0은 무거운 단일 패키지를 역할별로 쪼갠 4계층 + 레거시 분리 구조로 바뀌었습니다. 이걸 모르면 "분명 문서에 있는 클래스인데 import가 안 된다"는 상황에 계속 부딪힙니다. 다음 절에서 그 구조를 봅니다.
3. 패키지 4계층 + langchain-classic
1.0의 패키지는 아래처럼 역할별로 나뉩니다. 무엇이 어느 패키지에 있는지가 곧 "import가 되느냐"를 결정합니다.
pip install langchain-classic 필요여기에 더해 에이전트 런타임인 langgraph가 별도 패키지로 있습니다. 뒤에서 보겠지만 1.0의 create_agent는 내부적으로 LangGraph 그래프로 컴파일됩니다. 그래서 에이전트를 쓰면 langgraph도 함께 깔립니다.
4. 버전 진화 타임라인 & 1.0 안정성 정책
내가 보는 자료가 "언제 것"인지 가늠하려면 버전 분기점을 알아야 합니다. 굵직한 흐름은 이렇습니다.
📌 안정성 정책 — 1.0은 첫 메이저 안정 릴리스로 2.0까지 breaking change가 없습니다(LTS). 폐기(deprecated) ≠ 즉시 제거입니다. 실제 제거는 2.0에서만 일어납니다. 즉 폐기 API도 1.x 동안은 동작합니다. 다만 새 코드는 현행을 쓰는 게 맞습니다. 또한 1.x는 Python 3.10~3.14를 요구합니다(3.9는 1.0에서 종료).
5. 코어 진입점 ① — 모델 초기화 init_chat_model
현행 코드의 사실상 진입점은 벤더 클래스를 직접 import 하는 게 아니라 프로바이더 무관 초기화입니다.
이렇게 쓰는 이유는 프로바이더 교체 비용 때문입니다. "openai:gpt-5.5"를 "anthropic:..."로 바꾸기만 하면 모델이 교체됩니다. 공통 파라미터(temperature · max_tokens · timeout · max_retries)도 한 자리에서 다룹니다. 다만 모델 자체는 해당 파트너 패키지에서 오므로, 그 패키지 설치는 전제입니다. 임베딩도 같은 방식으로 init_embeddings(...)를 씁니다.
6. 코어 진입점 ② — 메시지 & 구조화 출력
대화는 역할이 다른 메시지의 리스트입니다. import는 from langchain.messages import ...(core 재export)로 합니다.
| 메시지 | 역할 |
|---|---|
| HumanMessage | 사용자 입력 |
| AIMessage | 모델 응답(도구 호출 시 .tool_calls 보유) |
| SystemMessage | 모델 동작 지시 |
| ToolMessage | 도구 실행 결과(tool_call_id로 연결) |
옛 자료의 FunctionMessage는 옛 functions API 잔재입니다. 현행 tools API에서는 AIMessage.tool_calls → ToolMessage 흐름을 씁니다. 텍스트 외에 이미지·오디오·파일을 함께 보낼 때는 content_blocks로 멀티모달 입력을 구성합니다.
검증된 객체를 받고 싶다면 1순위는 with_structured_output입니다. 옛 자료의 JSON/CSV 파서로 텍스트를 후처리하던 방식보다 신뢰도가 높습니다.
여기서 한 가지가 중요합니다. 1.0은 Pydantic v2를 전제하므로 스키마는 from pydantic import BaseModel로 직접 import 합니다. 옛 자료의 langchain_core.pydantic_v1은 폐기 경로이며, 구조화 출력·도구 스키마가 전부 v2 기반이라 영향이 광범위합니다.
7. 레거시 → 현행 마이그레이션 지도
옛 코드를 1.0에서 만났을 때 무엇으로 바꿔야 하는지, 같은 작업을 두 시대의 코드로 나란히 보면 한눈에 들어옵니다.
| 레거시 (옛 자료) | 현행 (1.x) |
|---|---|
| LLMChain / SequentialChain | LCEL prompt | model | parser (호환: langchain-classic) |
| RetrievalQA | 2-step LCEL RAG / Agentic RAG (5편) |
| ConversationBufferMemory | LangGraph checkpointer + thread_id (3편) |
| AgentExecutor + 텍스트 ReAct | langchain.agents.create_agent (4편) |
| JsonOutputParser(스키마 강제) | model.with_structured_output(Schema) |
| langchain_core.pydantic_v1 | from pydantic import BaseModel (v2) |
| 벤더 클래스 직접 import만 | init_chat_model("provider:model") |
표에서 "(N편)"으로 표시한 항목은 이 시리즈 뒤 편에서 본격적으로 다룹니다. 당장 옛 코드를 살려야 한다면 langchain-classic을 설치해 import 경로만 바꾸면 동작은 합니다. 다만 그건 임시방편이고, 신규 코드는 오른쪽(현행)으로 쓰는 것을 권합니다.
8. 시작하기 — 설치와 첫 코드
환경
- 언어/런타임: Python 3.10 이상(1.x 요구)
- 핵심: langchain · langchain-core · 파트너 패키지(예: langchain-openai)
- 선택: langgraph(에이전트) · langchain-classic(레거시 호환)
이 다섯 줄에 1.0의 진입점이 다 들어 있습니다. init_chat_model로 모델을 잡습니다. ChatPromptTemplate로 메시지를 구성한 뒤 파이프(|)로 잇는 LCEL입니다. 파이프가 왜 이렇게 강력한지는 다음 편에서 다룹니다. 지금은 "옛 LLMChain 대신 이렇게 쓴다"만 기억하면 충분합니다.
시리즈: 01 LangChain 1.0 시작하기 → 02 LCEL & Runnable → 03 LangGraph → 04 create_agent → 05 현대 RAG → 06 LangSmith
9. 정리 · 다음 편
LangChain 1.0은 가구를 버린 게 아니라 방을 새로 나눈 집입니다. 어느 방에 무엇이 있는지(패키지 4계층)와, 언제부터 그렇게 됐는지(버전 타임라인)를 알면, 옛 자료와 새 자료를 헷갈리지 않고 읽을 수 있습니다. 다음 편에서는 그 집의 배관 역할을 하는 LCEL과 Runnable — 파이프(|) 하나로 모델·프롬프트·파서를 잇는 표준 인터페이스를 봅니다.
- langchain-ai/langchain — 공식 저장소(소스·릴리스·CHANGELOG)
- LangChain — v1 마이그레이션 가이드
- LangChain — 릴리스 / 안정성 정책
'LangChain' 카테고리의 다른 글
| LLM 앱 운영 5종 세트 — 트레이싱·Async 콜백·LLM-as-judge·usage_metadata·캐싱 (0) | 2026.07.01 |
|---|---|
| 현대 RAG — 로드·분할부터 하이브리드 검색과 Agentic RAG까지 (0) | 2026.06.30 |
| create_agent & 미들웨어 — LangChain 1.0 에이전트 표준 (0) | 2026.06.29 |
| LangGraph 입문 — LCEL로 안 되던 순환·기억·사람 개입을 그래프로 풀기 (0) | 2026.06.26 |
| 파이프(|) 하나로 invoke·batch·stream이 공짜로 따라오는 이유 — LangChain Runnable (0) | 2026.06.24 |