samples/instructor_1 — awesome-ai-stack

예제

instructor — LLM에서 구조화 출력

실제로 실행 가능한 미니 프로젝트입니다. 받아서 Docker로 실행해 보세요.

GitHub에서 samples/instructor_1 보기 ↗

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만 커밋됩니다.

Docker로 실행

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로 실행 (DooD를 쓰는 devcontainer에서)

호스트 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'}

.env.sample

# 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=

app.py

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

Dockerfile

# 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"]