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

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

التثبيت:

pip install pydantic-ai
# or the slim variant with only the OpenAI dependencies:
# 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(
    "MiniMaxAI/MiniMax-M2.7",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-your-key",
    ),
)

agent = Agent(model)

result = agent.run_sync("Explain in two sentences what PoUW is")
print(result.output)

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

معاملات الموديلات: نافذة السياق في MiniMax M2.7 هي 180K توكن (180000)، وفي DeepSeek V4 Flash هي 380K، وفي GLM-5.3 Flash هي 390K؛ والحد الأقصى لطول الاستجابة عبر Gateway يصل إلى 8192 توكن في MiniMax وGLM-5.3 Flash، وإلى 32768 في DeepSeek. يمكنك تحديد المخرجات عبر إعدادات الموديل (OpenAIChatModelSettings(max_tokens=8192)). المتاح حاليًا: MiniMaxAI/MiniMax-M2.7 وdeepseek-ai/DeepSeek-V4-Flash-0731 وzai-org/GLM-5.3-Flash — كل ما عليك فعله هو تغيير اسم الموديل في الوسيط الأول لـ OpenAIChatModel.

السبب الرئيسي لاختيار PydanticAI هو structured output. فبدلًا من تحليل نص الاستجابة بتعابير regex، تصف النتيجة على هيئة Pydantic model وتمرّرها إلى الوسيط 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-your-key",
    ),
)


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


agent = Agent(model, output_type=Profile)

result = agent.run_sync(
    "Extract the data: Anna is a backend developer who knows Python, Go and Postgres"
)
print(result.output)
# name='Anna' role='backend developer' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — already a list[str], not text

وهذا يعمل لأن موديلات Gonka الثلاثة (MiniMax M2.7 وDeepSeek V4 Flash وGLM-5.3 Flash) تدعم tool calling الأصيل — ويعتمد عليه PydanticAI لإرجاع بنية JSON صحيحة. فتحصل في النهاية على كائن Python مُحدَّد النوع، لا على نص عليك تحليله يدويًا. مثالي لاستخراج البيانات والتصنيف وملء النماذج ومسارات RAG، حيث يجب أن تنتقل النتيجة داخل الشيفرة بصيغة صارمة.

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

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

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

القدرة الأساسية الثانية في PydanticAI هي الأدوات (tools). يمكنك تسجيل دالة عبر الديكوريتر @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(
    "MiniMaxAI/MiniMax-M2.7",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-your-key",
    ),
)

agent = Agent(
    model,
    instructions="You are an assistant. Use the tools when needed.",
)


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


@agent.tool_plain
def calculator(expression: str) -> str:
    """Evaluates a math expression."""
    return str(eval(expression))


result = agent.run_sync("Roll the die and multiply the result by 7")
print(result.output)

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

أي موديل تختار: MiniMaxAI/MiniMax-M2.7 — للمحادثات الطويلة والمهام المتوازنة، بمخرجات تصل إلى 8192. deepseek-ai/DeepSeek-V4-Flash-0731 — من أطول السياقات في الشبكة (380K) مع برومبتات كبيرة رخيصة، ومخرجات تصل إلى 32768. zai-org/GLM-5.3-Flash — موديل reasoning للاستدلالات المعقدة، وصاحب أطول سياق في الشبكة (390K)، بمخرجات تصل إلى 8192؛ ويستهلك الاستدلال جزءًا من max_tokens، فاضبطه بهامش (من 600 فما فوق). الثلاثة متاحة الآن بمفتاح واحد — يكفي تغيير سطر الموديل. أدوات شبيهة بالفكرة: LangChain للسلاسل وRAG، وLlamaIndex لفهرسة البيانات.