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

أولاً احصل على المفتاح: سجل في gate.joingonka.ai/register — عند التسجيل نمنحك 10 مليون توكن مجاني — وأنشئ مفتاح jg-xxx في Dashboard → API Keys.

التثبيت:

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

مثال مبسط هو وكيل عبر Gonka. يقوم PydanticAI بتعيين endpoint مخصص عبر 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(
    "MiniMaxAI/MiniMax-M2.7",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-مفتاحك",
    ),
)

agent = Agent(model)

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

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

بارامترات النموذج: نافذة السياق لنماذج الشبكة هي 200K توكن (200000)، والحد الأقصى لطول الاستجابة عبر Gateway — يصل إلى 8192 توكن. يمكنك تقييد المخرجات عبر إعدادات النموذج (OpenAIChatModelSettings(max_tokens=8192)). تتوفر أيضاً moonshotai/Kimi-K2.6 و MiniMaxAI/MiniMax-M2.7 (حتى 8192 توكن لكل منهما) — فقط قم بتغيير اسم النموذج في المعامل الأول لـ OpenAIChatModel.

السبب الرئيسي لاختيار PydanticAI هو structured output. بدلاً من تحليل نص الاستجابة باستخدام التعبيرات النمطية (regex)، تصف النتيجة كنموذج Pydantic وتمرره إلى المعامل output_type. يستخدم الإطار عمل خاصية tool calling للنموذج لإجباره على إرجاع البيانات بدقة وفقاً للمخطط، ويقوم بالتحقق منها وتقديم كائن جاهز عبر 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(
    "MiniMaxAI/MiniMax-M2.7",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-مفتاحك",
    ),
)


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


agent = Agent(model, output_type=Profile)

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

هذا يعمل لأن كلا نموذجي Gonka (Kimi K2.6 و MiniMax M2.7) يدعمان tool calling أصلي — ويعتمد PydanticAI عليه لإرجاع هيكل JSON صالح. المخرجات التي تحصل عليها هي كائن Python مفهرس (typed object)، وليس نصاً يحتاج إلى معالجة يدوية. مثالي لاستخراج البيانات، التصنيف، ملء النماذج وخطوط أنابيب RAG، حيث يجب أن تنتقل النتيجة عبر الكود بتنسيق صارم.

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

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

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

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

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

model = OpenAIChatModel(
    "MiniMaxAI/MiniMax-M2.7",
    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:
    """رمي نرد ذو 6 أوجه وإرجاع النتيجة."""
    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)

بما أن tool calling في Gonka أصلي (native)، يتم استدعاء الأدوات بشكل موثوق — بدون تحليل نصي هش للاستجابات. الدورة الكاملة (طلب ← استدعاء أداة ← استجابة نهائية) تكلف حوالي $0.00007 عبر Gonka مقابل $0.04–0.22 في OpenAI/Anthropic.

أي نموذج تختار: moonshotai/Kimi-K2.6 — قوي في البرمجة والاستدلال المعقد، المخرجات تصل إلى 8192. MiniMaxAI/MiniMax-M2.7 — للمحادثات الطويلة والمهام المتوازنة، المخرجات تصل إلى 8192. كلاهما متاح الآن بمفتاح واحد — فقط قم بتغيير اسم النموذج. أدوات مشابهة في الفلسفة: LangChain للسلاسل و RAG، LlamaIndex لفهرسة البيانات.