1. RecursiveCharacterTextSplitter
2. TokenTextSplitter

📊 RecursiveCharacterTextSplitter vs TokenTextSplitter

✅ 요약 권장사항

PyPDFLoader

• 각 줄 끝에 /n을 읽어들임 (문장 중간이라도)
• 원본 문서의 포맷을 완전히 캡처하지 못함 (/n/n 없음). PDF의 경우 분할이 덜 정확함.
• 대부분의 PDF 리더는 시각적 줄바꿈을 실제 \\n 줄바꿈으로 읽어들이며, 이는 단순한 줄 래핑 때문일지라도 실제 문장 경계가 아닐 수 있음.
• → 더 큰 청크 크기와 중첩으로 이러한 영향을 완화할 수 있음

Map-Reduce-Chain (배치 처리)

from langchain_community.document_loaders import PyPDFLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from langchain_core.output_parsers import StrOutputParser

# 1. PDF 문서 로드
pdf_path = "파일 이름"
loader = PyPDFLoader(pdf_path, mode = "single")
doc = loader.load()
#full_text = doc[0].page_content

# 2. 의미 있는 청크로 분할
splitter = RecursiveCharacterTextSplitter(
    chunk_size=10000, # 문자 단위! ~ 2000-2500 토큰
    chunk_overlap=2000, # 10-20%
    separators=["\\n\\n", "\\n", ".", "!", "?", " "],  # 광범위 -> 좁게
)
chunks = splitter.split_documents(doc)

# 3. 배치 API용 입력 준비
inputs = [{"text": chunk.page_content} for chunk in chunks]

# 4. 청크 요약용 프롬프트 (MAP)
map_prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a business anylyst and helpful assistant."),
    ("human", "Summarize the following text briefly in 3 bullet points:\\n\\n{text}\\n\\nSummary:")
])

# 5. 최종 요약용 프롬프트 (REDUCE)
reduce_prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a business anylyst and helpful assistant."),
    ("human", "Summarize the following texts in a consistent final summary {reduce_style}:\\n\\n{text}\\n\\nFinal Summary:")
])

# 6. LLM
llm = ChatOpenAI(
    model="gpt-4o-mini",
    temperature=0
)

# 7. 파서
parser = StrOutputParser()

# 8. 두 개의 별도 체인
map_chain = map_prompt | llm | parser
reduce_chain = reduce_prompt | llm | parser

# 9. MAP 단계: 각 청크를 *병렬로* 요약
summaries = map_chain.batch(
    inputs, # 청크 목록
    config={"max_concurrency": 4},   # AI API Rate limits 고려 필요
)

# 10. REDUCE 단계: 청크 요약들로부터 최종 요약
final_summary = reduce_chain.invoke({"reduce_style":"in a very detailed, structured and comprehensive manner while dropping duplicated info",
                                     "text": "\\n\\n".join(summaries)})

# 11. 최종 출력
print("\\n📄 Summary:\\n", final_summary)

Refine-Chain (반복적 업데이트)

from langchain_community.document_loaders import PyPDFLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from langchain_core.output_parsers import StrOutputParser

# 1. PDF 문서 로드
pdf_path = "파일 이름"
loader = PyPDFLoader(pdf_path, mode = "single")
doc = loader.load()

# 2. 의미 있는 청크로 분할
splitter = RecursiveCharacterTextSplitter(
    chunk_size=20000, # 문자 단위! ~ 4000-5000 토큰
    chunk_overlap=2000, # 10-20%
    separators=["\\n\\n", "\\n", ".", "!", "?", " "],  # 광범위 -> 좁게
)
chunks = splitter.split_documents(doc)

# 3. 첫 번째 청크 프롬프트
question_prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a business anylyst and helpful assistant. Do not speculate or invent facts; rely only on the provided text."),
    ("human",
     "Create an initial brief summary of the following passage. Only include information supported by the text."
     "The Summary should contain 3-5 bullet points. \\n\\n"
     "Text:\\n{text}\\n\\n"
     "Initial summary:")
])

# 4. 개선 프롬프트 (REFINE)
refine_prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a business anylyst and helpful assistant. Do not speculate or invent facts; rely only on the provided text."),
    ("human",
     "We have an existing summary that must remain consistent and high-quality:\\n"
     "{existing_answer}\\n\\n"
     "Incorporate the following new passage:\\n"
     "{text}\\n\\n"
     "Update rules:\\n"
     "If this passage is irrelevant to the current summary or fully redundant, leave the summary unchanged. Otherwise:\\n"
     "1) Crtically review the entire summary and fully rewrite the summary.\\n"
     "2) Use 5-12 Topic Headers (main topics!) and keep the structure consistent.\\n"
     "3) Add only new, material information; remove duplicates and redundancy.\\n"
     "4) Remove info from the previous summary that becomes more and more niche or irrelevant in the updated total context.\\n"
     "5) If the new text contradicts or clarifies earlier statements, correct the summary.\\n"
     "6) The summary length should not execeed the length of a typical executive summary. No irrelevant details.\\n"
     "7) Prefer concise wording; replace rather than append where possible.\\n\\n"
     "Return only the refined summary (no commentary):")
])

# 5. LLM
llm = ChatOpenAI(
    model="gpt-4o-mini",
    temperature=0
)

# 6. 파서
parser = StrOutputParser()

# 7. 2개 체인 구성
question_chain = question_prompt | llm | parser   # 첫 번째 청크
refine_chain    = refine_prompt   | llm | parser  # 이후 청크들

# 8. 첫 번째 청크에 대한 초기 요약
current_summary = question_chain.invoke({"text": chunks[0].page_content})
intermediate_summaries = [] # 중간 요약 저장
intermediate_summaries.append(current_summary)

# 9. 반복적 개선
for chunk in chunks[1:]:
    current_summary = refine_chain.invoke({
        "existing_answer": current_summary,
        "text":            chunk.page_content
    })
    intermediate_summaries.append(current_summary)

# 10. 최종 요약 출력
print(current_summary)

요약 전략 정리

실용 휴리스틱스

• 청킹: 1~2k 토큰에 10–15% 중첩이 좋은 시작점
• 일관성: 초기 및 refine/reduce 단계에서 동일한 출력 형식 유지 (예: 고정 제목이나 고정 불렛 개수)
• 가드레일: 간결한 표현 요청, "추가보다는 교체", 그리고 "지원되는 사실만 포함" 요청. 엄격한 구조가 필요할 때 JSON + 파서 고려
• 병렬화: map 단계만 병렬화. Rate limit에 맞는 보수적인 max_concurrency 사용
• 비용/시간: stuff < map_reduce < refine (일반적으로). 청크 크기 최적화, map 출력을 짧게 유지, 불필요한 재작성 피하기

경험적인 전략 시도

확실하지 않다면, 먼저 Map-Reduce 시도 (크기 + 속도에 좋은 기본값). 중요한 교차 섹션 의존성이 놓치고 있다면 Refine로 전환. 문서가 작다면 Stuff로 간단하게 유지.

기본적인 RAG 코드

from langchain_community.document_loaders import PyPDFLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain_community.vectorstores import FAISS # NEW
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_core.runnables import RunnablePassthrough


# 1. Loading a PDF doc
pdf_path = "파일 이름" 
loader = PyPDFLoader(pdf_path, mode = "single")
doc = loader.load()                    

# 2. split into coherent chunks
splitter = RecursiveCharacterTextSplitter(
    chunk_size=500,  
    chunk_overlap=100, 
    separators=["\n\n", "\n", ".", "!", "?", " "],  
)
chunks = splitter.split_documents(doc)

# 3. Embeddings + Vector‑Store
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
vectordb = FAISS.from_documents(chunks, embeddings)
retriever = vectordb.as_retriever(search_kwargs={"k": 4})

# 4. LLM
llm = ChatOpenAI(
    model="gpt-4o-mini",
    temperature=0,
)


# 5. Prompt‑Template
qa_prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a business analyst and helpful assistant."),
    ("human", "Answer the following question as accurate and diligent as possible."
              "Do not speculate or invent facts, rely only on the provided text."
              "\n\nContext:\n{context}\n\nQuestion: {question}\nAnswer:")
])



def format_docs(docs):
    return "\n\n---\n\n".join(doc.page_content for doc in docs)


# LCEL
rag_chain = (
    {"context": retriever | format_docs, "question": RunnablePassthrough()}
    | qa_prompt
    | llm
    | StrOutputParser()
)


question = input("❓ Your Question for the Bot: ")
result = rag_chain.invoke(question)

print("\nResponse:\n", result)

RAG가 필요한 이유

• Input 크기에 따라 확장 가능: 관련된 몇 개의 문단만 검색하므로, 위키/드라이브가 커지더라도 컨텍스트 윈도우 제한에 도달하지 않습니다.
• 더 낮은 비용 및 지연 시간: 전체 문서를 매번 프롬프트에 붙여넣는 것보다 훨씬 적은 토큰을 사용합니다.
• 더 높은 신호 대 잡음 비율: 모델이 짧고 관련성 높은 발췌문에 집중합니다. 답변을 인용과 함께 더 쉽게 근거를 제시할 수 있습니다.
• 최신 정보 + 권한 인식: 문서가 변경되면 재인덱싱하고 사용자 권한으로 필터링할 수 있으며, 모델을 재학습할 필요가 없습니다.

RAG의 장단점

• 더 많은 구성 요소: 수집, 청킹, 임베딩, 벡터 저장소/리랭커, 모니터링이 필요합니다.
• ”검색 실패” 위험: 청킹이 부족하거나 검색기가 약하면 올바른 문단을 찾지 못할 수 있습니다 (튜닝/평가 필요).
• 운영 작업: 접근 제어 매핑, 개인정보 처리, 품질 테스트가 지속적인 과제가 됩니다.

”모든 문서를 프롬프트에 넣는 방식”의 장점

• 구현이 간단: 파이프라인이나 인프라가 필요 없습니다.
• 검색 실패 없음: 프롬프트 컨텍스트에 있는 내용은 모델이 볼 수 있습니다.
• 작고 고정된 컨텍스트에 적합: 예: 짧은 핸드북 또는 단일 정책 문서.

전체 문서를 프롬프트에 넣는 방식의 단점

• 확장성 부족: 토큰 제한에 빠르게 도달하며 문서 크기에 비례해 비용이 증가합니다.
• 주의력 희석: 크고 노이즈가 많은 컨텍스트는 답변 품질을 저하시킵니다.
• 최소 권한 적용이 어려움: 모델/API에 과도한 콘텐츠를 공유할 수 있습니다.
• 출처 추적이 약함: 명확한 소스 발췌문을 보여주기 어렵고, 감사가 복잡합니다.

일반적인 지침

• Input 컨텍스트가 약 20~50페이지이고, 정기적으로 변경되며, 사용자별 권한이 있는 경우 RAG를 사용하세요 (선택적으로 리랭킹 및 캐싱과 함께).
• 작고 고정되어 있으며 신뢰 경계가 단순한 경우, 컨텍스트 스터핑이 적합하고 시작하기에 가장 저렴합니다.

chunk_size

10K 컨텍스트(긴 문서, 포멀하고 섹션이 구분된 구조): chunk 크기의 시작점으로는 약 1,800–2,400 tokens가 적절함

chunk_overlap

긴 보고서의 경우: 약 15% 중복 (또는 약 200 토큰)을 목표로 합니다. 20%도 괜찮지만, 일반적으로 컨텍스트를 잃지 않고 약 15%로 낮출 수 있습니다.

큰 청크 vs 작은 청크의 장단점

핵심 요약: 10K의 경우, 기준으로 청크당 약 8,000~10,000 문자에 약 15% 중복으로 시도한 다음, 평가 점수와 프롬프트 비용에 따라 조정하세요.

Retrieving 여러 방식

1. 기본적인 유사도 검색

   top_docs = vectordb.similarity_search(query, k=4) or

   retriever = vectordb.as_retriever(
      search_type="similarity",          
      search_kwargs={"k": 4}             
   )
   top_docs = retriever.invoke(query)

2. 유사도 점수 임계값 포함

   
   retriever = vectordb.as_retriever(
      search_type="similarity_score_threshold",
      search_kwargs={
          "score_threshold": 0.4,
          "k": 4 
      }
   )

3. MMR(Max Marginal Relevance) Search

   1. 쿼리와 유사도가 높은 상위 z개 후보 문서(청크)를 넓게 가져온>다.
   2. 이후 유사도(similarity)와 다양성(diversity)를 함께 고려해, 중>복을 줄이면서 최종 k개를 재선정한다.
   3. lambda_mult (0~1) 값으로 유사도 중심(1에 가까움) ↔ 다양성 >중심(0에 가까움)의 균형을 조절한다.

   
   retriever = vectordb.as_retriever(
      search_type="mmr",                   
      search_kwargs={"k": 4,
                     "fetch_k": 20,
                     "lambda_mult": 0.5}  
   )

요약

작업별 빠른 추천

문서 필터링: where_document 옵션

similarity_search 등의 검색 메서드에서 where_document 파라미터를 사용하여 문서 내용으로 필터링할 수 있습니다.

1. 문자열 포함 연산자

# 특정 문자열 포함 (대소문자 구분)
results = vectordb.similarity_search(
    "query",
    where_document={"$contains": "search_string"}
)

# 특정 문자열 미포함
results = vectordb.similarity_search(
    "query",
    where_document={"$not_contains": "unwanted_string"}
)

2. 정규표현식

# 정규표현식 패턴 매칭
results = vectordb.similarity_search(
    "query",
    where_document={"$regex": r"\bAPI\b"}
)

# 이메일 패턴 예시
results = vectordb.similarity_search(
    "query",
    where_document={"$regex": r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"}
)

3. 논리 연산자 ($and, $or 조합)

# AND 조건: 두 조건을 모두 만족하는 문서
results = vectordb.similarity_search(
    "query",
    where_document={
        "$and": [
            {"$contains": "machine learning"},
            {"$regex": "[0-9]+"}
        ]
    }
)

# OR 조건: 두 조건 중 하나라도 만족하는 문서
results = vectordb.similarity_search(
    "query",
    where_document={
        "$or": [
            {"$contains": "Python"},
            {"$contains": "JavaScript"}
        ]
    }
)

where vs where_document 비교

사용 예시

# 메타데이터와 문서 내용을 동시에 필터링
results = vectordb.similarity_search(
    "AI 기술 질문",
    k=5,
    where={"source": "technical_doc.pdf"},  # 메타데이터 필터
    where_document={"$contains": "neural network"}  # 문서 내용 필터
)

LangGraph에서는 add_messages reducer를 사용해 메시지 목록을 효율적으로 관리할 수 있습니다.

from langgraph.graph.message import add_messages
from langchain_core.messages import AIMessage, HumanMessage

# 빈 메시지 리스트 생성
msgs = []

# 메시지 생성 (ID 없음)
human = HumanMessage(content="Hi", type="human", name="Alex")
ai = AIMessage(content="Hi. How can I help you?", name="MyBot")

# 리스트와 단일 메시지 병합 → reducer가 자동으로 고유 ID 추가
msgs = add_messages(msgs, human)

# 두 메시지 리스트 병합
msgs = add_messages(msgs, [ai])

msgs

결과 예시:

[
    HumanMessage(
        content='Hi',
        additional_kwargs={},
        response_metadata={},
        name='Alex',
        id='0434f672-f473-46a1-8ea2-dd3e89def10d'
    ),
    AIMessage(
        content='Hi. How can I help you?',
        additional_kwargs={},
        response_metadata={},
        id='def7339f-294b-4954-be75-aefea1878c85',
        name='MyBot',
        tool_calls=[],
        invalid_tool_calls=[]
    )
]

메시지 ID가 필요한 이유

• ✅ 메시지 수정 가능: ID를 통해 특정 메시지를 식별하고 수정
• ✅ 중복 방지: 동일한 ID의 메시지가 여러 번 추가되는 것을 방지
• ✅ 메시지 삭제: ID를 기반으로 특정 메시지 삭제

2. 왜 대화 기록 관리가 필수인가?

긴 대화에서 "모든 것을 영원히 저장"하는 것은 부작용이 따릅니다.

대화 기록 관리가 필요한 이유

3. 대화 기록 관리 핵심 전략

단순한 전략부터 복잡한 전략까지 순서대로 소개합니다.

1) 슬라이딩 윈도우 (잘라내기)

마지막 K개 메시지 또는 T토큰만 유지합니다.

• 장점: 구현이 쉽고 비용이 저렴
• 단점: 초기에 나왔지만 중요한 사실이 컨텍스트에서 제외될 수 있음

2) 롤링 요약 (대화 개요)

"지금까지 중요한 것"에 대한 짧고 지속적으로 업데이트되는 요약을 유지하고, 원시 메시지는 최근 일부만 보관합니다.

• 장점: 오래된 사실을 압축된 형태로 유지, 토큰 크기 예측 가능
• 단점: 요약이 뉘앙스를 놓칠 수 있음, 추가 LLM 호출 필요

3) 계층적/에피소드 요약

주제/세그먼트별로 요약하고, 세그먼트가 끝나면 요약들을 다시 요약("챕터" 방식)합니다.

• 장점: 매우 긴 세션으로 확장 가능, 주제 전환 지원
• 단점: 관리할 부분이 많음

4) 엔티티/슬롯 메모리

안정적인 사실(이름, 선호도, 제약사항)을 구조화된 키→값 또는 작은 지식 그래프로 추출/저장하고, 시스템 또는 컨텍스트 메시지로 재주입합니다.

• 장점: 지속 가능하고 매우 작은 용량
• 단점: 추출 및 충돌 해결 필요 (예: "저는 바보입니다." → 나중에 "저는 천재입니다.")

5) 검색 메모리 (벡터 저장소)

대화 기록(또는 증류된 핵심)을 인덱싱합니다. 각 턴마다 가장 관련성 높은 k개 조각을 검색해 주입합니다.

• 장점: 관련 있는 것만 가져옴, 확장성 우수
• 단점: 인프라 추가(인덱스), 청킹 및 중복 제거 필요

6) 툴 트레이스 압축

툴 입출력을 제거하거나 요약하고 결과 또는 간결한 근거만 유지합니다.

• 장점: 큰 JSON을 반환하는 툴에서 큰 절감 효과

7) 프롬프트 위생 & 고정

핵심 규칙을 재설명하는 안정적인 시스템 메시지를 유지하고, 스크롤되어 사라지지 않게 합니다.

• 장점: 추가 토큰 없이 드리프트 감소 (시스템 메시지는 어차피 각 호출의 일부)

8) TTL, 편집, 사용자 컨트롤

메시지의 수명(TTL), PII 편집, "잊어" 명령, 스레드별 삭제를 제공합니다.

• 장점: 모델 성능을 저하시키지 않으면서 프라이버시 및 규정 준수

4. 실용적인 구성

• 작은 슬라이딩 윈도우 유지 (예: 마지막 6-12턴)
• 지속적인 사실과 결정을 캡처하는 롤링 요약 유지
• 벡터 저장소에 핵심 저장; 각 턴마다 3-5개 관련 항목 검색

→ 훌륭한 품질/비용 균형을 제공하고 확장 가능합니다.

5. 상황별 전략 선택 가이드

📚 시작하며

LangGraph를 학습하면서 가장 중요하게 이해해야 할 개념들을 정리했습니다. 특히 Tool Binding된 LLM 노드를 추가하는 방법과 Super-Step의 개념, 그리고 이것이 메모리 관리와 어떻게 연결되는지를 중심으로 기록했습니다.

🔧 Tool Binding - LLM에 도구를 연결하기

Tool의 기본 구조

LangChain은 일반 함수를 Tool로 변환할 수 있는 래퍼 클래스를 제공합니다. 예를 들어 검색 기능을 Tool로 만드는 과정은 다음과 같습니다.

from langchain.agents import Tool
from langchain_community.utilities import GoogleSerperAPIWrapper

serper = GoogleSerperAPIWrapper()
tool_search = Tool(
    name="search",
    func=serper.run,
    description="Useful for when you need more information from an online search"
)

이렇게 생성된 Tool은 독립적으로 호출할 수 있습니다.

tool_search.invoke("What is the capital of France?")

LLM에 Tool 바인딩하기

Tool을 구현할 때는 항상 2가지 변경사항이 필요합니다:

1. OpenAI 호출 시 Tool을 JSON 형식으로 제공
2. 응답 처리: finish_reason=="tool_calls"를 확인하고 함수를 실행한 후 결과 제공

LangGraph에서는 bind_tools() 메서드를 사용하여 LLM에 Tool을 바인딩합니다.

from langchain_openai import ChatOpenAI

tools = [tool_search]

llm = ChatOpenAI(model="gpt-4o-mini")
llm_with_tools = llm.bind_tools(tools)

💡 llm.bind_tools()는 LLM이 필요할 때 특정 도구를 호출할 수 있도록 연결해주는 핵심 메서드입니다. 이를 통해 LLM은 단순히 텍스트를 생성하는 것을 넘어 실제 기능을 수행할 수 있게 됩니다.

🔄 Graph 구조에서 Tool Node 추가하기

State 정의

from typing import Annotated, TypedDict
from langgraph.graph.message import add_messages

class State(TypedDict):
    messages: Annotated[list, add_messages]

TypedDict를 사용하여 State 객체를 정의했습니다. add_messages는 메시지 리스트를 관리하는 reducer입니다.

Graph Builder와 Node 추가

from langgraph.graph import StateGraph, START
from langgraph.prebuilt import ToolNode, tools_condition

# Step 1-2: Graph Builder 초기화
graph_builder = StateGraph(State)

# Step 3: Chatbot Node 추가
def chatbot(state: State):
    return {"messages": [llm_with_tools.invoke(state["messages"])]}

graph_builder.add_node("chatbot", chatbot)
graph_builder.add_node("tools", ToolNode(tools=tools))

# Step 4: Edge 연결
graph_builder.add_conditional_edges("chatbot", tools_condition, "tools")
graph_builder.add_edge("tools", "chatbot")
graph_builder.add_edge(START, "chatbot")

# Step 5: Compile
graph = graph_builder.compile()

💡 ToolNode는 LangGraph에서 제공하는 prebuilt 노드로, Tool 실행을 자동으로 처리합니다. tools_condition은 LLM이 Tool을 호출해야 하는지 판단하는 조건부 분기 입니다.

⚡ Super-Step - LangGraph의 핵심 개념

왜 State가 메모리를 자동으로 처리하지 않을까?

Graph가 State를 유지하고 append하고 있는데, 왜 이를 통해 메모리를 자동으로 관리하지 않을까요? 이것이 LangGraph를 이해하는 핵심 포인트입니다.

Super-Step의 정의

💡 Super-Step은 그래프 노드들의 단일 반복(iteration)으로 간주됩니다.
병렬로 실행되는 노드들은 같은 Super-Step에 속하고, 순차적으로 실행되는 노드들은 서로 다른 Super-Step에 속합니다.

관용적인 LangGraph 사용법

관용적인 LangGraph에서는 각 Super-Step마다, 즉 각 상호작용마다 invoke를 호출합니다.

• Reducer는 하나의 Super-Step 내에서 자동으로 State 업데이트를 처리합니다.
• 하지만 Super-Step 사이에서는 자동으로 처리하지 않습니다.

바로 이것이 체크포인팅(Checkpointing)이 달성하는 목표입니다.

💡 Super-Step의 개념을 이해하지 못하면 LangGraph의 메모리 관리와 State 전파 메커니즘을 제대로 활용할 수 없습니다. 각 invoke 호출이 하나의 Super-Step을 의미한다는 점을 명심해야 합니다.

💾 Checkpointing으로 메모리 구현하기

MemorySaver를 사용한 기본 메모리

from langgraph.checkpoint.memory import MemorySaver

memory = MemorySaver()

# Graph 컴파일 시 checkpointer 추가
graph = graph_builder.compile(checkpointer=memory)

Config를 통한 Thread 관리

config = {"configurable": {"thread_id": "1"}}

def chat(user_input: str, history):
    result = graph.invoke(
        {"messages": [{"role": "user", "content": user_input}]}, 
        config=config
    )
    return result["messages"][-1].content

State History 조회

# 현재 State 확인
graph.get_state(config)

# State 히스토리 조회 (최신순)
list(graph.get_state_history(config))

💡 LangGraph는 특정 시점으로 되돌아가거나 분기할 수 있는 도구를 제공합니다:

config = {"configurable": {"thread_id": "1", "checkpoint_id": ...}}
graph.invoke(None, config=config)

이를 통해 이전 체크포인트에서 복구하고 재실행할 수 있는 안정적인 시스템을 구축할 수 있습니다.

🗄️ SQL 기반 영구 메모리

SQLite를 이용해 기억하기

인메모리 저장소 대신 SQLite 데이터베이스를 사용하면 영구적인 메모리 관리가 가능합니다.

import sqlite3
from langgraph.checkpoint.sqlite import SqliteSaver

db_path = "memory.db"
conn = sqlite3.connect(db_path, check_same_thread=False)
sql_memory = SqliteSaver(conn)

# Graph에 SQL 메모리 적용
graph = graph_builder.compile(checkpointer=sql_memory)

config = {"configurable": {"thread_id": "3"}}

def chat(user_input: str, history):
    result = graph.invoke(
        {"messages": [{"role": "user", "content": user_input}]}, 
        config=config
    )
    return result["messages"][-1].content

💡 단순한 인메모리 상태 관리를 넘어, 데이터베이스 기반의 영구적이고 반복 가능하며 견고한 시스템을 구축할 수 있습니다. 이를 통해 에이전트 시스템에 자연스러운 기억력을 심어줄 수 있습니다.

📝 핵심 요약

LangGraph의 주요 구성 요소

1. State - 현재 앱의 스냅샷을 표현하는 불변 객체

   • Reducer를 통해 State 업데이트
   • 여러 노드의 동시 실행 가능

2. Nodes - 실제 작업을 수행하는 함수 단위

   • Chatbot Node: LLM 호출 담당
   • Tool Node: 도구 실행 담당

3. Edges - 노드 간 흐름 제어

   • Conditional Edges: 조건부 분기
   • Normal Edges: 고정된 전환

Tool Binding 핵심 포인트

• llm.bind_tools(tools)로 LLM에 도구 연결
• ToolNode와 tools_condition으로 자동 처리
• LLM이 필요시 적절한 도구를 선택하여 실행

Super-Step 이해

• 하나의 Super-Step = 하나의 invoke 호출
• Reducer는 Super-Step 내에서만 자동 작동
• Super-Step 간 상태 유지는 Checkpointing이 담당

Checkpointing의 중요성

• MemorySaver: 인메모리 임시 저장
• SqliteSaver: 영구 데이터베이스 저장
• Thread ID로 대화 세션 관리
• 특정 체크포인트로 복구 및 분기 가능

🎯 마치며

LangGraph는 단순한 상태 관리 라이브러리가 아니라, 복잡한 에이전트 시스템을 구축하기 위한 강력한 프레임워크입니다. Tool Binding을 통해 LLM에 실제 기능을 부여하고, Super-Step 개념으로 상태 전파를 제어하며, Checkpointing으로 견고하고 반복 가능한 시스템을 만들 수 있습니다.

특히 Super-Step과 Checkpointing의 관계를 정확히 이해하는 것이 LangGraph를 제대로 활용하는 핵심입니다. Reducer가 자동으로 모든 것을 처리해줄 것이라는 착각에서 벗어나, 명시적인 체크포인팅을 통해 상태를 관리해야 합니다.

이러한 개념들을 바탕으로 실제 프로덕션 환경에서 사용 가능한 에이전트 시스템을 구축할 수 있을 것입니다.

📝 서론

비동기 프로그래밍과 AI 에이전트를 결합하여 심층 검색(Deep Research) 시스템을 구현하는 방법을 정리했습니다. 이 글에서는 OpenAI SDK의 Agent 프레임워크를 활용하여 Plan → Search → Report 3단계 파이프라인을 구성하는 실제 구현 방법을 다룹니다.

핵심은 Python의 asyncio를 통한 병렬 처리와 Pydantic 기반 Structured Output을 통한 응답 제어입니다.

🧩 AsyncIO와 코루틴의 이해

AsyncIO 기본 개념

async def로 정의된 함수는 비동기 함수로, await 키워드를 사용하여 비동기 작업을 수행할 수 있습니다. 이러한 함수는 코루틴(Coroutine)을 생성합니다.

async def example_async_function():
    result = await some_async_operation()
    return result

코루틴(Coroutine)이란?

• 일반 함수와 비슷하지만, await 키워드를 사용하여 실행을 일시 중지하고 나중에 다시 시작할 수 있습니다.
• 호출 시 coroutine object를 반환합니다.
• Event Loop가 코루틴을 실행합니다.

Event Loop의 역할

Event Loop는 비동기 작업을 스케줄링하고 실행하는 역할을 합니다. 특정 coroutine이 waiting 상태라면 다른 coroutine을 실행하여 효율적인 동시성(concurrency)을 제공합니다.

💡 Event Loop는 단일 스레드 내에서 여러 작업을 동시에 처리할 수 있게 해주는 핵심 메커니즘입니다. I/O bound 작업에서 특히 효과적입니다.

🤖 OpenAI SDK Agent 프레임워크

Agent와 Tool 등록

OpenAI SDK는 AI 에이전트를 쉽게 구축할 수 있는 라이브러리를 제공합니다. @function_tool 데코레이터를 통해 Python 함수를 tool로 등록할 수 있습니다.

from agents import Agent, function_tool

@function_tool
def my_tool_function(param: str) -> str:
    """도구 설명"""
    return f"결과: {param}"

agent = Agent(
    name="MyAgent",
    instructions="당신의 역할은...",
    tools=[my_tool_function],
    model="gpt-4o-mini"
)

Agent를 Tool로 등록

Agent 자체도 다른 Agent의 tool로 등록할 수 있습니다. 이는 as_tool() 메서드를 사용합니다.

agent1.as_tool(
    tool_name="sales_agent1", 
    tool_description="영업 관련 질문에 답변하는 에이전트"
)

Handoffs: Agent 간 대화 관리

Handoffs는 Agent 간의 작업 전달을 관리하는 기능입니다. 특정 역할을 가진 Agent에게 작업을 전달하고, 해당 Agent의 작업이 끝나면 다른 Agent에게 작업을 전달할 수 있습니다.

handoffs_description 매개변수에 에이전트의 역할 또는 임무를 설명합니다.

🛡️ Guardrails 패턴

Guardrail을 Agent로 구현

가드레일 자체를 Agent로 구현하여 입력 검증 로직을 구조화할 수 있습니다.

from pydantic import BaseModel
from agents import Agent, input_guardrail, Runner, GuardrailFunctionOutput

class NameCheckOutput(BaseModel):
    is_name_in_message: bool
    name: str

guardrail_agent = Agent( 
    name="Name check",
    instructions="Check if the user is including someone's personal name in what they want you to do.",
    output_type=NameCheckOutput,  # Structured output
    model="gpt-4o-mini"
)

@input_guardrail
async def guardrail_against_name(ctx, agent, message):
    result = await Runner.run(guardrail_agent, message, context=ctx.context)
    is_name_in_message = result.final_output.is_name_in_message
    return GuardrailFunctionOutput(
        output_info={"found_name": result.final_output},
        tripwire_triggered=is_name_in_message
    )

💡 Pydantic 모델을 output_type으로 지정하면, Agent가 자유 형식이 아닌 정해진 구조로만 응답하도록 강제할 수 있습니다. 이는 강력한 가드레일 역할을 합니다.

🔬 Deep Research 구현 패턴

Deep Research는 OpenAI SDK의 내장 WebSearchTool과 Agent의 Structured Output을 활용하여 심층 검색 기능을 구현하는 패턴입니다.

전체 아키텍처: Plan → Search → Report

graph LR
    A[사용자 쿼리] --> B[Planner Agent]
    B -->|검색 계획| C[Search Agent]
    C -->|병렬 검색| D[검색 결과들]
    D --> E[Writer Agent]
    E --> F[최종 리포트]

📋 1단계: Plan - Structured Outputs를 통한 검색 계획

Pydantic 모델 정의

검색 계획을 구조화하기 위해 Pydantic 모델을 정의합니다.

from pydantic import BaseModel, Field

class WebSearchItem(BaseModel):
    reason: str = Field(description="이 검색이 필요한 이유")
    query: str = Field(description="검색어")

class WebSearchPlan(BaseModel):
    searches: list[WebSearchItem] = Field(description="수행할 웹 검색 목록")

Planner Agent 구성

from agents import Agent

HOW_MANY_SEARCHES = 5

planner_agent = Agent(
    name="PlannerAgent",
    instructions=f"You are a helpful research assistant. Given a query, come up with a set of web searches to perform to best answer the query. Output {HOW_MANY_SEARCHES} terms to query for.",
    model="gpt-4o-mini",
    output_type=WebSearchPlan,  # ← Structured Output (Format Guardrail)
)

💡 output_type을 지정하면 LLM이 반드시 해당 스키마에 맞는 JSON만 반환합니다. 이는 파싱 오류를 원천 차단하는 강력한 방법입니다.

실제 사용 예시

result = await Runner.run(planner_agent, f"Query: {query}")
search_plan = result.final_output_as(WebSearchPlan)
print(f"Will perform {len(search_plan.searches)} searches")

🌐 2단계: Search - 병렬 검색 실행

OpenAI WebSearchTool 활용

Search Agent는 OpenAI의 내장 WebSearchTool을 사용하여 실제 웹 검색을 수행합니다.

from agents import Agent, WebSearchTool

search_agent = Agent(
    name="Search agent",
    instructions="검색어에 대해 2-3문단으로 요약하세요.",
    tools=[WebSearchTool(search_context_size="low")],  # OpenAI 내장 검색 툴
    model="gpt-4o-mini",
)

AsyncIO를 통한 병렬 검색 구현

여러 검색어를 병렬(Parallel)로 처리하는 것이 Deep Research의 핵심입니다. asyncio.create_task와 asyncio.gather를 사용합니다.

import asyncio

async def perform_searches(search_plan: WebSearchPlan) -> list[str]:
    """검색 계획의 모든 검색을 병렬로 실행"""
    # 각 검색 아이템을 Task로 생성
    tasks = [
        asyncio.create_task(search(item)) 
        for item in search_plan.searches
    ]
    # 병렬로 실행 및 결과 수집
    results = await asyncio.gather(*tasks)
    return results

async def search(item: WebSearchItem) -> str:
    """개별 검색 수행"""
    input_text = f"Search term: {item.query}\nReason for searching: {item.reason}"
    result = await Runner.run(search_agent, input_text)
    return str(result.final_output)

💡 asyncio.gather(*tasks)는 모든 Task를 병렬로 실행하고, 모든 결과가 완료될 때까지 기다립니다. 5개의 검색을 순차적으로 하면 5배의 시간이 걸리지만, 병렬 처리로 큰 성능 향상을 얻을 수 있습니다.

실제 구현: 진행 상황 추적

실제 프로젝트에서는 asyncio.as_completed를 사용하여 완료되는 검색부터 처리하고 진행 상황을 추적할 수 있습니다.

async def perform_searches(self, search_plan: WebSearchPlan) -> list[str]:
    """검색을 병렬로 수행하고 진행 상황을 추적"""
    num_completed = 0
    tasks = [
        asyncio.create_task(self.search(item)) 
        for item in search_plan.searches
    ]

    results = []
    for task in asyncio.as_completed(tasks):
        result = await task
        if result is not None:
            results.append(result)
        num_completed += 1
        print(f"Searching... {num_completed}/{len(tasks)} completed")

    return results

✍️ 3단계: Report - 최종 보고서 작성

Writer Agent 구성

검색 결과를 종합하여 최종 리포트를 작성하는 Agent입니다.

from pydantic import BaseModel, Field

class ReportData(BaseModel):
    short_summary: str = Field(
        description="A short 2-3 sentence summary of the findings."
    )
    markdown_report: str = Field(description="The final report")
    follow_up_questions: list[str] = Field(
        description="Suggested topics to research further"
    )

writer_agent = Agent(
    name="WriterAgent",
    instructions=(
        "You are a senior researcher tasked with writing a cohesive report for a research query. "
        "You will be provided with the original query, and some initial research done by a research assistant.\n"
        "You should first come up with an outline for the report that describes the structure and "
        "flow of the report. Then, generate the report and return that as your final output.\n"
        "The final output should be in markdown format, and it should be lengthy and detailed. Aim "
        "for 5-10 pages of content, at least 1000 words.\n"
        "무조건 한국어로 작성해줘."
    ),
    model="gpt-4o-mini",
    output_type=ReportData,
)

보고서 생성

async def write_report(query: str, search_results: list[str]) -> ReportData:
    """검색 결과를 바탕으로 최종 리포트 작성"""
    input_text = f"Original query: {query}\nSummarized search results: {search_results}"
    result = await Runner.run(writer_agent, input_text)
    return result.final_output_as(ReportData)

🏗️ 전체 시스템 통합: ResearchManager

모든 단계를 통합하는 ResearchManager 클래스입니다.

class ResearchManager:
    def __init__(self, api_key: str):
        """Initialize the ResearchManager with an OpenAI API key"""
        self.api_key = api_key

    async def run(self, query: str):
        """Run the deep research process, yielding the status updates and the final report"""
        # 1. Planning phase
        search_plan = await self.plan_searches(query)

        # 2. Searching phase
        search_results = await self.perform_searches(search_plan)

        # 3. Writing phase
        report = await self.write_report(query, search_results)

        return report

API Key 관리 패턴

Gradio app 을 허깅페이스에 업로드하기 위해 동적으로 API Key를 관리하기 위해 환경 변수를 임시로 설정하는 패턴을 사용합니다.

async def plan_searches(self, query: str) -> WebSearchPlan:
    """Plan the searches to perform for the query"""
    original_key = os.environ.get("OPENAI_API_KEY")
    os.environ["OPENAI_API_KEY"] = self.api_key
    try:
        result = await Runner.run(planner_agent, f"Query: {query}")
        return result.final_output_as(WebSearchPlan)
    finally:
        # Restore original key
        if original_key:
            os.environ["OPENAI_API_KEY"] = original_key
        else:
            os.environ.pop("OPENAI_API_KEY", None)

💡 API Key를 다룰 때는 반드시 try-finally 블록을 사용하여 원래 환경 변수를 복원해야 합니다. 그렇지 않으면 다른 코드에서 잘못된 API Key를 사용할 수 있습니다.

🖥️ Gradio UI 통합

실시간 상태 업데이트를 제공하는 Gradio UI를 구축했습니다.

import gradio as gr

async def run(query: str, api_key: str):
    """Run research and yield status updates"""
    # Validate API key
    if not api_key or not api_key.strip():
        yield ("", "❌ **Error: Please provide a valid OpenAI API key**", "")
        return

    # Clear query box and show initial status
    yield ("", "🚀 **Starting research...**", "")

    status_text = ""
    final_report = ""

    async for chunk in ResearchManager(api_key).run(query):
        # Check if this chunk contains the final report
        if "---" in chunk:
            parts = chunk.split("## 📊 Research Report")
            if len(parts) == 2:
                status_text = parts[0]
                final_report = "## 📊 Research Report" + parts[1]
                yield ("", status_text, final_report)
        else:
            status_text = chunk
            yield ("", status_text, final_report)

CSS 애니메이션

.status-container {
    animation: fadeBlur 1.5s ease-in-out infinite;
}

@keyframes fadeBlur {
    0%, 100% {
        opacity: 1;
        filter: blur(0px);
    }
    50% {
        opacity: 0.6;
        filter: blur(0.5px);
    }
}

🎯 핵심 설계 원칙

1. Separation of Concerns

• Plan, Search, Report 각 단계를 독립적인 Agent로 분리하여 관심사를 명확히 구분했습니다.

2. Structured Output을 통한 신뢰성 확보

• Pydantic 모델을 사용하여 Agent의 출력 형식을 강제함으로써, 파싱 오류와 예측 불가능한 응답을 방지했습니다.

3. AsyncIO를 통한 성능 최적화

• 병렬 검색 처리로 전체 실행 시간을 크게 단축했습니다. 순차 처리 대비 N배의 성능 향상을 달성했습니다.

4. 에러 처리와 복원력

• API Key 관리, 예외 처리, 환경 변수 복원 등을 통해 시스템의 안정성을 확보했습니다.

💡 결론

OpenAI SDK의 Agent 프레임워크와 Python AsyncIO를 결합하여 효율적인 Deep Research 시스템을 구현했습니다. 핵심은 다음 세 가지입니다:

1. Structured Output을 통한 제어 가능성: Pydantic 모델로 LLM 응답을 구조화
2. 병렬 처리를 통한 성능: AsyncIO로 여러 검색을 동시에 실행
3. 명확한 단계 분리: Plan → Search → Report의 3단계 파이프라인
   이 패턴은 단순한 Q&A를 넘어서, 논리적이고 체계적인 심층 리서치 결과를 제공하는 AI 시스템을 구축하는 데 효과적입니다.

📚 참고 사항

OpenAI SDK 설명

📌 개요

Next.js 16의 새로운 캐싱 기능을 프로젝트에 적용하여 성능을 개선함. 기존의 fetch 기반 데이터 로딩 방식에서 서버 액션과 'use cache' 디렉티브를 활용한 최적화된 구조로 전환했음.

🎯 주요 변경 사항

1. 캐시된 서버 액션 추가

기존에는 클라이언트에서 직접 API를 호출하는 방식을 사용했으나, 이를 서버 액션으로 전환하고 캐싱을 적용함.

변경 전 (app/page.tsx):

const BASE_URL = process.env.NEXT_PUBLIC_BASE_URL;

const Page = async () => {
  if (!BASE_URL) return null;
  const res = await fetch(`${BASE_URL}/api/events`);
  const { events } = await res.json();
  // ...
}

변경 후 (app/page.tsx):

import { getAllEventsCached } from "@/lib/actions/event.actions";

const Page = async () => {
  const events = await getAllEventsCached();
  // ...
}

💡 주요 개선점

• 환경 변수 의존성 제거
• 불필요한 네트워크 오버헤드 감소
• 서버 사이드에서 직접 데이터베이스 접근으로 응답 속도 향상

2. getAllEventsCached 구현

lib/actions/event.actions.ts에 새로운 캐시된 서버 액션을 추가함:

export const getAllEventsCached = async () => {
    'use cache';

    try {
        await connectDB();

        const events = await Event.find().sort({ createdAt: -1 }).lean();

        return JSON.parse(JSON.stringify(events));
    } catch (error) {
        console.error("Error fetching all events:", error);
        throw error;
    }
};

🔥 핵심 포인트

• 'use cache' 디렉티브: Next.js 16의 새로운 기능으로, 함수 실행 결과를 자동으로 캐싱 (next.config.ts 에서 cacheComponents 를 true 로 해야함.)
• .lean(): Mongoose의 lean() 메서드로 순수 JavaScript 객체 반환, 메모리 사용량 감소
• JSON.parse(JSON.stringify()): MongoDB ObjectId와 Date 객체를 직렬화하여 클라이언트 컴포넌트에서도 안전하게 사용 가능하도록 처리

3. EventList 컴포넌트 분리

코드 구조 개선을 위해 이벤트 목록 렌더링 로직을 별도 컴포넌트로 추출함.

components/EventList.tsx:

import EventCard from "@/components/EventCard";
import { IEvent } from "@/database";

export default async function EventList({ events }: { events: IEvent[] }) {

  return (
    <ul className="events">
      {events && events.length > 0 ? (
        events.map((event: IEvent) => (
          <li key={event.title} className="list-none">
            <EventCard {...event} />
          </li>
        ))
      ) : (
        <p className="text-center text-gray-500">No events found at the moment.</p>
      )}
    </ul>
  );
}

이를 통해 다음과 같은 이점을 얻음:

• 관심사의 분리
• 재사용 가능한 컴포넌트 구조
• 더 나은 코드 가독성
• 빈 상태 처리 개선

4. Next.js 설정 업데이트

next.config.ts에 캐싱 관련 설정을 추가함:

const nextConfig: NextConfig = {
  cacheComponents: true,

  images: {
    remotePatterns: [
      // ...
    ]
  }
};

⚙️ cacheComponents 옵션

Next.js 16에서 기능으로, 컴포넌트 레벨의 캐싱을 활성화함. 이를 통해 서버 컴포넌트의 렌더링 결과도 캐시할 수 있음.

📊 성능 개선 효과

Before

1. 클라이언트 → API Route → MongoDB
2. 매 요청마다 전체 네트워크 라운드트립 발생
3. 환경 변수 검증 오버헤드

After

1. 서버 컴포넌트 → 캐시된 서버 액션 → MongoDB
2. 캐시 히트 시 데이터베이스 쿼리 생략
3. 직접적인 데이터베이스 접근으로 응답 시간 단축

🔍 기술적 인사이트

Next.js 16의 'use cache' 디렉티브

'use cache'는 Next.js 16에서 새롭게 도입된 기능으로, 다음과 같은 특징이 있음:

• 함수 레벨 캐싱: 특정 함수의 실행 결과를 캐시
• 자동 무효화: 배포 시 또는 revalidate 설정에 따라 자동으로 캐시 무효화
• 타입 안전성: TypeScript와 완벽하게 호환
• 서버 액션과의 통합: 서버 액션에서 바로 사용 가능

Mongoose .lean() 최적화

const events = await Event.find().sort({ createdAt: -1 }).lean();

.lean() 메서드는:

• Mongoose Document 대신 순수 JavaScript 객체 반환
• 메모리 사용량 약 30-40% 감소
• 직렬화 성능 향상
• 읽기 전용 데이터에 최적화

  ⚠️ 주의사항

  .lean()을 사용하면 Mongoose의 virtuals, getter/setter, 메서드 등을 사용할 수 없음. 순수하게 데이터만 읽어올 때 사용해야 함.

🎨 코드 구조 개선

컴포넌트 분리의 이점

기존에는 app/page.tsx에서 직접 이벤트 목록을 렌더링했으나, EventList 컴포넌트로 분리함으로써:

1. 단일 책임 원칙 준수: 각 컴포넌트가 하나의 명확한 역할 수행
2. 테스트 용이성: 독립적인 컴포넌트 테스트 가능
3. 재사용성: 다른 페이지에서도 동일한 이벤트 리스트 UI 재사용 가능
4. 유지보수성: 이벤트 목록 관련 변경사항을 한 곳에서 관리

🚦 다음 단계

현재 구현된 캐싱은 기본적인 수준이며, 추가로 고려할 수 있는 개선사항:

1. Revalidation 전략 수립

   • 이벤트 생성/수정 시 캐시 무효화
   • 시간 기반 revalidation 설정

2. 세분화된 캐싱

   • 개별 이벤트 단위 캐싱
   • 태그 기반 캐시 무효화

3. 모니터링

   • 캐시 히트율 측정
   • 성능 메트릭 추적

📝 결론

Next.js 16의 새로운 캐싱 기능을 활용하여 애플리케이션의 성능을 크게 개선함. 'use cache' 디렉티브와 서버 액션의 조합은 매우 강력하며, 기존의 복잡한 캐싱 전략을 단순화할 수 있음.

특히 다음과 같은 점에서 의미가 있음:

• ✅ 개발자 경험(DX) 향상: 선언적인 캐싱 방식
• ✅ 성능 개선: 불필요한 네트워크 요청 제거
• ✅ 코드 품질: 더 나은 구조와 관심사의 분리
• ✅ 확장성: 향후 추가 최적화를 위한 기반 마련

서론

AI 에이전트를 라이브러리 없이 순수하게 구현해보면서 에이전트의 핵심 작동 원리를 이해해봅시다. 이 글에서는 OpenAI의 Function Calling 기능과 반복 루프(Agent Loop)만으로 목표를 달성하기 위한 Todo 리스트를 자동으로 생성하고, 각 항목을 순차적으로 실행하는 완전한 에이전트 시스템을 구축하는 방법을 다룹니다.

개념 소개

Agent란 무엇인가?

에이전트에는 몇 가지 논의된 정의가 있습니다:

1. Sam Altman의 정의: 독립적으로 작업을 수행할 수 있는 AI 시스템
2. Anthropic의 정의: LLM이 워크플로우를 제어하는 시스템
3. 새로운 표준 정의: LLM이 목표를 달성하기 위해 도구를 반복적으로 실행하는 시스템

이 글에서는 세 번째 정의, 즉 "도구를 반복 실행하며 목표를 달성하는 에이전트"를 실제로 구현해봅니다.

Todo 관리 도구 만들기

에이전트가 사용할 도구를 먼저 만들어야 합니다. 여기서는 간단한 Todo 관리 시스템을 구현합니다.

# 필요한 라이브러리 import 및 환경변수 로드
from rich.console import Console #콘솔 print 를 이쁘게 꾸미기 위함
from dotenv import load_dotenv
from openai import OpenAI
import json
load_dotenv(override=True)

def show(text):
    try:
        Console().print(text)
    except Exception:
        print(text)

openai = OpenAI()

# 기본 데이터 구조
todos = []        # Todo 항목들을 저장하는 리스트
completed = []    # 각 Todo의 완료 여부를 저장하는 리스트

def create_todos(descriptions: list[str]) -> str:
    """
    새로운 Todo 항목들을 생성하는 도구

    Args:
        descriptions: Todo 항목들의 설명 리스트
    Returns:
        현재 Todo 리스트 상태를 문자열로 반환
    """
    todos.extend(descriptions)
    completed.extend([False] * len(descriptions))
    return get_todo_report()

def mark_complete(index: int, completion_notes: str) -> str:
    """
    특정 Todo를 완료 처리하는 도구

    Args:
        index: 완료할 Todo의 인덱스 (1부터 시작)
        completion_notes: 완료 과정에 대한 설명
    Returns:
        업데이트된 Todo 리스트 상태
    """
    if 1 <= index <= len(todos):
        completed[index - 1] = True
    else:
        return "No todo at this index."
    Console().print(completion_notes)  # 완료 노트를 출력
    return get_todo_report()

def get_todo_report() -> str:
    """
    현재 Todo 리스트 상태를 시각적으로 표시
    완료된 항목은 취소선과 녹색으로 표시
    """
    result = ""
    for index, todo in enumerate(todos):
        if completed[index]:
            # Rich 라이브러리의 마크업을 사용한 시각적 표현
            result += f"Todo #{index + 1}: [green][strike]{todo}[/strike][/green]\n"
        else:
            result += f"Todo #{index + 1}: {todo}\n"
    show(result)
    return result

이 도구들은 에이전트가 계획을 세우고(create_todos), 실행하고(mark_complete), 진행 상황을 확인(get_todo_report)할 수 있게 해줍니다.

Function Calling을 위한 JSON Schema

OpenAI의 Function Calling 기능을 사용하려면 각 도구를 JSON Schema 형식으로 정의해야 합니다.

# 🔧 Tool 정의: create_todos
create_todos_json = {
    "name": "create_todos",
    "description": "Add new todos from a list of descriptions and return the full list",
    "parameters": {
        "type": "object",
        "properties": {
            "descriptions": {
                'type': 'array',           # 배열 타입
                'items': {'type': 'string'},  # 문자열 항목들
                'title': 'Descriptions'
            }
        },
        "required": ["descriptions"],      # 필수 파라미터
        "additionalProperties": False
    }
}

# 🔧 Tool 정의: mark_complete
mark_complete_json = {
    "name": "mark_complete",
    "description": "Mark complete the todo at the given position (starting from 1) and return the full list",
    "parameters": {
        'properties': {
            'index': {
                'description': 'The 1-based index of the todo to mark as complete',
                'title': 'Index',
                'type': 'integer'
            },
            'completion_notes': {
                'description': 'Notes about how you completed the todo in rich console markup',
                'title': 'Completion Notes',
                'type': 'string'
            }
        },
        'required': ['index', 'completion_notes'],
        'type': 'object',
        'additionalProperties': False
    }
}

# OpenAI API에 전달할 tools 리스트
tools = [
    {"type": "function", "function": create_todos_json},
    {"type": "function", "function": mark_complete_json}
]

💡 JSON Schema는 LLM에게 도구의 사용법을 알려주는 명세서입니다. LLM은 이 스키마를 보고 언제, 어떻게 도구를 호출해야 하는지 결정합니다.

Agent Loop 구현하기

이제 핵심인 Agent Loop를 구현합니다.

# 🚀 Tool Call 처리 함수
def handle_tool_calls(tool_calls):
    """
    LLM이 요청한 도구 호출들을 실제로 실행

    Args:
        tool_calls: LLM이 요청한 tool call 객체들
    Returns:
        실행 결과를 담은 메시지 리스트
    """
    results = []
    for tool_call in tool_calls:
        tool_name = tool_call.function.name  # 호출할 함수 이름
        arguments = json.loads(tool_call.function.arguments)  # 함수 인자를 파싱

        # globals()에서 함수 찾기 - 실제 Python 함수 참조
        tool = globals().get(tool_name)

        # 함수 실행 및 결과 반환
        result = tool(**arguments) if tool else {}

        # OpenAI API 형식에 맞는 결과 메시지 생성
        results.append({
            "role": "tool",
            "content": json.dumps(result),
            "tool_call_id": tool_call.id
        })
    return results

# 🔄 핵심 Agent Loop
def loop(messages):
    """
    에이전트의 핵심 반복 루프
    LLM이 도구를 호출할 때마다 실행하고, 
    더 이상 도구 호출이 없을 때까지 반복
    """
    done = False
    while not done:
        # 1. LLM에게 현재 상황 전달 및 응답 받기
        response = openai.chat.completions.create(
            model="gpt-4", 
            messages=messages, 
            tools=tools
        )

        finish_reason = response.choices[0].finish_reason

        # 2. 응답 유형에 따라 분기
        if finish_reason == "tool_calls":
            # LLM이 도구를 호출하려고 함
            message = response.choices[0].message
            tool_calls = message.tool_calls

            # 3. 도구 실행
            results = handle_tool_calls(tool_calls)

            # 4. 대화 기록에 추가 (LLM의 요청 + 도구 실행 결과)
            messages.append(message)
            messages.extend(results)
            # 루프 계속 - LLM이 다시 판단하도록
        else:
            # LLM이 최종 답변을 제공함 - 루프 종료
            done = True

    # 최종 결과 출력
    show(response.choices[0].message.content)

💡Agent Loop의 핵심 원리

1. LLM에게 현재 상태와 가용 도구를 제공
2. LLM이 도구 호출을 요청하면 실행
3. 실행 결과를 대화 기록에 추가
4. LLM이 "완료"라고 판단할 때까지 1-3 반복

이 간단한 패턴으로 복잡한 여러 단계의 문제도 해결할 수 있습니다!

실제 사용 예시

목표 지향적인 시스템 프롬프트와 함께 실행해봅시다:

# 📋 시스템 프롬프트 - 에이전트의 역할 정의
system_message = """
당신은 주어진 문제를 해결하기 위해 '할 일 목록(todo)' 도구를 사용하여 계획을 세우고, 
각 단계를 순차적으로 실행하는 해결사입니다.
계획을 세우고, 실행하고, 최종 해결책을 응답하세요.
수치가 명확하지 않다면 합리적인 추정치를 포함하세요.
코드 블록 없이 Rich 콘솔 마크업으로 답변하고, 사용자에게 질문하지 마세요.
"""

# 💬 실제 문제 제시
user_message = """
서울역에서 오후 2시에 출발하는 시속 250km KTX가 있습니다.
오후 3시에 부산역에서 서울을 향해 출발하는 시속 300km 열차가 있습니다.
두 열차는 언제 만날까요? (서울-부산 거리는 약 400km로 가정합니다)
"""

messages = [
    {"role": "system", "content": system_message}, 
    {"role": "user", "content": user_message}
]

# 🎯 에이전트 실행
todos, completed = [], []
loop(messages)

에이전트가 수행하는 과정

1. 계획 수립: create_todos 호출
2. 순차 실행: 각 Todo를 mark_complete로 처리
3. 최종 답변: 모든 Todo 완료 후 결과 제시

• 결과 예시

💡 저는 단순히 질문을 했을 뿐이지만, AI 가 직접 문제를 해결하기 위한 조건을 생성하고 차례대로 해결해 나가는 것을 볼 수 있습니다. 이 패턴은 단순한 계산뿐만 아니라 웹 검색, 파일 조작, API 호출 등 다양한 도구와 결합하여 복잡한 작업을 자동화할 수 있습니다.

주의사항

1. 무한 루프 방지

• 실제 프로덕션에서는 최대 반복 횟수 제한 필요
• 예: max_iterations = 10

2. 에러 핸들링 필요

• 에러 내용에 대한 로그를 확인할 수 있는 시스템 구축 필요

3. 비용 관리

• 각 루프마다 API 호출이 발생하므로 토큰 사용량 모니터링 필요
• response.usage로 토큰 사용량 추적

4. 도구 보안

• globals().get(tool_name)은 편리하지만 보안 위험 존재
• 프로덕션에서는 허용된 도구 목록을 명시적으로 관리:

  ALLOWED_TOOLS = {
    "create_todos": create_todos,
    "mark_complete": mark_complete
  }
  tool = ALLOWED_TOOLS.get(tool_name)

  5. 평가-피드백 루프 추가

• Evaluator Agent 를 추가하여 각 Agent 의 답변이 올바른지 평가하고 피드백 Loop 를 추가하여 답변의 퀄리티를 높일 수 있습니다.

핵심 정리

• 기본적인 Agent Loop 패턴: LLM이 도구 호출과 결과 확인을 반복하며 목표를 달성하는 패턴
• 자율성: 도구 실행 결과를 대화 기록에 추가하여 LLM이 다음 행동을 스스로 결정
• 구현의 단순함: OpenAI Function Calling + while 루프만으로 강력한 에이전트 구현 가능
• 확장성: Todo 관리 도구를 웹 검색, 데이터베이스 조작, 코드 실행 등으로 대체하면 실용적인 에이전트로 발전

Next Step:

1. 멀티 에이전트 시스템: 여러 에이전트가 협력하여 작업 수행
2. 메모리 관리: 대화 기록이 너무 길어질 때 요약 기법 적용
3. 고급 도구: 파일 시스템 접근, API 호출, 데이터베이스 쿼리 등
4. 에이전트 프레임워크: LangChain, AutoGen 등의 프레임워크가 이 패턴을 어떻게 추상화하는지 학습

AI agent를 통한 개발이 활발하게 이루어지고 있고, 그에 따라 사용하는 프레임워크나 Tool 선택이 중요해졌습니다. 그 중 Next.js 가 16 버전으로 업데이트 되면서, ai와 함께 하는 풀스택 개발이 더욱 용이해진 것 같습니다. 개요 : 기존의 파일 기반 라우팅 시스템을 계승하면서도, 성능 최적화, 비동기 데이터 처리, 그리고 명시적 캐싱 모델에서 혁신적인 변화를 도입했습니다. 본 포스트에서는 이러한 핵심 개념들을 체계적으로 정리하고, 프로젝트에서 바로 활용할 수 있는 예제와 함께 정리해보겠습니다.

1. 파일 기반 라우팅(File-based Routing) 기초

Next.js의 라우팅 시스템은 "Convention over Configuration" 철학을 따릅니다. 별도의 라우팅 라이브러리나 복잡한 설정 없이, 파일 시스템 구조 자체가 곧 URL 경로가 됩니다.

1-1. 기본 원리 (App routing or Page routing)

app 디렉터리가 라우팅의 루트가 되며, 폴더 구조가 URL 경로와 1:1로 매핑됩니다.

app/
├── page.tsx           → /
├── about/
│   └── page.tsx       → /about
├── blog/
│   ├── page.tsx       → /blog
│   └── [slug]/
│       └── page.tsx   → /blog/:slug
└── dashboard/
    ├── page.tsx       → /dashboard
    └── settings/
        └── page.tsx   → /dashboard/settings

1-2. page.tsx의 역할

각 폴더 내의 page.tsx 파일이 해당 경로의 Entry Point가 됩니다. 이 파일이 없으면 해당 경로는 접근 불가능합니다.

// app/about/page.tsx
export default function AboutPage() {
  return (
    <main>
      <h1>About Us</h1>
      <p>Welcome to our about page!</p>
    </main>
  );
}

1-3. 중첩 라우팅의 장점

폴더 안에 폴더를 구성하여 계층 구조를 자연스럽게 형성할 수 있습니다. 이는 다음과 같은 이점을 제공합니다:

2. 동적 라우팅과 비동기 Params 처리

URL의 가변적인 세그먼트를 처리하는 동적 라우팅은 Next.js의 핵심 기능 중 하나입니다.

2-1. 동적 세그먼트 종류

2-2. 비동기적 Params 접근 (🆕 핵심 변경사항)

Next.js 15/16 버전부터 params와 searchParams는 Promise 객체로 전달됩니다. 이는 프레임워크의 렌더링 최적화를 위한 중요한 변화입니다.

// ❌ 이전 방식 (Next.js 14 이하) - 더 이상 동작하지 않음
export default function Page({ params }: { params: { id: string } }) {
  return <div>User ID: {params.id}</div>; // 런타임 에러!
}

// ✅ 현재 방식 (Next.js 15/16) - 비동기 처리 필수
export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  return <div>User ID: {id}</div>;
}

2-3. 클라이언트 컴포넌트에서의 처리

클라이언트 컴포넌트에서는 async/await를 직접 사용할 수 없으므로, React 19의 use() 훅을 활용합니다.

'use client';
import { use } from 'react';

export default function UserProfile({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = use(params);

  return (
    <div className="profile-card">
      <h2>User Profile</h2>
      <p>ID: {id}</p>
    </div>
  );
}

❗마이그레이션 체크리스트

• 모든 params 접근을 await 또는 use()로 변경
• searchParams 역시 동일하게 비동기 처리
• 타입 정의를 Promise<T>로 업데이트
• 기존 동기 접근 로직 제거

3. 레이아웃(Layouts) 및 성능 최적화

레이아웃은 여러 페이지 간에 공통 UI를 공유하고 상태를 유지하는 핵심 메커니즘입니다.

3-1. 레이아웃 계층 구조

app/
├── layout.tsx          ← 모든 페이지에 적용 (필수)
├── page.tsx
└── dashboard/
    ├── layout.tsx      ← /dashboard/* 경로에만 적용
    ├── page.tsx
    └── analytics/
        └── page.tsx    ← 상위 두 레이아웃 모두 적용

// app/layout.tsx (루트 레이아웃 - 필수)
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="ko">
      <body>
        <header>
          <nav>메인 네비게이션</nav>
        </header>
        <main>{children}</main>
        <footer>© 2026 My App</footer>
      </body>
    </html>
  );
}

// app/dashboard/layout.tsx (대시보드 전용 레이아웃)
export default function DashboardLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <div className="dashboard-wrapper">
      <aside className="sidebar">
        <ul>
          <li>개요</li>
          <li>분석</li>
          <li>설정</li>
        </ul>
      </aside>
      <section className="content">{children}</section>
    </div>
  );
}

3-2. Layout Deduplication (🆕 Next.js 16 핵심 최적화)

Next.js 16에서 도입된 Layout Deduplication은 동일한 레이아웃을 사용하는 경로들 사이를 탐색할 때, 해당 레이아웃 컴포넌트를 재다운로드하지 않고 재사용합니다.

[기존 방식]
/dashboard/overview → /dashboard/analytics
레이아웃 번들 다운로드 (중복 발생!)

[Next.js 16 Deduplication]
/dashboard/overview → /dashboard/analytics
레이아웃 캐시 활용 (네트워크 요청 없음!)

성능 개선 효과:

3-3. 레이아웃 vs 템플릿

4. 라우트 그룹(Route Groups)

URL 구조에 영향을 주지 않으면서 프로젝트 구조를 논리적으로 조직화할 수 있는 강력한 기능입니다.

4-1. 기본 사용법

폴더명을 소괄호 ()로 감싸면 해당 폴더는 URL 경로에서 제외됩니다.

app/
├── (marketing)/
│   ├── layout.tsx      ← 마케팅 전용 레이아웃
│   ├── page.tsx        → /
│   ├── about/
│   │   └── page.tsx    → /about
│   └── pricing/
│       └── page.tsx    → /pricing
├── (dashboard)/
│   ├── layout.tsx      ← 대시보드 전용 레이아웃
│   ├── overview/
│   │   └── page.tsx    → /overview
│   └── settings/
│       └── page.tsx    → /settings
└── (auth)/
    ├── layout.tsx      ← 인증 전용 레이아웃 (최소 UI)
    ├── login/
    │   └── page.tsx    → /login
    └── register/
        └── page.tsx    → /register

4-2. 활용 시나리오

시나리오 1: 다중 루트 레이아웃 동일한 루트 레벨에서 완전히 다른 레이아웃을 적용해야 할 때 유용합니다.

// app/(marketing)/layout.tsx - 화려한 랜딩 페이지 레이아웃
export default function MarketingLayout({ children }: { children: React.ReactNode }) {
  return (
    <div className="marketing-theme">
      <header className="hero-header">...</header>
      {children}
      <footer className="full-footer">...</footer>
    </div>
  );
}

// app/(dashboard)/layout.tsx - 미니멀한 앱 레이아웃
export default function DashboardLayout({ children }: { children: React.ReactNode }) {
  return (
    <div className="app-theme">
      <Sidebar />
      <main>{children}</main>
    </div>
  );
}

시나리오 2: 팀/도메인별 코드 분리

app/
├── (shop)/              ← 이커머스 팀 담당
│   ├── products/
│   └── cart/
├── (blog)/              ← 콘텐츠 팀 담당
│   ├── posts/
│   └── categories/
└── (admin)/             ← 관리자 기능
    └── users/

5. 특수 파일과 UI 상태 처리

Next.js는 특정 상태에 대응하기 위한 예약된 파일들을 제공하여 선언적인 UI 관리를 가능하게 합니다.

5-1. 특수 파일 종류

5-2. 로딩 상태 처리 (loading.tsx)

// app/dashboard/loading.tsx
export default function DashboardLoading() {
  return (
    <div className="loading-container">
      <div className="skeleton-header" />
      <div className="skeleton-grid">
        {[1, 2, 3, 4].map((i) => (
          <div key={i} className="skeleton-card" />
        ))}
      </div>
      <p className="loading-text">대시보드 로딩 중...</p>
    </div>
  );
}

5-3. 에러 처리 (error.tsx)

// app/dashboard/error.tsx
'use client'; // ⚠️ 필수!

import { useEffect } from 'react';

export default function DashboardError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    // 에러 로깅 서비스로 전송
    console.error('Dashboard Error:', error);
  }, [error]);

  return (
    <div className="error-container">
      <h2>⚠️ 문제가 발생했습니다</h2>
      <p>{error.message}</p>
      <button onClick={reset} className="retry-btn">
        다시 시도
      </button>
    </div>
  );
}

5-4. 인증/권한 에러 처리 (🆕 Next.js 16)

// app/admin/forbidden.tsx - 403 Forbidden
export default function AdminForbidden() {
  return (
    <div className="forbidden-page">
      <h1>🚫 접근 권한이 없습니다</h1>
      <p>이 페이지를 보려면 관리자 권한이 필요합니다.</p>
      <a href="/contact">권한 요청하기</a>
    </div>
  );
}

// app/dashboard/unauthorized.tsx - 401 Unauthorized
export default function DashboardUnauthorized() {
  return (
    <div className="unauthorized-page">
      <h1>🔐 로그인이 필요합니다</h1>
      <p>이 페이지를 보려면 먼저 로그인해주세요.</p>
      <a href="/login">로그인 페이지로 이동</a>
    </div>
  );
}

[!WARNING] Error Component 주의점 error.tsx는 클라이언트 사이드에서 에러를 캡처해야 하므로 반드시 파일 최상단에 'use client' 지시어를 포함해야 합니다. 이를 누락하면 에러 바운더리가 제대로 동작하지 않습니다.

6. API 라우트 핸들러(Route Handlers)

프론트엔드 라우팅과 동일한 파일 시스템 기반으로 백엔드 API 엔드포인트를 구축합니다.

6-1. 기본 구조

app/
└── api/
    ├── users/
    │   ├── route.ts          → GET/POST /api/users
    │   └── [id]/
    │       └── route.ts      → GET/PUT/DELETE /api/users/:id
    └── events/
        └── route.ts          → /api/events

6-2. HTTP 메서드 핸들러

// app/api/users/route.ts
import { NextRequest, NextResponse } from 'next/server';

// GET /api/users - 사용자 목록 조회
export async function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams;
  const page = parseInt(searchParams.get('page') || '1');
  const limit = parseInt(searchParams.get('limit') || '10');

  const users = await db.user.findMany({
    skip: (page - 1) * limit,
    take: limit,
  });

  return NextResponse.json({
    data: users,
    pagination: { page, limit },
  });
}

// POST /api/users - 사용자 생성
export async function POST(request: NextRequest) {
  try {
    const body = await request.json();
    const { name, email } = body;

    const newUser = await db.user.create({
      data: { name, email },
    });

    return NextResponse.json(newUser, { status: 201 });
  } catch (error) {
    return NextResponse.json(
      { error: 'Failed to create user' },
      { status: 500 }
    );
  }
}

6-3. 동적 API 라우트 (비동기 params 적용)

// app/api/events/[id]/route.ts
export async function GET(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params; // ⚠️ 비동기 처리 필수!

  const event = await db.event.findUnique({
    where: { id },
    include: { attendees: true },
  });

  if (!event) {
    return Response.json(
      { error: 'Event not found' },
      { status: 404 }
    );
  }

  return Response.json(event);
}

export async function PUT(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const body = await request.json();

  const updatedEvent = await db.event.update({
    where: { id },
    data: body,
  });

  return Response.json(updatedEvent);
}

export async function DELETE(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;

  await db.event.delete({ where: { id } });

  return new Response(null, { status: 204 });
}

7. 캐싱 변화: Cache Components

Next.js 16 캐싱의 핵심은 "기본 동적 렌더링, 선택적 캐싱(Opt-in)"으로의 패러다임 전환입니다.

• SSG(Static Site Generation)나 ISR(Incremental Static Regeneration)은 이제 별도의 설정이 아니라, 개발자가 Cache Boundaries를 어떻게 정의하느냐에 따른 결과물로 통합되었습니다.

7-1. 패러다임의 전환: Default Dynamic

7-2. "use cache" 지시어

// next.config.ts에서 활성화 필요
const nextConfig = {
  experimental: {
    cacheComponents: true,
  },
};

// 파일 단위 캐싱
'use cache';

export default async function CachedPage() {
  const data = await fetchExpensiveData();
  return <div>{data}</div>;
}

// 함수 단위 캐싱
async function getCachedProducts(category: string) {
  'use cache';
  const products = await db.product.findMany({
    where: { category },
  });
  return products;
}

// 컴포넌트 단위 캐싱
async function CachedSidebar() {
  'use cache';
  const categories = await getCategories();
  return (
    <aside>
      {categories.map((cat) => (
        <a key={cat.id} href={`/products/${cat.slug}`}>{cat.name}</a>
      ))}
    </aside>
  );
}

7-3. 세밀한 캐시 수명 제어

import { cacheLife } from 'next/cache';

async function getWeatherData(city: string) {
  'use cache';
  cacheLife('hours'); // 1시간 캐싱

  const response = await fetch(`https://weather-api.com/${city}`);
  return response.json();
}

7-4. 캐시 무효화 API

import { revalidateTag, updateTag } from 'next/cache';

// Server Action에서 캐시 갱신
export async function updateProduct(productId: string, data: ProductData) {
  'use server';

  await db.product.update({
    where: { id: productId },
    data,
  });

  // 태그 기반 캐시 무효화 (프로필 지정 필수)
  revalidateTag(`product-${productId}`, 'default');

  // 🆕 Read-your-writes 시맨틱: 변경 즉시 반영
  updateTag(`product-${productId}`);
}

8. 개발 생산성 최적화 (DX)

8-1. Server Components HMR Cache

로컬 개발 중 HMR 발생 시, 서버 컴포넌트 내의 fetch 응답을 캐싱합니다.

// 개발 모드에서 자동 적용
async function DataComponent() {
  // 코드 수정으로 HMR이 발생해도
  // 이 fetch는 캐시된 결과를 반환 (재호출 X)
  const data = await fetch('https://api.example.com/expensive-data');
  return <div>{data}</div>;
}

이점:

• 불필요한 API 재호출 방지
• 유료 API 비용 절감
• 빠른 UI 확인 가능

8-2. Turbopack File System Caching

// next.config.ts
const nextConfig = {
  experimental: {
    turbopackFileSystemCacheForDev: true,
  },
};

효과:

• 개발 서버 재시작 속도 ~50% 개선
• 컴파일 결과물이 디스크에 캐싱됨

9. 강력한 SEO 및 메타데이터 관리

9-1. 서버 사이드 렌더링의 SEO 이점

[클라이언트 사이드 렌더링 (CSR)]
크롤러 요청 → 빈 HTML → JS 로드 → 렌더링 → 콘텐츠 색인
(크롤러가 JS를 실행하지 않으면 색인 실패)
>
[서버 사이드 렌더링 (SSR) - Next.js]
크롤러 요청 → 완성된 HTML → 즉시 콘텐츠 색인 ✅
(JS 실행 필요 없음)

9-2. 메타데이터 관리

설정 기반 (Config-based):

// 정적 메타데이터
export const metadata = {
  title: 'My Blog',
  description: 'A blog about web development',
  openGraph: {
    title: 'My Blog',
    description: 'A blog about web development',
    images: ['/og-image.png'],
  },
};

// 동적 메타데이터 (⚠️ params 비동기 처리 필수)
export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = await getPost(slug);

  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      title: post.title,
      description: post.excerpt,
      images: [post.coverImage],
    },
  };
}

파일 기반 (File-based):

app/
├── favicon.ico         → <link rel="icon">
├── icon.png            → <link rel="icon">
├── apple-icon.png      → <link rel="apple-touch-icon">
├── opengraph-image.png → <meta property="og:image">
├── twitter-image.png   → <meta name="twitter:image">
└── sitemap.ts          → /sitemap.xml

9-3. SEO 성능 최적화 수치

10. Partial Pre-rendering (PPR)의 완성

PPR은 정적 구조와 동적 데이터를 한 페이지 내에서 결합하는 혁신적인 렌더링 전략입니다.

10-1. 작동 원리

export default async function ProductPage({ params }: Props) {
  const { id } = await params;

  return (
    <main>
      {/* 정적 영역: 빌드 시 프리렌더링 */}
      <Header />
      <ProductImages productId={id} />

      {/* 동적 영역: Suspense로 스트리밍 */}
      <Suspense fallback={<PriceSkeleton />}>
        <DynamicPrice productId={id} />
      </Suspense>

      <Suspense fallback={<ReviewsSkeleton />}>
        <LiveReviews productId={id} />
      </Suspense>

      {/* 캐시된 영역 */}
      <CachedRecommendations category={product.category} />

      <Footer />
    </main>
  );
}

10-2. 사용자 경험 플로우

1. 즉시 (0ms)     → 정적 Shell 표시 (Header, Footer)
2. 50ms           → 캐시된 ProductImages 로드
3. 100-200ms      → DynamicPrice 스트리밍 완료
4. 200-500ms      → LiveReviews 스트리밍 완료

📝 결론 및 마이그레이션 가이드

Next.js 16은 "명시성(Explicitness)"을 핵심 가치로 삼아, 개발자가 애플리케이션의 동작을 더 정확하게 예측하고 제어할 수 있도록 설계되었습니다.

핵심 체크리스트

• params/searchParams 비동기화: 모든 동적 라우트에서 await 적용
• 캐싱 전략 재정의: "use cache" + cacheLife 조합으로 명시적 설정
• 특수 파일 활용: forbidden.tsx, unauthorized.tsx 도입
• API 라우트 업데이트: Route Handler의 params도 비동기 처리
• PPR 적용: Suspense와 "use cache"를 활용한 하이브리드 렌더링

버전별 변경사항 요약

👍업데이트 된 Next.js 16 의 핵심 내용을 전반적으로 살펴 보았습니다. Vecel 등에서 공유한 React, Nextjs 관련 Skills 을 엮어 Spec 을 정의하고 agent와 함께 더욱 예측 가능하고 유지보수 하기 쉬운 프로덕트를 개발하기 용이할 것 같습니다!!

Reference

• https://nextjs.org/docs/app/guides (전체적인 next.js16 내용 with app routing)
• https://nextjs.org/blog/next-16 (변경내용 한번에 보기)

LLM 기반 애플리케이션이 단순한 프롬프팅을 넘어 복잡한 시스템으로 진화함에 따라, 신뢰성과 성능을 확보하기 위한 워크플로우 설계가 중요해짐. Anthropic에서 정의한 5가지 핵심 디자인 패턴을 분석하고 정리함.

🏗️ 1. Prompt Chaining

작업을 고정된 일련의 하위 작업 단계로 분해하여 순차적으로 실행하는 패턴임.

• 특징: 하나의 LLM 출력이 다음 LLM의 입력이 되는 구조. 중간에 코드(Gate)를 넣어 흐름을 제어할 수 있음.
• 장점: 각 단계를 정밀하게 설계할 수 있어 가드레일 적용이 용이하고 성능 최적화에 유리함.
• 예시: 섹터 선정 -> 페인 포인트 식별 -> 솔루션 제안 순으로 이어지는 비즈니스 로직.

💡 Note: Anthropic은 이를 워크플로우로 정의하지만, 첫 번째 단계의 결과에 따라 이후 작업의 맥락이 결정된다는 점에서 에이전트적 특성(자율성)과 경계가 모호한 지점이 있음.

🚦 2. Routing

입력을 분류하고, 해당 작업에 가장 적합한 전문 모델이나 프롬프트로 전달하는 패턴임.

• 특징: 'Router' 역할을 하는 LLM이 입력값의 의도를 파악하여 분기 처리를 수행함.
• 장점: 각 분야에 특화된 전문가(Specialist) 모델을 활용할 수 있어 관심사 분리(Separation of Concerns)가 가능함.
• 적용: 고객 문의를 기술 지원, 결제 문의, 일반 상담 등으로 분류하여 처리할 때 매우 유용함.

⚡ 3. Parallelization

하나의 작업을 여러 개로 쪼개어 동시에 처리한 후 결과를 합치는 패턴임.

• 특징: 코드(Python 등) 수준에서 제어하며, 여러 LLM 호출을 동시(Concurrent)에 실행함.
• 장점: 처리 속도(Latency)를 단축하고 결과의 일관성을 높일 수 있음.
• 유형:
  • Sectioning: 큰 작업을 독립적인 하위 작업으로 나누어 병렬 처리.
  • Voting/Averaging: 동일한 작업을 여러 번 수행하여 결과의 평균을 내거나 최적의 답변을 선택.

🎭 4. Orchestrator-Worker

복잡한 작업을 LLM이 동적으로 분해하고 하위 작업을 할당하는 패턴임.

• 특징: 3번(병렬화)과 유사해 보이지만, 제어 주체가 코드가 아닌 LLM(Orchestrator)이라는 점이 핵심임.
• 동작: 오케스트레이터가 작업을 분석하여 필요한 워커(Worker)의 수와 종류를 결정하고, 최종 결과를 합성(Synthesizer)함.

🚀 Insight: 워커에게 할당하는 방식에 재량권이 부여되므로 워크플로우와 에이전트의 중간 단계라고 볼 수 있음.

🔄 5. Evaluator-Optimizer

생성된 결과를 검증하고 피드백을 통해 지속적으로 개선하는 루프 패턴임.

• 특징: 생성자(Generator)와 검증자(Evaluator)가 협력함. 검증자가 거절(Reject)하면 피드백과 함께 생성자에게 되돌려 보냄.
• 장점: 정확성, 예측 가능성, 견고성(Robustness)을 극대화할 수 있음.
• 활용: 코드 생성, 기술 문서 작성 등 품질 보증이 필수적인 도메인에서 가장 강력한 효과를 발휘함.

🚀 Insight: 프로덕션 환경에서는 100% 보장되는 LLM은 없음. 따라서 이 패턴과 같은 검증 에이전트(Validation Agent)를 배치하는 것이 품질 상한선을 높이는 가장 현실적인 방법임.

📌 요약 및 결론

• Made by NotebookLLM

단순한 챗봇을 넘어 시스템을 설계할 때, 위 패턴들을 적재적소에 조합(Composition)하는 능력이 차세대 AI 개발자의 핵심 역량이 될 것임.

참고: Anthropic's Design Patterns for LLM Workflows

📌 개요

Multi-Agent 시스템에서 여러 에이전트를 조율하고 실행하는 Planning Agent를 구현했음. 이번 구현에서는 두 가지 접근 방식을 비교함:

1. PlanningAgent: 사전 정의된 순차적 워크플로우를 따르는 정적 에이전트
2. AutonomousPlanningAgent: OpenAI Tool Calling을 활용하여 동적으로 도구를 선택하고 실행하는 자율 에이전트

Key Concept: Autonomous Agent (자율 에이전트)

사전에 정의된 규칙 대신 LLM이 스스로 계획을 수립하고 적절한 도구(Tool)를 호출하여 목표를 달성하는 시스템임. 이는 기존의 정적 워크플로우와 달리 상황에 따라 유연하게 대응할 수 있는 장점이 있음.

🔧 구현 내용

1️⃣ PlanningAgent: 정적 워크플로우 구현

PlanningAgent는 세 가지 하위 에이전트를 순차적으로 실행하는 전통적인 접근 방식임:

class PlanningAgent(Agent):
    name = "Planning Agent"
    color = Agent.GREEN
    DEAL_THRESHOLD = 50

    def __init__(self, collection):
        """
        Create instances of the 3 Agents that this planner coordinates across
        """
        self.log("Planning Agent is initializing")
        self.scanner = ScannerAgent()
        self.ensemble = EnsembleAgent(collection)
        self.messenger = MessagingAgent()
        self.log("Planning Agent is ready")

워크플로우 실행 로직

plan() 메서드는 다음과 같은 순서로 작업을 수행함:

def plan(self, memory: List[str] = []) -> Optional[Opportunity]:
    """
    Run the full workflow:
    1. Use the ScannerAgent to find deals from RSS feeds
    2. Use the EnsembleAgent to estimate them
    3. Use the MessagingAgent to send a notification of deals
    """
    self.log("Planning Agent is kicking off a run")
    selection = self.scanner.scan(memory=memory)
    if selection:
        opportunities = [self.run(deal) for deal in selection.deals[:5]]
        opportunities.sort(key=lambda opp: opp.discount, reverse=True)
        best = opportunities[0]
        self.log(
            f"Planning Agent has identified the best deal has discount ${best.discount:.2f}"
        )
        if best.discount > self.DEAL_THRESHOLD:
            self.messenger.alert(best)
        self.log("Planning Agent has completed a run")
        return best if best.discount > self.DEAL_THRESHOLD else None
    return None

워크플로우 단계:

1. 스캔: ScannerAgent를 통해 RSS 피드에서 딜 정보 수집
2. 가격 평가: 각 딜에 대해 EnsembleAgent로 실제 가치 추정
3. 정렬 및 선택: 할인율 기준으로 정렬하여 최고의 딜 선택
4. 알림: 할인율이 임계값($50)을 초과하면 MessagingAgent로 사용자에게 알림

2️⃣ AutonomousPlanningAgent: Tool Calling 기반 자율 에이전트

AutonomousPlanningAgent는 OpenAI의 Tool Calling 기능을 활용하여 LLM이 스스로 도구를 선택하고 실행하도록 구현했음.

Tool 정의

세 가지 도구를 JSON Schema 형식으로 정의함:

scan_function = {
    "name": "scan_the_internet_for_bargains",
    "description": "Returns top bargains scraped from the internet along with the price each item is being offered for",
    "parameters": {
        "type": "object",
        "properties": {},
        "required": [],
        "additionalProperties": False,
    },
}

estimate_function = {
    "name": "estimate_true_value",
    "description": "Given the description of an item, estimate how much it is actually worth",
    "parameters": {
        "type": "object",
        "properties": {
            "description": {
                "type": "string",
                "description": "The description of the item to be estimated",
            },
        },
        "required": ["description"],
        "additionalProperties": False,
    },
}

notify_function = {
    "name": "notify_user_of_deal",
    "description": "Send the user a push notification about the single most compelling deal; only call this one time",
    "parameters": {
        "type": "object",
        "properties": {
            "description": {
                "type": "string",
                "description": "The description of the item itself scraped from the internet",
            },
            "deal_price": {
                "type": "number",
                "description": "The price offered by this deal scraped from the internet",
            },
            "estimated_true_value": {
                "type": "number",
                "description": "The estimated actual value that this is worth",
            },
            "url": {
                "type": "string",
                "description": "The URL of this deal as scraped from the internet",
            },
        },
        "required": ["description", "deal_price", "estimated_true_value", "url"],
        "additionalProperties": False,
    },
}

Tool Call 처리 메커니즘

LLM이 요청한 도구 호출을 실제로 실행하는 핸들러:

def handle_tool_call(self, message):
    """
    Actually call the tools associated with this message
    """
    mapping = {
        "scan_the_internet_for_bargains": self.scan_the_internet_for_bargains,
        "estimate_true_value": self.estimate_true_value,
        "notify_user_of_deal": self.notify_user_of_deal,
    }
    results = []
    for tool_call in message.tool_calls:
        tool_name = tool_call.function.name
        arguments = json.loads(tool_call.function.arguments)
        tool = mapping.get(tool_name)
        result = tool(**arguments) if tool else ""
        results.append(
            {"role": "tool", "content": result, "tool_call_id": tool_call.id}
        )
    return results

자율 실행 루프

LLM이 작업을 완료할 때까지 도구 호출을 반복하는 루프:

def plan(self, memory: List[str] = []) -> Optional[Opportunity]:
    """
    Run the full workflow, providing the LLM with tools to surface scraped deals to the user
    """
    self.log("Autonomous Planning Agent is kicking off a run")
    self.memory = memory
    self.opportunity = None
    messages = self.messages[:]
    done = False
    while not done:
        response = self.openai.chat.completions.create(
            model=self.MODEL, messages=messages, tools=self.get_tools()
        )
        if response.choices[0].finish_reason == "tool_calls":
            message = response.choices[0].message
            results = self.handle_tool_call(message)
            messages.append(message)
            messages.extend(results)
        else:
            done = True
    reply = response.choices[0].message.content
    self.log(f"Autonomous Planning Agent completed with: {reply}")
    return self.opportunity

실행 흐름:

1. LLM에게 시스템 메시지와 사용자 메시지 전달
2. LLM이 도구 호출을 요청하면 handle_tool_call()로 실행
3. 도구 실행 결과를 메시지 히스토리에 추가
4. LLM이 "OK"를 반환할 때까지 반복

🎯 두 접근 방식의 비교

정적 vs 동적 워크플로우 선택 기준

• 정적 워크플로우: 작업 순서가 명확하고 변하지 않는 경우, 비용 효율성이 중요한 경우
• 동적 워크플로우: 상황에 따라 유연한 대응이 필요한 경우, 복잡한 의사결정이 필요한 경우

💡 핵심 학습 내용

OpenAI Tool Calling의 동작 원리

1. 도구 정의: JSON Schema 형식으로 함수 시그니처와 설명 제공
2. LLM 요청: 도구 목록과 함께 LLM에 요청 전송
3. 도구 선택: LLM이 상황에 맞는 도구와 인자 결정
4. 실행 및 피드백: 도구 실행 결과를 LLM에 다시 전달
5. 반복: LLM이 작업 완료를 선언할 때까지 반복

자율 에이전트 설계 시 고려사항

system_message = "You find great deals on bargain products using your tools, and notify the user of the best bargain."
user_message = """
First, use your tool to scan the internet for bargain deals. Then for each deal, use your tool to estimate its true value.
Then pick the single most compelling deal where the price is much lower than the estimated true value, and use your tool to notify the user.
Then just reply OK to indicate success.
"""

효과적인 프롬프트 작성

• 명확한 작업 순서 제시
• 종료 조건 명시 ("reply OK to indicate success")
• 도구 사용 목적과 제약사항 설명 ("only call this one time")

🧪 실험 및 검증

Tool Calling 메커니즘을 단계별로 실험했음:

1. 가짜 함수로 프로토타입 구현: 실제 에이전트 없이 Tool Calling 흐름 검증
2. 도구 스키마 정의 및 테스트: JSON Schema 형식의 도구 정의 검증
3. 실제 에이전트 통합: ScannerAgent, EnsembleAgent, MessagingAgent와 통합

실행 결과:

Fake function to scan the internet - this returns a hardcoded set of deals
Fake function to estimating true value of The Hisense R6 Serie... - this always returns $300
Fake function to estimating true value of The Poly Studio P21 ... - this always returns $300
Fake function to estimating true value of The Lenovo IdeaPad S... - this always returns $300
Fake function to estimating true value of The Dell G15 gaming ... - this always returns $300
Fake function to notify user of The Poly Studio P21 ... which costs 30 and estimate is 300

LLM이 자율적으로:

1. 스캔 도구 호출
2. 각 deal에 대해 가치 평가 도구 호출
3. 최고의 deal 선택 및 알림 도구 호출
4. "OK" 응답으로 작업 완료

📝 결론

이번 구현을 통해 정적 워크플로우와 자율 에이전트의 장단점을 명확히 이해했음.

PlanningAgent는 예측 가능하고 비용 효율적이지만 유연성이 제한적임. 반면 AutonomousPlanningAgent는 OpenAI Tool Calling을 활용하여 상황에 맞게 동적으로 대응할 수 있지만, LLM 호출 비용과 예측 불가능성이라는 트레이드오프가 존재함.

실제 프로덕션 환경에서는 두 접근 방식을 하이브리드로 결합하는 것이 효과적일 수 있음:

• 핵심 워크플로우는 정적으로 구현
• 복잡한 의사결정이 필요한 부분만 자율 에이전트 활용

자율 에이전트 구현 시 주의사항

• 무한 루프 방지를 위한 최대 반복 횟수 설정 필요
• 도구 호출 비용 모니터링 필수
• 중요한 작업은 사람의 승인 단계 추가 권장

📚 참고 자료

• OpenAI Function Calling Documentation
• Multi-Agent System Design Patterns

거대 모델을 전체 튜닝하기에는 자원 소모가 너무 큼. 이를 해결하기 위해 QLoRA(Quantized Low-Rank Adaptation)를 도입함.

💡 핵심 메커니즘

• Freeze: 기존 모델의 가중치($W_0$)를 4비트 양자화 상태로 고정하여 메모리 점유율을 최소화함.

• Adapter: 별도의 작은 행렬($lora_A$, $lora_B$)만 추가하여 이 부분만 학습함.

• 수학적 원리:

  $$y = W_0x + \Delta Wx = W_0x + (B \cdot A)x$$

  여기서 $A$와 $B$는 저차원(Rank) 행렬로, 학습 파라미터를 수백만 개에서 수십만 개 수준으로 줄여줌.

🛠️ 레이어 구조 (q_proj 예시)

  (q_proj): lora.Linear4bit(
  (base_layer): Linear4bit(in_features=3072, out_features=3072, bias=False)
  (lora_A): Linear(in_features=3072, out_features=32, bias=False)
  (lora_B): Linear(in_features=32, out_features=3072, bias=False)
)

• Rank(r=32): 원래 $3072 \times 3072$ 크기의 변화를 학습하는 대신, 중간에 32차원을 둔 두 개의 행렬로 분해함. 약 940만 개의 파라미터를 19만 개로 압축한 효과임.

2. 모델 구조 분석: Attention vs MLP 🔍

LLM의 내부는 크게 '소통'을 담당하는 Attention과 '지식'을 담당하는 MLP로 나뉨.

Llama 3의 SwiGLU 구조

Llama 3 모델은 성능 향상을 위해 개선된 MLP 구조를 사용함.

• gate_proj / up_proj: 입력을 8192차원의 고차원으로 확장하여 복잡한 특징을 추출함.
• SiLU 활성화 함수: 비선형성을 도입하여 복잡한 논리 구조를 학습함.
• down_proj: 처리된 정보를 다시 3072차원으로 압축하여 다음 레이어로 전달함.

3. 학습 프로세스와 하이퍼파라미터 ⚙️

모델 학습은 순전파 → 손실 계산 → 역전파 → 최적화의 4단계 사이클을 반복함.

🔄 Training 4-Steps

1. Forward Pass: 입력 데이터를 통해 다음 토큰을 예측함.
2. Loss Calculation: 예측값과 정답 간의 차이를 계산함.
   • $Loss = -\log(P_{target})$ (정답 확률에 음의 로그를 취함)
3. Backward Pass: 오차를 역으로 전달하며 각 파라미터의 기여도(Gradient)를 계산함.
4. Optimization: Paged AdamW 옵티마이저를 사용해 가중치를 미세하게 조정함.

📊 주요 설정값

T4 환경과 A100 환경에서 데이터셋의 크기가 다름.

4. 훈련 모니터링

학습 도중 특정 시점에서 성능이 급격히 저하되는 현상을 포착함. Weights and Biases 를 통해 모니터링.

⚠️ 과적합(Overfitting) 탐지

아래 그래프를 보면 6,200 Step(약 2-Epoch) 지점에서 train/loss는 급격히 떨어지는 반면, eval/loss는 급격히 튀어 오르는 것을 확인할 수 있음. 이는 모델이 훈련 데이터의 노이즈까지 암기하기 시작했다는 강력한 신호임.

✅ 해결 방안 및 개선 아이디어

1. Weight Decay 상향: 가중치의 제곱 합을 손실 함수에 더해 모델의 복잡도를 강제로 제한함. 가중치를 작게 유지하여 '부드러운' 함수를 만듦.
2. Learning Rate 하향: 보폭을 줄여 손실 함수의 최저점에 더 세밀하게 접근함.
3. Cosine Scheduler 최적화: 후반부 학습률을 더 낮게 설정하여 안착을 도움.
4. Dropout 활용: 학습 시 뉴런을 무작위로 비활성화하여 특정 경로에 의존하지 않도록 함 (현재 0.1 설정 유지).

SpringAI 를 활용하여 문서를 기반으로 답변하는 챗봇을 만드는 과정 정리.

🧠 RAG 구조 간단 정리

RAG는 크게 두 단계로 나뉘어져 있다.

1. Retrieval (검색): 질문과 관련된 문서를 벡터 검색을 통해 가져옴
2. Generation (생성): 검색된 문서를 기반으로 답변 생성

Spring-AI는 이걸 아주 간단하게 구성할 수 있도록 DocumentRetriever, EmbeddingModel, VectorStore 같은 컴포넌트 및 상위 인터페이스를 제공한다.

• 아래 그림은 기본적은 RAG 의 흐름을 볼 수 있는 예시이다. 그림에서는 llamaindex, langchain 을 이용했지만, 그 구조는 SpringAI 와 같다.

🔧 준비 사항

0. PgVector 설치

• Local 환경에 Pgvector 를 설치하기 위해서는 Postgresql 과 pgvector와 관련된 확장들도 설치해야 하므로 복잡하다. 따라서 Docker 를 통해 설치하면 편리하다.
• 참고: Pgvector for SpringAI

docker-compose.yml

version: '3.8'
services:
  pgvector-db:
    image: pgvector/pgvector:pg16 # PostgreSQL with pgvector support
    container_name: pgvector-db
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: postgres
    ports:
      - "5432:5432"
    volumes:
      - ./postgres/data:/var/lib/postgresql/data

1. 의존성 추가

repositories {
  mavenCentral()
}

ext {
  set('springAiVersion', "1.0.0")
}

dependencies {
  implementation 'org.springframework.ai:spring-ai-advisors-vector-store'
  implementation 'org.springframework.ai:spring-ai-starter-model-ollama'
  implementation 'org.springframework.ai:spring-ai-starter-vector-store-pgvector'
}

dependencyManagement {
  imports {
    mavenBom "org.springframework.ai:spring-ai-bom:${springAiVersion}"
  }
}

2. application.yml 설정

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/postgres
    username: postgres
    password: postgres
  ai:
      ollama:
      base-url: http://localhost:11434  # Ollama 서버 URL
      chat:
        options:
          model: gemma3:4b # 사용할 chat 모델
      embedding:
        options:
          model:  # RAG 위한 임베딩 모델
    vectorstore:
      pgvector:
        index-type: HNSW
        distance-type: COSINE_DISTANCE
        # dimensions: 1536 <- 없으면 각 임베딩 모델에 맞는 적절한 dimensions 로 적용됨
        max-document-batch-size: 10000 # Optional: 각 배치 마다 처리될 수 있는 최대 document 수

📄 문서 임베딩 & 저장

SpringAI 에서는 검색 증강 생성 패턴을 구현하기 위한, ETL(Extract, Transform, and Load) 데이터 엔지니어링과 관련된 컴포넌트 및 인터페이스를 제공한다.

• 문서 데이터를 로드하여 가공 후 Vector DB 에 저장하는 흐름

위 그림과 같이 ETL 을 위한 인터페이스는 크게 DocumentReader, DocumentTransformer, DocumentWriter 가 존재하고, 아래의 클래스 다이어그램은 해당 인터페이스의 구현이 나와 있다.

각 구현체를 통해, 문서의 특성 및 상황을 고려하여 ETL 파이프라인을 구성할 수 있다. 또한, 각 문서 특성에 맞는 의존성을 설치하여야 한다. 예를 들어, pdf 문서를 로드하기 위해서는 아래의 의존성을 추가하면 된다.

dependencies {
    implementation 'org.springframework.ai:spring-ai-pdf-document-reader'
}

• pdf를 로드하고 Vector DB 에 저장하는 예시

@Component
public class MyPagePdfDocumentReader {
    private final VectorStore vectorStore;

    void getDocsFromPdf() {

        PagePdfDocumentReader pdfReader = new PagePdfDocumentReader("classpath:/sample1.pdf",
                PdfDocumentReaderConfig.builder()
                    .withPageTopMargin(0)
                    .withPageExtractedTextFormatter(ExtractedTextFormatter.builder()
                        .withNumberOfTopTextLinesToDelete(0)
                        .build())
                    .withPagesPerDocument(1)
                    .build());

        List<Document> docs = pdfReader.get();

        vectorStore.add(docs);
    }

}

💬 Advisor API for RAG

SpringAI 는 RAG 패턴을 쉽게 적용하기 위해 Advisor API를 사용한다. RAG 패턴은 사용자 프롬프트와 문서의 유사성을 평가하고 비슷한 문서 chunk 를 조합하여 사용자 프롬프트에 추가하는 방식이다. 이를 위해 SearchRequest 를 사용하여 문서 필터 및 유사도 옵션을 설정 가능하다.

QuestionAnswerAdvisor

• 모든 문서에 대한 유사성 검사

  ChatResponse response = ChatClient.builder(chatModel)
        .build().prompt()
        .advisors(new QuestionAnswerAdvisor(vectorStore))
        .user(userText)
        .call()
        .chatResponse();

• SearchRequest 를 사용

유사도 임계값을 0.8 으로 설정하고 검색된 상위 6개 결과를 반환

var qaAdvisor = QuestionAnswerAdvisor.builder(vectorStore)
        .searchRequest(SearchRequest.builder().similarityThreshold(0.8d).topK(6).build())
        .build();

ChatClient 에 Advisor 추가

ChatClient 의 기본 템플릿을 구성하여 Bean 을 설정할 수도 있다. 예를 들어, QuestionAnswerAdvisor 를 기본 Advisor 로 사용하려면 아래와 같이 작성할 수 있다.

    @Bean
    ChatClient chatClient(ChatClient.Builder builder) {
        return builder
                .defaultSystem(persona, StandardCharsets.UTF_8) //llm 의 페르소나, 기본 지시사항을 설정
                .defaultAdvisors(QuestionAnswerAdvisor
                    .builder(vectorStore)
                      .searchRequest(SearchRequest.builder().build())
                    .build())
                .build();
    }

위와 같이 ChatClient 에 Advisor 를 추가하여 쉽게 QA 챗봇을 구현 가능하다.

📌 마무리

지금까지 문서를 기반으로 답변하는 챗봇, 즉 RAG 시스템을 간단하게 구성해봤다. 실제 서비스에 적용하려면 문서 전처리, 인덱싱 전략, 프롬프트 튜닝 등이 더 필요하지만, 이 정도만 해도 기본 기능은 충분히 구현 가능하다.

다음 글에서는 각 문서 특성에 맞게 문서 처리 파이프라인을 고도화하고, VectorStore 에 문서 chunk 를 저장할 때 Metadata 추가하는 내용을 정리할 것이다.

⏭️ TODO

• 📂 문서 파이프라인 고도화: 분할, 요약, 필터링 전략
• 🧩 Modular-RAG 구조 설계: RAG 와 관련된 처리를 모듈화하여 쉽게 파이프라인 구성하기
• 🧠 LLM 응답 향상을 위한 페르소나 및 시스템 프롬프트 작성

최근 LLM을 개발하고 활용하는 추세가 빠르게 확산되고 있다. Spring AI는 LangChain과 같이 이러한 LLM을 보다 쉽게 사용하도록 돕는 라이브러리. 이러한 흐름과 함께, Spring Boot 환경에서 Spring AI를 활용하면 LLM 기능을 간편하게 통합하여 개발할 수 있을 것 같아 정리 사용 과정을 정리해보려고 한다.

🔍 목표

• Ollama 로컬 모델을 활용하여 Spring-AI 기반의 간단한 챗봇 구현
• Spring Boot 프로젝트에서 LLM을 연동하는 기초 흐름 이해

🧠 Ollama란?

Ollama는 로컬에서 LLM 모델(Mistral, LLaMA, Gemma 등)을 쉽게 실행할 수 있도록 도와주는 플랫폼이다. Docker를 통해 설치가 가능하며 RESTful API를 통해 다양한 언어에서 접근할 수 있는 것이 장점. 개발 환경에서 빠르게 테스트하고 배포 없이 모델을 활용할 수 있다는 점에서 RAG 시스템이나 LLM 서비스 개발에 유용하다.

⚙️ 환경 설정

1. Ollama 설치

• Ollama 설치는 공식 홈페이지에서 간편하게 설치가 가능하고, Mac 유저또는 Windows는 git bash를 통해 아래와 같이 터미널에서 설치 후 사용해 볼 수 있다. 자세한 건 Ollama 공식홈페이지 참고

curl -fsSL https://ollama.com/install.sh | sh
ollama run mistral

2. Spring Boot 프로젝트 설정

• Spring-AI 1.0.0 이 release 되었으므로 사용하는 것이 좋다. Spring initailizer 에서 간편하게 의존성 추가할 수 있다. 다른 필요한 의존성들 또한 Spring initializer 에서 추가 가능하다.
• 주의할 점: SpringAI 1.0.0 이전의 버전들은 라이브러리의 모듈 이름 등의 변화가 있으니 잘 체크해보고 넣어야 함.

build.gradle 또는 pom.xml에 Spring-AI 의존성 추가:

ext {
  set('springAiVersion', "1.0.0")
}

dependencies {
  implementation 'org.springframework.ai:spring-ai-starter-model-ollama'
}

dependencyManagement {
  imports {
    mavenBom "org.springframework.ai:spring-ai-bom:${springAiVersion}"
  }
}

Ollama 를 사용하기 위한 프로젝트 설정

• 공식 홈페이지를 참고하면 각 LLM 서빙 프레임워크 및 API 제공자에 맞게 설정 및 사용 방법이 나와 있다. 참고: Ollama Chat

application.yml 설정:

spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: gemma3:4b
          temperature: 0.7
          # 외 다른 옵션도 설정 가능 없으면 기본 값

모델은 ollama에서 공식으로 제공하는 gemma3:4b 를 사용하였다.

4b 는 LLM 의 파라미터 수를 의미함. ollama gemma3 페이지를 참고하여 여러 파라미터로 된 모델 및 양자화된 버전까지 선택하여 사용할 수 있다.

💬 간단한 Chat API 구현

Spring AI 는 auto-configuration 이 제공되므로 의존성을 추가하고 간단한 application.yml 설정을 하면 바로 사용할 수 있다.

1. ChatController 에서 바로 테스트

@RestController
@RequestMapping("/chat")
public class ChatController {

    private final ChatClient chatClient;

    public ChatController(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    @PostMapping
    public ResponseEntity<String> chat(@RequestBody String message) {
        ChatResponse chatResponse = chatClient.prompt()
                .user("Tell me a joke")
                .call()
                .chatResponse();

        String res = chatResposne
                .getResult().getOutput().getText();

        return ResponseEntity.ok(res);

    }
}

2. ChatClient 인터페이스 활용

Spring-AI에서는 ChatClient라는 추상화를 제공하므로 이를 이용하면 용이하다. 위의 Controller에서 처럼 제공하는 API 를 통해 LLM 서버와 통신이 가능하다. 아래는 공식문서 내용을 발췌한 것이다.

call() return values

After specifying the call() method on ChatClient, there are a few different options for the response type.

• String content(): returns the String content of the response

• ChatResponse chatResponse(): returns the ChatResponse object that contains multiple generations and also metadata about the response, for example how many token were used to create the response.

• ChatClientResponse chatClientResponse(): returns a ChatClientResponse object that contains the ChatResponse object and the ChatClient execution context, giving you access to additional data used during the execution of advisors (e.g. the relevant documents retrieved in a RAG flow).

• entity() to return a Java type

• entity(ParameterizedTypeReference type): used to return a Collection of entity types.

• entity(Class type): used to return a specific entity type.

• entity(StructuredOutputConverter structuredOutputConverter): used to specify an instance of a StructuredOutputConverter to convert a String to an entity type.
  You can also invoke the stream() method instead of call().

✅ 테스트

curl -X POST http://localhost:8080/chat -H "Content-Type: text/plain" -d "안녕!"

응답 예시

"안녕하세요! 무엇을 도와드릴까요?"

📌 마무리

이번 글에서는 Spring-AI와 Ollama를 이용해 가장 기본적인 챗봇 기능이 되는 지만 체크해 보았다. 다음 글에서는 Postgresql 에서 확장적으로 제공하는 PgVector DB 를 활용하여 데이터를 임베딩하고 RAG 를 구현하는 방법을 정리할 것이다.

🗓️ 다음 글 예고

• 📦 PgVector와 벡터 DB 연동하기
• 🔍 문서 기반 QnA 시스템: RAG 기본 개념 및 구현
• 📂 Document ETL Pipeline 설계

수정이나 삭제 등의 비즈니스 로직을 구현할 때, 엔티티의 소유자를 확인하고자 하는 로직을 작성해야할 때가 있습니다. 이런 경우에 서비스 코드마다 유저가 소유자인지 확인하는 코드를 써야 합니다. 아래에 보이는 코드는 짧을 지 모르지만, 서비스 코드마다 중복된 검증 로직이 들어가는 것은 비효율적일 수 있습니다.

// diary fetched ...
if (!diary.getUserAccount().getId().equals(userId)) {
            throw new CustomBaseException(DIARY_NOT_OWNER);
}
// 이후 비즈니스 로직

@EnableMethodSecurity 활용

Spring Security 에서는 AOP 개념을 활용한 Method 단위 Security 전략을 구현할 수 있습니다.

MethodSecurity 를 이용하기 위해서는 SecurityConfig 와 @EnableMethodSecurity 어노테이션을 선언한 Configuration 과 MethodSecurityExpressionHandler 이 필요합니다.

기본적인 SecurityConfig

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        return http
                .cors(cors -> cors
                        .configurationSource(corsConfigurationSource())
                )
                .csrf(AbstractHttpConfigurer::disable)
                .authorizeHttpRequests(
                        auth -> auth.anyRequest().permitAll()
                )
                .build();
    }


    //따로 정의한 AuthConfig 클래스 내용 일부
    @Bean
    public AuthenticationManager authenticationManager() throws Exception {
        DaoAuthenticationProvider authProvider = new DaoAuthenticationProvider();
        authProvider.setUserDetailsService(userDetailsService());
        authProvider.setPasswordEncoder(passwordEncoder());
        return new ProviderManager(authProvider);
    }
}

Spring Security 5.7 이후 부터는 WebSecurityConfigurerAdapter 를 상속받아 구현하지 않고 SecurityFilterChain 이라는 메소드 체인 형식의 코드를 구현하여 빈으로 주입하는 방식으로 이루어 집니다.

AuthenticationManager 는 useDetailService와 passwordEncoder를 주입받고, PrioviderManager 를 반환함으로써 login 시나 다른 인증관련 로직 시 Security Context 에 접근해 user 정보를 저장하거나 관리 할 수 있습니다.

MethodSecurityConfig

import lombok.RequiredArgsConstructor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.access.expression.method.DefaultMethodSecurityExpressionHandler;
import org.springframework.security.access.expression.method.MethodSecurityExpressionHandler;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;

@RequiredArgsConstructor
@EnableMethodSecurity
@Configuration
public class MethodSecurityConfig {
    private final CustomPermissionEvaluator customPermissionEvaluator;

    @Bean
    public MethodSecurityExpressionHandler createExpressionHandler() {
        DefaultMethodSecurityExpressionHandler expressionHandler = new DefaultMethodSecurityExpressionHandler();
        expressionHandler.setPermissionEvaluator(customPermissionEvaluator);
        return expressionHandler;
    }
}

위 클래스에서 중요한 것은 @EnableMethodSecurity 와 MethodSecurityExpressionHandler 를 구현하고 등록하는 것입니다.

CustomPermissionEvaluator

import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.security.access.PermissionEvaluator;
import org.springframework.security.core.Authentication;
import org.springframework.stereotype.Component;

import java.io.Serializable;

import static com.bodytok.healthdiary.exepction.CustomError.*;

@Slf4j
@RequiredArgsConstructor
@Component
public class CustomPermissionEvaluator implements PermissionEvaluator {
    private final DiaryRepository diaryRepository;

    @Override
    public boolean hasPermission(Authentication authentication, Object targetDomainObject, Object permission) {
        return false;
    }

    @Override
    public boolean hasPermission(Authentication authentication, Serializable targetId, String targetType, Object permission) {
        // Security Context 에 존재하는 유저 정보 가져오기
        CustomUserDetails userPrincipal = (CustomUserDetails) authentication.getPrincipal();
        TargetType type = TargetType.fromString(targetType);
        // targetId 가 중요하다.
        return switch (type) {
            case DIARY -> {
                Diary diary = diaryRepository.findById((Long) targetId)
                        .orElseThrow(() -> new CustomBaseException(DIARY_NOT_FOUND));
                yield diary.getUserAccount().getId().equals(userPrincipal.getId());
            }
            case COMMENT -> {
                Comment comment = commentRepository.findById((Long) targetId)
                        .orElseThrow(() -> new CustomBaseException(COMMENT_NOT_FOUND));
                yield comment.getUserAccount().getId().equals(userPrincipal.getId());
            }
            default -> {
                log.error("[인가 실패] 사용자 소유가 아닙니다.");
                yield false;
            }
        };
    }

    public enum TargetType {
        DIARY,
        COMMENT;

        public static TargetType fromString(String targetType) {
            try {
                return TargetType.valueOf(targetType.toUpperCase());
            } catch (IllegalArgumentException e) {
                throw new RuntimeException("Invalid target type: " + targetType);
            }
        }
    }
}

PermissionEvaluator 을 구현하는 CustomPermissionEvaluator 를 작성합니다.

구현해야하는 함수인 시그니처가 다른 두 개의 hasPermission 을 이용해 boolean 값을 리턴함으로서 인가를 수행할 수 있습니다. 위 함수에서 중요한 인자는 targetId, targetType 입니다.

• CustomUserDetails 는 UserDetails 를 구현하여 작성한 인증 클래스입니다.
• 작성된 로직은 Security Context 에 존재하는 유저의 정보를 가져와 현재 조회하는 엔티티의 유저 아이디와 비교해서 소유자인지 검증하는 것입니다.

아래는 @PreAuthorize() 를 활용한, 컨트롤러에서의 메소드 단위 보안 예시 코드입니다.

    @PreAuthorize("hasPermission(#diaryId, 'DIARY', 'UPDATE')")
    @PutMapping("/{diaryId}") 
    @Operation(summary = "다이어리 수정 - 이미지 먼저 저장 or 삭제 후 진행") // Swagger-ui 를 위한 어노테이션임
    public ResponseEntity<Void> updateDiary(
            @PathVariable(name = "diaryId") Long diaryId,
            @RequestBody DiaryUpdate request,
            @AuthenticationPrincipal CustomUserDetails userDetails
    ) {
        ... request 를 dto 로 변환 후 서비스로 넘기는 로직
    }

• hasPermission( #diaryId, 'DIARY', 'UPDATE' ) 의 인자들은 순서대로, 위에서 봤던 targetId, targetType, permission 입니다.

@PreAuthorization 안의 사용된 문법은 SpEL 이라고 하여 Spring 에서 사용하는 표현식입니다. 참고 링크

Debug

디버깅 시 아래와 같이 targetId 와 targetType 이 잘 들어간 것을 확인할 수 있습니다.

결론

SpringSecurity 를 활용하여 메소드 단위의 인가를 AOP 기반으로 하는 코드를 구현해 보았습니다. 이를 더 잘 사용하기 위해서는 AOP 에 대한 이해가 더욱 필요할 것 같습니다. Method Security - SpringSecurity

참고

IntelliJ 로 개발 시 주의

위와 같이 설정하면 잘 돼야 할텐데 계속해서 targetId 가 들어가지 않는 경우가 있습니다. 그런 상황이라면, settings -> Build Tools -> Gradle 에서 Intellij 로 빌드하지 말고 Gradle 로 빌드를 하면 해결할 수 있습니다.

Spring Boot 3.2 이상인가에서 @PathVariable 에 들어온 타입을 Serializable 로 읽지 않는 것 같습니다.

프로젝트 구성

프로젝트에 대한 구성은 아래의 글에서 확인할 수 있습니다.

• [Github Actions + Docker + EC2] 로 배포 자동화 구성하기

기존 Dockerfile

아래는 기존의 Dockerfile 입니다. 루트 컨텍스트에서 Dockerfile 의 빌드가 실행되게 하여, 각 서비스 모듈이 의존하는 다른 모듈들을 참조하기 위해 모든 파일을 복사하여 빌드를 수행합니다.

# Stage 1: Build the application
FROM gradle:8.10.1-jdk17 AS build

WORKDIR /app

# ARG로 전달된 파일 디렉터리 설정
ARG FILE_DIRECTORY

# 파일 복사
COPY $FILE_DIRECTORY /app

# Reservation 모듈만 빌드
RUN ./gradlew :reservation:clean :reservation:build -x test --no-daemon

FROM openjdk:17-jdk-slim

COPY --from=build /app/reservation/build/libs/*SNAPSHOT.jar /app.jar

# JAR 파일 실행
CMD ["java", "-jar", "/app.jar"]

문제점

현재 Dockerfile 의 문제점은 아래와 같습니다.

1. 모든 파일을 복사

• FILE_DIRECTORY 는 루트 컨텍스트의 docker-compose.yml 에서 넘겨준 인자로, 루트 위치를 넘겨줍니다.
• COPY $FILE_DIRECTORY /app 를 통해 루트 내의 하위 파일들을 모두 복사하므로 매우 비효율적입니다.

2. JDK 베이스 이미지 사용

• jar를 실행하기 위한 런타임 환경만 있으면 되는데, 불필요하게 Jdk 를 사용하고 있습니다. 이는 이미지를 무겁게 만듭니다.

개선된 Dockerfile

아래는 reservation 모듈의 Dockerfile 예시입니다.

# Stage 1: Build the application
FROM gradle:8.10.1-jdk17 AS build

WORKDIR /app

# ARG로 전달된 파일 디렉터리 설정
ARG FILE_DIRECTORY

# 필요한 모듈만 복사
COPY $FILE_DIRECTORY/settings.gradle /app/settings.gradle
COPY $FILE_DIRECTORY/gradle /app/gradle
COPY $FILE_DIRECTORY/gradlew /app/gradlew
COPY $FILE_DIRECTORY/reservation /app/reservation
COPY $FILE_DIRECTORY/build.gradle /app/build.gradle

COPY $FILE_DIRECTORY/GlowGrow-common/build.gradle /app/GlowGrow-common/build.gradle
COPY $FILE_DIRECTORY/GlowGrow-common/src /app/GlowGrow-common/src

COPY $FILE_DIRECTORY/GlowGrow-security/build.gradle /app/GlowGrow-security/build.gradle
COPY $FILE_DIRECTORY/GlowGrow-security/src /app/GlowGrow-security/src

COPY $FILE_DIRECTORY/GlowGrow-kafka/build.gradle /app/GlowGrow-kafka/build.gradle
COPY $FILE_DIRECTORY/GlowGrow-kafka/src /app/GlowGrow-kafka/src

# Gradle 빌드 캐시 사용을 위한 외부 의존성 다운로드
RUN ./gradlew :reservation:dependencies --no-daemon

# Reservation 모듈만 빌드
RUN ./gradlew :reservation:clean :reservation:build -x test --no-daemon

# Stage 2: Run the application
FROM eclipse-temurin:17-jre-alpine

# 빌드된 JAR 파일 복사
COPY --from=build /app/reservation/build/libs/*SNAPSHOT.jar /app.jar

# JAR 파일 실행
CMD ["java", "-jar", "/app.jar"]

1. 필요한 모듈만 복사하기

• 필요한 모듈들만 복사하도록 하여 빌드 시간을 단축시키고 이미지 크기를 줄일 수 있습니다.

2. JDK 대신 JRE 사용

• JAR 파일만 실행할 거라면 JRE 이미지를 사용하는 것이 더 적합합니다.
• JRE 이미지는 JDK보다 훨씬 가벼우므로 Docker 이미지 크기를 줄일 수 있습니다.

3. 멀티스테이지 빌드 최적화

• Gradle 빌드에서 종속성 모듈을 처리할 때 전체 프로젝트를 복사하기보다 필요한 부분만 복사하여 빌드를 진행할 수 있습니다.
• 이 부분은 Gradle의 캐시를 활용하는 방식으로 최적화할 수 있습니다.

비교

개선 전 크기

개선 후 크기

개선 전과 후가 거의 1.7 배의 차이를 보이므로 유의미한 수정이라고 할 수 있겠습니다.

사실 속도에 있어서는, 기존 빌드 속도가 느린 편은 아니며 현재 GithubActions 를 통해 Docker 빌드 스테이징을 수행하므로, 로컬 캐싱을 사용할 수 없고, GithubActions에서 캐싱을 진행해야 합니다. 이를 위해 Docker에서 제공하는 플러그인을 사용할 수 있습니다. 아래의 글을 참고하여 각자 구현해 보면 좋을 것 같습니다.

• 참고하기
  • Docker buildx 공식 깃헙
  • GithubActions + buildx 캐싱 블로그

이번 글에서는 멀티모듈 MSA 프로젝트를 기반으로, Github Actions와 Docker, 그리고 EC2를 활용해 배포 자동화를 구성한 경험과 주요 고려 사항을 공유하려 합니다.

이 글을 통해 다음 내용을 얻을 수 있습니다

• 멀티모듈 프로젝트에서 CI/CD의 필요성과 구성 전략
• Github Actions의 workflow를 활용한 단계별 자동화
• Docker 이미지를 빌드하고, EC2로 배포하는 실무적인 접근법
• 실사용 중 발생했던 이슈와 해결 방안

1. 프로젝트 구성

프로젝트는 멀티모듈 기반의 MSA(Microservices Architecture)로 설계되었으며, 각 기능별로 독립적인 모듈로 분리되어 있습니다. 이러한 구조를 통해 서비스 간 의존성을 최소화하고, 독립적인 배포 및 확장이 가능하도록 구성했습니다.

멀티모듈 구성 방식

아래는 주요 기능별로 모듈이 구성된 방식입니다

공통 모듈 (GlowGrow)

• GlowGrow-common: 공통 유틸리티, DTO, 예외 처리 등 모든 서비스에서 사용하는 공통 코드
• GlowGrow-security: JWT 기반 인증/인가 및 보안 관련 설정
• GlowGrow-kafka: Kafka 관련 설정
• GlowGrow-redis: Redis 관련 설정

도메인 서비스 모듈

• Auth: JWT를 활용한 로그인/회원 인증 기능
• Post: 게시글 및 프로필 관리, S3 이미지 업로드, 검색 및 인기 정렬 기능
• Reservation: 디자이너 예약 타임테이블 관리, 리뷰/신고 생성 및 상태 관리
• Grade: 예약/리뷰/신고 데이터를 기반으로 회원 등급 계산 및 관리
• Payment: Toss API를 활용한 결제 및 정산 관리
• Promotion: 프로모션/쿠폰 관리 및 Redis 동시성 처리
• Notification: Kafka 이벤트 기반 알림 처리
• Chat: WebSocket 기반 실시간 채팅, Kafka 브로커를 통한 메시지 전달
• Multimedia: 파일 업로드/다운로드 및 관리

인프라/운영 관련 모듈

• Gateway: API Gateway를 통한 클라이언트 요청 라우팅 및 인증 처리
• Eureka: 서비스 디스커버리 및 레지스트리
• Logging/Monitoring: Loki, Prometheus, Grafana를 활용한 로그 및 성능 모니터링

Github Actions + Docker

배포 자동화와 관련된 도구는 많지만 Github Actions + Docker 조합은 구성과 사용이 비교적 간단하기에 선택했습니다. 또한 아래와 같은 이유들로 배포 구성 기술로 채택했습니다.

완벽한 자동화

• GitHub Actions는 GitHub 리포지토리와 긴밀히 통합됩니다. 코드가 푸시되거나 PR(Pull Request)이 생성되면 자동으로 빌드, 테스트, 배포 과정을 실행합니다. 이를 통해 개발자는 코어 로직 개발에 더 집중할 수 있습니다.

환경 간 일관성 보장

• Docker는 “한 번 빌드하면 어디서나 실행 가능”한 컨테이너 환경을 제공합니다.

• 로컬 개발 환경과 프로덕션 환경의 차이를 없애고, 모든 서비스가 동일한 상태로 배포되도록 보장합니다.

• 이를 통해 “내 로컬에서는 잘 되는데” 라는 문제를 미연에 방지할 수 있습니다.

멀티모듈 MSA를 위한 최적화

• GitHub Actions와 Docker의 조합은 특히 마이크로서비스 아키텍처(MSA)에서 그 진가를 발휘합니다. 각 서비스는 독립적인 Docker 이미지를 생성하므로 개별적으로 빌드 및 배포가 가능합니다.
• 이를 통해 하나의 서비스 업데이트가 다른 서비스에 영향을 미치지 않도록 합니다.

2. CD 파이프라인 설계

배포 자동화의 목표 및 주요 단계

CD 파이프라인은 소스 코드 변경 사항이 자동으로 빌드되고 테스트되며, 최종적으로 배포되는 단계를 자동화합니다. 주요 단계는 아래와 같습니다:

1. 개발 브랜치 및 PR 관리

• 각 서비스는 독립적으로 기능 개발 후, dev 브랜치로 PR을 통해 병합됩니다.
• dev 브랜치에서는 테스트를 통해 기능의 정상 동작 여부를 확인합니다.

2.운영 브랜치로 병합 및 배포

• main 브랜치로 병합되면, Github Actions 워크플로우가 실행되어 자동으로 EC2에 배포됩니다.
• 병합 즉시 빌드 및 테스트가 수행됩니다.
• 배포 과정은 이미지 생성, Docker Hub 업로드, EC2로 전송 및 컨테이너 실행을 포함합니다.

각 모듈의 독립성과 통합 배포 전략

모듈별 Dockerfile 관리

• 각 모듈은 자체 Dockerfile을 보유하며, docker-compose.yml에서 통합 관리됩니다. 예: eureka, gateway, reservation 등 서비스가 개별적으로 빌드 가능.

통합된 docker-compose.yml

• 루트 컨텍스트에서 docker-compose.yml을 사용해 모든 서비스를 정의하고, 환경 설정(.env)을 기반으로 관리합니다.

depends_on 설정으로 서비스 간 의존성을 제어합니다.

• 동일한 네트워크에서 여러 컨테이너가 통신하도록 설계

3. Github Actions Workflow

워크플로우의 단계별 구성 소개

Github Actions는 push 이벤트를 감지하여 자동으로 워크플로우를 실행합니다. 파이프라인의 주요 단계: 코드 푸시 → 빌드 → 이미지 생성 및 푸시 → 배포

• CD.yml

name: CD with Gradle
>
on:
  push:
    branches: [ "main" ]
>
>
# 실제 실행될 내용들을 정의합니다.
jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    # 각 서비스를 모두 빌드할 수 있도록 변수로 지정합니다.
    # https://docs.github.com/ko/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow
    strategy:
      matrix:
        service: [eureka, auth, gateway, GlowGrow-users, notification, payment, post, promotion, reservation]
>
    steps:
      - name: Checkout
        uses: actions/checkout@v4
>
      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'
>
      - name: Build with Gradle
        run: ./gradlew :${{matrix.service}}:clean :${{matrix.service}}:build -x test --no-daemon
>
  Docker:
    name: Build docker image and Push to registry
    needs: build
    runs-on: ubuntu-latest
>
    steps:
      - name: Checkout
        uses: actions/checkout@v4
>
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: ${{ secrets.AWS_REGION }}
>
      - name: web docker build and push
        run: |
          docker login -u ${{ secrets.DOCKER_USERNAME }} -p ${{ secrets.DOCKER_PASSWORD }}
      # docker compose 를 이용해서 여러 이미지를 모두 빌드하고, 별도의 script를 사용해서 이미지를 push 합니다.
>
      - name: Give execution permission
        run: chmod +x ./dockerTagAndPush.sh
>
      - name: Build, Tag and Push docker image to Hub
        run: |
          docker compose build
          ./dockerTagAndPush.sh
        env:
          DOCKER_HUB_NAMESPACE: ${{ secrets.DOCKER_HUB_NAMESPACE }}
>
  Deploy:
    name: Deploy
    needs: Docker
    runs-on: ubuntu-latest
>
    steps:
      - uses: actions/checkout@v4
>
      # docker compose로 container를 실행하기 위해 docker-compose.yml 을 EC2로 복사합니다.
      - name: Copy Docker compose file to EC2
        uses: appleboy/scp-action@v0.1.7
        with:
          host: ${{ secrets.EC2_HOST }}
          username: ubuntu
          key: ${{ secrets.EC2_KEY }}
          source: "docker-compose.yml"
          target: "/home/ubuntu" # target 은 디렉토리임. target directory 아래에 같은 이름의 파일로 옮겨진다.
>
      # ssh를 통해 EC2에 접속하고 docker container를 재시작합니다.
      - name: Deploy to EC2
        uses: appleboy/ssh-action@v1.0.3
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_REGION: ${{ secrets.AWS_REGION }}
          DOCKER_HUB_NAMESPACE: ${{ secrets.DOCKER_HUB_NAMESPACE }}
        with:
          host: ${{ secrets.EC2_HOST }}
          username: ubuntu
          key: ${{ secrets.EC2_KEY }}
          port: 22
          envs: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, DOCKER_HUB_NAMESPACE
          script: |
            sudo docker-compose down
 > 
            # 이미지 업데이트
            sudo docker-compose pull
 > 
            # 컨테이너 실행
            SPRING_PROFILES_ACTIVE=prod sudo docker-compose --env-file /home/ubuntu/.env up -d

1. 코드 푸시 및 브랜치 감지

• main 브랜치를 대상으로 워크플로우가 실행됩니다.
• main 브랜치 병합 시 실제 배포가 시작됩니다.

2. 빌드 및 테스트

• Gradle을 사용하여 각 서비스 모듈을 빌드합니다.
• ./gradlew :${{matrix.service}}:build 명령으로 각 서비스 독립적으로 빌드.
• 테스트는 -x test로 배포 시 제외 가능합니다.

3. 도커 이미지 생성 및 푸시

• docker compose와 dockerTagAndPush.sh 스크립트를 통해 이미지 생성.
• 생성된 이미지를 Docker Hub에 태그별로 푸시합니다 (latest, commit_hash).

4. EC2로 배포

• EC2에 docker-compose.yml 파일 전송.
• 기존 컨테이너를 종료(docker-compose down) 후 이미지를 업데이트(docker-compose pull).
• 프로파일별 환경 설정 적용: SPRING_PROFILES_ACTIVE=prod.

Docker 이미지를 멀티모듈로 빌드

워크플로우에서 Docker 부분에서 dockerTagAndPush.sh 를 실행하는 모습을 볼 수 있습니다. 해당 쉘 스크립트는 각 서비스 모듈의 Docker 이미지를 빌드하고, Docker hub 와 같은 이미지 레지스트리로 push 합니다.

• dockerTagAndPush.sh

# 모든 서비스 도커 이미지를 빌드합니다.
services=(
  "glowgrow-eureka" "glowgrow-gateway" "glowgrow-auth" "glowgrow-user"
  "glowgrow-payment" "glowgrow-notification" "glowgrow-post" "glowgrow-promotion" "glowgrow-reservation" "glowgrow-multimedia"
)
>
# 도커 이미지에 commit hash를 기반으로한 이미지 태그를 설정합니다.
commit_hash=$(git rev-parse --short HEAD)
>
for service in "${services[@]}"
do
  imageName="$DOCKER_HUB_NAMESPACE/$service" # 워크플로우에서 env 로 넣어준 네임스페이스
>
  # 도커 이미지 빌드 (해당 service 디렉토리에 Dockerfile이 있어야 합니다.)
  docker build -t "$imageName:latest" "./$service"
>
  # 이미지를 구분하기 위해서 latest 이외의 태그를 추가합니다.
  docker tag "$imageName:latest" "$imageName:$commit_hash"
>
  # Docker Hub에 push
  docker push "$imageName:latest"
  docker push "$imageName:$commit_hash"
>
  echo "$service 이미지가 빌드되어 Docker hub에 푸쉬되었습니다."
done
>
echo "모든 서비스의 이미지 빌드 및 푸쉬가 완료되었습니다."
>

5. 주요 이슈와 해결 방법

1. 멀티모듈 간 의존성 문제

• 문제: 각 모듈이 공통 라이브러리를 의존할 경우 Docker 빌드가 실패하거나 누락이 됩니다.
• 해결: Dockerfile의 컨텍스트를 루트에서 시작하여 의존하는 모듈을 참조해야 합니다. 멀티모듈에서의 Docker 빌드 문제

2. Docker 이미지 빌드 최적화

• 문제: 만약 서비스 모듈이나 공통 모듈 추가로 인한 빌드 속도 및 크기 문제
• 해결
  • 빌드 후 Docker 로 실행할 것이기에 jdk 이미지 대신에 빌드만을 위한 jre 관련 이미지 사용
  • Gradle의 빌드 캐시와 병렬 빌드 옵션 활용.
  • 의존하는 모듈만 copy
  • Docker 이미지는 변경된 서비스만 재빌드하여 효율성 증대. 멀티모듈에서의 Dockerfile 최적화하기

6. 결론 및 배운 점

멀티모듈 MSA에서 GithubActions 와 Docker 조합으로 CD 를 구성하는 방법을 학습하고, 그 장점에 대해서 알 수 있었습니다. 또한 Docker 빌드 최적화에 대해서도 학습하고 적용해 보았습니다.

향후 개선 방안

• Blue-Green Deployment 도입
  • 배포 중 서비스 중단 없는 업데이트 가능.
• Helm 및 Kubernetes
  • 컨테이너 오케스트레이션 도입으로 확장성과 유연성 개선.

내일배움캠프 이전의 삶

저는 컴퓨터과학과를 전공한 후, 졸업하고 1년 동안 혼자서 방향을 잡지 못하고 방황했습니다. 개발 공부를 하긴 했지만, 체계적인 학습이 부족하여 실질적인 기술을 쌓는 데 어려움을 겪었습니다. 이 시기에 다양한 기술을 배우고 싶었지만, 혼자서는 한계가 있었습니다.

내일배움캠프를 선택한 계기

내일배움캠프를 선택한 이유는 체계적인 교육과 실무 중심의 프로젝트 경험을 통해 제 실력을 발전시키고 싶었기 때문입니다. SpringBoot와 MSA(마이크로서비스 아키텍처)에 대한 지식을 배우고, 팀프로젝트를 경험할 수 있다는 것이 저의 목표와 잘 맞았습니다. 또한, 스프링 심화 1기는 기존 프로젝트 경험을 가진 인원을 선발했기에 어느 정도 실력이 있는 팀원들(경력자도 다수 있었음)과 개발을 할 수 있어 큰 도움이 되었습니다.

내일배움캠프의 장점

1. 사전캠프강의 및 MSA 강의 제공

개강 전부터 기본기를 기를 수 있는 사전캠프가 있어, 수업에 들어가기 전에 필요한 기초 지식을 쌓을 수 있었습니다. 사전캠프라고 해서 기본적인 Spring 강의만 있는 것이 아닌 Docker, Jpa 등에 대한 더욱 자세한 내용을 포함한 강의도 포함되어 있어, 개강 전 팀프로젝트에서 필요한 지식들을 한 번 다시 되새겨보거나, 더욱 업그레이드 할 수 있었습니다. 그리고, 실제 개강 후 제공되는 강의에서는 MSA 에 대한 기본적인 내용들과 실습도 포함되어 있어, 프로젝트 시 필요한 지식들을 가질 수 있게 됩니다.

2. 현직 튜터의 멘토링

캠프 정규 시간 동안 상주하시는 다섯 분의 튜터님들의 멘토링을 통해 개발적인 지식이나 프로젝트에 대한 내용을 논의할 수 있고, 실제 현직자 분들의 꿀팁을 배울 수 있어 좋습니다.

3. 실무 중심의 프로젝트

강의를 듣는 2~3 주 정도의 기간 이후, 총 세 번의 프로젝트를 진행하게 되는데 아래와 같이 마지막을 제외한 두 번의 프로젝트는 내용 발제에서 주제 및 개발 가이드라인을 잡아주게 되고, 마지막 최종 프로젝트에서는 실제로 제대로 배포 레벨까지 개발할 수 있도록, 대규모 트래픽을 가정한 성능 테스트의 가이드 라인 및 배포 비용 지원(팀 당 20만원ㄷㄷ)까지 해줍니다.

1. AI 검증 비즈니스 프로젝트 프로젝트

주문 관리 플랫폼을 모놀리식 아키텍쳐로 개발해보면서, Springboot 서버 개발 실력을 기르고, 다음 프로젝트를 진행하기 앞서, MSA(마이크로서비스 아키텍쳐) 도입의 필요성에 대한 생각을 해볼 수 있습니다. 아래는 프로젝트 개발 가이드 예시 입니다.

2. 대규모 AI 시스템 설계 프로젝트

앞의 주문 관리 플랫폼 개발 프로젝트에 이어서, 물류 관리 및 배송 시스템을 MSA로 개발해 볼 수 있습니다. 특히 API 연동, 데이터 무결성 유지, 그리고 서비스 간 통신의 신뢰성을 확보하는 방법에 대해 집중적으로 고민하고, Spring Cloud와 Spring Boot를 활용하여 이러한 과제들을 해결할 방안들을 모색하는 과정에서, MSA 개발에 대한 실력을 빠르게 높일 수 있었습니다.

이 또한 개발 프로세스 가이드가 제공이 되고, 필수 기능과 도전 기능 가이드로 나뉘어 프로젝트 진행 상황에 따라 프로젝트의 완성도를 높일 수 있습니다.

3. 최종 프로젝트 (자유 주제 MSA 프로젝트)

두 번의 팀 프로젝트를 통해 충분히 개발 프로세스에 대해 이해했다면, 마지막으로 자유 주제를 가지고 실제 배포 레벨까지 이루어지는 MSA 프로젝트를 개발할 수 있습니다. 자유 주제이지만, 너무 걱정하지 않아도 됩니다. 초기 아이디어를 가지고 튜터님들과의 미팅을 통해 개발적인 고려 사항이나 추가해야할 사항들을 충분히 논의하고 프로젝트를 고도화 할 수 있습니다.

또한, 최종 프로젝트를 진행하면서 의무적으로 WIL(Weekly I Learned) 를 작성해야 하기 때문에 해당 내용을 통해 개발 중 발생했던 트러블슈팅에 대해서 집중적으로 고민하고, 정리해 볼 수 있습니다. 이는 노션에서 공개적으로 작성하기 때문에 다른 팀이나 팀원들의 트러블 슈팅을 간접적으로 경험할 수 있어 개발적인 식견을 높일 수 있어 좋았습니다.

개발을 완료했다면, 최종 발표를 준비하기 위해 브로슈어, 깃헙 리드미 작성이나 이미지 제작을 하는 시간을 가지기 때문에 포트폴리오 어필에도 도움이 될 것 같습니다.

추가적으로 최종프로젝트에 대한 Bug Bounty 이벤트 경연을 진행해서, 각 팀끼리 서로 버그를 발견해주고, 부족한 부분에 대해 리팩토링을 진행할 수 있습니다. 또한 점수를 매겨 상품 또한 받을 수 있습니다.( 저희 팀은 1등을 해서 키보드를 받았습니다!! )

• 최종 프로젝트 Github Link

4. 무제한 취업 지원

3개월 동안 집중적으로 개발 실력을 기르고 포트폴리오를 완성했다면, 그것에 대해 정리하는 시간을 가지고, 취업을 위한 어필을 할 수 있어야겠죠. 내일배움캠프에서는 취업할 때까지 아래와 같이 무제한 취업 지원을 해줍니다. 저는 이 글을 작성하는 시점에서는 이력서, 포트폴리오 완성 기간에 참여해서 매우 기대가 됩니다!

• 이력서, 포트폴리오 완성 및 피드백 (약 2주)
• 면접 피드백 ( 서류 합격 시 면접 대비 )
• 한달 인턴 ( 수료 후 6개월 이내 )

내일배움캠프 이전과 이후, 무엇이 가장 달라졌나요?

캠프를 통해 기술적인 지식뿐만 아니라, 문제 해결 능력과 팀워크의 중요성을 깨달았습니다. 이전에는 혼자서 고민하던 문제들을 이제는 팀원들과 함께 해결할 수 있는 능력을 갖추게 되었습니다. 또한 SpringBoot와 Docker, 배포, 모니터링 지식 및 마이크로서비스 아키텍쳐에 대한 지식을 쌓아, 실제로 대규모 트래픽을 처리할 수 있는 MSA 백엔드 서버 개발에 대한 자신감을 얻었습니다.

내일배움캠프 생활 중 가장 기억에 남았던 순간은?

가장 기억에 남는 순간은 팀 프로젝트 발표 날이었습니다. 각 팀이 준비한 내용을 발표하고, 서로의 아이디어를 공유하는 과정에서 많은 것을 배웠습니다. 특히, 다른 팀의 프로젝트를 보며 새로운 영감을 얻고, 제 프로젝트에 대한 피드백을 받는 것이 매우 유익했습니다.

내일배움캠프를 고민하시는 분들에게 한 마디

내일배움캠프는 단순한 교육이 아니라, 실무 경험을 쌓고 네트워크를 형성할 수 있는 좋은 기회인 것 같습니다. 고민하고 계신다면, 주저하지 말고 도전해보세요. 여러분의 경력에 큰 도움이 될 것이라 생각합니다.

이 후기를 통해 내일배움캠프의 경험과 그로 인해 얻은 변화에 대해 잘 전달될 수 있기를 바랍니다. 여러분도 이 캠프를 통해 많은 것을 배우고 성장하시길 바랍니다!

진행 중인 MSA 프로젝트에서 각 서비스 모듈에 대해 Docker를 활용한 CI/CD 파이프라인을 구축하던 중 Docker 환경 구축에 관련된 몇 가지 문제를 겪었습니다. 이를 해결하는 과정을 공유하고자 합니다.

겪었던 문제

1. Docker 빌드 컨텍스트에서 모듈 참조 문제

프로젝트가 멀티모듈 구조로 되어 있어서, 서비스 모듈별로 Docker 이미지를 빌드할 때 각 서비스가 공통 모듈(common, security)을 의존하고 있었습니다. Docker 빌드 중 해당 모듈들을 컨텍스트에서 가져오지 못해 빌드가 실패하는 문제가 발생했습니다. 구체적으로 Gradle 빌드 단계에서 공통 모듈이 복사되지 않았기 때문에 Could not get unknown property 에러가 발생했습니다.

• 문제 발생 시의 Dockefile

# Stage 1: Build the application
FROM gradle:8.10.1-jdk17 AS build

WORKDIR /app

COPY . /app

RUN ./gradlew clean build -x test

FROM openjdk:17-jdk-slim

COPY --from=build /app/auth/build/libs/*SNAPSHOT.jar /app.jar

# JAR 파일 실행
CMD ["java", "-jar", "/app.jar"]

해결

해당 문제를 해결하기 위해 Docker 이미지 빌드 시의 컨텍스트가 루트 모듈에서 시작하도록 지정해야 합니다.

1. 단일 이미지 빌드 시 루트 모듈의 위치에서 터미널 명령어 실행

 docker build --build-arg FILE_DIRECTORY=. -f ./<모듈 이름>/Dockerfile -t my-app .

2. 루트 모듈 위치에서 Docker-compose.yml 작성

version: '3.8'

services:
//... 중략
  auth:
    image: ${DOCKER_HUB_NAMESPACE}/glowgrow-auth
    container_name: auth
    ports:
      - "19099:19099"
    build:
      context: .
      dockerfile: ./auth/Dockerfile
      args:
        - FILE_DIRECTORY=.
    environment:
      - SPRING_PROFILES_ACTIVE=${SPRING_PROFILES_ACTIVE}
    depends_on:
      - eureka

//... 생략

• 컨테이너에 대한 설명을 살펴 보면 build context 가 루트 모듈의 현재 위치에서 시작되고, args 를 통해 현재의 위치를 변수로 넘겨주고 있는 것을 볼 수 있습니다.

해당 변경에 따라 아래와 같이 Dockerfile 도 수정해야합니다.

# Stage 1: Build the application
FROM gradle:8.10.1-jdk17 AS build

WORKDIR /app

# ARG로 전달된 파일 디렉터리 설정
ARG FILE_DIRECTORY

# 파일 복사
COPY $FILE_DIRECTORY /app

# auth 모듈만 빌드
RUN ./gradlew :auth:clean :auth:build -x test --no-daemon

FROM openjdk:17-jdk-slim

COPY --from=build /app/auth/build/libs/*SNAPSHOT.jar /app.jar

# JAR 파일 실행
CMD ["java", "-jar", "/app.jar"]

루트 모듈에 존재하는 다른 모듈들에 대한 의존성과 gradle 을 참조하여, 해당 모듈을 Build 해줄 수 있었습니다.

2. Dockerfile 에서 gradlew 못 찾는 문제

위 문제가 있기 전 사소하지만, 시간을 많이 잡아먹은 문제가 하나 있었습니다. 해당 문제를 해결하기 전, 아까 위의 Dockerfile 을 실행해보면 아래와 같이 에러를 볼 수 있습니다.

내용만 보면 gradlew 에 대한 권한문제가 있거나, 애초에 gradlew 파일이 없다고 생각할 수 있습니다. 하지만, 검색 후 단순히 개행 문제였던 것을 알 수 있습니다.

• 참고 글 스택오버플로우

저는 윈도우 노트북을 사용하고 있어, 인텔리제이의 개행 형식도 CRLF 로 되어 있었습니다. 그런데 같은 프로젝트를 진행 중인 팀원들은 모두 Mac OS 를 사용하고 있어 저한테만 에러가 발생했던 것입니다.

해결

단순히 인텔리제이에서 gradlew 을 열어 CRLF 를 LF 로 변경만 하면 끝입니다. (매우 허무함)

프로젝트를 진행하면서, 여러 팀원과 환경을 맞추기 위해 편리하게 docker 를 설정 후 실행하고 있었다.

그런데, 어느 날 잘 실행되던 docker 가 안되는 것이다...! 아래 사진은 에러 내용이다.

Error response from daemon: Ports are not available: exposing port TCP 0.0.0.0:2181 -> 0.0.0.0:0: listen tcp 0.0.0.0:2181: bind: An attempt was made to access a socket in a way forbidden by its access permissions.

내용을 살펴보면, docker를 2181 port 로 binding 하려고 하면 접근 권한이 없다고 하는 것 같다.

원인 파악

팀원들 중 나만 윈도우 운영체제를 사용하고 있어서 나에게만 발생한 에러이기에 window, docker port bind error 등의 단어 조합으로 검색했더니 좋은 글을 발견했다.

https://blog.retrotv.dev/docker-bind-error/

원인은 아래와 같을 것이라고 해당 글에서는 말하고 있다.

일반적으로 포트를 점유한 프로세스도 찾을 수 없는데도 해당 포트를 사용 중인 상황을 겪고 있다면, 보통은 운영체제나 프로세스에 의해 미리 동적 포트가 할당되어서 그럴 가능성이 높다. 운영체제나 프로세스는 처음 시작 시, 시스템에서 사용할 포트를 동적으로 할당 시킨다. 당연한 소리지만, 이 때 할당된 포트는 사용자가 사용할 수 없다. 컴퓨터를 재부팅 시, 다시 포트를 사용 할 수 있게 되는 것은 매번 이 동적으로 할당된 포트가 바뀌게 되기 때문이다.

잘 되던 docker 가 실행이 안 되었던 이유가 운영체제의 동적 포트 점유 때문이라는 것을 알았다! 우선, 점유된 port 가 어떤 것인지 확인하려면 Powershell 을 열어 아래 명령어를 입력하자.

netsh interface ipv4 show excludedportrange protocol=tcp

위 사진과 같이, 여러 범위로 포트들이 운영체제에 의해 미리 할당돼있는 것을 볼 수 있다. (문제 발생 시, port 사진이 없어서 퍼온 사진입니다.)

그래서 해당 글에서 제시한 해결책을 따르면, Powershell 에서 netsh(Network Shell 의 약자로 Windows 운영 체제에서 사용되는 명령줄 도구로, 네트워크 설정 및 관리를 위한 명령어)를 사용하여 내가 사용하고자 하는 port 를 미리 점유하는 설정을 하면 된다.

해결

1. 일단 port가 다른 프로세스에 의해 사용 중일 가능성이 있으므로, window NAT(윈도우 NAT이란?) 네트워크를 멈추게 한다.

net stop winnat

2. 그 다음, 내가 사용하고자 하는 port를 시스템 또는 다른 내부 프로세스가 사용하지 않도록 미리 점유해놓는다.

netsh int ipv4 add excludedportrange protocol=tcp startport=2181 numberofports=1 store=persistent

• 중요한 것은 startport 를 통해 내가 사용하는 port 를 지정하는 것이다.
• numberofports 는 startport 부터 어디 범위까지 지정할 지 설정하는 것이다.

3. 위 명령어를 입력했다면, 다시 winnat 을 실행하고 확인해보자.

net start winnat

netsh interface ipv4 show excludedportrange protocol=tcp

나는 zookeeper 를 사용하기 위해 2181 포트를 미리 내가 사용할 수 있게 점유해놓았다. 숫자 맨 오른쪽에 '*' 표시가 시스템이나 내부 프로세스가 사용하지 않는다는 뜻이다.

정리

해당 문제 덕분에(?) window 가 관리하는 가상 네트워크에 대해 조금이라도 살펴보고 powershell 에 대한 사용도 조금 더 나아진 것 같다. 이제 더 이상 docker port 문제로 시간을 버리지는 않을 것 같다.

프로젝트 진행 중, 컨트롤러에 대한 단위테스트를 하기 위해 Mockito 와 WebMvcTest 를 이용해 테스트를 작성하고 있었다.

현재 프로젝트는 여러 멀티모듈로 이어져 있고, application 에서 다른 모듈의 component 도 scan 하고 있어서 SpringBootTest 를 통해 모든 context 를 load 하는 것은 비효율적이라고 판단했다. 그래서 WebMvcTest 로 진행~!

@DisplayName("[Reservaition] - TimeSlot")
@AutoConfigureMockMvc
@WebMvcTest(TimeSlotController.class)
class TimeSlotControllerTest {

    @Autowired
    private MockMvc mvc;

    @MockBean
    private TimeSlotService timeSlotService;

    @Autowired
    private ObjectMapper objectMapper;

    @DisplayName("[POST] 예약 타임 슬롯 생성 - 정상 호출")
    @Test
    @WithMockUser(username = "user@example.com", roles = {"PROVIDER"})
    void 예약타임슬롯_생성_성공() throws Exception {
        // 테스트용 데이터 준비
        LocalDate localDate = LocalDate.parse("2024-10-02");
        CreateTimeSlotRequest request = new CreateTimeSlotRequest(1L, localDate, 20);
        TimeSlotDto timeSlotDto = createTimeSlotDto(localDate);
        given(timeSlotService.createTimeSlot(any(CreateTimeSlotRequestDto.class),any())).willReturn(timeSlotDto);

        // POST 요청 수행 및 결과 검증
        mvc.perform(post("/api/time-slots")
                        .contentType("application/json")
                        .content(objectMapper.writeValueAsString(request))
                        .with(csrf())
                        .with(user("user@example.com").roles("PROVIDER"))
                )
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.code").value(200))
                .andExpect(jsonPath("$.message").value(TIMESLOT_CREATE_SUCCESS.getMessage()))
                .andExpect(jsonPath("$.data.id").value(timeSlotDto.id().toString()))
                .andExpect(jsonPath("$.data.serviceProviderId").value(1L))
                .andExpect(jsonPath("$.data.availableDate").value("2024-10-02"))
                .andExpect(jsonPath("$.data.availableTime").value(20))
                .andExpect(jsonPath("$.data.isReserved").value(false))
                .andDo(print());

        then(timeSlotService).should().createTimeSlot(any(CreateTimeSlotRequestDto.class), any());
    }
//Other codes...
}

해당 테스트는 예약가능시간정보 CRUD 에 대한 단위테스트를 목적으로 작성되었다. 하지만 WebMvcTest + Application의 ComponentScan의 영향으로 TimeSlotController와 전혀 상관 없는, 다른 Controller들을 빈으로 등록하다가 에러가 발생한다.

Application 에는 아래와 같이 다른 멀티모듈( common, security...) 등의 필요한 component 들을 scan 하도록 설정해놓았었다.

@SpringBootApplication
@EnableFeignClients
@EnableSpringDataWebSupport(pageSerializationMode = EnableSpringDataWebSupport.PageSerializationMode.VIA_DTO)
@ComponentScan(basePackages = {"com.tk.gg.common","com.tk.gg.security"})
public class ReservationApplication { //Reservation 모듈에는 reservation, review, timeSlot 서비스가 존재한다.

    public static void main(String[] args) {
        SpringApplication.run(ReservationApplication.class, args);
    }
}

common 과 security 등은 다른 멀티모듈에 존재하므로 어떻게 수정해야 하는지 고민이었다.

그래서, 관련 Spring document 를 찾아보았더니 WebMvcTest 의 bean 스캔에 대한 글을 발견했다. Auto-configured Spring MVC Tests

공식문서에 나와 있는 어노테이션으로 만들어진 Component 외에는 따로 @Import 를 통해 추가적으로 scan 하도록 명시해야한다고 이해했다.

해결

그러면 WebMvcTest는 Configuration 파일을 스캔하지 않기 때문에, ComponentScan 을 Application 에 설정하지 않고 Configuration 파일을 따로 작성해 설정하면 될 것 같았다.

package com.tk.gg.reservation.infrastructure.config;

import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;

@Configuration
@ComponentScan(basePackages = {"com.tk.gg.common","com.tk.gg.security"})
public class ComponentScanConfig {
}

지금 보니까, infrastructure 디렉토리에 해당 config 를 생성한 게 조금 어색한 것 같긴 하지만... 일단 놔두고 테스트를 실행해보자.

별 것 아닌 성공테스트들 이지만...초록색이 뜨면 항상 기분은 좋다...

다른 문제점

사실, 위의 문제가 발생하기 전에 또 다른 문제가 있었다. 현재 프로젝트는 MSA 로 이루어져 있고, Security 모듈이 존재했다. 그리고 요청 프로세스는 아래와 같다.

사용자가 gateway 를 통해 auth-service 에 회원가입 및 로그인 요청 -> security 모듈에서 인증 정보 저장 및 다음 요청 시 인증 로직 수행, request 별 인가 -> 유저 정보를 methodArgumentResolver 에 담기

프로세스에서, 요청 인자 resolver 에 담기 위해 어노테이션과 HandlerMethodArgumentResolver 를 구현하였고, 아래와 같이 컨트롤러에서 유저 정보를 얻을 수 있다.

@PostMapping
public GlobalResponse<TimeSlotResponse> create(
            @RequestBody @Valid CreateTimeSlotRequest request,
            @AuthUser AuthUserInfo userInfo //유저 정보
            ) {
        return ApiUtils.success(
                TIMESLOT_CREATE_SUCCESS.getMessage(),
                TimeSlotResponse.from(timeSlotService.createTimeSlot(request.toDto(), userInfo))
        );
}

문제는 MockMvc 기반의 단위 컨트롤러 테스트를 진행할 때, AuthUserInfo 의 구현체를 mocking 해서 argumentResolver 에 등록하려고 했기에 발생했다.

여기서AuthUserInfo 자체는 인터페이스이고, impl 의 생성자는 모두 PRIVATE 으로 설정 및 builder 를 통해 생성되게 작성되었기 때문에 에러가 발생한다.

@BeforeEach
    public void setup() {
        // SecurityMockMvc 설정
        mvc = MockMvcBuilders.webAppContextSetup(context)
                .apply(SecurityMockMvcConfigurers.springSecurity())  // Spring Security 설정 적용
                .build();

        given(authUserArgumentResolver.supportsParameter(any())).willReturn(true);

        given(authUserArgumentResolver.resolveArgument(any(), any(), any(), any()))
                .willReturn(AuthUserInfoImpl.builder()
                        .id(1L)
                        .email("user@example.com")
                        .username("TestUser")
                        .userRole(UserRole.PROVIDER)
                        .token("sample-token")
                        .build());
    }

AuthUserInfo 라는 것은 사실 Security 모듈에 존재하고, WebMvcTest 에서는 관심을 가지지 않아도 되는 부분이었다. 그런데, 계속 저 부분에 집착하느라 시간을 많이 날린 것 같다...

어떻게 해도 나의 기존 지식과 검색으로는 해결이 되지 않아 그냥 setup 부분을 지우고, 컨트롤러의 요청이 잘 수행되고 데이터가 원하는 형식으로 반환되는지만 확인하였다. ( 이게 맞는 것 같음 )

이제, Test 부분에 @WithMockUser 와 user() 를 통해 인증된 가짜 유저를 넣어 테스트를 수행하면 간단한 일이었다.

최종 테스트 코드

@DisplayName("[Reservaition] - TimeSlot")
@AutoConfigureMockMvc
@WebMvcTest(TimeSlotController.class)
class TimeSlotControllerTest {

    @Autowired
    private MockMvc mvc;

    @MockBean
    private TimeSlotService timeSlotService;

    @Autowired
    private ObjectMapper objectMapper;

    @DisplayName("[POST] 예약 타임 슬롯 생성 - 정상 호출")
    @Test
    @WithMockUser(username = "user@example.com", roles = {"PROVIDER"})
    void 예약타임슬롯_생성_성공() throws Exception {
        // 테스트용 데이터 준비
        LocalDate localDate = LocalDate.parse("2024-10-02");
        CreateTimeSlotRequest request = new CreateTimeSlotRequest(1L, localDate, 20);
        TimeSlotDto timeSlotDto = createTimeSlotDto(localDate);
        given(timeSlotService.createTimeSlot(any(CreateTimeSlotRequestDto.class),any())).willReturn(timeSlotDto);

        // POST 요청 수행 및 결과 검증
        mvc.perform(post("/api/time-slots")
                        .contentType("application/json")
                        .content(objectMapper.writeValueAsString(request))
                        .with(csrf())
                        .with(user("user@example.com").roles("PROVIDER"))
                )
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.code").value(200))
                .andExpect(jsonPath("$.message").value(TIMESLOT_CREATE_SUCCESS.getMessage()))
                .andExpect(jsonPath("$.data.id").value(timeSlotDto.id().toString()))
                .andExpect(jsonPath("$.data.serviceProviderId").value(1L))
                .andExpect(jsonPath("$.data.availableDate").value("2024-10-02"))
                .andExpect(jsonPath("$.data.availableTime").value(20))
                .andExpect(jsonPath("$.data.isReserved").value(false))
                .andDo(print());

        then(timeSlotService).should().createTimeSlot(any(CreateTimeSlotRequestDto.class), any());
    }


    @DisplayName("[GET] 예약타임슬롯 페이징, 정렬 조회 - 정상 호출")
    @Test
    @WithMockUser(username = "user@example.com", roles = {"PROVIDER"})
    void 예약타임슬롯_전체조회_페이징및정렬_성공() throws Exception {
        Sort sort = Sort.by(Sort.Order.desc("availableDate"));
        Pageable pageable = PageRequest.of(0, 5, sort);
        // 저장 메서드 모킹
        given(timeSlotService.getAllTimeSlot(eq(null),eq(null), eq(pageable)))
                .willReturn(new PageImpl<>(List.of(), pageable, 0));

        mvc.perform(get("/api/time-slots")
                    .queryParam("page", "0")
                    .queryParam("size", "5")
                    .queryParam("sort", "availableDate,desc")
                    .contentType(MediaType.APPLICATION_JSON)
                    .with(csrf())
                    .with(user("user@example.com").roles("PROVIDER"))
                )
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.code").value(200))
                .andExpect(jsonPath("$.data.page.size").value(5))
                .andExpect(jsonPath("$.message").value(TIMESLOT_RETRIEVE_SUCCESS.getMessage()))
                .andDo(print());

        then(timeSlotService).should().getAllTimeSlot(eq(null),eq(null), eq(pageable));
    }

    @DisplayName("[GET] 예약타임슬롯 단건 조회 - 정상 호출")
    @Test
    @WithMockUser(username = "user@example.com", roles = {"PROVIDER"})
    void 예약타임슬롯_단건조회_성공() throws Exception {
        // 저장 메서드 모킹
        LocalDate localDate = LocalDate.parse("2024-10-02");
        TimeSlotDto timeSlotDto = createTimeSlotDto(localDate);
        given(timeSlotService.getTimeSlotDetails(timeSlotDto.id())).willReturn(timeSlotDto);

        mvc.perform(get("/api/time-slots/{timeSlotId}", timeSlotDto.id())
                        .contentType(MediaType.APPLICATION_JSON)
                        .with(csrf())
                        .with(user("user@example.com").roles("PROVIDER"))
                )
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.code").value(200))
                .andExpect(jsonPath("$.message").value(TIMESLOT_RETRIEVE_SUCCESS.getMessage()))
                .andDo(print());

        then(timeSlotService).should().getTimeSlotDetails(timeSlotDto.id());
    }

    @DisplayName("[POST] 예약 타임 슬롯 수정 - 정상 호출")
    @Test
    @WithMockUser(username = "user@example.com", roles = {"PROVIDER"})
    void 예약타임슬롯_수정_성공() throws Exception {
        // 테스트용 데이터 준비
        LocalDate localDate = LocalDate.parse("2024-10-02");
        UpdateTimeSlotRequest request = new UpdateTimeSlotRequest(1L,localDate,10,false);
        willDoNothing().given(timeSlotService)
                .updateTimeSlot(any(UUID.class),any(UpdateTimeSlotRequestDto.class),any());

        // POST 요청 수행 및 결과 검증
        mvc.perform(put("/api/time-slots/{timeSlotId}", UUID.randomUUID())
                        .contentType("application/json")
                        .content(objectMapper.writeValueAsString(request))
                        .with(csrf())
                        .with(user("user@example.com").roles("PROVIDER"))
                )
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.code").value(200))
                .andExpect(jsonPath("$.message").value(TIMESLOT_UPDATE_SUCCESS.getMessage()))
                .andDo(print());

        then(timeSlotService).should().updateTimeSlot(any(UUID.class),any(UpdateTimeSlotRequestDto.class), any());
    }


    private TimeSlotDto createTimeSlotDto(LocalDate localDate){
        return TimeSlotDto.builder()
                .id(UUID.randomUUID())
                .availableDate(localDate)
                .serviceProviderId(1L)
                .isReserved(false)
                .availableTime(20).build();
    }
}