Tutorial Lengkap Instructor: Output Terstruktur dari LLM dengan Pydantic

Halo temen-temen, di tutorial ini aku mau ngajak kalian kenalan sama salah satu library Python yang menurutku wajib banget dipelajari kalau kalian sering kerja bareng LLM, namanya Instructor. Kalau kalian pernah frustrasi karena output dari model bahasa itu kadang rapi kadang berantakan, kadang JSON-nya valid kadang malah ada teks nyasar di depan atau belakang, nah Instructor ini jawabannya. Aku sendiri udah lama pakai library ini di beberapa project produksi, dan jujur aja ini ngubah cara aku ngoding sama LLM secara total.

Di artikel ini aku bakal bahas dari nol banget, mulai dari kenapa structured output itu penting, cara instalasi, penggunaan dasar, sampai ke fitur-fitur canggih kayak nested model, retry otomatis, streaming, dan dukungan multi-provider. Aku juga bakal kasih banyak contoh kode Python yang beneran bisa kalian jalanin sendiri. Yuk kita mulai.

Kenapa Structured Output Itu Penting

Sebelum masuk ke Instructor, aku mau cerita dulu masalah yang sering banget kita hadapi waktu kerja sama LLM. Bayangin temen-temen lagi bikin aplikasi yang butuh nge-ekstrak data dari teks. Misalnya kalian punya email pelanggan, terus kalian pengen ambil nama, email, dan tingkat urgensi dari email itu. Cara paling naif adalah kalian minta LLM buat balikin JSON.

Masalahnya, LLM itu kan pada dasarnya generator teks. Dia gak punya jaminan bakal ngasih output yang formatnya konsisten. Kadang dia balikin JSON yang valid, kadang dia tambahin kalimat pembuka kayak "Tentu, ini hasilnya:" sebelum JSON-nya. Kadang malah dia bungkus pakai markdown code block. Kadang tipe datanya salah, misalnya kalian minta angka tapi dia kasih string. Ini bikin pusing banget kalau outputnya mau kita proses lebih lanjut di kode.

Pendekatan lama biasanya kita parsing manual pakai regex, atau kita coba json.loads() terus kita bungkus pakai try-except gede-gedean. Tapi ini rapuh banget. Begitu format outputnya berubah dikit, kode kita langsung error. Belum lagi kita harus validasi manual satu-satu, misalnya mastiin field email itu beneran format email, mastiin umur itu angka positif, dan seterusnya.

Nah, di sinilah Instructor masuk. Idenya simpel tapi brilian, temen-temen. Kita definisiin struktur output yang kita mau pakai Pydantic, terus Instructor yang ngurusin biar LLM ngasih output sesuai struktur itu, sekaligus validasinya. Kalau outputnya gak sesuai, Instructor bakal otomatis minta LLM buat benerin. Jadi kita dapet output yang udah terjamin tipe dan validasinya, langsung bisa dipakai di kode. Gak perlu lagi parsing manual yang bikin sakit kepala.

Buat yang belum tau, Pydantic itu library Python buat data validation berbasis type hints. Kita definisiin class dengan field-field beserta tipenya, terus Pydantic yang mastiin data yang masuk sesuai sama definisi itu. Instructor memanfaatkan Pydantic ini sebagai kontrak antara kode kita dan LLM.

Instalasi

Oke, sekarang kita mulai praktik. Instalasinya gampang banget, cukup satu baris pakai pip.

pip install instructor

Instructor secara otomatis udah bawa dependency yang dibutuhin, termasuk Pydantic. Tapi kalian tetep butuh library provider LLM-nya, misalnya OpenAI atau Anthropic. Jadi biasanya aku install sekalian gini.

pip install instructor openai anthropic

Kalau kalian pakai environment virtual (yang mana aku saranin banget), aktifin dulu venv kalian sebelum install. Ini biar dependency project kalian gak campur aduk sama project lain.

python -m venv venv
source venv/bin/activate  # kalau di Windows: venv\Scripts\activate
pip install instructor openai

Jangan lupa juga siapin API key kalian. Kalau pakai OpenAI, set environment variable OPENAIAPIKEY. Kalau pakai Anthropic, set ANTHROPICAPIKEY. Aku biasanya taruh di file .env terus load pakai library python-dotenv.

# file .env
OPENAIAPIKEY=sk-xxxxxxxxxxxxxxxx

Penggunaan Dasar

Sekarang kita masuk ke bagian yang seru. Aku bakal tunjukin contoh paling dasar dulu biar temen-temen ngerti konsep intinya. Konsep utama Instructor cuma ada dua, yaitu kita patch client LLM kita, terus kita kasih parameter responsemodel yang isinya class Pydantic.

import instructor
from openai import OpenAI
from pydantic import BaseModel

Definisiin struktur output yang kita mau
class Orang(BaseModel):
    nama: str
    umur: int