Instructor: Mendapatkan Structured Output dari LLM dengan Python

Salah satu tantangan terbesar saat bekerja dengan Large Language Models (LLM) adalah mendapatkan output yang terstruktur dan konsisten. LLM secara default menghasilkan teks bebas, yang sulit di-parse dan diintegrasikan ke dalam aplikasi. Library Instructor hadir untuk menyelesaikan masalah ini dengan memanfaatkan Pydantic untuk validasi dan ekstraksi data terstruktur dari LLM.

Dalam tutorial ini, kita akan mempelajari cara menggunakan Instructor untuk mendapatkan output JSON/Pydantic yang reliable dari berbagai LLM provider seperti OpenAI, Anthropic, dan lainnya.

Apa Itu Instructor?

Instructor adalah library Python yang meng-patch client LLM (seperti OpenAI) agar bisa mengembalikan objek Pydantic yang tervalidasi, bukan sekadar string. Instructor bekerja dengan memanfaatkan function calling atau JSON mode dari LLM, kemudian memvalidasi hasilnya menggunakan Pydantic.

Keunggulan utama Instructor:

• Type-safe: Output dijamin sesuai dengan schema Pydantic yang didefinisikan
• Automatic retry: Jika validasi gagal, Instructor otomatis me-retry dengan feedback error
• Streaming support: Mendukung partial streaming untuk objek yang kompleks
• Multi-provider: Mendukung OpenAI, Anthropic, Google, Mistral, dan lainnya
• Validasi kustom: Bisa menambahkan validator Pydantic untuk business logic

Instalasi

Pertama, install Instructor beserta dependensi yang diperlukan:

pip install instructor openai pydantic

Untuk provider lain, install dependensi tambahan:

# Untuk Anthropic
pip install instructor anthropic

Untuk Google Gemini
pip install instructor google-generativeai

Untuk Mistral
pip install instructor mistralai

Pastikan Anda memiliki API key dari provider yang akan digunakan:

export OPENAIAPIKEY="sk-your-api-key-here"

Penggunaan Dasar dengan OpenAI

Mari mulai dengan contoh sederhana: mengekstrak informasi pengguna dari teks.

import instructor
from openai import OpenAI
from pydantic import BaseModel

Patch client OpenAI dengan Instructor
client = instructor.fromopenai(OpenAI())


Definisikan schema output
class UserInfo(BaseModel):
    name: str
    age: int
    email: str

Ekstrak data terstruktur dari teks
user = client.chat.completions.create(
    model="gpt-4o-mini",
    responsemodel=UserInfo,
    messages=[
        {
            "role": "user",
            "content": "Nama saya Budi Santoso, umur 28 tahun. "
                       "Email saya budi.santoso@email.com"
        }
    ],
)

print(user)
UserInfo(name='Budi Santoso', age=28, email='budi.santoso@email.com')
print(user.name)   # Budi Santoso
print(user.age)    # 28
print(user.email)  # budi.santoso@email.com

Perhatikan bahwa responsemodel=UserInfo adalah parameter kunci yang memberitahu Instructor schema apa yang diharapkan. Hasilnya bukan dictionary atau string, melainkan objek Pydantic yang sudah tervalidasi.

from pydantic import BaseModel, Field
from typing import Optional, List
from enum import Enum

class JobLevel(str, Enum):
    JUNIOR = "junior"
    MID = "mid"
    SENIOR = "senior"
    LEAD = "lead"

class Skill(BaseModel):
    name: str = Field(description="Nama skill atau teknologi")
    yearsexperience: int = Field(
        description="Tahun pengalaman", ge=0, le=50
    )
    proficiency: str = Field(
        description="Tingkat kemahiran: beginner, intermediate, advanced"
    )

class WorkExperience(BaseModel):
    company: str
    role: str
    durationmonths: int = Field(ge=1)

    description: str

class CandidateProfile(BaseModel):
    name: str
    currentrole: str
    level: JobLevel
    totalyearsexperience: int = Field(ge=0)
    skills: List[Skill]
    workhistory: List[WorkExperience]

    education: str
    summary: str = Field(