PydanticAI: Panduan Komprehensif untuk Membina Aplikasi AI Sedia Pengeluaran

PydanticAI ialah rangka kerja Python yang berkuasa direka untuk menyelaraskan pembangunan aplikasi gred pengeluaran menggunakan Generative AI. Ia dibina oleh pasukan yang sama di belakang Pydantic, perpustakaan pengesahan data yang digunakan secara meluas, dan bertujuan untuk membawa reka bentuk inovatif dan ergonomik FastAPI ke bidang pembangunan aplikasi AI. PydanticAI memfokuskan pada keselamatan jenis, modulariti dan penyepaduan lancar dengan alatan Python yang lain.

Konsep Teras

PydanticAI berkisar pada beberapa konsep utama:

ejen

Agen ialah antara muka utama untuk berinteraksi dengan Model Bahasa Besar (LLM). Ejen bertindak sebagai bekas untuk pelbagai komponen, termasuk:

• Gesaan sistem: Arahan untuk LLM, ditakrifkan sebagai rentetan statik atau fungsi dinamik.
• Alat fungsi: Fungsi yang LLM boleh panggil untuk mendapatkan maklumat tambahan atau melakukan tindakan.
• Jenis hasil berstruktur: Jenis data yang mesti dikembalikan oleh LLM pada penghujung larian.
• Jenis pergantungan: Data atau perkhidmatan yang boleh digunakan oleh fungsi gesaan sistem, alatan dan pengesah hasil.
• Model LLM: LLM yang akan digunakan oleh ejen, yang boleh ditetapkan pada penciptaan ejen atau pada masa jalan.

Ejen direka bentuk untuk kebolehgunaan semula dan biasanya digunakan sekali dan digunakan semula sepanjang aplikasi.

Gesaan Sistem

Gesaan sistem ialah arahan yang diberikan kepada LLM oleh pembangun. Mereka boleh menjadi:

• Gesaan sistem statik: Ditakrifkan apabila ejen dicipta, menggunakan parameter system_prompt bagi pembina Ejen.
• Gesaan sistem dinamik: Ditakrifkan oleh fungsi yang dihiasi dengan @agent.system_prompt. Ini boleh mengakses maklumat masa jalan, seperti kebergantungan, melalui objek RunContext.

Ejen tunggal boleh menggunakan kedua-dua gesaan sistem statik dan dinamik, yang dilampirkan mengikut tertib yang ditakrifkan semasa masa jalan.

from pydantic_ai import Agent, RunContext
from datetime import date

agent = Agent(
    'openai:gpt-4o',
    deps_type=str,
    system_prompt="Use the customer's name while replying to them.",
)

@agent.system_prompt
def add_the_users_name(ctx: RunContext[str]) -> str:
    return f"The user's name is {ctx.deps}."

@agent.system_prompt
def add_the_date() -> str:
    return f'The date is {date.today()}.'

result = agent.run_sync('What is the date?', deps='Frank')
print(result.data)
#> Hello Frank, the date today is 2032-01-02.

Alat Fungsi

Alat fungsi membolehkan LLM mengakses maklumat luaran atau melakukan tindakan yang tidak tersedia dalam gesaan sistem itu sendiri. Alat boleh didaftarkan dalam beberapa cara:

• @agent.tool decorator: Untuk alatan yang memerlukan akses kepada konteks ejen melalui RunContext.
• @agent.tool_plain decorator: Untuk alatan yang tidak memerlukan akses kepada konteks ejen.
• argumen kata kunci alat dalam pembina Ejen: Boleh mengambil fungsi biasa atau contoh kelas Alat, memberikan lebih kawalan ke atas definisi alat.

from pydantic_ai import Agent, RunContext
from datetime import date

agent = Agent(
    'openai:gpt-4o',
    deps_type=str,
    system_prompt="Use the customer's name while replying to them.",
)

@agent.system_prompt
def add_the_users_name(ctx: RunContext[str]) -> str:
    return f"The user's name is {ctx.deps}."

@agent.system_prompt
def add_the_date() -> str:
    return f'The date is {date.today()}.'

result = agent.run_sync('What is the date?', deps='Frank')
print(result.data)
#> Hello Frank, the date today is 2032-01-02.

Parameter alat diekstrak daripada tandatangan fungsi dan digunakan untuk membina skema JSON alat. Rentetan doktrin fungsi digunakan untuk menjana perihalan alat dan perihalan parameter dalam skema.

Kebergantungan

Pergantungan menyediakan data dan perkhidmatan kepada gesaan sistem, alatan dan pengesah hasil ejen melalui sistem suntikan pergantungan. Ketergantungan diakses melalui objek RunContext. Mereka boleh menjadi mana-mana jenis Python, tetapi kelas data ialah cara yang mudah untuk mengurus berbilang kebergantungan.

import random
from pydantic_ai import Agent, RunContext

agent = Agent(
    'gemini-1.5-flash',
    deps_type=str,
    system_prompt=(
        "You're a dice game, you should roll the die and see if the number "
        "you get back matches the user's guess. If so, tell them they're a winner. "
        "Use the player's name in the response."
    ),
)

@agent.tool_plain
def roll_die() -> str:
    """Roll a six-sided die and return the result."""
    return str(random.randint(1, 6))

@agent.tool
def get_player_name(ctx: RunContext[str]) -> str:
    """Get the player's name."""
    return ctx.deps

dice_result = agent.run_sync('My guess is 4', deps='Anne')
print(dice_result.data)
#> Congratulations Anne, you guessed correctly! You're a winner!

Keputusan

Hasil ialah nilai akhir yang dikembalikan daripada ejen yang dikendalikan. Ia dibalut dengan RunResult (untuk larian segerak dan tak segerak) atau StreamedRunResult (untuk larian distrim), menyediakan akses kepada data penggunaan dan sejarah mesej. Keputusan boleh berupa teks biasa atau data berstruktur dan disahkan menggunakan Pydantic.

from dataclasses import dataclass
import httpx
from pydantic_ai import Agent, RunContext

@dataclass
class MyDeps:
    api_key: str
    http_client: httpx.AsyncClient

agent = Agent(
    'openai:gpt-4o',
    deps_type=MyDeps,
)

@agent.system_prompt
async def get_system_prompt(ctx: RunContext[MyDeps]) -> str:
    response = await ctx.deps.http_client.get(
        'https://example.com',
        headers={'Authorization': f'Bearer {ctx.deps.api_key}'},
    )
    response.raise_for_status()
    return f'Prompt: {response.text}'

async def main():
    async with httpx.AsyncClient() as client:
        deps = MyDeps('foobar', client)
        result = await agent.run('Tell me a joke.', deps=deps)
        print(result.data)
        #> Did you hear about the toothpaste scandal? They called it Colgate.

Pengesah hasil, ditambah melalui penghias @agent.result_validator, menyediakan cara untuk menambah logik pengesahan selanjutnya, terutamanya apabila pengesahan memerlukan IO dan tidak segerak.

Ciri-ciri Utama

PydanticAI menawarkan beberapa ciri utama yang menjadikannya pilihan yang menarik untuk pembangunan aplikasi AI:

• Model Agnostik: PydanticAI menyokong pelbagai LLM, termasuk OpenAI, Anthropic, Gemini, Ollama, Groq dan Mistral. Ia juga menyediakan antara muka yang mudah untuk melaksanakan sokongan untuk model lain.
• Keselamatan Jenis: Direka bentuk untuk berfungsi dengan lancar dengan penyemak jenis statik seperti mypy dan pyright. Ia membenarkan pemeriksaan jenis kebergantungan dan jenis hasil.
• Reka Bentuk Python-Centric: Memanfaatkan aliran kawalan Python yang biasa dan komposisi ejen untuk membina projek AI, menjadikannya mudah untuk menggunakan amalan Python standard.
• Respons Berstruktur: Menggunakan Pydantic untuk mengesahkan dan menstrukturkan output model, memastikan respons yang konsisten.
• Sistem Suntikan Kebergantungan: Menawarkan sistem suntikan kebergantungan untuk menyediakan data dan perkhidmatan kepada komponen ejen, meningkatkan kebolehujian dan pembangunan berulang.
• Respons Strim: Menyokong penstriman output LLM dengan pengesahan segera, membolehkan hasil yang cepat dan tepat.

Bekerja dengan Ejen

Ejen Larian

Agen boleh dijalankan dalam beberapa cara:

• run_sync(): Untuk pelaksanaan segerak.
• run(): Untuk pelaksanaan tak segerak.
• run_stream(): Untuk respons penstriman.

from pydantic_ai import Agent, RunContext
from datetime import date

agent = Agent(
    'openai:gpt-4o',
    deps_type=str,
    system_prompt="Use the customer's name while replying to them.",
)

@agent.system_prompt
def add_the_users_name(ctx: RunContext[str]) -> str:
    return f"The user's name is {ctx.deps}."

@agent.system_prompt
def add_the_date() -> str:
    return f'The date is {date.today()}.'

result = agent.run_sync('What is the date?', deps='Frank')
print(result.data)
#> Hello Frank, the date today is 2032-01-02.

Perbualan

Larian ejen mungkin mewakili keseluruhan perbualan, tetapi perbualan juga boleh terdiri daripada berbilang larian, terutamanya apabila mengekalkan keadaan antara interaksi. Anda boleh menghantar mesej daripada larian sebelumnya menggunakan argumen message_history untuk meneruskan perbualan.

import random
from pydantic_ai import Agent, RunContext

agent = Agent(
    'gemini-1.5-flash',
    deps_type=str,
    system_prompt=(
        "You're a dice game, you should roll the die and see if the number "
        "you get back matches the user's guess. If so, tell them they're a winner. "
        "Use the player's name in the response."
    ),
)

@agent.tool_plain
def roll_die() -> str:
    """Roll a six-sided die and return the result."""
    return str(random.randint(1, 6))

@agent.tool
def get_player_name(ctx: RunContext[str]) -> str:
    """Get the player's name."""
    return ctx.deps

dice_result = agent.run_sync('My guess is 4', deps='Anne')
print(dice_result.data)
#> Congratulations Anne, you guessed correctly! You're a winner!

Had Penggunaan

PydanticAI menyediakan struktur tetapan.UsageLimits untuk mengehadkan bilangan token dan permintaan. Anda boleh menggunakan tetapan ini melalui argumen usage_limits pada fungsi run.

from dataclasses import dataclass
import httpx
from pydantic_ai import Agent, RunContext

@dataclass
class MyDeps:
    api_key: str
    http_client: httpx.AsyncClient

agent = Agent(
    'openai:gpt-4o',
    deps_type=MyDeps,
)

@agent.system_prompt
async def get_system_prompt(ctx: RunContext[MyDeps]) -> str:
    response = await ctx.deps.http_client.get(
        'https://example.com',
        headers={'Authorization': f'Bearer {ctx.deps.api_key}'},
    )
    response.raise_for_status()
    return f'Prompt: {response.text}'

async def main():
    async with httpx.AsyncClient() as client:
        deps = MyDeps('foobar', client)
        result = await agent.run('Tell me a joke.', deps=deps)
        print(result.data)
        #> Did you hear about the toothpaste scandal? They called it Colgate.

Tetapan Model

Struktur tetapan.ModelSettings membolehkan anda memperhalusi gelagat model melalui parameter seperti suhu, token_maks dan tamat masa. Anda boleh menggunakan ini melalui hujah model_settings dalam fungsi run.

from pydantic import BaseModel
from pydantic_ai import Agent

class CityLocation(BaseModel):
    city: str
    country: str

agent = Agent('gemini-1.5-flash', result_type=CityLocation)
result = agent.run_sync('Where were the olympics held in 2012?')
print(result.data)
#> city='London' country='United Kingdom'

Alat Fungsi secara Terperinci

Pendaftaran Alat

Alat boleh didaftarkan menggunakan penghias @agent.tool (untuk alatan yang memerlukan konteks), penghias @agent.tool_plain (untuk alatan tanpa konteks) atau melalui argumen alatan dalam pembina Ejen.

from pydantic_ai import Agent

agent = Agent('openai:gpt-4o')

# Synchronous run
result_sync = agent.run_sync('What is the capital of Italy?')
print(result_sync.data)
#> Rome

# Asynchronous run
async def main():
    result = await agent.run('What is the capital of France?')
    print(result.data)
    #> Paris

    async with agent.run_stream('What is the capital of the UK?') as response:
        print(await response.get_data())
        #> London

Skema Alat

Perihalan parameter diekstrak daripada docstrings dan ditambahkan pada skema JSON alat. Jika alat mempunyai parameter tunggal yang boleh diwakili sebagai objek dalam skema JSON, skema dipermudahkan menjadi objek itu sahaja.

from pydantic_ai import Agent

agent = Agent('openai:gpt-4o', system_prompt='Be a helpful assistant.')
result1 = agent.run_sync('Tell me a joke.')
print(result1.data)
#> Did you hear about the toothpaste scandal? They called it Colgate.

result2 = agent.run_sync('Explain?', message_history=result1.new_messages())
print(result2.data)
#> This is an excellent joke invent by Samuel Colvin, it needs no explanation.

Alat Dinamik

Alat boleh disesuaikan dengan fungsi penyediaan, yang dipanggil pada setiap langkah untuk mengubah suai definisi alat atau meninggalkan alat daripada langkah itu.

from pydantic_ai import Agent
from pydantic_ai.settings import UsageLimits
from pydantic_ai.exceptions import UsageLimitExceeded

agent = Agent('claude-3-5-sonnet-latest')
try:
    result_sync = agent.run_sync(
        'What is the capital of Italy? Answer with a paragraph.',
        usage_limits=UsageLimits(response_tokens_limit=10),
    )
except UsageLimitExceeded as e:
    print(e)
    #> Exceeded the response_tokens_limit of 10 (response_tokens=32)

Mesej dan Sejarah Sembang

Mengakses Mesej

Mesej yang ditukar semasa ejen dijalankan boleh diakses melalui kaedah all_messages() dan new_messages() pada objek RunResult dan StreamedRunResult.

from pydantic_ai import Agent

agent = Agent('openai:gpt-4o')
result_sync = agent.run_sync(
    'What is the capital of Italy?',
    model_settings={'temperature': 0.0},
)
print(result_sync.data)
#> Rome

Mesej Guna Semula

Mesej boleh dihantar ke parameter message_history untuk meneruskan perbualan merentasi berbilang ejen dijalankan. Apabila mesej_history ditetapkan dan tidak kosong, gesaan sistem baharu tidak dijana.

Format Mesej

Format mesej adalah bebas model yang membenarkan mesej digunakan dalam ejen yang berbeza atau dengan ejen yang sama menggunakan model yang berbeza.

Penyahpepijatan dan Pemantauan

Api Log Pydantic

PydanticAI disepadukan dengan Pydantic Logfire, platform kebolehmerhatian yang membolehkan anda memantau dan nyahpepijat keseluruhan aplikasi anda. Logfire boleh digunakan untuk:

• Penyahpepijatan masa nyata: Untuk melihat perkara yang berlaku dalam aplikasi anda dalam masa nyata.
• Memantau prestasi aplikasi: Menggunakan pertanyaan SQL dan papan pemuka.

Untuk menggunakan PydanticAI dengan Logfire, pasang dengan kumpulan pilihan logfire: pip install 'pydantic-ai[logfire]'. Anda kemudiannya perlu mengkonfigurasi projek Logfire dan mengesahkan persekitaran anda.

Pemasangan dan Persediaan

Pemasangan

PydanticAI boleh dipasang menggunakan pip:

from pydantic_ai import Agent, RunContext
from datetime import date

agent = Agent(
    'openai:gpt-4o',
    deps_type=str,
    system_prompt="Use the customer's name while replying to them.",
)

@agent.system_prompt
def add_the_users_name(ctx: RunContext[str]) -> str:
    return f"The user's name is {ctx.deps}."

@agent.system_prompt
def add_the_date() -> str:
    return f'The date is {date.today()}.'

result = agent.run_sync('What is the date?', deps='Frank')
print(result.data)
#> Hello Frank, the date today is 2032-01-02.

Pemasangan tipis juga tersedia untuk menggunakan model tertentu, contohnya:

import random
from pydantic_ai import Agent, RunContext

agent = Agent(
    'gemini-1.5-flash',
    deps_type=str,
    system_prompt=(
        "You're a dice game, you should roll the die and see if the number "
        "you get back matches the user's guess. If so, tell them they're a winner. "
        "Use the player's name in the response."
    ),
)

@agent.tool_plain
def roll_die() -> str:
    """Roll a six-sided die and return the result."""
    return str(random.randint(1, 6))

@agent.tool
def get_player_name(ctx: RunContext[str]) -> str:
    """Get the player's name."""
    return ctx.deps

dice_result = agent.run_sync('My guess is 4', deps='Anne')
print(dice_result.data)
#> Congratulations Anne, you guessed correctly! You're a winner!

Integrasi Logfire

Untuk menggunakan PydanticAI dengan Logfire, pasangkannya dengan kumpulan pilihan logfire:

from dataclasses import dataclass
import httpx
from pydantic_ai import Agent, RunContext

@dataclass
class MyDeps:
    api_key: str
    http_client: httpx.AsyncClient

agent = Agent(
    'openai:gpt-4o',
    deps_type=MyDeps,
)

@agent.system_prompt
async def get_system_prompt(ctx: RunContext[MyDeps]) -> str:
    response = await ctx.deps.http_client.get(
        'https://example.com',
        headers={'Authorization': f'Bearer {ctx.deps.api_key}'},
    )
    response.raise_for_status()
    return f'Prompt: {response.text}'

async def main():
    async with httpx.AsyncClient() as client:
        deps = MyDeps('foobar', client)
        result = await agent.run('Tell me a joke.', deps=deps)
        print(result.data)
        #> Did you hear about the toothpaste scandal? They called it Colgate.

Contoh

Contoh tersedia sebagai pakej berasingan:

from pydantic import BaseModel
from pydantic_ai import Agent

class CityLocation(BaseModel):
    city: str
    country: str

agent = Agent('gemini-1.5-flash', result_type=CityLocation)
result = agent.run_sync('Where were the olympics held in 2012?')
print(result.data)
#> city='London' country='United Kingdom'

Pengujian dan Penilaian

Ujian Unit

Ujian unit mengesahkan bahawa kod aplikasi anda berkelakuan seperti yang diharapkan. Untuk PydanticAI, ikut strategi ini:

• Gunakan pytest sebagai abah-abah ujian anda.
• Gunakan TestModel atau FunctionModel sebagai ganti model sebenar anda.
• Gunakan Agent.override untuk menggantikan model anda di dalam logik aplikasi anda.
• Tetapkan ALLOW_MODEL_REQUESTS=Salah secara global untuk mengelakkan panggilan tidak sengaja kepada model bukan ujian.

from pydantic_ai import Agent

agent = Agent('openai:gpt-4o')

# Synchronous run
result_sync = agent.run_sync('What is the capital of Italy?')
print(result_sync.data)
#> Rome

# Asynchronous run
async def main():
    result = await agent.run('What is the capital of France?')
    print(result.data)
    #> Paris

    async with agent.run_stream('What is the capital of the UK?') as response:
        print(await response.get_data())
        #> London

Evals

Evals digunakan untuk mengukur prestasi LLM dan lebih seperti penanda aras daripada ujian unit. Evals memberi tumpuan kepada mengukur prestasi LLM untuk aplikasi tertentu. Ini boleh dilakukan melalui ujian hujung ke hujung, ujian serba lengkap sintetik, menggunakan LLM untuk menilai LLM atau dengan mengukur prestasi ejen dalam pengeluaran.

Contoh Kes Penggunaan

PydanticAI boleh digunakan dalam pelbagai jenis kes penggunaan:

• Roulette Wheel: Mensimulasikan roda rolet menggunakan ejen dengan kebergantungan integer dan hasil boolean.
• Aplikasi Sembang: Mencipta aplikasi sembang dengan berbilang larian, menghantar mesej sebelumnya menggunakan message_history.
• Ejen Sokongan Bank: Membina ejen sokongan untuk bank menggunakan alatan, suntikan pergantungan dan respons berstruktur.
• Ramalan Cuaca: Mencipta aplikasi yang mengembalikan ramalan cuaca berdasarkan lokasi dan tarikh menggunakan alat fungsi dan kebergantungan.
• Penjanaan SQL: Menjana pertanyaan SQL daripada gesaan pengguna, dengan pengesahan menggunakan pengesah hasil.

Kesimpulan

PydanticAI menawarkan rangka kerja yang teguh dan fleksibel untuk membangunkan aplikasi AI dengan penekanan yang kuat pada keselamatan jenis dan modulariti. Penggunaan Pydantic untuk pengesahan dan penstrukturan data, ditambah dengan sistem suntikan kebergantungannya, menjadikannya alat yang ideal untuk membina aplikasi AI yang boleh dipercayai dan boleh diselenggara. Dengan sokongan LLM yang luas dan penyepaduan lancar dengan alatan seperti Pydantic Logfire, PydanticAI membolehkan pembangun membina projek dipacu AI yang berkuasa dan sedia pengeluaran dengan cekap.

Atas ialah kandungan terperinci PydanticAI: Panduan Komprehensif untuk Membina Aplikasi AI Sedia Pengeluaran. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!