Vercel AI SDK + Gonka AI - تطبيقات AI على TypeScript بتكلفة زهيدة

مفتاح API الخاص بـ JoinGonka: سجّل في gate.joingonka.ai/register — نمنحك في البداية 3M توكن مجاني. وفي Dashboard أنشئ مفتاحًا يبدأ بالبادئة jg-.

تثبيت الحزم. لنقطة نهاية مخصصة متوافقة مع OpenAI، يوصي Vercel AI SDK بالمزوّد @ai-sdk/openai-compatible:

npm install ai @ai-sdk/openai-compatible

أبسط طريقة للاتصال — ننشئ نسخة من المزوّد عبر createOpenAICompatible ثم نستدعي generateText:

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText } from 'ai';

const gonka = createOpenAICompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY, // jg-your-key
});

const { text } = await generateText({
  model: gonka('MiniMaxAI/MiniMax-M2.7'),
  prompt: 'Explain what a decentralized inference network is',
});

console.log(text);

المعامل apiKey يضيف تلقائيًا الترويسة Authorization: Bearer jg-your-key — دون أي إعداد إضافي. احفظ المفتاح في متغير البيئة GONKA_API_KEY (مثلًا في .env.local) لا داخل الكود.

البديل — حزمة @ai-sdk/openai مع الدالة createOpenAI({ baseURL, apiKey }). الطريقتان فعّالتان؛ لكن لنقاط النهاية غير التابعة لـ OpenAI، تنصح وثائق AI SDK باستخدام @ai-sdk/openai-compatible تحديدًا — فهو لا يحمل معه افتراضات إضافية خاصة بـ OpenAI.

أبرز ميزات Vercel AI SDK هي إرجاع الرد على شكل بثّ مباشر. الدالة streamText تبدأ ببثّ التوكنات فورًا، بينما يمرّر المساعد toUIMessageStreamResponse() البثّ الجاهز مباشرة من route handler في Next.js App Router.

معالج الخادم app/api/chat/route.ts:

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { streamText, convertToModelMessages, type UIMessage } from 'ai';

const gonka = createOpenAICompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY,
});

// allow streaming for up to 30 seconds
export const maxDuration = 30;

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();

  const result = streamText({
    model: gonka('MiniMaxAI/MiniMax-M2.7'),
    system: 'You are a helpful assistant. Answer briefly and to the point.',
    messages: convertToModelMessages(messages),
    maxOutputTokens: 8192, // Gateway output cap
  });

  return result.toUIMessageStreamResponse();
}

على جانب العميل، اربط الخطّاف useChat من @ai-sdk/react — فهو يتصل بنفسه بـ /api/chat ويعرض تدفّق الرسائل. وهنا يتوجّه الـ backend إلى Gonka لا إلى OpenAI.

سكربت بدون واجهة (Node، عبر async-iterator على البثّ):

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { streamText } from 'ai';

const gonka = createOpenAICompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY,
});

const result = streamText({
  model: gonka('MiniMaxAI/MiniMax-M2.7'),
  prompt: 'Write a haiku about distributed computing',
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

معاملات الموديلات. عبر Gateway تتوفر ثلاثة موديلات: سياق 180K توكن مع MiniMax M2.7، و380K مع DeepSeek V4 Flash، و390K مع GLM-5.3 Flash؛ أما سقف الرد (maxOutputTokens) فهو 8192 مع MiniMax M2.7 وGLM-5.3 Flash، و32768 مع DeepSeek V4 Flash:

• MiniMaxAI/MiniMax-M2.7 — الافتراضي (MiniMax M2.7)؛
• deepseek-ai/DeepSeek-V4-Flash-0731 (DeepSeek V4 Flash، سياق 380K)؛
• zai-org/GLM-5.3-Flash (GLM-5.3 Flash، موديل reasoning — يفكّر قبل أن يجيب).

إذا لم تحدّد maxOutputTokens، فسيعيد Gateway افتراضيًا حتى 1500 توكن للطلب غير المتدفّق — ومع الدردشة المتدفّقة الأفضل تحديد القيمة صراحةً.

عادة ما يكون Vercel AI SDK خلف واجهة تفاعلية — محادثة، وكيل، مساعد في التطبيق. كل رسالة تجلب معها سجل الحوار، وكل خطوة يقوم بها الوكيل تجلب سياق الأدوات. لذلك، يتم حساب التكلفة الفعلية ليس حسب طلب واحد، بل حسب حمل الإنتاج (prod). لنقارن السيناريوهات النموذجية:

سعر JoinGonka يبلغ حوالي $0.0062 لكل 1M توكن عند الإدخال، ويكون المخرج أغلى بثلاث مرات تقريبًا. بالنسبة لتطبيق يحتوي على آلاف الطلبات يوميًا، هذا هو الفرق بين فاتورة بمئات الدولارات وفاتورة ببضعة سنتات. 3M توكن مجاني كافية لتشغيل الطلبات الأولى للمشروع.

يعتمد Vercel AI SDK أسلوبًا تصريحيًا في تعريف الأدوات عبر الكائن tools ومخطط zod. تدعم نماذج الشبكة استدعاء الدوال الأصلي (function calling)، لذا يتلقى AI SDK استدعاءات tool_calls منظمة دون تحليل الردود النصية. تتيح المعلمة stopWhen: stepCountIs(n) تنفيذ عدة خطوات متتالية — يستدعي النموذج الأداة، ويستلم النتيجة، ثم يواصل.

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText, tool, stepCountIs } from 'ai';
import { z } from 'zod';

const gonka = createOpenAICompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY,
});

const { text } = await generateText({
  model: gonka('MiniMaxAI/MiniMax-M2.7'),
  stopWhen: stepCountIs(5),
  tools: {
    weather: tool({
      description: 'Get the weather in a city',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ city, tempC: 17 }),
    }),
  },
  prompt: 'What is the weather in Moscow? Answer in one sentence.',
});

console.log(text);

يستدعي النموذج الأداة weather، ويستلم النتيجة، ثم يصوغ الرد النهائي. تكلّف الدورة كاملة نحو $0.000048 عبر Gonka مقابل $0.03-0.10 لدى Anthropic أو OpenAI. وفي تطبيقات الوكلاء (agents)، حيث يتحول كل طلب من المستخدم إلى 5-10 خطوات، تُقاس التوفيرات في بيئة الإنتاج بآلاف الدولارات شهريًا.

إذا كنت تبني تطبيق ذكاء اصطناعي بلغة Python، فاطّلع على الدليل الخاص بـ LangChain — فيه النهج نفسه عبر فئة متوافقة مع OpenAI.