BAML vs Instruktur: Output LLM yang Terstruktur

Keluaran LLM yang aman secara tipis dengan BAML dan Instructor

Konten Halaman

Ketika bekerja dengan Large Language Models dalam produksi, mendapatkan output yang terstruktur dan aman jenisnya sangat penting. Dua kerangka kerja populer - BAML dan Instructor - mengambil pendekatan yang berbeda untuk menyelesaikan masalah ini.

Perbandingan ini membantu Anda memilih alat yang tepat untuk aplikasi Python LLM Anda.

circular-flow

Memahami Tantangan Output Terstruktur

LLM secara alami menghasilkan teks yang tidak terstruktur, tetapi aplikasi modern membutuhkan data yang dapat diprediksi dan dapat diparse. Baik Anda sedang membangun chatbot, pipeline ekstraksi data, atau agen AI, Anda membutuhkan objek JSON, jenis data yang divalidasi, dan penanganan kesalahan—bukan respons bebas.

Kedua BAML dan Instructor menangani tantangan ini tetapi dengan filosofi yang berbeda secara mendasar: BAML menggunakan pendekatan berbasis kontrak dengan pembuatan kode, sedangkan Instructor memanfaatkan sistem jenis Python dengan validasi runtime. Jika Anda tertarik dengan konteks yang lebih luas tentang pendekatan output terstruktur di berbagai penyedia LLM, memahami kerangka kerja ini menjadi semakin berharga.

BAML: Bahasa Domain-Spesifik untuk LLM

BAML (BoundaryML’s language) memperkenalkan bahasa DSL khusus untuk mendefinisikan interaksi LLM. Anda menulis file .baml yang mendeklarasikan prompt, jenis, dan fungsi Anda, lalu BAML menghasilkan kode klien aman jenis untuk beberapa bahasa termasuk Python.

Fitur Utama BAML

Keamanan Jenis di Seluruh Bahasa: BAML menghasilkan klien untuk Python, TypeScript, dan Ruby dari definisi .baml yang sama, memastikan konsistensi di seluruh tumpukan Anda.

Kontrol Versi untuk Prompt: Prompt Anda berada di file .baml, membuatnya mudah untuk dilacak, direview, dan diuji secara independen dari kode aplikasi.

Rangkaian Uji Bawaan: BAML menyertakan alat uji untuk memvalidasi perilaku prompt sebelum diterapkan, menangkap masalah sejak awal pengembangan.

Antarmuka Playground: Playground BAML memungkinkan Anda mengiterasi prompt secara visual dengan umpan balik segera, mempercepat siklus pengembangan.

Implementasi Contoh BAML

# Pertama, definisikan skema Anda dalam file .baml:
# persona.baml

class Person {
  name string
  age int
  occupation string
  skills string[]
}

function ExtractPerson(text: string) -> Person {
  client GPT4
  prompt #"
    Ekstrak informasi orang dari: {{ text }}
    Kembalikan data terstruktur.
  "#
}

Klien Python yang dihasilkan menyediakan akses aman jenis:

from baml_client import b
from baml_client.types import Person

# Gunakan klien yang dihasilkan
text = "John Smith, 34, software engineer skilled in Python and Go"
result: Person = b.ExtractPerson(text)

print(f"{result.name} berusia {result.age} tahun")
print(f"Keterampilan: {', '.join(result.skills)}")

Pendekatan BAML bercahaya ketika Anda memiliki beberapa layanan yang mengonsumsi kontrak LLM yang sama atau ketika Anda membutuhkan jaminan kuat tentang bentuk data di batas bahasa.

Instructor: Kerangka Kerja Python-Native Berbasis Pydantic

Instructor mengambil pendekatan Python-first, memperluas model Pydantic dengan kemampuan LLM. Ini terasa alami bagi pengembang Python yang sudah menggunakan Pydantic untuk validasi dan petunjuk jenis.

Fitur Utama Instructor

Nol Boilerplate: Instructor bekerja langsung dengan model Pydantic Anda menggunakan dekorator sederhana. Tidak diperlukan pembuatan kode atau langkah-langkah pembangunan.

Validasi Kaya: Manfaatkan seluruh ekosistem validasi Pydantic—validator kustom, batasan bidang, bidang terhitung, dan struktur kompleks bersarang.

Dukungan Multi-Provider: Bekerja dengan mulus dengan OpenAI, Anthropic, Google, dan Ollama melalui antarmuka yang terpadu.

Dukungan Streaming: Dukungan kelas satu untuk respons streaming dengan pembaruan model Pydantic bertahap.

Logika Ulang: Mekanisme ulang bawaan dengan penurunan eksponensial dan pemulihan kesalahan berbasis validator.

Implementasi Contoh Instructor

from pydantic import BaseModel, Field
from instructor import from_openai
from openai import OpenAI

# Definisikan model Pydantic Anda
class Person(BaseModel):
    name: str = Field(description="Nama lengkap orang")
    age: int = Field(ge=0, le=120, description="Usia dalam tahun")
    occupation: str
    skills: list[str] = Field(description="Daftar keterampilan profesional")

# Perbaiki klien OpenAI
client = from_openai(OpenAI())

# Ekstrak data terstruktur
text = "John Smith, 34, software engineer skilled in Python and Go"
result = client.chat.completions.create(
    model="gpt-4",
    response_model=Person,
    messages=[
        {"role": "user", "content": f"Ekstrak informasi orang: {text}"}
    ]
)

print(f"{result.name} berusia {result.age} tahun")
print(f"Keterampilan: {', '.join(result.skills)}")

Kekuatan Instructor terletak pada kesederhanaannya dan integrasinya dengan ekosistem Python. Jika Anda sudah menggunakan Pydantic, kurva belajarnya minimal. Untuk pengembang baru di Python atau yang membutuhkan referensi cepat untuk pola khusus Python, cheatsheet Python kami menyediakan ingat-ingat sintaks yang membantu bersama dengan kerangka kerja ini.

Perbandingan Rinci: BAML vs Instructor

Pengalaman Pengembangan

BAML memerlukan langkah pembangunan tambahan dan pengaturan alat. Anda menulis file .baml, menjalankan generator, lalu mengimpor kode yang dihasilkan. Ini menciptakan pemisahan jelas antara rekayasa prompt dan logika aplikasi, yang dapat bermanfaat untuk tim yang lebih besar.

Instructor tidak memiliki gesekan pengaturan—instal pip dan Anda siap. Prompt Anda berada di samping kode Anda, membuat iterasi cepat lebih mudah untuk proyek kecil atau prototipe.

Keamanan Jenis dan Validasi

BAML menyediakan pemeriksaan jenis waktu kompilasi dalam kode yang dihasilkan. IDE Anda tahu persis apa bidang yang tersedia sebelum Anda menjalankan apa pun. Konsistensi lintas bahasa dijamin karena file .baml yang sama menghasilkan klien untuk semua bahasa yang didukung.

Instructor menawarkan validasi runtime melalui Pydantic. Meskipun petunjuk jenis Python menyediakan dukungan IDE, kesalahan muncul selama eksekusi. Ini standar untuk Python tetapi berarti jaminan statis kurang dari kode yang dihasilkan BAML.

Bekerja dengan LLM Lokal

Kedua kerangka kerja mendukung model lokal, yang sangat penting untuk privasi, pengendalian biaya, dan pengembangan offline. Ketika menggunakan Ollama atau penyedia LLM lokal lainnya, Anda mempertahankan manfaat output terstruktur yang sama tanpa ketergantungan API eksternal. Untuk analisis lebih dalam tentang membatasi LLM dengan output terstruktur menggunakan Ollama, Qwen3, dan Python atau Go, kerangka kerja ini menyediakan abstraksi siap produksi di atas API tingkat rendah.

BAML terhubung ke Ollama dengan mengatur klien di file .baml Anda:

# Dalam file .baml Anda:
client OllamaLocal {
  provider ollama
  options {
    model "llama2"
    base_url "http://localhost:11434"
  }
}

Instructor bekerja dengan Ollama melalui API yang kompatibel dengan OpenAI:

from openai import OpenAI
from instructor import from_openai

client = from_openai(OpenAI(
    base_url="http://localhost:111434/v1",
    api_key="ollama"  # kunci dummy
))

Catat bahwa ketika bekerja dengan model lokal, Anda harus menyadari potensi masalah output terstruktur dengan Ollama dan model GPT-OSS, karena tidak semua model menangani output terstruktur dengan keandalan yang sama.

Penanganan Kesalahan dan Ulang

BAML menangani ulang di tingkat kerangka kerja dengan strategi yang dapat dikonfigurasi. Kesalahan dalam validasi skema memicu ulang otomatis dengan konteks kesalahan.

Instructor menyediakan logika ulang dekoratif dengan hook untuk perilaku kustom. Anda dapat mendefinisikan validator yang memicu ulang dengan prompt yang dimodifikasi:

from instructor import patch
from tenacity import retry, stop_after_attempt

@retry(stop=stop_after_attempt(3))
def extract_with_retry(text: str) -> Person:
    return client.chat.completions.create(
        model="gpt-4",
        response_model=Person,
        messages=[{"role": "user", "content": text}]
    )

Uji dan Observabilitas

BAML menyertakan kerangka uji di mana Anda dapat menulis kasus uji langsung dalam file .baml, memvalidasi perilaku prompt di berbagai input. Playground menyediakan debugging visual.

Instructor terintegrasi dengan kerangka uji Python standar. Anda dapat menggunakan fixture pytest, perpustakaan mocking, dan bantuan asersi seperti kode Python apa pun.

Pertimbangan Kinerja

Kinerja runtime sebanding—kedua kerangka kerja akhirnya membuat panggilan API LLM yang sama. Overhead untuk validasi dan parsing dapat diabaikan dibandingkan latensi jaringan dan waktu inferensi model.

Kecepatan pengembangan berbeda secara signifikan:

  • Pembuatan kode BAML berarti autocomplete yang lebih baik dan deteksi kesalahan lebih awal tetapi memerlukan langkah pembangunan
  • Pendekatan dekorator Instructor berarti iterasi yang lebih cepat tetapi penemuan kesalahan runtime

Untuk sistem produksi yang memproses jutaan permintaan, kedua kerangka kerja menangani beban dengan sama baiknya. Pilihan Anda bergantung lebih pada preferensi alur kerja pengembangan daripada karakteristik kinerja.

Kapan Memilih BAML

Pilih BAML ketika Anda membutuhkan:

  • Dukungan multi-bahasa: Akses kontrak LLM yang sama dari layanan Python, TypeScript, dan Ruby
  • Pengembangan berbasis kontrak: Pengembangan gaya API di mana antarmuka LLM dirancang sebelum implementasi
  • Kolaborasi tim: Pemisahan alur kerja rekayasa prompt dari pengembangan aplikasi
  • Jaminan jenis kuat: Pemeriksaan waktu kompilasi di seluruh tumpukan Anda
  • Pengembangan prompt visual: Iterasi prompt yang didorong oleh playground

Kapan Memilih Instructor

Pilih Instructor ketika Anda ingin:

  • Proyek Python-only: Tidak perlu konsistensi lintas bahasa
  • Prototipe cepat: Minimum pengaturan untuk membuat output terstruktur berjalan
  • Integrasi Pydantic: Memanfaatkan model dan validator Pydantic yang sudah ada
  • Pengujian sederhana: Tidak ada langkah pembangunan atau kode yang dihasilkan untuk dikelola
  • Ekosistem Python kaya: Menggunakan perpustakaan dan pola khusus Python

Menggabungkan Pendekatan

Beberapa proyek mendapatkan manfaat dari menggunakan kedua kerangka kerja. Misalnya, Anda mungkin menggunakan BAML untuk API berhadapan dengan pelanggan yang membutuhkan klien lintas bahasa, sementara menggunakan Instructor untuk layanan Python internal yang membutuhkan iterasi cepat.

Anda juga dapat beralih antar kerangka kerja seiring proyek Anda berkembang—mulai dengan Instructor untuk validasi cepat, lalu pindah ke BAML ketika Anda membutuhkan dukungan bahasa yang lebih luas atau kontrak yang lebih ketat.

Kasus Penggunaan Nyata

Pipa Ekstraksi Data (BAML)

Sistem pemrosesan dokumen menggunakan BAML untuk mengekstrak data terstruktur dari faktur, kontrak, dan struk. Definisi .baml bertindak sebagai kontrak antara tim ML dan layanan backend, dengan klien TypeScript untuk dashboard web dan klien Python untuk pemrosesan batch.

Bot Dukungan Pelanggan (Instructor)

Bot dukungan menggunakan Instructor untuk mengklasifikasikan tiket, mengekstrak niat pengguna, dan menghasilkan respons. Tim mengiterasi cepat pada prompt menggunakan model Pydantic, dengan validator memastikan nomor telepon, email, dan ID tiket yang diekstrak memenuhi persyaratan format.

Agen AI Multi-Modal (Keduanya)

Sistem agen AI menggunakan BAML untuk kontrak komunikasi antar agen inti, memastikan keamanan jenis di seluruh sistem terdistribusi, sementara agen individu menggunakan Instructor secara internal untuk pemrosesan input pengguna yang fleksibel dan native Python. Pola serupa berlaku ketika membangun server MCP dalam Python, di mana output terstruktur memungkinkan integrasi alat yang andal dengan asisten AI.

Jalur Migrasi dan Integrasi

Jika Anda sudah menggunakan parsing JSON dasar dengan LLM, kedua kerangka kerja menawarkan jalur migrasi yang sederhana:

Dari JSON ke BAML: Konversi skema JSON Anda ke definisi jenis BAML, pindahkan prompt ke file .baml, buat klien, dan ganti parsing manual dengan tipe yang dihasilkan.

Dari JSON ke Instructor: Tambahkan model Pydantic yang cocok dengan struktur JSON Anda, instal instructor, perbaiki klien OpenAI Anda, dan ganti parsing JSON dengan parameter response_model.

Kedua migrasi dapat dilakukan secara bertahap—Anda tidak perlu mengonversi seluruh kodebase sekaligus.

Pandangan Masa Depan dan Komunitas

Kedua kerangka kerja sedang dikembangkan secara aktif dengan komunitas yang kuat:

BAML (BoundaryML) fokus pada ekspansi dukungan bahasa, peningkatan playground, dan peningkatan kemampuan uji. Dukungan komersial menunjukkan stabilitas jangka panjang.

Instructor mempertahankan kehadiran open-source yang kuat dengan pembaruan sering, dokumentasi yang luas, dan adopsi yang berkembang. Proyek ini dirawat dengan baik oleh Jason Liu dan kontributor.

Kesimpulan

BAML dan Instructor mewakili dua pendekatan yang sangat baik tetapi berbeda untuk output LLM terstruktur. Filosofi BAML berbasis kontrak dan multi-bahasa cocok untuk tim yang membangun sistem terdistribusi dengan persyaratan jenis ketat. Pendekatan Instructor berbasis Python-native dan Pydantic cocok untuk pengembangan cepat dan stack Python-sentris.

Tidak ada yang secara universal lebih baik—pilihan Anda bergantung pada ukuran tim, preferensi bahasa, alur kerja pengembangan, dan persyaratan keamanan jenis. Banyak tim akan menemukan bahwa memulai dengan Instructor untuk prototipe, lalu mengadopsi BAML untuk arsitektur multi-layanan produksi, menawarkan yang terbaik dari kedua dunia.

Tautan Berguna

Artikel terkait di situs ini

Referensi Eksternal