Pydantic AI: دليل الإنتاج (ما وراء Hello World)

Pydantic AI: دليل الإنتاج (ما وراء Hello World)

مخرجات نماذج اللغة الخام تُعطّل التطبيقات. تطلب JSON فتحصل على Markdown. تطلب رقماً بين 1 و10 فتحصل على "بالطبع! إليك رقم: سبعة." إذا كنت قد بنيت شيئاً حقيقياً باستخدام واجهات برمجة نماذج اللغة، فأنت قد كتبت كوداً دفاعياً للتحليل يجعلك تشكك في خياراتك المهنية. Pydantic AI يحل هذه المشكلة -- إنه إطار عمل العملاء الآمن من الناحية النوعية الذي بناه نفس الفريق الذي أنشأ Pydantic وFastAPI. فكّر به باعتباره "FastAPI لعملاء الذكاء الاصطناعي": تحدد ما تريده باستخدام تلميحات النوع في Python، ويتولى الإطار التحقق من الصحة وإعادة المحاولة واستدعاء الأدوات.

دليل Pydantic AI هذا مخصص للمطورين الذين أجروا أول استدعاء لنموذج لغوي بالفعل ويريدون أنماط الإنتاج: مخرجات منظمة لا تنكسر، وحقن التبعيات للعملاء القابلة للاختبار، وأدوات واقعية تتجاوز واجهات برمجة التطبيقات للطقس. بنهاية هذا الدليل، سيكون لديك عملاء يعملون مع أدوات وDI وبث واختبارات.

Pydantic AI في لمحة سريعة

الميزات البارزة هي المخرجات المنظمة (يُتحقق منها بنماذج Pydantic)، وحقن التبعيات (مثل Depends في FastAPI)، وTestModel (نموذج لغوي وهمي للاختبار دون استدعاءات API). إذا كنت قادماً من LangChain وتتساءل "هل هناك شيء أنظف؟"، فهذا على الأرجح هو الجواب.

التثبيت والعميل الأول

# تثبيت مع دعم OpenAI (استبدل openai بـ anthropic أو google وما إلى ذلك)
pip install "pydantic-ai[openai]"

# تعيين مفتاح API الخاص بك
export OPENAI_API_KEY="sk-..."

عميلك الأول في 5 أسطر:

from pydantic_ai import Agent

agent = Agent("openai:gpt-4o", system_prompt="You are a helpful assistant.")

result = agent.run_sync("What's the capital of France?")
print(result.output)  # "Paris"

هذا كل شيء. Agent يُغلّف النموذج، run_sync يرسل موجهاً ويعيد نتيجة. result.output هنا نص عادي، لكن هذا على وشك أن يتغير.

المخرجات المنظمة -- سبب وجود Pydantic AI

هذه الميزة الأساسية. بدلاً من الحصول على نص من النموذج اللغوي والأمل في أنه JSON صالح، تحدد نموذج Pydantic ويعيد العميل كائن Python مُتحقَّقاً منه.

قبل: مخرجات نموذج اللغة الخام

# الطريقة القديمة -- أمِّل الأفضل
from openai import OpenAI

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Review the movie Inception. Return JSON with title, rating (1-10), summary."}]
)
# response.choices[0].message.content هو نص
# ربما يكون JSON. ربما يحتوي على أسوار كود Markdown. ربما يكون التقييم "eight".
# أنت وحدك.

بعد: منظَّم مع Pydantic AI

from pydantic import BaseModel
from pydantic_ai import Agent

class MovieReview(BaseModel):
    title: str
    rating: int  # مضمون أن يكون int وليس "eight"
    summary: str
    recommended: bool

agent = Agent("openai:gpt-4o", result_type=MovieReview)

result = agent.run_sync("Review the movie Inception")
review = result.output  # هذه نسخة MovieReview وليست نصاً

print(f"{review.title}: {review.rating}/10")
print(f"موصى به: {review.recommended}")
print(review.summary)

الفرق كالليل والنهار. result.output هو كائن MovieReview حقيقي. إذا أعاد النموذج اللغوي rating: "eight" بدلاً من rating: 8، تلتقط عملية التحقق في Pydantic ذلك. للاطلاع على شرح أعمق لكيفية عمل هذا عبر مزودين مختلفين، راجع دليلنا حول المخرجات المنظمة عبر مزودي نماذج اللغة.

ماذا يحدث عند فشل التحقق

هذا هو الجزء الذي لا يُظهره أي برنامج تعليمي آخر: ماذا يحدث عندما يُخطئ النموذج اللغوي؟

from pydantic import BaseModel, Field
from pydantic_ai import Agent

class StrictReview(BaseModel):
    title: str
    rating: int = Field(ge=1, le=10)  # يجب أن يكون بين 1 و10
    pros: list[str] = Field(min_length=2)  # ميزتان على الأقل

agent = Agent("openai:gpt-4o", result_type=StrictReview)

# إذا أعاد النموذج rating=15 أو ميزة واحدة فقط:
# 1. يفشل التحقق في Pydantic
# 2. يُرسل رسالة الخطأ عائداً إلى النموذج اللغوي
# 3. يحاول النموذج مجدداً بمخرجات مصححة
# 4. يتكرر هذا حتى حد إعادة المحاولة
result = agent.run_sync("Review the movie Inception")

حلقة إعادة المحاولة مع التغذية الراجعة هذه هي الميزة القاتلة في Pydantic AI. يتعلم النموذج اللغوي من أخطاء التحقق الخاصة به. لا تكتب منطق إعادة المحاولة -- الإطار يتولى ذلك.

الحكم: المخرجات المنظمة هي السبب الوحيد الأفضل لاستخدام Pydantic AI بدلاً من استدعاءات API الخام. إذا كنت تُحلّل JSON نموذج اللغة يدوياً، توقف.

الأدوات واستدعاء الدوال

تتيح الأدوات لعميلك استدعاء دوال Python للحصول على بيانات حقيقية. بدلاً من أن يهلوس النموذج اللغوي بالحقائق، يمكنه الاستعلام من قاعدة بياناتك أو البحث في مستنداتك أو استدعاء API.

تسجيل أداة

from pydantic_ai import Agent

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

@agent.tool
async def search_docs(query: str) -> str:
    """Search the documentation for relevant articles."""
    # منطق البحث الفعلي هنا
    results = await doc_search_engine.search(query, limit=5)
    return "\n".join(r.title + ": " + r.snippet for r in results)

يسجّل الديكوراتور @agent.tool الدالة. يقرأ Pydantic AI تلميحات النوع والـ docstring للدالة لإخبار النموذج اللغوي بما تفعله الأداة، وما هي الحجج التي تأخذها، وماذا تعيد. لا كتابة مخطط يدوية -- تلميحات النوع الخاصة بك هي المخطط. لمعرفة الخلفية حول كيف يعمل استدعاء الدوال في نماذج اللغة تحت الغطاء، لدينا دليل مخصص.

RunContext: تمرير البيانات إلى الأدوات

هنا يختلف Pydantic AI عن الأطر الأخرى. RunContext يتيح لك تمرير بيانات وقت التشغيل (اتصالات قاعدة البيانات، معلومات المستخدم، عملاء API) إلى أدواتك دون حالة عامة.

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class SupportDeps:
    customer_id: str
    db_connection: DatabaseConnection

agent = Agent("openai:gpt-4o", deps_type=SupportDeps)

@agent.tool
async def get_order_history(ctx: RunContext[SupportDeps], limit: int = 5) -> str:
    """Fetch recent orders for the current customer."""
    orders = await ctx.deps.db_connection.query(
        "SELECT * FROM orders WHERE customer_id = $1 ORDER BY date DESC LIMIT $2",
        ctx.deps.customer_id, limit
    )
    return format_orders(orders)

ctx.deps يمنح الأداة وصولاً إلى كل ما مررته في وقت التشغيل. لا تستورد الأداة اتصال قاعدة بيانات عاماً -- تستقبل واحداً. هذا هو حقن التبعيات، وهو ما يجعل عملاءك قابلين للاختبار.

مثال أداة واقعي

@agent.tool
async def run_sql_query(ctx: RunContext[SupportDeps], sql: str) -> str:
    """Run a read-only SQL query against the analytics database.
    Only SELECT queries are allowed."""
    if not sql.strip().upper().startswith("SELECT"):
        return "Error: only SELECT queries are allowed"
    results = await ctx.deps.db_connection.fetch(sql)
    return json.dumps(results, default=str)

الحكم: استدعاء الأدوات في Pydantic AI أنظف من أي إطار عمل آخر بفضل تلميحات النوع التي تقوم بالعمل الثقيل. تكتب دوال Python عادية مع تعليقات النوع. الإطار يحل الباقي.

حقن التبعيات -- الميزة التي يتمنى LangChain أن يمتلكها

إذا كنت قد استخدمت Depends في FastAPI، فأنت تفهم بالفعل نظام DI في Pydantic AI. إذا لم تفعل، إليك النسخة المختصرة: بدلاً من أن يمتد عميلك للحصول على ما يحتاجه (اتصالات قاعدة البيانات العامة، عملاء API، التكوين)، تسلّمه كل شيء في وقت التشغيل.

تعريف التبعيات

from dataclasses import dataclass
from pydantic_ai import Agent

@dataclass
class AppDeps:
    db: AsyncDatabasePool
    search_client: SearchAPIClient
    current_user: User

agent = Agent(
    "openai:gpt-4o",
    deps_type=AppDeps,
    system_prompt="You are a customer support agent."
)

استخدام التبعيات في الأدوات

@agent.tool
async def lookup_account(ctx: RunContext[AppDeps]) -> str:
    """Look up the current user's account details."""
    account = await ctx.deps.db.fetchrow(
        "SELECT * FROM accounts WHERE user_id = $1",
        ctx.deps.current_user.id
    )
    return json.dumps(account, default=str)

# التشغيل بتبعيات حقيقية
result = await agent.run(
    "What's my account status?",
    deps=AppDeps(db=real_db, search_client=real_search, current_user=user)
)

لماذا يجعل DI عملاءك قابلين للاختبار

هذا هو العائد الحقيقي. في LangChain، ستمرر السياق عبر kwargs السلسلة أو الإغلاقات -- لا يوجد نمط قياسي. في Pydantic AI، استبدال التبعيات الحقيقية بنماذج اختبارية أمر تافه:

# في ملف الاختبار الخاص بك
from pydantic_ai import Agent
from your_app import agent, AppDeps

async def test_account_lookup():
    mock_deps = AppDeps(
        db=MockDatabase({"user_123": {"status": "active", "plan": "pro"}}),
        search_client=MockSearch(),
        current_user=User(id="user_123")
    )
    result = await agent.run("What's my account status?", deps=mock_deps)
    assert "active" in result.output
    assert "pro" in result.output

لا monkey-patching. لا محاكاة لاستيرادات عامة. فقط تمرر deps مختلفة.

الحكم: حقن التبعيات هو سبب تفضيل مطوري Python ذوي الخبرة لـ Pydantic AI. إنه تأثير FastAPI يظهر.

مزودو النماذج -- OpenAI وAnthropic وGemini وOllama

Pydantic AI مستقل عن النموذج. تغيير المزود هو تعديل سطر واحد:

# OpenAI
agent = Agent("openai:gpt-4o")

# Anthropic
agent = Agent("anthropic:claude-sonnet-4-20250514")

# Google Gemini
agent = Agent("google-gla:gemini-2.0-flash")

# Ollama المحلي
agent = Agent("ollama:llama3.1")

كل شيء آخر -- الأدوات، المخرجات المنظمة، DI -- يبقى متطابقاً. منطق أعمالك لا يتغير عند تغيير النماذج.

الحكم: التصميم المستقل عن النموذج يعني أنك لن تكون مقيداً بمزود واحد أبداً. ابدأ بـ OpenAI للراحة، قارن مع Anthropic، واستخدم Ollama للتطوير المحلي.

ردود البث

لواجهات المستخدم للدردشة والتطبيقات الفورية، البث ضروري. يدعمه Pydantic AI مع الحفاظ على سلامة النوع:

from pydantic_ai import Agent
from pydantic import BaseModel

class AnalysisResult(BaseModel):
    summary: str
    sentiment: str
    confidence: float

agent = Agent("openai:gpt-4o", result_type=AnalysisResult)

async def stream_analysis(text: str):
    async with agent.run_stream(f"Analyze this text: {text}") as stream:
        async for partial in stream.stream_structured():
            # partial هو AnalysisResult مُتحقَّق منه جزئياً
            print(f"بث: {partial}")

        # النتيجة النهائية مُتحقَّق منها بالكامل
        result = await stream.get_output()
        print(f"النهائي: {result.summary} (ثقة {result.confidence:.0%})")

يعمل هذا بشكل رائع مع StreamingResponse في FastAPI -- نفس النظام البيئي، نفس الأنماط. توثيق عملاء Pydantic AI يغطي خيارات البث المتقدمة بما فيها البث النصي فقط مع stream_text().

Pydantic AI مقابل LangGraph مقابل OpenAI Agents SDK

أنت هنا، لذا ربما تسأل: "هل يجب أن أستخدم Pydantic AI أم LangGraph؟" الجواب الصادق: يحلان مشكلات مختلفة، وقد تستخدم كليهما.

جدول مقارنة الميزات

متى تستخدم كل منها

اختر Pydantic AI عندما تريد كوداً نظيفاً وآمناً نوعياً للعميل. مثالي للمهام أحادية العميل مع الأدوات (روبوتات دعم العملاء، استخراج البيانات، عملاء مراجعة الكود) والحالات التي تهم فيها قابلية الاختبار. إذا كان فريقك يستخدم بالفعل FastAPI وPydantic، فمنحنى التعلم يكاد يكون منبسطاً.

اختر LangGraph عندما تحتاج إلى سير عمل متعددة الخطوات مع تفريع شرطي، وموافقة بشرية في الحلقة، وإدارة حالة متطورة. يتفوق LangGraph في تنسيق خطوات متعددة، وليس جودة العميل الفردي. للتعمق، راجع مقارنتنا الكاملة لـ LangGraph مقابل CrewAI مقابل OpenAI Agents SDK.

اختر OpenAI Agents SDK عندما تكون 100% على OpenAI، وتريد أبسط إعداد ممكن، ولا تحتاج إلى دعم متعدد المزودين أو DI.

نمط الجمع بينهما

إليك ما تفعله الفرق ذات الخبرة فعلاً: تستخدم Pydantic AI للعملاء الفرديين (كود نظيف، قابل للاختبار، مخرجات مكتوبة) وLangGraph للتنسيق بين العملاء (التوجيه، آلات الحالة، المنطق الشرطي). إنهما لا يتنافسان -- بل يمثلان طبقات تكميلية.

# عميل Pydantic AI -- نظيف، قابل للاختبار، آمن نوعياً
support_agent = Agent("openai:gpt-4o", result_type=SupportResponse, deps_type=SupportDeps)

# رسم بياني LangGraph -- ينسق متى يستدعي أي عميل
graph = StateGraph(SupportState)
graph.add_node("classify", classify_intent)
graph.add_node("support", lambda state: support_agent.run_sync(state["query"]))
graph.add_node("escalate", escalate_to_human)

الحكم: اختر Pydantic AI لكود العميل النظيف القابل للاختبار. اختر LangGraph لسير العمل المعقدة متعددة الخطوات. إنهما لا يستبعدان بعضهما.

اختبار عملاءك مع TestModel

هذا هو القسم الذي يفصل دليل المبتدئين عن دليل الإنتاج. كل قاعدة كود حقيقية تحتاج إلى اختبارات، واختبار العملاء أمر صعب بشكل معروف -- استدعاءات النماذج اللغوية بطيئة ومكلفة وغير حتمية. يوفر Pydantic AI حلاً: TestModel.

from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel
from pydantic import BaseModel

class SupportResponse(BaseModel):
    answer: str
    confidence: float
    escalate: bool

agent = Agent("openai:gpt-4o", result_type=SupportResponse)

# في الاختبارات: استبدل النموذج الحقيقي بـ TestModel
def test_support_agent():
    with agent.override(model=TestModel()):
        result = agent.run_sync("I need help with billing")
        # يعيد TestModel بيانات منظمة صالحة تطابق result_type الخاص بك
        assert isinstance(result.output, SupportResponse)
        assert isinstance(result.output.confidence, float)
        assert isinstance(result.output.escalate, bool)

TestModel يُولّد بيانات صالحة تطابق result_type الخاص بك دون إجراء أي استدعاءات API. تكلفة صفر، حتمي، سريع. توثيق اختبار Pydantic AI يغطي أنماطاً متقدمة مثل FunctionModel للردود المخصصة وcapture_run_messages لفحص استدعاءات الأدوات.

اختبار الأدوات وDI معاً

def test_order_lookup_tool():
    # تبعيات وهمية
    mock_deps = SupportDeps(
        customer_id="test-123",
        db_connection=MockDB(orders=[{"id": "ord-1", "status": "shipped"}])
    )

    with agent.override(model=TestModel()):
        result = agent.run_sync(
            "Where is my order?",
            deps=mock_deps
        )
        assert isinstance(result.output, SupportResponse)

لا استدعاءات API. لا اختبارات غير موثوقة. لا تكلفة. شغّل هذا في CI/CD إلى جانب بقية مجموعة الاختبارات الخاصة بك.

هذه هي الفجوة الأولى في المحتوى على SERP بأكمله. لا يغطي أي دليل آخر لـ Pydantic AI الاختبار. إذا كنت تبني عملاء للإنتاج، هذا ما تحتاجه.

قابلية الملاحظة -- تكامل Logfire في 5 دقائق

تحتاج عملاء الإنتاج إلى قابلية ملاحظة الذكاء الاصطناعي. تريد رؤية كل استدعاء لنموذج اللغة، واستدعاء الأداة، والتأخر، وعدد الرموز، والتكلفة. يتكامل Pydantic AI بشكل أصلي مع Logfire، منصة قابلية الملاحظة التابعة لفريق Pydantic (مبنية على OpenTelemetry).

import logfire
from pydantic_ai import Agent

logfire.configure()  # يستخدم متغير بيئة LOGFIRE_TOKEN
logfire.instrument_pydantic_ai()

agent = Agent("openai:gpt-4o", result_type=MovieReview)
# كل تشغيل الآن مُتتبَّع تلقائياً
result = agent.run_sync("Review Inception")

ثلاثة أسطر. تحصل على آثار كاملة تُظهر: الموجه المُرسَل، استجابة النموذج، استدعاءات الأدوات (إن وجدت)، نجاحات/فشل التحقق، إعادة المحاولات، التأخر، والتكلفة المقدرة. إذا لم يكن Logfire مناسباً لك، فـ Langfuse بديل ممتاز مفتوح المصدر مع دعم هندسة السياق لتتبع كيفية تطور موجهاتك.

الأسئلة الشائعة

ما هو Pydantic AI وكيف يختلف عن LangChain؟

Pydantic AI هو إطار عمل عملاء آمن نوعياً حيث تقود تلميحات النوع في Python التحقق من الصحة، ومخططات الأدوات، وحقن التبعيات. LangChain هو إطار عمل أكبر يركز على سلسلة استدعاءات نموذج اللغة. الفرق الرئيسي: Pydantic AI يُتحقق من المخرجات على مستوى الإطار ويوفر حقن التبعيات المدمج لقابلية الاختبار -- LangChain لا يفعل أياً منهما افتراضياً.

كيف أبني عميل ذكاء اصطناعي آمناً نوعياً مع Pydantic AI؟

عرّف BaseModel في Pydantic لمخرجاتك، مرره كـ result_type إلى Agent واستدعِ run_sync() أو run(). يعيد العميل نسخة مُتحقَّقاً منها من نموذجك، وليس نصاً خاماً. راجع قسم المخرجات المنظمة للحصول على أمثلة كاملة.

هل يجب أن أستخدم Pydantic AI أم LangGraph للعملاء في الإنتاج؟

استخدم Pydantic AI للعملاء الفرديين حيث تهم سلامة النوع وقابلية الاختبار والكود النظيف. استخدم LangGraph لتنسيق سير العمل المعقدة متعددة الخطوات مع التوجيه الشرطي. كثير من الفرق تستخدم كليهما -- عملاء Pydantic AI داخل طبقة تنسيق LangGraph.

كيف يتعامل Pydantic AI مع استدعاء الأدوات وحقن التبعيات؟

زيّن دالة بـ @agent.tool وسيقرأ Pydantic AI تلميحات النوع الخاصة بها لإنشاء مخطط الأداة. للـ DI، عيّن deps_type على Agent واقبل RunContext[YourDeps] في الأدوات. تبعيات وقت التشغيل (اتصالات DB، عملاء API) تتدفق دون حالة عامة.

كيف أضيف البث إلى عميل Pydantic AI؟

استخدم agent.run_stream() بدلاً من agent.run(). يعيد مدير سياق غير متزامن يُنتج نتائج جزئية عبر stream_structured() أو stream_text(). النتيجة النهائية لا تزال مُتحقَّقاً منها بالكامل وفق result_type الخاص بك.

هل Pydantic AI جاهز للإنتاج في 2026؟

نعم. الإصدار 1.0 صدر في سبتمبر 2025 مع التزام بثبات API. يدعمه فريق Pydantic (مكتبة Python الأكثر تحميلاً للتحقق من صحة البيانات) وهو حالياً في الإصدار v1.74.0 مع تحديثات منتظمة.

هل يمكنني استخدام Pydantic AI مع Ollama والنماذج المحلية؟

نعم. استخدم Agent("ollama:llama3.1") وتأكد من أن Ollama يعمل محلياً. ثبّت إضافة مزود ollama: pip install "pydantic-ai[ollama]". المخرجات المنظمة والأدوات تعمل بنفس الطريقة مع مزودي السحابة.

كيف أختبر عملاء Pydantic AI؟

استخدم TestModel -- نموذج وهمي يُولّد بيانات منظمة صالحة تطابق result_type الخاص بك دون استدعاءات API. اضمّ اختبارك في agent.override(model=TestModel()) وشغّل تحققات على المخرجات. راجع قسم الاختبار للحصول على أمثلة pytest كاملة.

هل يعمل Pydantic AI مع FastAPI؟

بشكل مثالي. يشتركان في نفس فلسفة حقن التبعيات ومبنيان من قِبل نفس الفريق. يمكنك استخدام عملاء Pydantic AI داخل نقاط نهاية FastAPI، ومشاركة أنواع التبعيات بينهما، وبث ردود العميل عبر StreamingResponse.

ما الفرق بين Pydantic AI وOpenAI Agents SDK؟

Pydantic AI مستقل عن النموذج (يعمل مع OpenAI وAnthropic وGemini وOllama وغيرها)، ولديه حقن التبعيات وTestModel للاختبار والتحقق من Pydantic. OpenAI Agents SDK أبسط لكنه مقيد بنماذج OpenAI ويفتقر إلى DI والاختبار المدمج. اختر Pydantic AI للمرونة؛ اختر OpenAI Agents SDK للإعداد الأبسط الممكن لـ OpenAI فقط.

الأفكار الرئيسية والخطوات التالية

ابدأ بعميل صغير يحتوي على مخرجات منظمة. أضف أداة. أضف التبعيات. اكتب اختباراً مع TestModel. هذا هو مسار الإنتاج -- والآن لديك كل ما تحتاجه للسير فيه.

التوثيق الرسمي لـ Pydantic AI ومستودع GitHub ممتازان للتعمق أكثر. الإطار يتحرك بسرعة، لذا احفظ سجل التغييرات في المفضلة.

المصادر

• Pydantic AI -- التوثيق الرسمي
• توثيق التبعيات في Pydantic AI
• توثيق الاختبار في Pydantic AI
• إعلان إصدار Pydantic AI v1
• قابلية ملاحظة الذكاء الاصطناعي في Logfire
• pydantic/pydantic-ai -- مستودع GitHub