AI Engineering Academy · Pelajaran

Instructor: Ekstraksi Bertipe dengan Pydantic

Gunakan pustaka instructor untuk memodifikasi klien OpenAI agar secara otomatis mencoba ulang dan memvalidasi respons terhadap skema Pydantic sampai ekstraksi berhasil.

Instructor: Ekstraksi Bertipe dengan Pydantic adalah pelajaran AI Engineering Academy gratis di CoddyKit. Ini adalah pelajaran 1 dari 4. Kamu bisa membaca pelajaran lengkapnya di bawah secara gratis — lalu praktikkan langsung di browser dengan editor kode bawaan dan tutor AI 24/7. Ini adalah bagian dari jalur belajar AI Engineering Academy, dan progresmu tersinkronisasi di web dan aplikasi CoddyKit. Kursus AI Engineering Academy mencakup 4 pelajaran total.

Apa Itu Pustaka Instructor?

Pustaka instructor adalah pembungkus tipis di sekitar klien OpenAI yang membuat ekstraksi terstruktur lebih andal. Alih-alih berharap model mengembalikan JSON yang valid, instructor menerapkan skema Pydantic Anda dan otomatis mencoba lagi jika validasi gagal. Pustaka ini menghilangkan kebutuhan untuk menulis sendiri penguraian khusus dan logika percobaan ulang.

Memasang Instructor

Pasang instructor dengan satu perintah pip. Pustaka ini memerlukan pydantic v2 dan SDK openai. Setelah terpasang, tambal klien OpenAI dengan instructor.patch() untuk mendapatkan klien yang ditingkatkan dan mendukung parameter response_model pada setiap pemanggilan.

pip install instructor openai pydantic

Menambal Klien OpenAI

Instructor bekerja dengan menambal klien OpenAI standar. Pemanggilan instructor.from_openai(client) mengembalikan klien baru yang setiap pemanggilan chat.completions.create-nya menerima argumen kata kunci response_model. Pemanggilan API yang mendasarinya tetap sama—instructor hanya menambahkan penerapan skema di atasnya.

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI())

Mendefinisikan Skema Pydantic Anda

Definisikan bentuk data yang ingin Anda terima dari model sebagai Pydantic BaseModel. Nama bidang, tipe, dan docstring otomatis diubah menjadi JSON Schema yang dikirimkan ke model. Gunakan nama bidang yang jelas dan deskriptif agar model memahami data yang harus diisi. Tambahkan validator untuk aturan bisnis.

from pydantic import BaseModel, Field
from typing import Optional

class PersonExtract(BaseModel):
    name: str = Field(description='Full name of the person')
    age: Optional[int] = Field(None, description='Age in years if mentioned')
    email: Optional[str] = Field(None, description='Email address if present')
    company: Optional[str] = Field(None, description='Company or employer')

Melakukan Pemanggilan Ekstraksi

Berikan kelas model Pydantic Anda sebagai response_model kepada klien yang telah ditambal. Instructor membuat pemanggilan alat di balik layar, model mengisi bidang-bidang tersebut, dan instructor melakukan deserialisasi hasilnya menjadi objek Python bertipe. Anda mendapatkan pelengkapan otomatis IDE dan keamanan tipe penuh pada data yang dikembalikan.

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=PersonExtract,
    messages=[
        {'role': 'user', 'content': 'Alice Smith, 34, works at Acme Corp. Email: alice@acme.com'}
    ]
)
print(result.name)   # Alice Smith
print(result.email)  # alice@acme.com

Percobaan Ulang Otomatis Saat Validasi Gagal

Jika model mengembalikan data yang gagal divalidasi oleh Pydantic, instructor otomatis mengirimkan kesalahan validasi tersebut kembali ke model dan memintanya memperbaiki respons. Anda dapat mengonfigurasi jumlah maksimum percobaan ulang dengan parameter max_retries. Putaran perbaikan mandiri ini menghilangkan sebagian besar kegagalan ekstraksi sesekali tanpa kode tambahan.

import instructor
from openai import OpenAI
from pydantic import BaseModel, field_validator

client = instructor.from_openai(OpenAI())

class Product(BaseModel):
    name: str
    price_usd: float

    @field_validator('price_usd')
    @classmethod
    def must_be_positive(cls, v):
        if v <= 0:
            raise ValueError('Price must be positive')
        return v

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=Product,
    max_retries=3,
    messages=[{'role': 'user', 'content': 'Widget costs $12.99'}]
)

Model Bersarang untuk Struktur Kompleks

Instructor menangani model Pydantic bersarang dengan lancar. Anda dapat mendefinisikan skema yang sangat bersarang dengan daftar, objek turunan opsional, dan gabungan terdiskriminasi. Model menerima JSON Schema lengkap dan harus mengisi semua bidang wajib, sehingga pendekatan ini ideal untuk mengekstrak objek terstruktur seperti faktur atau resume dengan beberapa bagian.

from pydantic import BaseModel
from typing import List

class LineItem(BaseModel):
    description: str
    quantity: int
    unit_price: float

class Invoice(BaseModel):
    vendor: str
    invoice_number: str
    total_amount: float
    line_items: List[LineItem]

result = client.chat.completions.create(
    model='gpt-4o',
    response_model=Invoice,
    messages=[{'role': 'user', 'content': invoice_text}]
)

Mengalirkan Ekstraksi Parsial

Untuk tugas ekstraksi berukuran besar, instructor mendukung pengaliran parsial melalui instructor.Partial[YourModel]. Saat model menghasilkan token, Anda menerima instans model yang terisi sebagian secara waktu nyata. Hal ini berguna untuk menampilkan kemajuan di UI atau memproses bidang segera setelah diterima, alih-alih menunggu respons lengkap.

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI())

for partial in client.chat.completions.create_partial(
    model='gpt-4o-mini',
    response_model=PersonExtract,
    messages=[{'role': 'user', 'content': long_text}]
):
    print(partial.name, partial.email)

Mengekstrak Daftar Objek

Saat Anda perlu mengekstrak beberapa entitas dari satu dokumen, bungkus model Anda dalam List[YourModel]. Instructor menangani skema larik JSON dan melakukan deserialisasi setiap elemen menjadi objek Python bertipe. Pola ini cocok untuk mengekstrak semua orang yang disebutkan dalam sebuah artikel, semua transaksi dalam laporan, atau semua tanggal dalam kontrak.

from pydantic import BaseModel
from typing import List

class Mention(BaseModel):
    entity: str
    entity_type: str  # PERSON, ORG, DATE, LOCATION
    context: str

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=List[Mention],
    messages=[{'role': 'user', 'content': article_text}]
)
for mention in result:
    print(f'{mention.entity} ({mention.entity_type})')

Memilih Model yang Tepat untuk Ekstraksi

Tidak semua ekstraksi memerlukan GPT-4o. Untuk skema datar sederhana dengan kurang dari 10 bidang, gpt-4o-mini menghasilkan hasil yang hampir sama dengan biaya sepersepuluhnya. Gunakan GPT-4o untuk skema bersarang yang kompleks, dokumen panjang, atau kasus yang mengutamakan perolehan kembali. Selalu lakukan pembandingan pada sampel data nyata Anda sebelum memilih model untuk produksi.

# Cost comparison for 1000 extractions
# GPT-4o-mini: ~$0.002 per call = $2.00 total
# GPT-4o: ~$0.015 per call = $15.00 total
# Test both on 50 samples and compare F1 score
# before committing to the expensive model

Mencatat dan Menelusuri Kesalahan Ekstraksi

Instructor menyediakan sistem hooks untuk observabilitas. Daftarkan callback on_completion untuk mencatat respons API mentah, penggunaan token, dan jumlah percobaan ulang untuk setiap ekstraksi. Hal ini membantu Anda mengidentifikasi jenis dokumen yang paling sering menyebabkan kegagalan dan menyesuaikan skema atau perintah Anda.

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI())

@client.on('completion:response')
def log_usage(response):
    usage = response.usage
    print(f'Tokens: {usage.prompt_tokens}+{usage.completion_tokens}')

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=PersonExtract,
    messages=[{'role': 'user', 'content': text}]
)

Pemeriksaan Singkat

Uji pemahaman Anda tentang pustaka instructor untuk ekstraksi bertipe.

Rangkuman Pelajaran

Dalam pelajaran ini, Anda mempelajari bahwa instructor menambal klien OpenAI agar menerima parameter response_model yang menerapkan skema Pydantic, percobaan ulang otomatis saat validasi gagal membuat ekstraksi andal tanpa penanganan kesalahan manual, dan model bersarang serta ekstraksi daftar memungkinkan Anda mengurai dokumen kompleks dengan banyak entitas menjadi objek Python yang sepenuhnya bertipe. Selanjutnya, kita akan menangani data parsial dan data yang hilang dalam skema hasil ekstraksi.

Pertanyaan yang Sering Diajukan

Apakah pelajaran “Instructor: Ekstraksi Bertipe dengan Pydantic” gratis?

Ya — teks lengkap “Instructor: Ekstraksi Bertipe dengan Pydantic” gratis dibaca di sini di web. Untuk praktiknya secara interaktif (editor kode bawaan dan tutor AI 24/7) dan buka sisa kursus AI Engineering Academy, upgrade ke CoddyKit PRO. Kursus AI Engineering Academy mencakup 4 pelajaran total.

Apa yang akan aku pelajari di “Instructor: Ekstraksi Bertipe dengan Pydantic”?

Gunakan pustaka instructor untuk memodifikasi klien OpenAI agar secara otomatis mencoba ulang dan memvalidasi respons terhadap skema Pydantic sampai ekstraksi berhasil. Kamu berlatih AI Engineering Academy dengan kode praktik yang langsung kamu jalankan di browser, dan tutor AI 24/7 menjawab pertanyaanmu saat kamu mengerjakan pelajaran ini.

Apakah aku perlu pengalaman untuk memulai AI Engineering Academy?

Tidak diperlukan pengalaman sebelumnya. AI Engineering Academy di CoddyKit dirancang untuk pemula hingga pelajar tingkat lanjut, jadi kamu bisa memulai di sini atau dari awal dan belajar sesuai kecepatan kamu sendiri. Ini adalah pelajaran 1 dari 4.

Berapa lama pelajaran “Instructor: Ekstraksi Bertipe dengan Pydantic” memakan waktu?

Sebagian besar pelajaran CoddyKit memakan waktu sekitar 5–10 menit. Setiap pelajaran ringkas dan interaktif, jadi kamu membuat kemajuan stabil dan melanjutkan dari tempat kamu tinggalkan di web dan aplikasi.

Bisakah aku menulis dan menjalankan kode dalam pelajaran AI Engineering Academy ini?

Ya. Setiap pelajaran AI Engineering Academy menyertakan editor kode bawaan, jadi kamu menulis dan menjalankan kode nyata langsung di browser dan mendapatkan umpan balik AI instan — tidak diperlukan penyiapan lokal.

Semua pelajaran dalam kursus ini

Instructor: Ekstraksi Bertipe dengan Pydantic
Menangani Data Parsial dan Hilang
Pemrosesan Kelompok dengan Asinkron dan Antrean
Evolusi Skema dan Kompatibilitas Mundur

← Kembali ke AI Engineering Academy