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

مفتاح API الخاص بـ JoinGonka: سجل في gate.joingonka.ai/register — نمنحك 10M توكن مجاني عند البدء. في 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 هي دفق الاستجابة. تبدأ دالة streamText ببث التوكنات فورًا، ويقوم المساعد toUIMessageStreamResponse() بإخراج الدفق الجاهز مباشرة من معالج المسارات في Next.js App Router.

معالج الخادم (Server handler) 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 ألف توكن؛ سقف الاستجابة (maxOutputTokens) يصل إلى 8192 لكل منهما:

• moonshotai/Kimi-K2.6 — الافتراضي (Kimi K2.6);
• MiniMaxAI/MiniMax-M2.7 (MiniMax M2.7).

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

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

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

يقوم Vercel AI SDK بوصف الأدوات بشكل توضيحي من خلال كائن tools ومخطط zod. يدعم Kimi K2.6 استدعاء الوظائف (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. بالنسبة للتطبيقات الوكيلة (agentic)، حيث يتوسع كل طلب من المستخدم إلى 5-10 خطوات، يتم قياس التوفير في بيئة الإنتاج بآلاف الدولارات شهرياً.

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