응답 모델(Response Model)

응답 모델(Response Model)

응답 모델은 Instructor의 핵심 개념이에요. LLM이 반환할 구조를 Pydantic 클래스로 정의하고, 이를 response_model로 넘기면 Instructor가 그 구조에 맞는 출력을 보장해요. 이 방식의 장점은 스키마를 별도로 작성할 필요 없이 파이썬 타입만으로 원하는 데이터 형태를 표현할 수 있다는 점이에요.

가장 단순한 예부터 볼게요. create 호출의 response_model에 User 클래스를 넘기면, 반환값은 dict나 문자열이 아니라 User 인스턴스예요. 그러니 .name, .age처럼 속성 접근으로 바로 쓸 수 있어요.

import instructor
from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int

client = instructor.from_provider("openai/gpt-4o-mini")

user = client.create(
    response_model=User,
    messages=[{"role": "user", "content": "Extract: John is 25 years old"}],
)

print(user.name)  # John
print(user.age)   # 25

출처: https://python.useinstructor.com/concepts/response_model/

필드 설명으로 추출 품질 높이기

LLM은 필드 설명을 참고해서 정확히 무엇을 추출할지 판단해요. 단순히 타입만 있으면 모호할 수 있으니, Field(description=...)로 각 필드의 의미를 명시해 주는 걸 권장해요.

from pydantic import BaseModel, Field

class User(BaseModel):
    name: str = Field(description="The user's full name")
    age: int = Field(description="The user's age in years")

모드(Mode) 이해하기

Instructor는 provider와 상황에 따라 LLM에게 구조화 출력을 강제하는 방식을 바꿔요. Mode 열거형이 이를 나타내는데, 대표적인 것들로는:

  • Mode.TOOLS: 함수 호출(tool calling, response_model을 도구 스키마로 사용)을 통해 구조를 강제해요. 모델이 함수 호출을 지원하면 기본적으로 쓰이는 방식이에요.
  • Mode.JSON: 모델에게 JSON으로 응답하도록 요청하고 스키마를 함께 안내하는 방식이에요. tool calling을 지원하지 않는 모델에서 유용해요.

from_provider(..., mode=Mode.JSON)처럼 설정할 수 있어요.

실용 요령

  • 구조는 될 수 있으면 단순하게 유지하세요. 복잡하게 얽힌 중첩 모델도 동작하지만, 필드 설명이 부족하면 추출이 흔들릴 수 있어요.
  • messages에 추출 대상을 분명히 담아 두는 게 응답 모델만큼 중요해요.
  • 검증 실패 시 자동 재시도(reask)와 결합하면, 잘못된 값을 받았을 때 LLM이 스스로 고쳐 반환하는 흐름을 만들 수 있어요.

더 알아보기