랭체인 v0.2 to v0.3으로 변화하면서 달라진 import 경로와 주요사항 정리

LangChain v0.3에서 핵심 모듈이 대폭 분리되어 langchain_core라는 독립 패키지로 다수 기능이 이동되었습니다. 주요 변화 및 표 보완은 아래와 같습니다.

주요 컴포넌트	v0.2 import 경로	v0.3 import 경로
기본 패키지	langchain	langchain
커뮤니티/커넥터	langchain_community	langchain_community
OpenAI Chat 모델	langchain.chat_models.OpenAI	langchain_openai.chat_models.OpenAI
OpenAI Embeddings	langchain.embeddings.OpenAIEmbeddings	langchain_openai.embeddings.OpenAIEmbeddings
Azure OpenAI	langchain.llms.AzureOpenAI	langchain_openai.AzureOpenAI
Tool	langchain.agents.Tool	langchain_core.tools.Tool
Agent	langchain.agents.initialize_agent	langgraph.prebuilt.create_react_agent
Pydantic(1.x)	langchain_core.pydantic_v1, langchain.pydantic_v1	사용 불가(삭제), pydantic 직접 import
Custom Validator	from pydantic import validator	from pydantic import field_validator
Document 구조	langchain.schema.Document	langchain_core.documents.Document
Prompt Template	langchain.prompts.PromptTemplate	langchain.prompts.PromptTemplate
Memory	langchain.chains.conversation.memory	langchain_core.memory
Gemini(Google Generative AI)	(공식지원 없음, community 커스텀)	langchain_google_genai.ChatGoogleGenerativeAI

langchain_core 분리로 인한 주요 변화

Document, Tool, Memory 등 다양한 핵심 타입과 모듈이 langchain_core로 이동: 이전까지는 langchain.schema.Document 등으로 불러왔으나, v0.3부터는 대부분 langchain_core.documents.Document, langchain_core.tools.Tool, langchain_core.memory 등으로 import해야 합니다.
Tool 래핑 및 Agent 관련 로직: langchain.agents.Tool에서 langchain_core.tools.Tool로 변경 필요. 에이전트 생성은 langgraph.prebuilt 경로 이용.
Schema/구조체 전반: 여러 기본형 schema, validator 등이 langchain_core 네임스페이스로 대거 이동하여, migration 시 import 경로 재검토가 필수입니다.

이 표와 설명을 참고하면 패키지 마이그레이션과 코드 리팩터링 시 langchain_core 도입 영역과 import 경로 변경을 한눈에 파악할 수 있습니다.

아래는 랭체인(LangChain) v0.2와 v0.3에서 간단한 “서울의 날씨” 질의를 예시로 사용할 때의 문법 차이를 비교한 내용입니다.

주요 변경점 요약

v0.3 주요 변화
- 내부적으로 Pydantic 1 → 2 업그레이드: 기존 validator, Field 등에서 field_validator 등으로 변경 필요
- 더 이상 langchain_core.pydantic_v1나 langchain.pydantic_v1 등 사용 금지, 모두 pydantic에서 직접 import
- 대부분의 패키지 import 경로가 변경되고 일부는 분리(특히 community/파트너 패키지)
- 툴 및 API 래퍼의 정의 방식과 래핑이 더 단순·명확해짐
- 구버전 인터페이스는 0.4에서 제거 예정, 0.3에서는 deprecated 처리

실제 코드 변화 예시

v0.2: 서울의 날씨 질의

from langchain_community.utilities import OpenWeatherMapAPIWrapper

import os
os.environ["OPENWEATHERMAP_API_KEY"] = "발급받은_키"

weather = OpenWeatherMapAPIWrapper()
print(weather.run("Seoul,KR"))

langchain_community에서 유틸리티 가져옴
Wrapper 객체 직접 생성 및 run 메소드로 호출

v0.3: 서울의 날씨 질의

from langchain_community.utilities import OpenWeatherMapAPIWrapper

import os
os.environ["OPENWEATHERMAP_API_KEY"] = "발급받은_키"

weather = OpenWeatherMapAPIWrapper()
print(weather.run("Seoul,KR"))

코드 자체의 큰 변화는 없음
내부적으로 Pydantic 2를 사용, import 방식에 주의 필요
만약 커스텀 툴이나 pydantic 모델을 함께 쓴다면, validator → field_validator로 변경 필요 (ex: 커스텀 툴 제작 시)

Agent와 Tool 활용 시 예시 변화

v0.2 스타일 예시

from langchain_community.utilities import OpenWeatherMapAPIWrapper
from langchain.agents import initialize_agent, Tool

weather = OpenWeatherMapAPIWrapper()
tools = [Tool(
    name="Weather",
    func=weather.run,
    description="도시명으로 현재 날씨를 조회합니다."
)]

agent = initialize_agent(tools, ...)
result = agent.run("서울의 날씨 알려줘")

v0.3 스타일 예시

from langchain_community.utilities import OpenWeatherMapAPIWrapper
from langgraph.prebuilt import create_react_agent

weather = OpenWeatherMapAPIWrapper()
tools = [weather.run]

agent = create_react_agent("openai:gpt-4.1-mini", tools)

input_message = {
    "role": "user",
    "content": "서울의 날씨는 어때?"
}

for step in agent.stream({"messages": [input_message]}, stream_mode="values"):
    print(step["messages"][-1].content)

v0.3에서는 에이전트 생성과 tool 전달이 훨씬 간결해짐
커스텀 툴 정의 시, Pydantic 2 형식으로 속성 및 validator, Field 활용이 필요

문법상 핵심 차이

	v0.2	v0.3
패키지 구조	`langchain`, `langchain_community`가 강하게 연결	`langchain`과 `langchain_community`가 별도로 동작
Pydantic	1.x 지원, 기존 validator 등 그대로 사용 가능	오직 Pydantic 2.x 지원, field_validator로 변경 필요
커스텀 툴	Pydantic v1 기반 schema/validator 적극 활용	Pydantic v2, 새로운 import, `field_validator` 적용
Tool 전달	Tool 객체로 wrapping 후 전달	함수 참조만 리스트에 전달 가능, 구조 간결화
Deprecated	deprecated imports 일부 작동 (0.4에 완전 제거 예정)	deprecated imports 불가, 새 방식 강제, migration 필요

참고

간단한 Wrapper 사용 및 invoke(함수 호출) 스타일은 큰 차이가 없지만, 0.3에선 **내부 구조(Pydantic, import, agent방식)**가 대폭 변경되어 구버전 코드는 마이그레이션이 필요합니다.
커스텀 툴이나 직접적인 Pydantic 모델 커스터마이징 시 validator → field_validator, 직접 pydantic에서 import 등이 필수입니다.
패키지 구조가 분리되었기 때문에 앞으로는 공식 가이드에 따라 각각 별도 관리/설치가 필요합니다.

[펼치기]

tobony? 또 보니?

Search This Blog