LangGraph 실전 메모

LangGraph Node & Edge 설계 실전 팁

좋은 워크플로우는 좋은 노드에서 시작된다

---

LangGraph의 문법 자체는 어렵지 않다. 핵심은 “좋은 품질의 노드” 를 어떻게 설계하느냐에 있다. Node는 최대한 세분화해서 설계하는 것이 유리하다.

예를 들어, 질문 이해, 문서 검색, 답변 생성, 답변 평가 를 하나의 노드에서 처리하는 것보다, 각 task를 별도 노드로 분리하면 디버깅도 쉬워지고, 흐름 제어 및 튜닝도 더 정밀해진다.

**LangGraph에서는 “작게 쪼갠 Node”가 최고의 무기다.

---

✅ 기본 예제: 문서 검색 노드 만들기

def retrieve_document(state: GraphState) -> GraphState:
	retrieved_docs = pdf_retriever.invoke(state["question"])
	return GraphState(context=format_docs(retrieved_docs))

• 입력도 GraphState, 출력도 GraphState
• context에 필요한 정보를 저장하여 다음 노드에 넘긴다

---

🔁 State 타입 구성 시 주의할 점

from typing import TypedDict, Annotated, List
from langchain_core.documents import Document
from operator import add
 
class GraphState(TypedDict):
	context: Annotated[List[Document], add]
	answer: Annotated[List[Document], add]
	# question: Annotated[str, add] ← ❌ 문자열엔 add Reducer 사용 불가
	question: Annotated[str, "user_question"]

⚠️ add Reducer는 문자열에는 적용할 수 없다.

📌 추천

from langgraph.graph.message import add_messages

• operator.add 대신 add_messages 를 쓰는 것이 명시적이고 안전하다.

---

🔧 노드 반환 방식: 어떤 스타일을 쓸까?

LangGraph 튜토리얼에서 많이 보이는 두 가지 방식이 있다.

✅ 방식 1: 딕셔너리 반환

def retrieve(state: GraphState) -> GraphState:
	documents = "검색된 문서"
	return {"context": documents}

✅ 방식 2: GraphState 타입 반환

def retrieve(state: GraphState) -> GraphState:
	documents = "검색된 문서"
	return GraphState(context=documents)

두 방식 모두 기능적으로 동일하지만,

타입 힌팅 + 일관성 있는 코드 유지를 위해 2번 방식 사용을 권장한다.

---

⚙️ 그래프 생성 방식: 어떤 게 더 좋을까?

LangGraph에서는 두 가지 방식으로 그래프를 정의할 수 있다.

📌 방식 1: START 명시

from langgraph.graph import START, StateGraph
 
workflow = StateGraph(state_schema=GraphState)
workflow.add_node("retrieve", retrieve)
workflow.add_edge(START, "retrieve")

📌 방식 2: set_entry_point 사용

from langgraph.graph import StateGraph
 
workflow = StateGraph(state_schema=GraphState)
workflow.add("retrieve", retrieve)
workflow.set_entry_point("retrieve")

✅ 기능적으로는 동일하며, 둘 중 어떤 걸 사용해도 결과는 같다.
→ 취향 또는 코드 스타일에 맞춰 선택하면 된다.

---

📝 설계 팁: 그래프 구조는 먼저 종이에 그려라

직접 구현에 들어가기 전에,

질문 흐름, 분기 조건, 노드 순서 등을 메모장이나 다이어그램 툴에 그려보는 것을 강력 추천하다.

• 불필요한 분기 제거
• 병렬 처리 가능한 지점 확인
• 나중에 LangGraph 시각화 기능과 1:1 매핑하기 쉬움

---

📚 RAG 사용 시 추가 팁: 문서 포맷 처리

LLM에 List[Document] 객체를 넘기기보다는,

문서들을 포맷팅해서 하나의 문자열로 변환하는 것이 성능상 훨씬 유리하다.

formatted_context = format_docs(retrieved_docs)

🎯 이유

• LLM이 이해하기 쉬운 형태로 정제
• 불필요한 metadata 제거
• 문서 경계에 태그 추가 (예: ### 문서 1 ###, <document></document> 등)