Pydantic AI 教學:用型別安全的方式打造 LLM Agent,從第一支程式到上線

Pendahuluan: Mengapa Model Mengembalikan Sesuatu yang Berbeda Setiap Saat

Jika Anda pernah menggunakan API LLM, Anda mungkin sudah tidak asing dengan situasi ini: Anda meminta model untuk "mengembalikan sebuah JSON dengan nama dan skor", dan semuanya berjalan lancar selama sembilan kali pertama, tetapi pada kali kesepuluh, model menambahkan kalimat "Baik, berikut adalah hasilnya:" di awal JSON, sehingga json.loads() Anda gagal. Kemudian, Anda mulai menulis berbagai ekspresi reguler untuk membersihkan string dan menulis berbagai kondisi untuk memeriksa apakah kolom ada atau tidak - dan akhirnya, tujuh puluh persen kode "Aplikasi AI" Anda digunakan untuk melawan ketidakstabilan output model.

Saya sendiri pernah memelihara sebuah layanan klasifikasi internal, dan hanya dengan menangani model yang terkadang menghilangkan satu kolom, saya harus menambahkan tiga hari kerja. Setelah beralih ke Pydantic AI, sebagian besar kode pertahanan saya dihapus, karena kerangka kerja secara langsung menangani validasi. Artikel ini akan menjelaskan cara menggunakannya.

Apa itu Pydantic AI

Pydantic AI adalah kerangka kerja agen Python yang dikembangkan oleh tim Pydantic. Nama Pydantic mungkin sudah Anda kenal dari tempat lain - SDK resmi OpenAI, Anthropic, Google, serta LangChain dan LlamaIndex, banyak menggunakan Pydantic untuk validasi data. Dengan demikian, Pydantic adalah orang yang paling berhak untuk melakukan validasi.

Filosofi desain Pydantic AI sangat mirip dengan FastAPI: menggunakan tipe data asli Python untuk mendefinisikan perilaku dengan jelas, dan sisanya didelegasikan kepada kerangka kerja. Konsep intinya hanya beberapa - Agen, Alat, Ketergantungan, dan Keluaran Terstruktur. Anda tidak perlu menghafal berbagai kelas abstrak yang diciptakan oleh Pydantic, karena penulisan kode tetap menggunakan Python biasa, tetapi IDE Anda akan memberikan otomatisasi penyelesaian, dan pemeriksa tipe seperti Pyright atau mypy dapat menangkap kesalahan sebelum Anda menjalankan program.

Pydantic AI adalah model-agnostik, artinya tidak terikat dengan vendor model tertentu. OpenAI, Anthropic, Google, Groq, Coherence, Mistral, Ollama, dan lebih dari sepuluh vendor lainnya didukung, dan untuk beralih antar model, Anda hanya perlu mengubah satu string. Jika Anda ingin memahami perbedaan antara agen dan panggilan API biasa, Anda dapat membaca apa itu agen AI.

Apa yang Dapat Dilakukan dengan Pydantic AI

Dengan bahasa sederhana, Pydantic AI cocok untuk setiap skenario di mana "model perlu mengembalikan hasil yang dapat diandalkan":

• Pengambilan Terstruktur: Anda melemparkan sebuah surat keluhan ke dalam model dan meminta untuk mengeluarkan emosi, kategori, dan tingkat urgensi dalam tiga kolom, dengan menjamin tipe data yang benar.
• Klasifikasi dan Pelabelan: Anda memiliki banyak dokumen yang perlu diberi label, dan output dibatasi pada enum yang Anda definisikan, sehingga model tidak dapat memberikan jawaban yang salah.
• Agen Alat: Anda memungkinkan model untuk memanggil fungsi Anda - mencari database, memanggil API cuaca, atau melakukan perhitungan matematika, dan kerangka kerja akan menangani konversi tipe fungsi menjadi deskripsi alat yang dapat dipahami oleh model.
• RAG Pertanyaan-Jawaban: Dengan menggabungkan pencarian vektor, Anda dapat membuat sistem pertanyaan-jawaban yang memiliki dasar, dan bagian ini dapat Anda pelajari lebih lanjut melalui panduan implementasi RAG.

Dibandingkan dengan LangChain yang merupakan kerangka kerja besar yang mencakup semua hal, Pydantic AI secara sengaja dibuat sangat ramping. Jika Anda hanya perlu membuat output model lebih dapat diandalkan dan tidak ingin memikul seluruh ekosistem hanya untuk satu fungsi kecil, maka kurva pembelajaran Pydantic AI akan lebih ramah.

Cara Menggunakan Pydantic AI: Pertama Kali

1. Instalasi

bash
pip install pydantic-ai

Disarankan untuk membuka lingkungan virtual. Versi Python yang digunakan sebaiknya 3.9 atau lebih tinggi.

2. Pengaturan Kunci API

Sebagai contoh, untuk Anthropic, Anda dapat mengatur variabel lingkungan:

bash
export ANTHROPIC_API_KEY=kunci_anda

Jika Anda menggunakan OpenAI, maka Anda perlu mengatur OPENAI_API_KEY, dan seterusnya.

3. Menulis Agen Pertama

python
from pydantic_ai import Agent

agen = Agent('anthropic:claude-sonnet-4-6')
hasil = agen.run_sync('Jelaskan apa itu basis data vektor dalam satu kalimat')
print(hasil.output)

Parameter pertama adalah nama model, dengan format vendor:model. Untuk beralih ke OpenAI, Anda hanya perlu mengubahnya menjadi 'openai:gpt-4o', dan kode lainnya tidak perlu diubah - ini adalah kelebihan model-agnostik.

4. Membuat Output Terstruktur

Ini adalah inti dari Pydantic AI. Anda perlu mendefinisikan sebuah model Pydantic sebagai format output:

python
from pydantic import BaseModel
from pydantic_ai import Agent

class Review(BaseModel):
sentimen: str # positif / negatif / netral
skor: int # 1 sampai 5
ringkasan: str

agen = Agent('anthropic:claude-sonnet-4-6', output_type=Review)
hasil = agen.run_sync('Toko ini memiliki makanan yang enak, tapi saya menunggu hampir satu jam, agak berlebihan')
print(hasil.output.skor) # Anda dapat langsung mengambil nilai integer
print(hasil.output.sentimen) # Anda dapat langsung mengambil string

Jika output model tidak sesuai dengan tipe yang Anda definisikan, kerangka kerja akan secara otomatis meminta model untuk mencoba lagi. Ketika Anda mengakses hasil.output, itu sudah merupakan objek Python yang divalidasi, dan IDE Anda juga akan membantu Anda dengan otomatisasi penyelesaian untuk kolom-kolomnya.

5. Memberikan Alat kepada Agen

python
from pydantic_ai import Agent

agen = Agent('anthropic:claude-sonnet-4-6')

@agen.tool_plain
def dapatkan_cuaca(kota: str) -> str:
"""Cari cuaca kota yang ditentukan"""
return f'{kota} saat ini 28 derajat, cerah'

hasil = agen.run_sync('Cuaca seperti apa di Taipei sekarang?')
print(hasil.output)

String dokumen tersebut tidak hanya untuk dibaca - itu akan menjadi deskripsi alat yang dilihat oleh model. Tipe data fungsi (kota: str) juga akan dikonversi menjadi spesifikasi parameter yang dipahami oleh model, dan parameter tersebut juga akan divalidasi oleh Pydantic.

Tips Lanjutan

Injeksi Ketergantungan adalah fitur yang paling kurang dinilai dari Pydantic AI. Anda dapat menggunakan RunContext untuk mengirimkan koneksi database, identitas pengguna, klien API, dan lain-lain ke dalam agen dan alat dengan keamanan tipe:

python
from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class Ketergantungan:
id_pengguna: int
db: object # Koneksi database Anda

agen = Agent('anthropic:claude-sonnet-4-6', ketergantungan_type=Ketergantungan)

@agen.tool
def dapatkan_pesanan(ctx: RunContext[Ketergantungan]) -> str:
return f'Cari pesanan pengguna {ctx.ketergantungan.id_pengguna}'

Saat menulis tes, Anda dapat mengganti db dengan objek palsu, sehingga tidak perlu mengganggu database asli, yang sangat penting untuk penulisan tes unit.

Penggunaan Streaming: Untuk membuat efek mengetik secara real-time, gunakan agen.run_stream(), yang akan memvalidasi output terstruktur secara bertahap, sehingga pengalaman pengguna menjadi lebih baik.

Pengamatan: Pydantic AI terintegrasi dengan sangat baik dengan Logfire dari tim yang sama. Setelah terhubung, setiap panggilan model, setiap pemanggilan alat, berapa token yang digunakan, dan berapa lama waktu yang dibutuhkan, semua dapat dilihat. Aplikasi LLM paling sulit di-debug adalah "mengapa model memberikan jawaban seperti itu", dan dengan Pydantic AI, Anda tidak perlu menebak-nebak. Untuk merencanakan agen dengan lebih lengkap, Anda dapat membaca panduan pembangunan agen bersamaan dengan ini.

Kesalahan Umum dan Perhatian

• Menganggap menambahkan output_type sudah membuatnya 100% aman: Kerangka kerja akan meminta model untuk mencoba lagi jika validasi gagal, tetapi ada batasan untuk percobaan tersebut. Jika terus gagal, kerangka kerja akan melempar pengecualian, dan Anda masih perlu menangani pengecualian tersebut dengan try/except. Validasi tipe mengurangi "data kotor yang masuk ke dalam sistem", bukan "model tidak pernah salah".
• Menulis docstring alat dengan sembarangan: Model sepenuhnya mengandalkan docstring untuk menentukan kapan harus memanggil alat. Jika docstring tidak jelas, model mungkin akan memanggil alat secara salah atau tidak memanggilnya sama sekali. Tulislah docstring seperti Anda menulis panduan untuk model.
• Meletakkan terlalu banyak logika dalam alat tanpa menangani pengecualian: Jika kode dalam alat mengalami kesalahan, pesan kesalahan akan dikembalikan ke model, yang mungkin akan menghabiskan banyak token karena kesalahan tersebut. Pastikan Anda menangani pengecualian dengan baik.
• Mengabaikan biaya: Output terstruktur yang gagal dan pemanggilan alat berulang dapat menghabiskan token dengan cepat. Pastikan Anda terhubung dengan pengamatan sebelum meluncurkan, untuk melihat biaya yang sebenarnya.
• Menggunakan Pydantic AI seperti kerangka kerja besar: Pydantic AI secara sengaja dibuat ramping. Jika Anda membutuhkan pengaturan langkah yang kompleks atau koneksi yang sudah jadi, mungkin LlamaIndex atau solusi lain lebih sesuai, jangan memaksakan Pydantic AI.

Evaluasi dari TheAI Akademi

Secara jujur, ada banyak kerangka kerja agen di pasar, tetapi Pydantic AI menyelesaikan masalah yang sangat spesifik dan umum dihadapi oleh setiap pengembang LLM: ketidakandalan output. Pydantic AI tidak berusaha menjadi "kerangka kerja terkuat di alam semesta", tetapi hanya memindahkan "keamanan tipe" yang sudah menjadi perhatian di lingkungan Python ke dalam pengembangan AI. Bagi mereka yang sudah terbiasa dengan cara penulisan FastAPI atau Pydantic, hampir tidak ada biaya pembelajaran.

Pydantic AI tidak akan membuat model Anda lebih pintar, tetapi akan membuat kode Anda lebih dapat diandalkan - dan itulah yang akan menyelamatkan Anda setelah meluncurkan.

Jika Anda hanya ingin membuat demo atau bereksperimen, mungkin Anda tidak akan merasakan manfaatnya secara dalam; tetapi begitu aplikasi Anda benar-benar diluncurkan, digunakan oleh orang, dan perlu dipelihara dalam jangka panjang, nilai keamanan tipe dan pengamatan akan menjadi semakin jelas seiring waktu.