[TIL-0509] DSPy란?

🌟 개요

✨ 스터디 프로젝트 소개

우리 스터디에서는 LangChain 기반의 인플루언서 매칭 에이전트 플랫폼을 만들고 있다.
광고주가 광고 컨셉, 광고 아이템, 광고주 브랜드명 세 가지를 입력하면, 에이전트가 최적의 인플루언서 후보를 추천해주는 시스템이다.
에이전트는 다음 5개의 도구를 자율적으로 선택하면서 동작한다.

도구	역할
search_influencers_by_category	카테고리로 DB 검색
search_influencers_by_platform	플랫폼으로 DB 검색
search_influencers_by_followers	팔로워 범위로 DB 검색
get_influencer_details	특정 인플루언서 상세 정보 조회
calculate_match_score	4차원 매칭 점수 계산

구현 자체는 어렵지 않았지만, 이 에이전트가 잘 작동하고 있는지 어떻게 평가할지가 관건이었다.

😣 에이전트 평가의 어려움

일반적인 소프트웨어라면 단위 테스트로 "입력 A → 출력 B"를 검증하면 그만이다.
그런데 LLM 에이전트는 다르다. 같은 입력을 줘도 매번 조금씩 다른 경로로 도구를 호출하고, 다른 문장으로 응답한다. 정해진 정답이 없다.

그렇다고 매번 눈으로 직접 응답을 읽어보는 방식은 지속 가능하지 않다. 테스트 케이스를 10개만 만들어도 코드를 조금 바꿀 때마다 10번을 읽어야 한다.

이 문제를 구체적으로 표현하면 다음과 같다.

• 에이전트가 추천한 인플루언서가 실제로 DB에 존재하는 사람인가?
• 추천 이유가 실제 데이터와 일치하는가?
• 뷰티 광고에 뷰티 카테고리 인플루언서를 추천했는가?
• 추천된 인플루언서가 경쟁사 광고 이력은 없는가?

각 질문은 "맞다/틀리다"로 판단할 수 있다. 즉, 자동화할 수 있다. 우리가 필요한 건 이 체크리스트를 코드로 표현하는 것이었다.

✨ 두 가지 접근 방법

팀에서는 자연스럽게 두 가지 방향이 떠올랐다.

첫 번째는 단계별 파이프라인 방식이다.
에이전트를 그대로 실행하고, 응답을 파싱하고, DB와 대조하고, 미리 정의한 체크리스트로 점수를 내는 것이다. 직관적이고 구현도 어렵지 않다.

두 번째는 스터디에서 짚고 넘어간 적 있는 DSPy를 활용하는 방식이다.
DSPy는 단순히 평가를 자동화하는 데 그치지 않고, 그 평가 결과를 피드백 삼아 프롬프트 자체를 자동으로 개선해주는 프레임워크이다.
DSPy의 MIPROv2 optimizer는 평가 지표를 토대로 프롬프트를 최적화하는 역할을 한다. 수동으로 프롬프트를 이리저리 수정하는 대신, 평가 기준을 코드로 정의해 두면 optimizer가 스스로 더 좋은 프롬프트를 찾아준다는 아이디어이다.

이 글은 우리 팀이 DSPy를 어떻게 이해했고, 실제로 프로젝트에 어떻게 적용해봤으며, 그 과정에서 무엇을 배웠는지에 대한 기록이다.

---

🌟 DSPy란?

DSPy(Declarative Self-improving Python)는 스탠퍼드 NLP 연구팀이 만든 프레임워크로, 프롬프트를 직접 작성하는 대신 LLM 프로그램의 구조를 선언하고 최적화를 자동화하는 것을 목표로 한다.
이게 어떤 의미인지는 기존 방식의 문제를 먼저 보면 더 잘 와닿는다.

💥 프롬프트 엔지니어링의 문제

LLM 기반 애플리케이션을 개발하다 보면 한 번쯤 이런 경험을 한다.

에이전트가 엉뚱한 답을 내놓는다. → 프롬프트를 수정한다. → 조금 나아진다. → 그런데 다른 케이스에서 또 틀린다. → 다시 수정한다. → 그러면 처음에 잘 되던 케이스가 망가진다. → ...

이 과정은 소프트웨어 개발이라기보다 감에 의존한 조율에 가깝다. 프롬프트가 왜 잘 되는지, 왜 안 되는지 명확히 설명하기 어렵다. 조금만 다른 모델로 바꾸거나, 다른 태스크에 적용하면 처음부터 다시 해야 한다.

DSPy는 이 문제에 정면으로 도전한다.

"프롬프트 문자열을 직접 만지는 대신, LLM에게 무엇을 원하는지 선언하고 최적화는 프레임워크에 맡겨라."

✨ 기존 방식 vs. DSPy 방식

두 접근의 차이를 코드로 직접 비교해보면 더 명확하다.

• 기존 방식 (수동 프롬프트 엔지니어링)

  prompt = """
   당신은 인플루언서 매칭 전문가입니다.
   다음 광고 정보를 분석하여 적합한 카테고리를 추론하세요.
   
   광고 컨셉: {ad_concept}
   광고 아이템: {ad_item}
   광고주: {advertiser}
   
   반드시 다음 중에서만 선택하세요:
   beauty, fashion, tech, food, travel, fitness, gaming, music, education, lifestyle
   
   카테고리:
   """
   
   response = llm.invoke(prompt.format(...))

  이 방식의 문제는 프롬프트 문자열 자체가 로직이 된다는 점이다. 모델을 바꾸면 "반드시"라는 강조어의 효과가 달라진다. 출력 형식이 조금만 달라져도 파싱이 깨진다. 성능을 높이려면 사람이 직접 문장을 고쳐야 한다.

• DSPy 방식 (선언형 명세)

  class InferCategories(dspy.Signature):
     """광고 정보를 분석하여 DB 검색에 사용할 카테고리를 추론합니다."""
     
     ad_concept: str = dspy.InputField(desc="광고 컨셉 설명")
     ad_item: str = dspy.InputField(desc="광고 상품/서비스명")
     advertiser: str = dspy.InputField(desc="광고주 브랜드명")
     categories: str = dspy.OutputField(
        desc="쉼표로 구분된 카테고리. 반드시 다음 중에서만 선택: beauty, fashion, ..."
     )
  
  predictor = dspy.Predict(InferCategories)
  result = predictor(ad_concept="...", ad_item="...", advertiser="...")

  프롬프트 문자열이 사라졌다. 대신 "어떤 입력을 받아서 어떤 출력을 내놓는가"만 선언한다. 실제 프롬프트는 DSPy가 자동으로 구성한다.

✨ DSPy가 해결하는 것: "프롬프트를 하드코딩하지 마라"

기존 방식에서 프롬프트는 모델과 강하게 결합되어 있다. GPT-4에 맞게 튜닝한 프롬프트를 Claude에 그대로 쓰면 성능이 달라진다. Ollama 로컬 모델에 쓰면 더 달라진다.

DSPy는 이 결합을 끊는다. 개발자는 "무엇을 원하는가(What)"만 선언하고, "어떻게 표현할 것인가(How)"는 DSPy와 Optimizer가 담당한다.
모델이 바뀌면 Optimizer를 다시 돌려서 그 모델에 맞는 최적 표현을 자동으로 찾아낸다.

이 관점에서 DSPy를 한 문장으로 정의하면 이렇다.

LLM 호출을 선언형으로 구조화하고, 평가 기준(metric)을 정의하면 프롬프트와 few-shot 예시를 자동으로 최적화해주는 프레임워크

✨ 머신러닝적 관점에서 본 DSPy

DSPy의 설계는 머신러닝의 학습 루프에서 직접 영감을 받았다.

전통적인 ML에서는 모델 가중치를 직접 수정하는 대신, 손실 함수(loss function)를 정의하고 역전파로 최적화한다. 개발자는 "무엇이 좋은 출력인지"만 정의하면 된다.

DSPy는 이 패러다임을 프롬프트에 적용한다.

ML	DSPy
모델 가중치	프롬프트 & few-shot 예시
손실 함수	metric 함수 (0.0 ~ 1.0)
역전파 + Optimizer	MIPROv2 등 Teleprompter
학습 데이터	trainset (dspy.Example 목록)

"가중치를 직접 수정하지 않고 손실 함수로 최적화한다"는 게 딥러닝의 핵심이듯, "프롬프트를 직접 수정하지 않고 metric으로 최적화한다"는 게 DSPy의 핵심이다.

🧐 LangChain과의 차이점

LangChain은 LLM 호출, 체인 구성, 도구 연결 등 LLM 애플리케이션 빌딩 블록을 제공하는 프레임워크이다. 어떤 프롬프트를 쓸지는 개발자가 결정한다.

DSPy는 그 위에서 작동하는 최적화 레이어이다. LLM 연결은 LangChain처럼 하고, 프롬프트 자체를 어떻게 구성할지는 DSPy가 찾아준다.

둘은 대체 관계가 아니라 역할이 다르다. 실제로 DSPy는 내부적으로 LiteLLM을 통해 OpenAI, Anthropic, Ollama 등 다양한 모델에 연결된다. 우리 프로젝트에서도 DSPy가 Ollama 위에서 작동하도록 구성했다.

---

🌟 DSPy의 핵심 개념

DSPy를 이루는 핵심 개념은 Signature, Module, Optimizer 세 가지이다. 각각이 무엇인지, 그리고 우리 프로젝트에서 어떻게 표현됐는지를 함께 살펴보겠다.

✨ Signature: LLM에게 무엇을 원하는지 선언

Signature는 LLM 호출 하나의 입출력 명세이다. "어떤 정보를 주면 어떤 정보를 돌려달라"를 코드로 선언하는 것이다.

일반적인 형태는 이렇다.

class 시그니처_이름(dspy.Signature):
   """이 LLM 호출의 목적을 설명하는 docstring (자동으로 프롬프트 지시사항이 된다)"""
   
   입력필드: str = dspy.InputField(desc="필드 설명")
   출력필드: str = dspy.OutputField(desc="필드 설명")

docstring과 각 필드의 desc가 그대로 프롬프트의 지시사항으로 변환된다. 개발자가 프롬프트 문자열을 직접 작성하지 않아도 된다.

우리 프로젝트에서는 Signature를 두 개 설계했다.

1. 광고 정보 → 카테고리 추론

   class InferCategories(dspy.Signature):
      """광고 정보를 분석하여 DB 검색에 사용할 카테고리를 추론합니다.
      반드시 한국어로 답변하세요."""
      
      ad_concept: str = dspy.InputField(desc="광고 컨셉 설명")
      ad_item: str = dspy.InputField(desc="광고 상품/서비스명")
      advertiser: str = dspy.InputField(desc="광고주 브랜드명")
      categoreis: str = dspy.OutputField(
         desc=(
            "쉼표로 구분된 카테고리. 반드시 다음 중에서만 선택: "
            "beauty, fashion, tech, food, travel, fitness, gaming, music, education, lifestyle"
         )
      )

   ➡️ "이니스프리 유기농 스킨케어" 광고가 들어오면 beauty를 출력하는 LLM 호출 하나를 선언한 것이다.

2. 점수 결과 → TOP3 선정 + 추천문 작성

   class RankAndRecommend(dspy.Signature):
      """매칭 점수 결과를 분석하여 TOP3를 선정하고 한국어 추천 결과를 작성합니다.
      반드시 한국어로만 답변하세요. 중국어 사용 절대 금지."""
      
      ad_concept: str = dspy.InputField(desc="광고 컨셉")
      ad_item: str = dspy.InputField(desc="광고 아이템")
      scores_summary: str = dspy.InputField(
         desc="인플루언서별 overall_grade(S>A>B>C>D)와 차원 평가(상/중/하) JSON"
      )
      top3_names: list[str] = dspy.OutputField(
         desc="overall_grade 기준 상위 3명의 인플루언서 이름 리스트 (정확히 3개)"
      )
      recommendation: str = dspy.OutputField(
         desc="한국어 추천 결과문. 각 인플루언서별 이름, 종합 등급, 추천 이유 포함"
      )

   ➡️ 여기서 주목할 것이 있다. 출력 필드로 top3_names: list[str]처럼 타입을 선언하면 DSPy가 LLM 추력을 해당 타입으로 파싱해준다. 기존 방식에서 정규식으로 이름을 일일이 추출하던 코드가 필요 없어진다.

✨ Module: LLM 호출과 Python 로직을 하나의 프로그램으로

Signature가 LLM 호출 하나를 정의한다면, Module은 여러 Signature와 결정론적 Python 코드를 조합해 완전한 프로그램 하나를 만드는 단위이다. PyTorch의 nn.Module에서 직접 영감을 받은 구조다.

Module을 만들 때는 두 가지를 정의한다.

• __init__: 어떤 Predictor(LLM 호출)를 사용할지 선언
• forward(): 실제 실행 흐름 (LLM 호출 + Python 로직)

우리 프로젝트의 InfluencerMatchingModule이 이 구조를 잘 보여준다.

class InfluencerMatchingModule(dspy.Module):

   def __init__(self, repo):
      super().__init__()
      self.repo = repo
      self.infer_categories = dspy.Predict(InferCategories) # LLM 호출 1
      self.rank = dspy.ChainOfThought(RankAndRecommend) # LLM 호출 2
      
   def forward(self, ad_concept: str, ad_item: str, advertiser: str):
   
      # -- Step 1: LLM → 카테고리 추론 ----------------------
      cats_pred = self.infer_categories(
         ad_concept=ad_concept, ad_item=ad_item, advertiser=advertiser
      )
      categories = [c.strip() for c in cats_pred.categories.split(",")]
      
      # -- Step 2: Python → DB 검색 (결정론적) --------------
      influencers = self.repo.find_by_categories(categories)
      
      # -- Step 3: Python → 매칭 점수 계산 (결정론적) --------
      scores = []
      for inf in influencers:
         result = calculate_match_score_raw(inf, categories, [])
         scores.append({ "name": inf.name, "overall_grade": result["overall_grade"], ... })
      scores.sort(key=lambda x: grade_order[x["overall_grade"]], reverse=True)
      
      # -- Step 4: LLM → TOP3 선정 + 추천문 생성 -------------
      rank_pred = self.rank(
         ad_concept=ad_concept,
         ad_item=ad_item,
         scores_summary=json.dumps(scores[:10], ensure_ascii=False),
      )
      return rank_pred

forward()의 흐름을 보면 LLM이 담당하는 부분과 Python이 담당하는 부분이 명확하게 나뉜다.

단계	담당	이유
카테고리 추론	LLM	자연어 이해가 필요
DB 검색	Python	정확한 쿼리가 필요, LLM이 개입하면 오류 가능성
점수 계산	Python	수치 계산은 결정론적이어야 함
TOP3 선정 + 추천문	LLM	자연어 생성이 필요

이것이 Module이 주는 핵심 가치이다. LLM이 해야 할 일과 Python이 해야 할 일을 코드 구조로 분리한다. 기존 ReAct 에이전트처럼 LLM이 흐름 전체를 결정하는 것이 아니라, 흐름은 forward() 코드가 고정하고 LLM은 필요한 지점에서만 호출된다.

dspy.Predict와 dspy.ChainOfThought의 차이도 짚고 가자.

• dspy.Predict: Signature를 그대로 LLM에 전달해 출력을 받는다. 가장 기본적인 LLM 호출
• dspy.ChainOfThought: LLM에게 최종 답 전에 추론 과정을 먼저 쓰도록 유도한다. RankAndRecommend처럼 여러 후보 중 순위를 매기는 작업에 적합하다.

✨ Optimizer: metric을 정의하면 프롬프트를 자동으로 개선

Optimizer가 DSPy의 핵심이다. 앞서 만든 Module을 더 잘 작동하도록 프롬프트와 few-shot 예시를 자동으로 최적화해주는 역할을 한다.

작동 원리를 이해하려면 먼저 두 가지가 필요하다.

1. trainset: 최적화의 기준이 되는 예시 데이터

   def _make_example(tc: TestCase) -> dspy.Example:
      return dspy.Example(
         ad_concept=tc.ad_concept,
         ad_item=tc.ad_item,
         advertiser=tc.advertiser,
         expected_categories=tc.expected_categories,
         competitor_brands=tc.competitor_brands,
      ).with_inputs("ad_concept", "ad_item", "advertiser")
   
   trainset = [_make_example(tc) for tc in TEST_CASES] # 10개

   우리 프로젝트에서는 이니스프리, bhc, 삼성전자 등 실제 한국 브랜드 10개를 trainset으로 구성했다.

2. metric 함수: "이 예측이 얼마나 좋은가"를 0.0~1.0으로 반환하는 함수

   def matching_metric(example, prediction, trace=None) -> float:
      recommended_names = list(prediction.top3_names or [])
      
      # evidence_pack 구성 후 4개 메트릭 계산
      results = [
         calculate_evidence_coverage(evidence_pack),  # 데이터 완전성
         calculate_semantic_relevance(evidence_pack), # 광고 적합도
         calculate_groundedness(evidence_pack),       # 할루시네이션 여부
         calculate_competitor_check(evidence_pack),   # 경쟁사 이력 여부
      ]
      passed = sum(r["passed"] for r in results)
      return passed / len(results)  # 0.0 ~ 1.0

   4개 메트릭 중 몇 개를 통과했는지 비율로 반환한다. 4개 모두 통과하면 1.0, 하나도 못 통과하면 0.0이다.

이 두 가지가 준비되면 Optimizer를 실행한다.

from dspy.teleprompt import MIPROv2

optimizer = MIPROv2(
   metric=metric,
   auto="light",  # 탐색 예산: light / medium / heavy
   num_threads=1,
)

optimized_module = optimizer.compile(
   module,
   trainset=trainset,
)

optimized_module.save("outputs/dspy_optimized.json")

MIPROv2가 하는 일을 단계별로 풀면 이렇다.

1. 현재 Module을 trainset에 돌려서 각 예시의 metric 점수를 측정한다.
2. 점수가 낮은 지점을 분석해 더 나은 프롬프트 후보를 여러 개 생성한다.
3. 후보들을 다시 trainset에 돌려서 점수를 비교한다.
4. 가장 높은 점수의 프롬프트 조합을 최종 결과로 저장한다.

이 과정에서 개발자가 하는 일은 없다. metric을 정의하고 compile()을 호출하면 나머지는 자동이다.

최적화 결과는 JSON 파일로 저장되고, 이후에는 Module을 로드해서 바로 사용할 수 있다.

optimized_module = InfluencerMatchingModule(repo)
optimized_module.load("outputs/dspy_optimized.json")

result = optimized_module(
   ad_concept="건강하고 자연스러운 이미지의 뷰티 제품",
   ad_item="유기농 스킨케어 라인",
   advertiser="이니스프리",
)
print(result.top3_names)  # ['홍서연', '김민준', '이수진']
print(result.recommendation)  # 한국어 추천 결과문

✨ 세 개념의 관계 정리

Signature는 부품, Module은 완성품, Optimizer는 완성품을 더 잘 만들어주는 공장이다.

---

🌟 프로젝트에 DSPy 도입

🧐 기존 에이전트 구조 다시 보기

우리 프로젝트의 에이전트는 ReAct(Reasoning + Acting) 패턴 기반으로, LangChain으로 구현되어 있다. 에이전트는 5개의 도구를 자유롭게 선택하면서 동작한다.이 구조의 특징은 LLM이 흐름을 직접 결정한다는 것이다. 어떤 도구를 몇 번 호출할지, 어떤 순서로 진행할지를 모두 LLM이 판단한다.
덕분에 유연하지만, 그 유연함이 평가를 어렵게 만든다. 실행할 때마다 경로가 달라지고, 최종 응답의 형식도 일정하지 않다.

✨ 기존 코드와 DSPy 개념의 1:1 매핑

이 에이전트를 DSPy로 재설계할 때, 기존 코드의 각 요소가 DSPy의 어떤 개념에 대응되는지를 먼저 정리했다.

기존 코드	DSPy 개념	역할
AGENT_SYSTEM_PROMPT (문자열)	Signature	LLM 호출의 입출력 명세
AgentService (LangChain)	InfluencerMatchingModule	전체 실행 흐름
TEST_CASES 리스트	trainset	최적화 기준 데이터
metrics.py 4개 함수	matching_metric	예측 품질 측정 함수
수동 프롬프트 수정	MIPROv2	자동 최적화

핵심은 마지막 행이다. 기존에는 에이전트가 잘못된 결과를 내놓으면 AGENT_SYSTEM_PROMPT를 열어서 직접 문장을 수정했다. DSPy에서는 그 작업을 MIPROv2가 대신한다.

✨ 아키텍처의 근본적인 차이

매핑 표보다 중요한 것은, DSPy 방식이 기존 에이전트와 구조적으로 어떻게 다른가이다.

• 기존 LangChain ReAct 에이전트: LLM이 흐름을 결정한다.
  

• DSPy InfluencerMatchingModule: 코드가 흐름을 결정하고, LLM은 지정된 지점에서만 호출된다.
  

ReAct 에이전트도 DB 검색과 점수 계산은 Python으로 처리한다. search_influencers_by_category나 calculate_match_score는 모두 Python 함수다. 차이는 그 Python 함수가 어떻게 호출되느냐에 있다.

ReAct에서는 LLM이 "지금 이 도구를 써야겠다"고 판단해야 Python 함수가 실행된다. LLM이 흐름의 주도권을 갖고 있어서, 어떤 도구를 몇 번 호출할지, 어떤 순서로 진행할지가 실행할 때마다 달라질 수 있다.

DSPy Module에서는 forward() 코드가 흐름을 처음부터 고정한다. DB 검색과 점수 계산은 LLM의 판단을 거치지 않고 코드가 직접 호출한다. LLM은 "자연어로 카테고리를 추론하는 것"과 "자연어로 추천문을 생성하는 것", 딱 두 지점에서만 개입한다.

결국 두 방식 모두 Python이 계산하는 건 같지만, 달라지는 것은 그 계산을 LLM의 결정에 의해 트리거하느냐, 코드가 직접 트리거하느냐다.

✨ 평가 기준 - 4개의 Metric 설계

DSPy Optimizer가 작동하려면 "좋은 추천이란 무엇인가"를 코드로 정의해야 한다. 우리는 이를 4개의 메트릭으로 표현했다.

1. Evidence Coverage: 데이터 완전성 (임계값 60%)
   추천된 인플루언서가 DB에 실제로 존재하는지, 그리고 팔로워 수·참여율·플랫폼·카테고리 등 필수 데이터를 갖추고 있는지 5개 항목으로 점검한다.

   • has_followers: 팔로워 수 > 0
   • has_engagement: 참여율 데이터 존재
   • has_platform: 플랫폼 정보 존재
   • has_description: 소개 텍스트 존재
   • category_fit: 기대 카테고리와 일치

2. Semantic Relevance: 광고 적합도 (임계값 0.2)
   광고 텍스트의 키워드와 인플루언서 설명의 키워드가 얼마나 겹치는지를 측정한다. 카테고리가 완전히 일치하면 +0.3 보너스를 준다.

   similarity = |광고 키워드 ∩ 인플루언서 키워드| / |광고 키워드|

3. Groundedness: 할루시네이션 체크 (임계값 66%)
   에이전트가 응답에 적은 내용이 실제 DB 데이터와 일치하는지 확인한다.

   • name_in_db: 추천 이름이 DB에 실제로 존재
   • category_mentioned: 응답에 해당 카테고리가 언급됨
   • follower_data_exists: 팔로워 수 데이터가 실제로 있음

4. Competitor Check: 경쟁사 이력 (HIGH 리스크 0명)
   추천된 인플루언서의 과거 광고 이력에서 경쟁사 이력이 있는지 확인한다.

   • LOW: 이력 없음
   • MEDIUM: 동일 카테고리 광고 이력 있음
   • HIGH: 경쟁사 직접 광고 이력 있음 → FAIL

이 4개 중 몇 개를 통과했는지 비율이 MIPROv2에 전달되는 최종 점수이다. Optimizer는 이 점수를 높이는 방향으로 프롬프트를 자동으로 조정한다.

✨ Trainset / Testset 분리 전략

ML에서 학습 데이터와 검증 데이터를 분리하듯, DSPy에서도 같은 원칙을 적용했다.

# TEST_CASES (10개) - MIPROv2 최적화에 사용하는 trainset
# 이니스프리, bhc, 삼성전자, 나이키, 에어비앤비 등

# TEST_SET (3개) - 최적화 완료 후 최종 성능 검증에만 사용하는 held-out testset
# 다이슨, 제주항공, GS25

held-out testset의 역할이 중요하다. Optimizer가 trainset 10개의 점수를 높이는 과정에서 그 데이터에 과적합될 수 있다. 최적화에 한 번도 노출되지 않은 3개 케이스로 최종 성능을 검증해야 실제 일반화 성능을 알 수 있다.

💥 설계 과정에서 드러난 구조적 긴장

설계를 마무리하고 코드를 돌려보면서 흥미로운 문제 하나가 드러났다. RankAndRecommend에서 LLM에게 상위 10명의 점수 요약 JSON을 넘기고 TOP3 이름을 뽑아달라고 했는데, LLM이 가끔 JSON에 없는 이름을 만들어냈다.

# LLM이 점수 기준 TOP3 안에 없는 이름을 포함하면 DB 기준으로 대체
valid_names = {s["name"] for s in scores}
final_top3 = [n for n in llm_top3 if n in valid_names][:3]

if len(final_top3) < 3:
   for name in db_top3:
     if name not in final_top3:
        final_top3.append(name)
     if len(final_top3) == 3:
        break

이 방어 코드는 DSPy를 도입하면서 생긴 것이다. 기존 ReAct 에이전트는 도구를 통해 DB 결과를 직접 받아오기 때문에 이런 종류의 할루시네이션이 구조적으로 차단된다. 반면 DSPy 방식에서는 LLM에게 "점수 요약 텍스트"를 건네면서 새로운 할루시네이션 경로를 만들어버렸다.

---

🌟 실제로 부딪힌 문제들

🚨 문제 1: 에이전트를 평가한 게 아니라 교체한 것이었다

가장 근본적인 문제였다.

처음 의도는 "기존 LangChain 에이전트를 DSPy로 평가하고, MIPROv2로 프롬프트롤 최적화해서 에이전트 성능을 높이자"는 것이었다. 그런데 실제로 만들어진 것을 다시 들여다보니 그게 아니었다.

InfluencerMatchingModule은 기존 AgentService를 감싼 래퍼가 아니었다. 완전히 다른 아키텍처였다.MIPROv2가 최적화하는 대상은 InferCategories와 RankAndRecommend, 두 Signature의 프롬프트이다. 그런데 이 프롬프트는 실제로 배포된 에이전트의 AGENT_SYSTEM_PROMPT와 아무 관련이 없다. DSPy Module 안에서만 존재하는 별도의 프롬프트이다.

즉, MIPROv2 최적화를 아무리 돌려도 실제 서비스 중인 LangChain 에이전트는 한 글자도 개선되지 않는다. 우리는 에이전트를 더 좋게 만들려고 했는데, 기존 에이전트를 아예 안 쓰고 에이전트를 다른 것으로 갈아치운 다음 그것을 최적화하고 있었다.

🚨 문제 2: 할루시네이션 경로를 새로 만들었다

기존 ReAct 에이전트에서는 이런 종류의 할루시네이션이 구조적으로 막혀있다. get_influencer_details 도구가 DB에서 직접 인플루언서 객체를 가져오기 때문에, 에이전트가 최종 응답에 쓰는 이름은 도구 호출 결과에서 온 것이다. LLM이 이름을 지어낼 여지가 없다.

반면 DSPy Module의 RankAndRecommend는 LLM에게 점수 요약 JSON 텍스트를 넘기고, 거기서 TOP3 이름을 뽑아달라고 요청한다.

scores_summary = json.dumps(scores[:10], ensure_ascii=False, indent=2)

rank_pred = self.rank(
   ad_concept=ad_concept,
   ad_item=ad_item,
   scores_summary=scores_summary,  # 텍스트로 전달
)

# LLM이 반환한 이름: rank_pred.top3_names

문제는 LLM이 이 JSON을 읽고 TOP3을 고르는 과정에서 가끔 JSON에 없는 이름을 만들어냈다는 것이다. "홍서연"이 없는데 "홍서연"이 top3_names에 포함되는 식이다.

결국 이를 막기 위한 방어 코드가 생겼다.

valid_names = {s["name"] for s in scores}
final_top3 = [n for n in llm_top3 if n in valid_names][:3]

# LLM이 뽑은 이름이 3개가 안 되면 점수 기준 상위 이름으로 채움
if len(final_top3) < 3:
   for name in db_top3:
      if name not in final_top3:
         final_top3.append(name)
      if len(final_top3) == 3:
         break

이 코드의 존재 자체가 문제를 드러낸다. DSPy를 도입하면서 "LLM이 자연어 텍스트를 보고 이름을 선택한다"는 새로운 단계를 만들었고, 그 단계가 새로운 할루시네이션 경로가 됐다. 해결하려던 문제를 더 복잡하게 만든 셈이다.

🚨 문제 3: 로컬 Ollama에서 MIPROv2는 현실적으로 너무 느리다

DSPy의 가장 강력한 기능은 MIPROv2의 최적화인데, 이게 로컬 환경에서는 쓰기 어려웠다.

MIPROv2가 하는 일을 단순화하면 이렇다. 프롬프트 후보를 여러 개 만들고, 각 후보를 trainset 전체에 돌려보고, 점수를 비교해서 가장 좋은 것을 선태한다. 이 과정을 여러 라운드 반복한다.

가장 가벼운 설정인 auto="light"로 해도 LLM 호출이 수십 번 발생한다. 여기에 trainset 10개를 곱하면 총 호출 수가 수백 번에 이른다.

optimizer = MIPROv2(
   metric=metric,
   auto="light",
   num_threads=1,  # 로컬 Ollama: 병렬 1개 (API 사용 시 늘려도 됨)
)

num_threads=1이라는 주석이 상황을 잘 보여준다. OpenAI나 Anthropic API를 쓰면 스레드를 늘려서 병렬로 돌릴 수 있는데, 로컬 Ollama는 그게 안 된다. 요청을 하나씩 순차적으로 처리해야 하고, 각 호출에 몇 초씩 걸리면 전체 최적화가 몇 시간이 될 수 있다.

스터디 특성상 실험을 빠르게 돌려보고 결과를 확인하는 게 중요한데, 한 번 최적화 실행에 몇 시간이 걸리는 방식은 지속하기 어려웠다.

🚨 세 문제의 관계

세 문제는 각각 독립적인 것처럼 보이지만 하나의 공통된 원인에서 출발한다.

DSPy가 진짜 힘을 발휘하는 상황은 이렇다. LLM 호출이 2~3개로 구성된 명확한 파이프라인이 있고, 각 호출의 입출력이 잘 정의되어 있으며, 충분한 trainset과 빠른 추론 환경이 갖춰져 있을 때다.

우리 프로젝트의 상황은 달랐다. 평가하려는 대상은 ReAct 에이전트, 즉 LLM이 흐름을 자율적으로 결정하는 방식이었다. 이 구조는 forward()로 고정된 흐름을 전제하는 DSPy Module과 맞지 않았다. 맞추려다 보니 에이전트를 교체하는 결과가 됐고, 교체 과정에서 오히려 새로운 문제가 생겼으며, 최적화를 돌리기에는 환경이 너무 느렸다.

---

🌟 단계별 파이프라인으로 돌아온 이유

✨ 단계별 파이프라인이 하는 일

단계별 파이프라인은 구조가 단순하다. 기존 LangChain 에이전트를 그대로 실행하고, 그 결과를 측정한다.

1. 에이전트 실행
   • AgentService.run_matching() 호출 (실제 에이전트)
   • 결과를 outputs/step1_results.json에 저장

2. Evidence 수집
   • 에이전트가 추천한 인플루언서 이름을 응답 텍스트에서 파싱
   • DB와 CSV에서 실제 데이터 조회
   • 결과를 outputs/step2_evidence.json에 저장

3. 메트릭 계산
   • 4개 메트릭 계산 (Evidence Coverage, Semantic Relevance, Groundedness, Competitor Check)
   • 결과를 outputs/step3_metrics.json에 저장

4. 리포트 생성
   • 전체 결과를 읽기 좋은 텍스트 리포트로 출력
   • 결과를 evaluation/reports/ 폴더에 저장

DSPy Module이 에이전트를 교체했던 것과 달리, 여기서는 에이전트가 바뀌지 않는다. Step 1에서 실제로 AgentService가 실행되고, Step 2~4는 그 결과를 분석할 뿐이다. 평가 파이프라인이 에이전트의 내부 구조에 전혀 개입하지 않는다.

✨ JSON으로 단계를 이어붙인 설계의 가치

각 단계가 JSON 파일로 결과를 저장하고 다음 단계가 그것을 읽는 구조가 처음에는 단순한 편의 설계처럼 보일 수 있다. 그런데 실제로 써보면 이게 꽤 중요하다.

LLM 호출이 포함된 Step 1은 느리고 비용이 든다. 10개 테스트 케이스를 전부 돌리면 몇 분이 걸린다. 반면 Step 2~4는 저장된 JSON을 읽어서 처리하기 때문에 거의 즉시 끝난다.

메트릭 계산 로직을 조금 바꾸고 싶을 때 Step 1을 다시 돌릴 필요 없이, Step 3만 다시 실행하면 된다. 리포트 형식을 바꾸고 싶으면 Step 4만 다시 실행하면 된다. MIPROv2가 모든 과정을 한 번에 처리하면서 중간 결과를 확인하기 어려웠던 것과 대조적이다.

✨ 두 방식이 각각 잘 맞는 문제가 달랐다

DSPy 방식과 단계별 파이프라인 방식은 애초에 해결하려는 문제의 성격이 달랐다.

DSPy와 MIPROv2가 진짜 힘을 발휘하는 상황은 명확하게 정의된 LLM 파이프라인이 있고, 지금 그 파이프라인의 프롬프트를 더 좋게 만들고 싶을 때다. 예를 들어 "분류 정확도를 높이고 싶다", "요약 품질을 높이고 싶다"처럼 LLM 호출 자체를 최적화하는 게 목표일 때 강력하다.

우리가 실제로 필요했던 것은 달랐다. 에이전트가 지금 잘 작동하고 있는지 측정하는 것, 즉 평가가 먼저였다. 무엇이 문제인지도 모르는 상태에서 최적화부터 하려 했던 것이다.

	DSPy + MIPROv2	단계별 파이프라인
목적	LLM 파이프라인 프롬프트 자동 최적화	기존 에이전트 품질 측정
대상	DSPy로 새로 설계한 별도 시스템	실제 배포 중인 에이전트
실행 환경	로컬 Ollama에서 최적화 실행이 비현실적	로컬 Ollama에서 충분히 동작
결과 해석	최적화 완료까지 결과 확인 어려움	단계별 JSON으로 중간 확인 가능
에이전트 코드 변경	에이전트 자체가 교체됨	없음

DSPy로는 기존 LangChain 에이전트를 최적화할 방법이 없다.
MIPROv2가 프롬프트를 최적화하려면 "어떤 프롬프트를 바꿔야 하는지" 알아야 한다. 그러러면 시스템 안에 DSPy의 Signature과 Predictor가 있어야 한다. MIPROv2는 그것들을 찾아서 튜닝한다.

LangChain ReAct 에이전트는 DSPy와 무관하게 만들어진 블랙박스이다. MIPROv2 입장에서는 내부를 들여다볼 수가 없다.

즉, DSPy + MIPROv2는 처음부터 DSPy로 설계된 시스템을 최적화하는 도구이다. 기존에 다른 방식으로 만들어진 에이전트를 평가하거나 개선하는 도구가 아니다.
우리 프로젝트처럼 이미 LangChain으로 만들어진 에이전트가 있는 상황에서는 애초에 DSPy가 맞는 도구가 아니었던 거고, 그 불일치를 해결하려다 에이전트를 교체하는 결과로 이어진 것이다.

---

🌟 DSPy는 언제 쓰면 좋은가?

😀 DSPy가 잘 맞는 상황

• 처음부터 DSPy로 설계할 때
  가장 중요한 조건이다. 앞서 살펴봤듯이 MIPROv2는 시스템 안에 DSPy Signature와 Predictor가 있어야 최적화할 수 있다. 기존에 다른 방식으로 만들어진 시스템을 나중에 DSPy로 개선하려 하면 결국 다시 만드는 수밖에 없다.
  새 프로젝트를 시작하거나, LLM 파이프라인을 처음 설계하는 시점이라면 DSPy가 훨씬 자연스럽다.

• 파이프라인의 흐름이 고정되어 있을 때
  DSPy Module의 forward()는 실행 흐름을 코드로 고정한다. 이 구조는 "항상 같은 단계를 같은 순서로 실행하는" 파이프라인에 적합하다. 예를 들어, "문서 요약 → 핵심 키워드 추출 → 카테고리 분류"처럼 순서가 명확하게 정해진 파이프라인이 좋은 예다.
  반면 ReAct 에이전트처럼 LLM이 상황에 따라 다른 경로를 택하는 동적인 구조는 forward()로 표현하기 어렵고, 억지로 맞추면 에이전트의 유연함을 잃는다.

• "좋은 결과"를 코드로 정의할 수 있을 때
  MIPROv2를 쓰려면 metric 함수가 있어야 한다. "이 출력이 얼마나 좋은가"를 0.0~1.0으로 반환하는 코드이다. 이게 정의되지 않으면 Optimizer가 무엇을 향해 최적화해야 할지 모른다.
  우리 프로젝트에서는 4개 메트릭을 이미 가지고 있었기 때문에 이 조건은 충족됐다. 품질 기준이 모호하거나 사람의 주관적 판단에 의존해야 하는 경우라면 metric 설계 자체가 먼저 해결해야 할 과제가 된다.

• 빠른 추론 환경이 갖춰져 있을 때
  MIPROv2는 (trainset) × (후보 프롬프트 수) × (최적화 라운드)만큼 LLM을 호출한다. OpenAI나 Anthropic API처럼 빠른 환경에서는 병렬 호출로 수십 분 안에 끝낼 수 있지만, 로컬 Ollama처럼 순차 처리만 가능한 환경에서는 몇 시간이 걸릴 수 있다. 최적화를 실용적으로 쓰려면 추론 속도가 받쳐줘야 한다.

🥲 DSPy가 맞지 않는 상황

• 이미 만들어진 시스템을 평가하거나 개선하고 싶을 때
  우리가 겪은 문제 그대로다. DSPy는 기존 시스템을 평가하는 도구가 아니다. 기존 시스템을 개선하려면 DSPy로 다시 만들어야 하는데, 그 순간 원본 시스템과 별개의 것이 된다.
  이미 동작하는 에이전트가 있고 그것을 측정하고 싶다면, 단계별 평가 파이프라인처럼 에이전트를 그대로 실행하는 방식이 더 적합하다.

• 최적화보다 평가가 먼저 필요할 때
  에이전트가 지금 잘 작동하는지도 모르는 상태에서 최적화부터 시작하는 건 순서가 맞지 않는다. "지금 어디서 문제가 생기는가"를 먼저 파악해야 "무엇을 최적화해야 하는가"를 알 수 있다. 평가 없이 최적화부터 시도하면 엉뚱한 것을 개선하는 결과가 나올 수 있다.

✨ 정리

	적합	부적합
시스템 설계 시점	처음부터 DSPy로 설계	기존 시스템을 나중에 DSPy로 전환
에이전트 유형	흐름이 고정된 파이프라인	동적으로 경로가 바뀌는 ReAct 에이전트
품질 기준	metric을 코드로 정의 가능	주관적 판단에 의존
추론 환경	API 기반 (병렬 호출 가능)	로컬 모델 (순차 처리만 가능)
현재 상태	평가는 마쳤고 프롬프트를 자동으로 최적화하고 싶을 때	평가 자체가 아직 안 됐을 때