기존 클라이언트 패치(Patch)

기존 클라이언트 패치(Patch)

Instructor를 쓰는 가장 전통적인 방법 중 하나는 이미 만들어 둔 provider 클라이언트를 patch로 감싸는 방법이에요. from_provider는 최신 권장 API지만, 기존 코드나 특정 provider 공식 SDK를 그대로 쓰면서 구조화 출력만 추가하고 싶을 땐 instructor.patch(client) 또는 instructor.from_openai(client) 패턴이 여전히 유효해요. 이러면 평소 쓰던 클라이언트의 메서드에 response_model, max_retries 같은 인자를 추가로 쓸 수 있게 되죠.

import instructor
from openai import OpenAI
from pydantic import BaseModel

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

client = OpenAI()          # 기존 OpenAI 클라이언트
client = instructor.patch(client)  # Instructor 기능 부여

user = client.chat.completions.create(
    model="gpt-4o-mini",
    response_model=User,
    messages=[{"role": "user", "content": "Extract: Jason is 25"}],
)
print(user.name)  # Jason

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

자동 재시도(reask) 적용

패치된 클라이언트는 max_retries를 지원해요. 검증 실패 시 Instructor가 실패 사유를 담아 LLM에 다시 요청해 올바른 구조·값을 얻도록 반복해요. 이 기능 덕분에 수동으로 "다시 파싱해 달라"고 요청할 필요가 없어요.

user = client.chat.completions.create(
    model="gpt-4o-mini",
    response_model=User,
    messages=[{"role": "user", "content": "Extract: Jason is 25"}],
    max_retries=3,
)

patch와 from_provider의 관계

from_provider는 provider 식별 문자열 하나로 클라이언트를 만들고 동시에 Instructor 기능을 활성화하는 단축형이에요. 반면 patch는 이미 존재하는 클라이언트에 기능을 얹는 방식이라, 커스텀 base URL·인증·타임아웃 설정을 이미 해 둔 클라이언트를 그대로 재사용하려 할 때 자연스러워요. 두 방식 모두 결과적으로는 같은 response_model 기반 구조화 출력을 제공해요.

주의할 점

  • 패치된 클라이언트로 만든 요청은 리턴 타입이 response_model로 지정한 클래스가 되므로, 타입 체크 환경에서 적절히 안내가 필요할 수 있어요.
  • provider가 tool calling을 지원하는지에 따라 내부적으로 강제 방식이 달라지니, 동작이 예상과 다르면 mode 설정을 확인해 보세요.

더 알아보기