DSPydantic: DSPy를 활용한 Pydantic 모델 자동 최적화 도구

9bow · 12월 10, 2025, 3:30오전

DSPydantic 소개

DSPydantic은 Pydantic 모델의 필드 설명(description)과 프롬프트를 자동으로 최적화해주는 오픈소스 라이브러리입니다. LLM(대규모 언어 모델)을 사용하여 구조화된 데이터를 추출할 때, 개발자가 수동으로 프롬프트를 튜닝하거나, Pydantic의 필드 설명을 일일이 수정하는 번거로움을 덜어주기 위해 개발되었습니다.

DSPydantic의 핵심은 스탠포드에서 공개한 LM 프로그래밍 프레임워크인 DSPy의 최적화 알고리즘을 활용한다는 점입니다. 개발자가 몇 가지 입력 예시와 기대하는 출력값(Expected Output)을 제공하면, DSPydantic은 이를 바탕으로 LLM이 데이터를 가장 정확하게 추출할 수 있는 필드 설명과 시스템 프롬프트를 자동으로 찾아냅니다.

LLM을 이용해 텍스트나 이미지에서 데이터를 JSON 형태로 추출할 때, Pydantic은 매우 유용한 도구입니다. 하지만 모델의 정확도를 높이기 위해서는 Field(description="...") 부분에 들어갈 설명을 정교하게 작성해야 했습니다. DSPydantic은 이러한 '프롬프트 엔지니어링' 과정을 자동화하여, 예시 데이터만으로 추출 성능을 극대화할 수 있도록 돕습니다. 텍스트뿐만 아니라 이미지, PDF 등 다양한 입력 소스를 지원하며, 사람의 개입 없이도 최적의 설정을 도출할 수 있습니다.

기존 Pydantic 사용 방식과 비교

일반적인 Pydantic 사용 방식과 DSPydantic을 도입했을 때의 가장 큰 차이점은 '개발자가 무엇에 집중하는가'입니다. 기존에는 개발자가 직접 모델의 description 필드에 들어갈 자연어 설명을 작성해야 했습니다. 이 때, 추출 결과가 좋지 않으면 설명을 조금씩 수정하며 반복적인 테스트(Trial & Error)를 거쳤으며, 개발자의 프롬프트 작성 능력에 따라 결과 품질이 달라집니다.

하지만 DSPydantic를 사용하게 되면 개발자는 설명 대신 '입력 데이터'와 '정답 데이터(Ground Truth)'의 쌍(pair)만 제공하면 됩니다. 라이브러리가 DSPy의 옵티마이저를 사용하여 해당 데이터를 가장 잘 처리할 수 있는 필드 설명과 프롬프트를 역으로 생성하고 검증합니다.

DSPydantic의 주요 기능

필드 설명 및 프롬프트 자동 최적화: DSPydantic의 가장 강력한 기능은 PydanticOptimizer입니다. 사용자가 제공한 예시(Examples)를 기반으로 Pydantic 모델의 각 필드에 가장 적합한 설명을 자동으로 생성합니다. 또한, 시스템 프롬프트(System Prompt)와 지시 프롬프트(Instruction Prompt)까지 함께 최적화하여 전반적인 데이터 추출 정확도를 높입니다.
다양한 입력 데이터 지원 (Multimodal): DSPydantic은 단순 텍스트뿐만 아니라 다양한 형태의 비정형 데이터 처리를 지원합니다. 즉, 일반적인 문장이나 문서 데이터의 텍스트 데이터 외에, 영수증 이미지와 같은 이미지의 경로(image_path)를 입력하면 해당 경로에 위치한 이미지의 시각적 데이터를 분석하여 구조화된 정보로 변환합니다. 또한, PDF 문서를 이미지로 변환하거나 텍스트를 추출하여 처리할 수 있도록 지원합니다.
평가 메커니즘과 LLM 평가자: DSPydantic은 최적화 과정에서 모델의 성능을 평가하기 위해 다음과 같은 다양한 평가 방식들을 제공합니다:
- 정확도 기반 평가: exact (완전 일치), levenshtein (문자열 유사도 거리) 등을 사용하여 정답과 출력값을 비교합니다.
- Human-in-the-Loop (HITL): 사람이 직접 평가 과정에 개입할 수 있는 GUI 팝업 기능을 제공하여, 미묘한 차이를 사람이 판단할 수 있게 합니다.
- LLM Judge: 정답 데이터(Ground Truth)가 없는 경우, 또 다른 LLM을 심판(Judge)으로 사용하여 추출된 데이터의 품질을 평가할 수 있습니다.
스마트 옵티마이저 선택: DSPydantic는 사용하는 데이터셋의 크기에 따라 가장 적합한 DSPy 옵티마이저를 자동으로 선택합니다. 20개 미만의 예시만 존재하는 경우, 적은 데이터에 효율적인 BootstrapFewShot을 사용합니다. 20개 이상 예시가 존재하는 경우에는 더 나은 성능을 보이는 BootstrapFewShotWithRandomSearch를 사용합니다. 물론, 자동 선택하는 옵티마이저 외에 MIPROv2나 COPRO 같은 고급 옵티마이저를 수동으로 지정할 수도 있습니다.

DSPydantic 사용 예시

다음은 DSPydantic의 기본적인 사용 흐름을 보여주는 코드입니다:

from pydantic import BaseModel, Field
from dspydantic import PydanticOptimizer, Example, create_optimized_model

# 1. 모델 정의 (초기 설명은 간단하게 작성)
class User(BaseModel):
    name: str = Field(description="User name")
    age: int = Field(description="User age")
    email: str = Field(description="Email address")

# 2. 예시 데이터 제공
examples = [
    Example(
        text="홍길동, 30세, hong@test.com",
        expected_output=User(name="홍길동", age=30, email="hong@test.com")
    ),
    # ... 추가 예시
]

# 3. 최적화 실행
optimizer = PydanticOptimizer(
    model=User,
    examples=examples,
    evaluate_fn="exact",
    model_id="gpt-4o",
)
result = optimizer.optimize()

# 4. 최적화된 모델 생성 및 사용
# 최적화된 description이 적용된 새로운 모델 클래스를 생성합니다.
OptimizedUser = create_optimized_model(User, result.optimized_descriptions)

라이선스

DSPydantic 프로젝트는 Apache-2.0 라이선스로 공개 및 배포되고 있습니다.

DSPydantic 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~