PydanticAI: Ein umfassender Leitfaden zum Erstellen produktionsbereiter KI-Anwendungen

PydanticAI ist ein leistungsstarkes Python-Framework, das entwickelt wurde, um die Entwicklung von Anwendungen in Produktionsqualität mithilfe generativer KI zu optimieren. Es wurde von demselben Team entwickelt, das hinter Pydantic, einer weit verbreiteten Datenvalidierungsbibliothek, steht, und zielt darauf ab, das innovative und ergonomische Design von FastAPI in den Bereich der KI-Anwendungsentwicklung zu bringen. PydanticAI konzentriert sich auf Typsicherheit, Modularität und nahtlose Integration mit anderen Python-Tools.

Kernkonzepte

PydanticAI dreht sich um mehrere Schlüsselkonzepte:

Agenten

Agenten sind die primäre Schnittstelle für die Interaktion mit Large Language Models (LLMs). Ein Agent fungiert als Container für verschiedene Komponenten, darunter:

• Systemaufforderungen: Anweisungen für das LLM, definiert als statische Zeichenfolgen oder dynamische Funktionen.
• Funktionstools: Funktionen, die das LLM aufrufen kann, um zusätzliche Informationen zu erhalten oder Aktionen auszuführen.
• Strukturierte Ergebnistypen: Datentypen, die das LLM am Ende eines Laufs zurückgeben muss.
• Abhängigkeitstypen: Daten oder Dienste, die Systemaufforderungsfunktionen, Tools und Ergebnisvalidatoren verwenden können.
• LLM-Modelle: Das LLM, das der Agent verwenden wird, kann bei der Agentenerstellung oder zur Laufzeit festgelegt werden.

Agenten sind auf Wiederverwendbarkeit ausgelegt und werden normalerweise einmal instanziiert und in einer Anwendung wiederverwendet.

Systemaufforderungen

Systemaufforderungen sind Anweisungen, die der Entwickler dem LLM zur Verfügung stellt. Sie können sein:

• Statische Systemaufforderungen: Definiert, wenn der Agent erstellt wird, unter Verwendung des system_prompt-Parameters des Agent-Konstruktors.
• Dynamische Systemaufforderungen: Definiert durch Funktionen, die mit @agent.system_prompt dekoriert sind. Diese können über das RunContext-Objekt auf Laufzeitinformationen, wie z. B. Abhängigkeiten, zugreifen.

Ein einzelner Agent kann sowohl statische als auch dynamische Systemaufforderungen verwenden, die in der Reihenfolge angehängt werden, in der sie zur Laufzeit definiert werden.

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.

Funktionstools

Funktionstools ermöglichen es LLMs, auf externe Informationen zuzugreifen oder Aktionen auszuführen, die in der Systemeingabeaufforderung selbst nicht verfügbar sind. Werkzeuge können auf verschiedene Arten registriert werden:

• @agent.tool decorator: Für Tools, die über RunContext Zugriff auf den Kontext des Agenten benötigen.
• @agent.tool_plain decorator: Für Tools, die keinen Zugriff auf den Kontext des Agenten benötigen.
• tools-Schlüsselwortargument im Agent-Konstruktor: Kann einfache Funktionen oder Instanzen der Tool-Klasse annehmen und bietet so mehr Kontrolle über Tool-Definitionen.

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.

Tool-Parameter werden aus der Funktionssignatur extrahiert und zum Erstellen des JSON-Schemas des Tools verwendet. Die Dokumentzeichenfolgen der Funktionen werden verwendet, um die Beschreibungen des Tools und die Parameterbeschreibungen innerhalb des Schemas zu generieren.

Abhängigkeiten

Abhängigkeiten stellen über ein Abhängigkeitsinjektionssystem Daten und Dienste für die Systemaufforderungen, Tools und Ergebnisvalidatoren des Agenten bereit. Der Zugriff auf Abhängigkeiten erfolgt über das RunContext-Objekt. Sie können ein beliebiger Python-Typ sein, aber Datenklassen sind eine bequeme Möglichkeit, mehrere Abhängigkeiten zu verwalten.

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!

Ergebnisse

Ergebnisse sind die endgültigen Werte, die von einer Agentenausführung zurückgegeben werden. Sie sind in RunResult (für synchrone und asynchrone Ausführungen) oder StreamedRunResult (für gestreamte Ausführungen) eingeschlossen und bieten Zugriff auf Nutzungsdaten und den Nachrichtenverlauf. Die Ergebnisse können reiner Text oder strukturierte Daten sein und werden mit Pydantic validiert.

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.

Ergebnisvalidatoren, die über den Dekorator @agent.result_validator hinzugefügt werden, bieten eine Möglichkeit, weitere Validierungslogik hinzuzufügen, insbesondere wenn die Validierung E/A erfordert und asynchron ist.

Hauptmerkmale

PydanticAI verfügt über mehrere Schlüsselfunktionen, die es zu einer überzeugenden Wahl für die Entwicklung von KI-Anwendungen machen:

• Modellunabhängig: PydanticAI unterstützt eine Vielzahl von LLMs, darunter OpenAI, Anthropic, Gemini, Ollama, Groq und Mistral. Es bietet auch eine einfache Schnittstelle zur Implementierung der Unterstützung für andere Modelle.
• Typsicherheit: Entwickelt für die nahtlose Zusammenarbeit mit statischen Typprüfern wie mypy und pyright. Es ermöglicht die Typprüfung von Abhängigkeiten und Ergebnistypen.
• Python-zentriertes Design: Nutzt den vertrauten Python-Kontrollfluss und die Agentenzusammensetzung, um KI-Projekte zu erstellen, wodurch die Anwendung standardmäßiger Python-Praktiken vereinfacht wird.
• Strukturierte Antworten: Verwendet Pydantic, um Modellausgaben zu validieren und zu strukturieren und so konsistente Antworten sicherzustellen.
• Abhängigkeitsinjektionssystem: Bietet ein Abhängigkeitsinjektionssystem, um Daten und Dienste für die Komponenten eines Agenten bereitzustellen und so die Testbarkeit und iterative Entwicklung zu verbessern.
• Gestreamte Antworten: Unterstützt das Streaming von LLM-Ausgaben mit sofortiger Validierung und ermöglicht so schnelle und genaue Ergebnisse.

Arbeiten mit Agenten

Laufende Agenten

Agenten können auf verschiedene Arten ausgeführt werden:

• run_sync(): Für synchrone Ausführung.
• run(): Für asynchrone Ausführung.
• run_stream(): Für Streaming-Antworten.

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.

Gespräche

Eine Agentenausführung kann eine ganze Konversation darstellen, aber Konversationen können auch aus mehreren Durchläufen bestehen, insbesondere wenn der Status zwischen Interaktionen beibehalten wird. Sie können Nachrichten aus früheren Läufen mit dem Argument message_history übergeben, um eine Konversation fortzusetzen.

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!

Nutzungsbeschränkungen

PydanticAI bietet eine Settings.UsageLimits-Struktur, um die Anzahl der Token und Anfragen zu begrenzen. Sie können diese Einstellungen über das Argument „usage_limits“ auf die Ausführungsfunktionen anwenden.

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.

Modelleinstellungen

Die Struktur „settings.ModelSettings“ ermöglicht Ihnen die Feinabstimmung des Modellverhaltens durch Parameter wie Temperatur, max_tokens und Timeout. Sie können diese über das Argument model_settings in den Ausführungsfunktionen anwenden.

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'

Funktionstools im Detail

Werkzeugregistrierung

Tools können mit dem @agent.tool-Dekorator (für Tools, die Kontext benötigen), dem @agent.tool_plain-Dekorator (für Tools ohne Kontext) oder über das Tools-Argument im Agent-Konstruktor registriert werden.

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

Werkzeugschema

Parameterbeschreibungen werden aus Dokumentzeichenfolgen extrahiert und dem JSON-Schema des Tools hinzugefügt. Wenn ein Tool über einen einzelnen Parameter verfügt, der als Objekt im JSON-Schema dargestellt werden kann, wird das Schema so vereinfacht, dass es nur dieses Objekt darstellt.

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.

Dynamische Werkzeuge

Werkzeuge können mit einer Vorbereitungsfunktion angepasst werden, die bei jedem Schritt aufgerufen wird, um die Werkzeugdefinition zu ändern oder das Werkzeug aus diesem Schritt wegzulassen.

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)

Nachrichten und Chat-Verlauf

Auf Nachrichten zugreifen

Auf Nachrichten, die während einer Agentenausführung ausgetauscht werden, kann über die Methoden all_messages() und new_messages() der Objekte RunResult und StreamedRunResult zugegriffen werden.

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

Wiederverwendung von Nachrichten

Nachrichten können an den Parameter message_history übergeben werden, um Konversationen über mehrere Agentenläufe hinweg fortzusetzen. Wenn ein message_history festgelegt und nicht leer ist, wird keine neue Systemaufforderung generiert.

Nachrichtenformat

Das Nachrichtenformat ist modellunabhängig, sodass Nachrichten in verschiedenen Agenten oder mit demselben Agenten unter Verwendung verschiedener Modelle verwendet werden können.

Debuggen und Überwachen

Pydantisches Holzfeuer

PydanticAI lässt sich in Pydantic Logfire integrieren, einer Observability-Plattform, mit der Sie Ihre gesamte Anwendung überwachen und debuggen können. Holzfeuer kann verwendet werden für:

• Echtzeit-Debugging: Um in Echtzeit zu sehen, was in Ihrer Anwendung passiert.
• Überwachung der Anwendungsleistung: Verwendung von SQL-Abfragen und Dashboards.

Um PydanticAI mit Logfire zu verwenden, installieren Sie es mit der optionalen Logfire-Gruppe: pip install 'pydantic-ai[logfire]'. Anschließend müssen Sie ein Logfire-Projekt konfigurieren und Ihre Umgebung authentifizieren.

Installation und Einrichtung

Installation

PydanticAI kann mit pip:
installiert werden

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.

Eine schlanke Installation ist auch verfügbar, um bestimmte Modelle zu verwenden, zum Beispiel:

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!

Logfire-Integration

Um PydanticAI mit Logfire zu verwenden, installieren Sie es mit der optionalen Logfire-Gruppe:

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.

Beispiele

Beispiele sind als separates Paket erhältlich:

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'

Prüfung und Bewertung

Unit-Tests

Unit-Tests überprüfen, ob sich Ihr Anwendungscode wie erwartet verhält. Befolgen Sie für PydanticAI diese Strategien:

• Verwenden Sie pytest als Testumgebung.
• Verwenden Sie TestModel oder FunctionModel anstelle Ihres tatsächlichen Modells.
• Verwenden Sie Agent.override, um Ihr Modell innerhalb Ihrer Anwendungslogik zu ersetzen.
• Legen Sie ALLOW_MODEL_REQUESTS=False global fest, um versehentliche Aufrufe von Nicht-Testmodellen zu verhindern.

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

Bewertungen

Bewertungen werden verwendet, um die Leistung des LLM zu messen und ähneln eher Benchmarks als Unit-Tests. Evals konzentrieren sich auf die Messung der Leistung des LLM für eine bestimmte Anwendung. Dies kann durch End-to-End-Tests, synthetische eigenständige Tests, die Verwendung von LLMs zur Bewertung von LLMs oder durch die Messung der Agentenleistung in der Produktion erfolgen.

Beispielanwendungsfälle

PydanticAI kann in einer Vielzahl von Anwendungsfällen eingesetzt werden:

• Roulette-Rad: Simulation eines Roulette-Rades unter Verwendung eines Agenten mit einer ganzzahligen Abhängigkeit und einem booleschen Ergebnis.
• Chat-Anwendung: Erstellen einer Chat-Anwendung mit mehreren Durchläufen, Weitergabe früherer Nachrichten mithilfe von message_history.
• Bank-Support-Agent: Aufbau eines Support-Agenten für eine Bank mithilfe von Tools, Abhängigkeitsinjektion und strukturierten Antworten.
• Wettervorhersage: Erstellen einer Anwendung, die mithilfe von Funktionstools und Abhängigkeiten eine Wettervorhersage basierend auf Ort und Datum zurückgibt.
• SQL-Generierung: Generieren von SQL-Abfragen aus Benutzereingaben, mit Validierung mithilfe des Ergebnisvalidators.

Abschluss

PydanticAI bietet ein robustes und flexibles Framework für die Entwicklung von KI-Anwendungen mit einem starken Schwerpunkt auf Typsicherheit und Modularität. Die Verwendung von Pydantic zur Datenvalidierung und -strukturierung in Verbindung mit seinem Abhängigkeitsinjektionssystem macht es zu einem idealen Werkzeug für die Erstellung zuverlässiger und wartbarer KI-Anwendungen. Mit seiner breiten LLM-Unterstützung und der nahtlosen Integration mit Tools wie Pydantic Logfire ermöglicht PydanticAI Entwicklern, leistungsstarke, produktionsreife KI-gesteuerte Projekte effizient zu erstellen.

Das obige ist der detaillierte Inhalt vonPydanticAI: Ein umfassender Leitfaden zum Erstellen produktionsbereiter KI-Anwendungen. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!