만든 곳 567 Labs
어떤 LLM에서든 구조화·검증된 출력을 받습니다 — Pydantic 모델을 정의하면 타입이 있는 객체로 돌려줍니다.
문서버전 1.0 · 업데이트
instructor는 LLM을 타입이 있는 함수처럼 만듭니다.
출력을 Pydantic 모델로
기술하면 자유 텍스트 대신 검증된 파이썬 객체를 돌려줍니다.
호출을 감싸 — LiteLLM으로 라우팅하며 — 응답이 스키마에 맞을 때까지 다시 요청하므로, 이후 코드가 타입을 신뢰할 수 있습니다.
flowchart LR schema[Pydantic model] --> inst[instructor] msg[messages] --> inst inst --> llm[LLM via LiteLLM] llm --> obj[typed object]
코드 샘플 탭에는 기본 추출과 검증·재시도 예시가 있습니다 — 선택기에서 골라 비교해 보세요.
LLM 출력이 구조를 기대하는 코드로 이어질 때 — 추출·분류·라우팅 — 깨지기 쉬운 JSON 파싱 대신 검증과 재시도를 원한다면 instructor를 쓰세요.
오픈소스(MIT)라 무료로 셀프호스트하며, LLM 호출 비용만 부담합니다.
출처 ↗ · 기준일 2026-06-27
모델 출력을 자유 텍스트가 아니라 타입이 있는 객체로 받아야 할 때 instructor를 쓰세요.
Pydantic response_model을 넘기면 instructor가 모델을 그 스키마에 맞는 JSON으로
유도하고, 검증한 뒤 인스턴스를 돌려줍니다.
flowchart LR schema[Pydantic model] --> inst[instructor] msg[messages] --> inst inst --> llm[LLM via LiteLLM] llm --> obj[typed object]
import instructor
from pydantic import BaseModel
class User(BaseModel):
name: str
age: int
# from_provider routes through LiteLLM, so any provider works by string.
client = instructor.from_provider("anthropic/claude-opus-4-8")
user = client.chat.completions.create(
response_model=User,
messages=[{"role": "user", "content": "Extract: Alice is 30 years old."}],
)
print(user.name, user.age) # -> Alice 30
출력이 단순한 형태뿐 아니라 규칙까지 만족해야 할 때, 검증기와 max_retries를
함께 쓰세요.
Pydantic 검증기가 실패하면 그 오류가 모델에 다시 전달되고, 통과하거나 한도에 도달할 때까지 재시도합니다.
flowchart LR
call[create] --> llm[LLM]
llm --> val{valid?}
val -->|no| call
val -->|yes| obj[typed object]
import instructor
from pydantic import BaseModel, field_validator
class Answer(BaseModel):
sentiment: str
@field_validator("sentiment")
@classmethod
def known(cls, v: str) -> str:
if v not in {"positive", "negative", "neutral"}:
raise ValueError("must be positive, negative, or neutral")
return v
client = instructor.from_provider("openai/gpt-4o")
answer = client.chat.completions.create(
response_model=Answer,
max_retries=3, # re-ask the model when validation fails
messages=[{"role": "user", "content": "Classify: 'It was fine.'"}],
)
print(answer.sentiment)
실제로 실행 가능한 미니 프로젝트입니다. 받아서 Docker로 실행해 보세요.
2026년 6월 28일
instructor — LLM에서 구조화 출력아주 작은 instructor 스크립트입니다. 자유
텍스트에서 타입이 있는 Person(name·age·occupation)을 추출합니다. Pydantic 모델을
정의하면 파싱할 문자열이 아니라 검증된 객체를 돌려받습니다. from_litellm이 호출을
라우팅하므로 MODEL이 제공자를 결정합니다.
cd samples/instructor_1
cp .env.sample .env
# .env 편집: MODEL과 해당 제공자의 키를 설정
MODEL은 LiteLLM 형식 이름입니다:
| 제공자 | MODEL 예시 |
.env의 키 |
|---|---|---|
| Anthropic Claude | anthropic/claude-opus-4-8 |
ANTHROPIC_API_KEY |
| OpenAI | openai/gpt-4o |
OPENAI_API_KEY |
| Google AI Studio | gemini/gemini-2.5-flash |
GEMINI_API_KEY |
.env는 gitignore 처리되어 있고, .env.sample만 커밋됩니다.
cd samples/instructor_1
docker build -t aas-instructor .
docker run --rm --env-file .env aas-instructor \
"Ada Lovelace, 36, was a mathematician and the first programmer."
호스트 Docker 데몬과 통신하는 dev container(Docker-outside-of-Docker)에서는 위의
포그라운드 docker run이 종종 아무것도 출력하지 않고 exit 0으로 끝납니다. 하지만
실행 자체는 성공한 것입니다. 스크립트는 끝까지 실행되고 출력도 Docker가 모두
캡처하는데, 실시간 attach 스트림만 그 출력을 VM 경계에서 흘려버립니다.
detached로 실행하고 로그를 따라가세요:
cd samples/instructor_1
docker build -t aas-instructor .
docker logs -f "$(docker run -d --env-file .env aas-instructor \
"Ada Lovelace, 36, was a mathematician and the first programmer.")"
cd samples/instructor_1
pip install -r requirements.txt
python app.py "Ada Lovelace, 36, was a mathematician and the first programmer."
python-dotenv가 .env를 자동으로 불러옵니다.
모델과 실행마다 결과가 달라집니다 — LLM은 비결정적입니다. 형태는 Pydantic 모델이 고정하고, 값은 추출됩니다. 아래는
anthropic/claude-opus-4-8로 실행한 한 예입니다.
{'name': 'Ada Lovelace', 'age': 36, 'occupation': 'Mathematician'}
파일
# Copy this file to `.env` and fill in the key for the provider you want.
# cp .env.sample .env
#
# instructor's from_provider routes via LiteLLM, so MODEL picks the provider.
# Pick the model. Examples:
# anthropic/claude-opus-4-8 Anthropic Claude -> needs ANTHROPIC_API_KEY
# openai/gpt-4o OpenAI -> needs OPENAI_API_KEY
# gemini/gemini-2.5-flash Google AI Studio -> needs GEMINI_API_KEY
MODEL=anthropic/claude-opus-4-8
# Set only the key for the provider you chose; leave the rest blank.
ANTHROPIC_API_KEY=
OPENAI_API_KEY=
GEMINI_API_KEY=
# Local secrets — never commit the real .env
.env
# ...but keep the committed template (root .gitignore's `.env.*` would hide it).
!.env.sample
"""instructor: structured, validated output from an LLM.
Extracts a typed `Person` from free text. `from_provider` routes through
LiteLLM, so MODEL in `.env` picks the provider (claude / gpt / gemini) without
touching the code; instructor returns a validated Pydantic object, not text.
Run:
docker build -t aas-instructor .
docker run --rm --env-file .env aas-instructor "Ada Lovelace, 36, was a mathematician."
"""
import os
import sys
import instructor
import litellm
from dotenv import load_dotenv
from pydantic import BaseModel
# Load .env when running locally; in Docker the keys come from --env-file.
load_dotenv()
MODEL = os.environ.get("MODEL", "anthropic/claude-opus-4-8")
class Person(BaseModel):
name: str
age: int
occupation: str
def main() -> None:
text = " ".join(sys.argv[1:]) or "Ada Lovelace, 36, was a mathematician and the first programmer."
# from_litellm keeps dependencies to litellm only (no per-provider SDKs).
client = instructor.from_litellm(litellm.completion)
person = client.chat.completions.create(
model=MODEL,
response_model=Person,
messages=[{"role": "user", "content": f"Extract the person from: {text}"}],
)
print(person.model_dump())
if __name__ == "__main__":
main()
# Minimal image for the instructor sample.
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
# Provide your config at run time (.env is NOT baked into the image):
# docker run --rm --env-file .env aas-instructor "<text to extract from>"
ENTRYPOINT ["python", "app.py"]
instructor>=1.9,<2
litellm>=1.80,<2
python-dotenv>=1.2,<2