DSPy 사용법: 평가 지표로 시작하는 프롬프트 최적화

이 글은 2026년 10월 15일에 DSPy의 현행 문서, PyPI, Google의 모델 요금을 기준으로 확인했습니다. PyPI에 등록된 버전은 2026년 10월 12일에 출시된 DSPy 3.4.1이며, Python 3.10 이상, 3.16 미만을 지원합니다. 설치할 패키지 이름은 dspy입니다. PyPI 패키지 메타데이터.

DSPy란 무엇이며, 컴파일은 어떤 의미인가요?

DSPy는 언어 모델 작업을 프로그램으로 정의하고 프롬프트를 개선하는 오픈 소스 Python 프레임워크입니다. 특정 옵티마이저를 선택하면 모델 가중치도 개선할 수 있습니다. 핵심은 직접 정한 성공 기준에 따라 개선 과정을 반복할 수 있다는 점입니다. 처음 생성한 프롬프트가 사람이 공들여 작성한 프롬프트보다 반드시 낫다는 뜻은 아닙니다. DSPy 개요.

공연 리허설에 빗대면 이해하기 쉽습니다. 시그니처는 공연의 요구사항, 모듈은 공연을 진행하는 방식, 평가 지표는 심사 기준에 해당합니다. 옵티마이저는 일부를 바꿔 보고 결과를 확인한 뒤 도움이 된 변경을 남깁니다. 심사 기준이 없다면 리허설을 끝없이 바꿔도 실제로 나아졌는지 알 수 없습니다.

시그니처로 작업을 정의합니다

시그니처는 입력과 출력, 작업 지침을 선언합니다. "ticket -> category"는 티켓을 입력받아 분류 결과를 출력한다는 뜻입니다. 클래스 기반 시그니처에는 타입이 지정된 필드와 작업을 설명하는 독스트링을 추가할 수 있습니다. 어떤 필드를 정의할지는 여전히 중요합니다. 업무상 ‘긴급’의 의미가 모호하다면 옵티마이저가 대신 해결해 주지는 못합니다. 시그니처 문서.

DSPy 모듈로 실행 방식을 정합니다

모듈은 작업을 수행할 전략을 구현합니다. dspy.Predict는 기본적인 예측 구성 요소입니다. dspy.ChainOfThought는 답변 앞에 추론 필드를 추가합니다. dspy.ReAct는 추론과 툴 사용을 반복하는 루프를 지원합니다. 모델을 한 번 실행하는 것만으로 부족하다면 Python에서 모듈을 조합할 수 있습니다. 모듈 문서.

고객 지원 티켓을 담당 부서로 분류하려면 Predict부터 시작하는 편이 좋습니다. 짧은 메시지를 분류하는 데 툴 사용 루프까지 추가하면, 필요성이 입증되기도 전에 관리할 요소만 늘어납니다.

컴파일은 최적화 절차입니다

옵티마이저는 예제와 평가 지표를 바탕으로 프로그램의 일부를 변경합니다. 프롬프트 최적화에서 .compile()은 수정된 지침이나 시연 예제, 즉 프롬프트 안에 포함되는 예제를 담은 프로그램을 반환합니다. 애플리케이션을 네이티브 실행 파일로 변환하거나 이후 모델 호출을 없애는 과정은 아닙니다. 가중치를 학습하려면 그에 맞는 옵티마이저를 별도로 선택해야 합니다. 옵티마이저 선택 가이드.

DSPy 사용법: 현행 문서의 최소 예제 실행하기

현행 입문 예제는 하이쿠를 생성합니다. 데이터베이스나 툴, 최적화 탐색 없이도 이 작은 예제로 인터페이스를 파악할 수 있습니다.

Python 환경에 확인된 버전을 설치합니다.

python -m pip install 'dspy[litellm]==3.4.1'

환경 변수 GEMINI_API_KEY에 유효한 Google Gemini API 키를 설정합니다. 다음 코드를 first_dspy.py로 저장하고 python first_dspy.py를 실행합니다.

import os
import dspy

lm = dspy.LM(
    "gemini/gemini-2.5-flash-lite",
    api_key=os.environ["GEMINI_API_KEY"],
    engine="litellm",
)
dspy.configure(lm=lm)

haiku_signature = "subject -> haiku"
haiku_generator = dspy.Predict(haiku_signature)
result = haiku_generator(subject="computer science")
print(result.haiku)

마지막 네 줄은 현행 문서의 첫 프로그램과 같습니다. 설정은 DSPy의 모델 구성 방식을 따르되, 아래 실험에서 저렴한 모델 하나를 일관되게 사용하도록 Google Gemini 2.5 Flash-Lite로 바꿨습니다. 프로바이더 문자열은 LiteLLM의 Gemini 연동 방식을 따릅니다. 백엔드를 명시하는 설정은 DSPy LM API에서 지원합니다.

DSPy는 시그니처로 프롬프트를 구성해 설정된 모델에 보내고, 응답에서 haiku 필드를 파싱합니다. 이 코드는 최적화가 아닌 추론 예제입니다. 특정한 시가 출력된다거나 품질이 개선된다고 주장하는 예제는 아닙니다.

DSPy 프롬프트 최적화에는 평가 지표가 필요합니다

평가 지표가 없으면 의미 있는 최적화도 없습니다. 평가 지표는 예측 결과를 점수로 바꾸는 함수입니다. 티켓 분류에서는 예측한 카테고리와 사람이 승인한 라벨을 비교할 수 있습니다. 생성형 답변의 정답 여부는 평가 기준표나 코드로 실행할 수 있는 검사로 판단해야 할 수도 있습니다. DSPy의 평가 지표 인터페이스는 사용자가 작성한 채점 함수를 받습니다. 어떤 결과에 높은 점수를 줄지는 프레임워크가 대신 정해 주지 않습니다. 평가 지표와 평가.

그래서 규모가 작더라도 라벨이 붙은 평가 데이터셋이 중요합니다. ‘간결하게 작성하라’를 ‘짧게 답하라’로 바꾸는 일이 지겹다면, 실제 실패 사례를 모아 보십시오. 기술 지원팀으로 잘못 전달된 환불 요청, 결제 문제로 오인된 로그인 문제, 요청 두 가지가 함께 담긴 메시지 같은 사례입니다. 새 프롬프트의 출력을 보기 전에 의도한 결과부터 라벨로 정해 둡니다.

첫 파일럿에서는 서로 다른 예제 60개를 준비해 학습용 20개, 검증용 20개, 최종 테스트용 20개로 나누는 구성을 제안합니다. 이는 실험 규모를 정하기 위한 제안일 뿐, DSPy의 필수 요건이나 운영 환경에서의 신뢰성을 입증하는 수치는 아닙니다.

• 학습 예제는 옵티마이저가 학습에 활용할 재료를 제공합니다.
• 검증 예제는 버전을 비교하고 개발 방향을 결정하는 데 사용합니다.
• 최종 테스트 예제는 후보 프로그램과 평가 규칙을 확정할 때까지 사용하지 않습니다.

같은 고객이나 사건에서 나온 관련 티켓은 하나의 데이터 분할에 모아 둡니다. 거의 같은 사례가 여러 분할에 흩어지면 최적화된 프롬프트의 일반화 성능이 실제보다 좋아 보일 수 있습니다. 각 분할을 쉬운 사례로만 채우지 말고, 드물더라도 중요한 실패를 포함해야 합니다.

다만 ‘평가 지표가 없으면’이라는 말에는 정확한 단서가 필요합니다. 최적화하지 않은 DSPy 프로그램은 평가 지표 없이 실행할 수 있고, LabeledFewShot은 예제에 점수를 매기지 않고도 프롬프트에 추가할 수 있습니다. 이는 구성 작업이지, 변경으로 작업 성능이 나아졌다는 증거는 아닙니다. 모든 작업에 사람이 작성한 정답이 필요한 것도 아닙니다. 실행 가능한 정답 검사로 평가 신호를 만들 수도 있습니다. 업무 분류에서는 대체로 승인된 라벨이 가장 명확한 출발점입니다. 퓨샷 베이스라인.

DSPy 옵티마이저: 현행 문서의 종류와 선택 기준

설명할 수 있는 실패가 있다면, 그 문제를 다루는 가장 단순한 옵티마이저부터 시작합니다. 더 많은 탐색이 도움이 되려면 먼저 평가 지표가 좋은 후보와 나쁜 후보를 구별할 수 있어야 합니다.

현행 옵티마이저 API 목록에는 다음 항목이 정확히 이 이름으로 올라 있습니다. BetterTogether, BootstrapFewShot, BootstrapFewShotWithRandomSearch, BootstrapFinetune, BootstrapRS, COPRO, Ensemble, GEPA, InferRules, KNN, KNNFewShot, LabeledFewShot, MIPROv2, SIMBA입니다.

각 항목이 모두 독립적인 탐색 알고리즘인 것은 아닙니다. BootstrapRS는 BootstrapFewShotWithRandomSearch의 별칭이며, KNN은 KNNFewShot에서 사용하는 검색 보조 도구입니다. 현행 선택 가이드에는 에이전트형 프로그램을 위한 AvatarOptimizer도 나오지만, 해당 API 목록에는 포함되어 있지 않습니다. 계열별 상세 설명, 선택 가이드.

MIPROv2는 지침을 제안하고, 이전 점수를 바탕으로 탐색하는 방법인 베이지안 최적화를 통해 지침과 시연 예제의 조합을 살펴봅니다. SIMBA는 미니배치 단위로 작업하면서 규칙이나 시연 예제를 제안합니다. 두 방식은 서로 다르며, BootstrapFewShot의 이름만 바꾼 버전이 아닙니다. MIPROv2 API, SIMBA API.

GEPA는 리플렉션 모델이 실행 피드백을 읽고 지침 변경을 제안하도록 합니다. 예를 들어 ‘고장 난 기능을 언급했더라도 환불 요청은 결제 담당으로 분류해야 한다’는 구체적인 설명을 점수와 함께 주면, 단순히 실패 점수만 주는 것보다 유용한 신호가 됩니다. 상세 문서에서는 숫자만 반환하는 평가 지표도 허용하지만, 이 경우 더 풍부한 피드백을 활용할 수 없다고 설명합니다. GEPA 작동 방식.

첫 최적화 실험은 실행 범위부터 정합니다

작은 BootstrapFewShot 실험은 범위를 정하지 않은 지침 탐색보다 실행량을 계산하기 쉽습니다. 다음 설계는 Predict 모듈 하나, 결정론적 라벨 평가 지표, 그리고 교사 역할과 예측 역할에 동일한 모델을 사용합니다.

DSPy BootstrapFewShot: 작게 시작하는 실험

train.jsonl, validation.jsonl, test.jsonl을 준비하고, 각 파일에 사람이 라벨을 붙인 서로 다른 티켓을 20개씩 넣습니다. 각 줄은 text와 label을 가진 JSON 객체입니다. 허용되는 라벨은 billing, technical, account, other입니다. 예를 들어 청구서 주소 변경 요청에는 billing 라벨을 붙일 수 있습니다. 하이쿠 출력이 아니라 직접 준비한 업무 예제를 사용해야 합니다.

다음 코드를 별도 스크립트 optimize_tickets.py로 저장하고, 앞서 사용한 API 키를 설정한 뒤 실행합니다.

import json
import os
from typing import Literal
import dspy

lm = dspy.LM(
    "gemini/gemini-2.5-flash-lite",
    api_key=os.environ["GEMINI_API_KEY"],
    engine="litellm",
    cache=False,
)
dspy.configure(lm=lm)

class RouteTicket(dspy.Signature):
    """Choose the support queue responsible for the ticket's main request."""
    text: str = dspy.InputField()
    label: Literal["billing", "technical", "account", "other"] = (
        dspy.OutputField()
    )

def load_examples(path):
    with open(path, encoding="utf-8") as source:
        rows = [json.loads(line) for line in source if line.strip()]
    assert len(rows) == 20
    return [dspy.Example(**row).with_inputs("text") for row in rows]

train = load_examples("train.jsonl")
validation = load_examples("validation.jsonl")
test = load_examples("test.jsonl")
assert len({e.text for e in train + validation + test}) == 60

def correct_label(example, prediction, trace=None):
    return prediction.label == example.label

program = dspy.Predict(RouteTicket)
evaluate = dspy.Evaluate(
    devset=validation, metric=correct_label, num_threads=1
)
print("Baseline validation:", evaluate(program).score)

optimizer = dspy.BootstrapFewShot(
    metric=correct_label,
    max_bootstrapped_demos=4,
    max_labeled_demos=0,
    max_rounds=1,
)
optimized = optimizer.compile(program, trainset=train)
print("Optimized validation:", evaluate(optimized).score)

# Freeze this candidate before opening the final test results.
final_test = dspy.Evaluate(
    devset=test, metric=correct_label, num_threads=1
)
print("Baseline final test:", final_test(program).score)
print("Optimized final test:", final_test(optimized).score)
optimized.save("candidate_ticket_router.json")

이 코드는 문서에 나온 BootstrapFewShot 생성자와 평가 인터페이스를 응용한 예제이며, 벤치마크 결과를 제시하는 것이 아닙니다. 성공한 시연 예제를 최대 네 개까지 확보하도록 요청하고, 학습 예제마다 부트스트랩 시도를 한 번 허용하며, 원본 라벨 예제는 그대로 추가하지 않습니다. 저장된 파일은 검토할 후보일 뿐, 자동으로 운영 환경에 배포되는 결과물이 아닙니다.

이 설계의 실행 횟수는 다음과 같습니다.

• 검증 데이터에서 베이스라인 평가: 프로그램 실행 20회.
• 학습 데이터에 대한 부트스트랩: 교사 모델 실행 최대 20회. 충분한 수의 시연 예제가 통과하면 더 일찍 끝날 수 있습니다.
• 검증 데이터에서 최적화된 프로그램 평가: 프로그램 실행 20회.
• 최종 테스트 데이터에서 두 버전 평가: 프로그램 실행 40회.

평가까지 포함해 단일 단계 실행 최대 100회이며, 컴파일 자체가 차지하는 실행은 최대 20회입니다. 각 실행에서 모델 요청이 한 번에 성공하고 재시도나 파싱 실패 시 대체 처리가 없다면, 작업 모델 호출도 최대 100회가 됩니다. 앞서 하이쿠로 기본 동작을 확인한 호출은 별도입니다. LLM 평가자, 에이전트 루프, 재시도 또는 추가 최적화 시도가 들어가면 총횟수는 달라집니다.

Google의 Gemini 2.5 Flash-Lite Standard 유료 텍스트 정가는 입력 토큰 100만 개당 $0.10, 출력 토큰 100만 개당 $0.40입니다. 호출당 평균 입력 토큰 1,000개와 출력 토큰 100개를 가정하면 100회 호출 비용은 $0.014입니다. 계산식은 100,000 ÷ 1,000,000 × $0.10 + 10,000 ÷ 1,000,000 × $0.40입니다. Google 요금표.

이는 모델 비용만 계산한 산술 예시이며, 실제 청구액을 측정한 결과나 지출 상한이 아닙니다. 입력 토큰 가정에는 DSPy의 형식 구성과 첨부된 시연 예제까지 포함해야 합니다. 티켓이 길어지거나 출력이 늘어나거나 과금 대상 추론이 추가되면 비용도 커집니다. 이 추정에는 배치나 캐시 할인을 적용하지 않았습니다. 실제 비용은 프로바이더의 사용량 기록으로 확인해야 합니다.

DSPy, 직접 작성한 프롬프트, 파인튜닝은 어떻게 다를까요?

측정 가능한 프로그램을 반복 가능한 방식으로 개선해야 한다면 DSPy를 사용합니다. 직접 작성한 프롬프트가 이미 작업 요건을 충족한다면 그대로 유지합니다. 프롬프트 변경만으로는 부족하다는 근거가 있고 모델 학습이 배포 제약에 맞는다면 파인튜닝을 검토합니다.

이 기법들은 함께 사용할 수 있습니다. DSPy에는 BootstrapFinetune이 포함되어 있고, BetterTogether는 프롬프트 최적화와 가중치 최적화를 결합합니다. 실무에서 중요한 차이는 어느 이름이 더 고급스럽게 들리는지가 아니라, 무엇을 바꾸고 유지하느냐입니다. 프롬프트와 가중치 최적화.

전환을 고민할 시점은 운영 부담에서 드러납니다. 모델이 바뀌거나 새 실패 사례가 나올 때마다 엔지니어가 여러 프롬프트를 수동으로 고쳐야 한다면, 점수에 기반한 최적화 루프가 매력적인 선택이 됩니다. 반대로 짧은 프롬프트가 이미 합격 기준을 충족한다면, 프레임워크로 대체해서 얻을 이점은 아직 입증되지 않은 셈입니다.

누가 도입하고, 누가 기다리거나 건너뛰어야 할까요?

엔지니어는 반복 작업, 작동하는 베이스라인, 대표적인 실패 사례를 갖췄을 때 시작하는 것이 좋습니다. 티켓 분류와 구조화된 정보 추출은 기대 출력을 검사할 수 있어 좋은 출발점입니다. 시스템을 확장하기 전에 작은 구성 요소부터 최적화하십시오. DSPy의 한계는 목표의 품질에서 나타납니다. 평가 지표가 잘못된 동작에 보상을 준다면, 더 높은 점수를 받은 후보를 골라도 원하는 결과와 멀어질 수 있습니다.

운영 담당자는 라벨과 오류의 우선순위를 책임져야 합니다. 고객 지원 관리자는 일반적인 결제 문의보다 계정 접근 문제를 잘못 분류하는 일을 훨씬 심각하게 볼 수 있습니다. 점수가 두 오류를 똑같이 취급한다면 최적화 결과가 관리자의 우선순위와 어긋날 수 있습니다. 엔지니어에게 점수를 높여 달라고 하기 전에 이 정책부터 정해야 합니다.

도입 결정자는 처음 보는 예제에서의 성능 근거를 요구해야 합니다. 어떤 베이스라인과 비교했는지, 어떤 사례에서 성능이 떨어졌는지, 실제 서비스할 프로그램에 이제 무엇이 포함되는지, 워크플로가 여전히 지연 시간 요건을 충족하는지 확인하십시오. 옵티마이저의 이름은 도입을 승인할 근거가 아닙니다. 평가 작업을 정비하는 팀이라면 이 사이트의 Promptfoo 리뷰도 함께 읽어 볼 만합니다.

비즈니스 팀은 가끔 하는 카피 작성, 일회성 조사, 예제가 쌓이기도 전에 바뀌는 워크플로에는 DSPy를 도입하지 않는 편이 낫습니다. Python 코드를 유지할 사람이 없거나 채점 기준에 합의할 수 없는 경우도 마찬가지입니다. 좋은 프롬프트, 체크리스트, 사람의 검토만으로 더 적절한 체계를 만들 수 있습니다. 실제 문제가 원천 데이터의 부재나 정의되지 않은 업무 절차라면 도입을 미루십시오. 문구를 최적화한다고 둘 중 어느 것도 생기지는 않습니다.

DSPy에 대한 기대는 어디서 과장될까요?

‘프롬프팅 대신 프로그래밍한다’고 해서 프롬프트가 사라지는 것은 아닙니다. DSPy가 프롬프트를 생성하고 관리할 뿐, 작업을 정의하고 실패를 판단하며 결과의 수용 여부를 결정하는 일은 여전히 사람의 몫입니다.

‘컴파일’은 모델이 영구적으로 학습했다는 뜻이 아닙니다. 프롬프트 옵티마이저가 학습한 결과물은 지침이나 시연 예제입니다. 추론 시에는 여전히 모델을 호출하며, 시연 예제는 프롬프트 공간을 차지합니다. 학습한 상태를 JSON으로 저장하고 새 프로그램에 불러올 수 있습니다. 저장과 불러오기.

‘자동 최적화’가 성능 향상까지 자동으로 보장하지는 않습니다. 의미 있는 비교는 처음 보는 입력에서 기존 접근 방식과 비교하는 것입니다. 개발 점수가 높아진 이유가 과적합, 관대한 평가자, 또는 비용이 큰 실패를 놓치는 데이터셋 때문일 수도 있습니다.

또한 평가 지표 호출 수와 프로바이더 호출 수는 다릅니다. GEPA의 max_metric_calls는 채점 함수 호출 횟수의 예산을 정합니다. 리플렉션 과정에서도 모델을 호출하고, 채점 대상 프로그램 자체가 여러 요청을 보낼 수도 있습니다. auto 설정이 어느 경우에나 통하는 청구액을 뜻하지는 않습니다. GEPA 예산 제어.

개발자가 자주 묻는 DSPy 질문

다음 업무일에 해볼 일

월요일에는 반복되는 티켓 분류나 정보 추출 실패 하나를 골라, 해당 업무 책임자에게 대표적인 예제의 라벨을 요청해 보십시오. 베이스라인을 고정하고 채점 규칙을 정한 뒤, 범위를 제한한 실험을 한 번 실행합니다. 후보를 승인하기 전에 달라진 답변을 검토합니다. 점수를 정의할 수 없다면, 다음에 해야 할 유용한 일은 업무 규칙에 합의하는 것입니다.

뉴스레터에서 실무에 도움이 되는 AI 엔지니어링 해설을 받아보십시오.