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

JoinGonka API-key: قم بالتسجيل في 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: 'اشرح ما هي شبكة الاستنتاج اللامركزية',
});

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 في بث الاستجابة (streaming). تبدأ وظيفة streamText في بث الرموز (tokens) فوراً، ويقوم المساعد 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,
});

// السماح بالبث لمدة تصل إلى 30 ثانية
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: 'أنت مساعد مفيد. أجب بإيجاز وفي صلب الموضوع.',
    messages: convertToModelMessages(messages),
    maxOutputTokens: 8192, // سقف الإخراج عبر Gateway
  });

  return result.toUIMessageStreamResponse();
}

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

نص برمجي بدون واجهة مستخدم (Node، مكرر غير متزامن للتدفق):

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: 'اكتب قصيدة هايكو عن الحوسبة الموزعة',
});

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

معلمات النماذج. تتوفر ثلاثة نماذج عبر Gateway: سياق 200 ألف رمز (tokens) لـ MiniMax M2.7، و380 ألف لـ DeepSeek V4 Flash، و390 ألف لـ 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، سياق 380 ألف);
• zai-org/GLM-5.3-Flash (GLM-5.3 Flash، نموذج استنتاجي — يقوم بالاستدلال قبل الرد).

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

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

سعر JoinGonka يبلغ حوالي $0.0069 لكل 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: 'Узнать погоду в городе',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ city, tempC: 17 }),
    }),
  },
  prompt: 'Какая погода в Москве? Ответь одним предложением.',
});

console.log(text);

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

إذا كنت تبني تطبيق AI باستخدام Python، ألقِ نظرة على دليل LangChain — هناك نفس النهج عبر فئة متوافقة مع OpenAI.