PydanticAI + Gonka - وكلاء AI محددون النوع بتكلفة زهيدة

أولاً، احصل على المفتاح: سجل على gate.joingonka.ai/register - عند التسجيل، نقدم 10 ملايين رمز مجاني - وأنشئ مفتاح jg-xxx في لوحة التحكم -> مفاتيح API.

التثبيت:

pip install pydantic-ai
# أو الخيار الخفيف مع تبعيات OpenAI فقط:
# pip install "pydantic-ai-slim[openai]"

مثال بسيط - وكيل عبر Gonka. يحدد PydanticAI نقطة نهاية مخصصة عبر OpenAIProvider(base_url=..., api_key=...)، والتي يتم تمريرها إلى OpenAIChatModel:

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-your-key" (مفتاحك),
    ),
)

agent = Agent(model)

result = agent.run_sync("اشرح في جملتين ما هو PoUW")
print(result.output)

هذا كل شيء - يعمل وكيل PydanticAI الخاص بك من خلال شبكة Gonka اللامركزية بتكلفة زهيدة. طريقة run_sync مناسبة للنصوص البرمجية؛ للكود غير المتزامن، يوجد await agent.run(...).

معلمات النموذج: نافذة سياق Qwen3-235B - 128 ألف رمز (131072)، الحد الأقصى لطول الإخراج عبر Gateway - حتى 8192 رمزًا. يمكن تقييد الإخراج من خلال إعدادات النموذج (OpenAIChatModelSettings(max_tokens=8192)). تتوفر أيضًا moonshotai/Kimi-K2.6 (حتى 3072 رمز إخراج) و MiniMaxAI/MiniMax-M2.7 (حتى 4096) - يكفي تغيير اسم النموذج في الوسيطة الأولى لـ OpenAIChatModel.

السبب الرئيسي لاختيار PydanticAI هو الإخراج المهيكل. بدلاً من تحليل نص الاستجابة بالتعبيرات العادية، تصف النتيجة كنموذج Pydantic وتقوم بتمريره إلى المعلمة output_type. يستخدم الإطار استدعاء الأدوات للنموذج لجعله يُعيد البيانات بدقة وفقًا للمخطط، ويتحقق منها، ويعيد الكائن الجاهز عبر result.output.

from pydantic import BaseModel
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-your-key" (مفتاحك),
    ),
)


class Profile(BaseModel):
    name: str
    role: str
    skills: list[str]


agent = Agent(model, output_type=Profile)

result = agent.run_sync(
    "استخرج البيانات: آنا - مطورة الواجهة الخلفية، تعرف بايثون، جو، وبوستغريس"
)
print(result.output)
# name='آنا' role='مطورة الواجهة الخلفية' skills=['بايثون', 'جو', 'بوستغريس']
print(result.output.skills)  # ['بايثون', 'جو', 'بوستغريس'] - بالفعل list[str]، وليس نص

يعمل هذا لأن Qwen3-235B (والنموذجين الآخرين من Gonka) يدعمان استدعاء الأدوات الأصلي - يعتمد PydanticAI عليه لإرجاع بنية JSON صالحة. تحصل على كائن Python مكتوب بشكل قوي في الإخراج بدلاً من سلسلة تحتاج إلى تحليلها يدويًا. مثالي ل استخراج البيانات، التصنيف، ملء النماذج، وخطوط أنابيب RAG حيث يجب أن تستمر النتيجة في الكود بتنسيق صارم.

PydanticAI هو إطار عمل للوكلاء وخطوط الأنابيب التي تعمل باستمرار: تستخرج البيانات، وتستدعي الأدوات، وتعالج تدفقات الطلبات. هنا، تحدد تكلفة الرموز المميزة ما إذا كان المشروع سيظل نموذجًا أوليًا أم سينتقل إلى الإنتاج. دعنا نقارن الأحمال النموذجية:

الفرق - في مئات وآلاف المرات. بالنسبة للنموذج الأولي، هذا يعني أن 10 ملايين رمز مجاني تكفي لمئات تشغيل الوكيل. بالنسبة للإنتاج الذي يعالج مئات الآلاف من الطلبات يوميًا، يبلغ التوفير عشرات الآلاف من الدولارات شهريًا - بنفس الكود على PydanticAI، فقط مع base_url مختلف.

مفتاح واحد jg-xxx ورصيد واحد يعملان لكل من تنسيق OpenAI (/v1) وتنسيق Anthropic (/v1/messages) - ولكن لـ PydanticAI، يكفي نقطة نهاية متوافقة مع OpenAI، كما هو موضح أعلاه.

الميزة الرئيسية الثانية لـ PydanticAI هي الأدوات. يمكن تسجيل الدالة باستخدام المزين @agent.tool_plain (بدون سياق) أو @agent.tool (مع الوصول إلى RunContext و حقن التبعية). يقرر النموذج بنفسه متى يتم استدعاء الأداة، ويستقبل النتيجة ويستمر في التفكير:

import random
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-your-key" (مفتاحك),
    ),
)

agent = Agent(
    model,
    instructions="أنت مساعد. استخدم الأدوات عند الحاجة.",
)


@agent.tool_plain
def roll_dice() -> str:
    """يلقي نردًا سداسي الأوجه ويعيد النتيجة."""
    return str(random.randint(1, 6))


@agent.tool_plain
def calculator(expression: str) -> str:
    """يحسب تعبيرًا رياضيًا."""
    return str(eval(expression))


result = agent.run_sync("ألقِ النرد واضرب النتيجة في 7")
print(result.output)

نظرًا لأن استدعاء الأدوات في Gonka أصلي، يتم استدعاء الأدوات بشكل موثوق - بدون تحليل هش للاستجابات النصية. تبلغ تكلفة الدورة بأكملها (طلب ← استدعاء أداة ← استجابة نهائية) حوالي 0.00001 دولار عبر Gonka مقابل 0.04 - 0.22 دولار مع OpenAI/Anthropic.

أي نموذج تختار: Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 - الافتراضي، أفضل توازن بين الجودة وأكبر حد للإخراج (8192). moonshotai/Kimi-K2.6 قوي في البرمجة والاستدلال المعقد (إخراج يصل إلى 3072). MiniMaxAI/MiniMax-M2.7 - للحوارات الطويلة (إخراج يصل إلى 4096). جميع النماذج الثلاثة متاحة الآن بنفس المفتاح - يتغير فقط سلسلة اسم النموذج. الأدوات ذات الصلة: LangChain للسلاسل و RAG، LlamaIndex لفهرسة البيانات.