Instructor 시작하기

Instructor 시작하기

Instructor는 LLM에서 구조화되고 예측 가능한 데이터를 얻기 위한 파이썬 라이브러리예요. 모델이 마음대로 응답하게 두는 대신 "폼을 채워 달라"고 하는 것과 같아요. GPT·Claude 같은 모델에서 정해진 구조의 데이터를 뽑아낼 수 있게 해주죠. 데이터를 파싱하느라 헤매지 않아도 되고, 검증까지 자동으로 이뤄져요.

기본 아이디어는 간단해요. 파이썬 클래스로 원하는 구조를 정의하고, 그 클래스를 response_model로 넘기면 Instructor가 LLM이 그 구조대로 데이터를 반환하게 해줘요. Pydantic 기반이라 데이터 검증도 함께 받아요.

import instructor
from pydantic import BaseModel

class Person(BaseModel):
    name: str
    age: int
    city: str

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

person = client.create(
    response_model=Person,
    messages=[
        {"role": "user", "content": "Extract: John is 30 years old and lives in New York."}
    ],
)

print(f"Name: {person.name}")  # Name: John
print(f"Age: {person.age}")    # Age: 30
print(f"City: {person.city}")  # City: New York

출처: https://python.useinstructor.com/start-here/

핵심 개념

1. 응답 모델(Response Model)

응답 모델은 LLM이 반환하길 원하는 구조를 정의해요. Pydantic을 써서 만들고, 필드 설명(description)을 달면 LLM이 무엇을 추출해야 하는지 더 잘 이해해요.

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")

2. 클라이언트 설정

from_provider 함수로 LLM provider를 연결해요. provider별 설정을 자동으로 처리해 주니까 편리해요.

# OpenAI
client = instructor.from_provider("openai/gpt-4o-mini")
# Anthropic
client = instructor.from_provider("anthropic/claude-3-5-haiku-latest")

instructor.from_provider는 최신 추천 방식이고, 기존에 널리 쓰이던 instructor.from_openai(client) / instructor.patch(client) 방식도 여전히 동작해요. provider와 모델을 문자열로 한 번에 지정할 수 있다는 점이 달라요.

Instructor가 해결하는 문제

LLM에서 구조화된 데이터를 얻는 일은 여러모로 까다로워요. 응답마다 형식이 다를 수 있고, JSON이나 특정 구조를 요구하면 오류가 생기기 쉬우며, 응답이 원하는 것과 맞는지 검증하기도 번거로워요. Instructor는 파이썬 클래스로 원하는 데이터를 정확히 정의하고, LLM이 그 구조로 반환하도록 강제하며, 출력을 검증하고 문제를 자동으로 고쳐줘요.

지원 기능

추가로 재시도(retry), 검증(validation), 비동기(async), 핸드폰 패치(patch) 같은 개념들이 이 라이브러리의 확장 포인트예요. 각각의 상세 내용은 이 허브 아래의 다른 문서에서 다뤄요.

더 알아보기