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

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

التثبيت:

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

مثال مبسط — وكيل (Agent) عبر 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-مفتاحك",
    ),
)

agent = Agent(model)

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

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

معلمات النموذج: نافذة السياق لنموذج MiniMax M2.7 هي 200K توكن (200000)، ولدى 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 وتمريرها إلى المعامل 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 الثلاثة (MiniMax M2.7 و DeepSeek V4 Flash و GLM-5.3 Flash) تدعم تقنية tool calling بشكل أصلي — يعتمد PydanticAI عليها لإرجاع هيكل JSON صالح. في النهاية تحصل على كائن Python مكتوب النمط (typed object)، وليس سلسلة نصية تحتاج إلى فكها يدوياً. مثالي لاستخراج البيانات، والتصنيف، وملء النماذج، وخطوط معالجة 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-ваш-ключ",
    ),
)

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)

بما أن استدعاء الأدوات (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 — نموذج تفكير للاستدلالات المعقدة وأطول سياق في الشبكة (390K)، مخرجات تصل إلى 8192؛ تستهلك الاستدلالات جزءًا من max_tokens، لذا قم بتعيينها بهامش (من 600). النماذج الثلاثة متاحة الآن بمفتاح واحد — يتم تغيير سطر النموذج فقط. أدوات مشابهة في المفهوم: LangChain للسلاسل و RAG، و LlamaIndex لفهرسة البيانات.