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

مفتاح API الخاص بـ JoinGonka: سجل على gate.joingonka.ai/register - في البداية نمنحك 10 ملايين رمز مجاني. في لوحة التحكم، أنشئ مفتاحًا بالبادئة 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-مفتاحك
});

const { text } = await generateText({
  model: gonka('Qwen/Qwen3-235B-A22B-Instruct-2507-FP8'),
  prompt: 'اشرح ما هي شبكة استدلال لامركزية',
});

console.log(text);

يضيف المعامل apiKey تلقائيًا عنوان Authorization: Bearer jg-مفتاحك - لا يلزم إعداد منفصل. قم بتخزين المفتاح في متغير البيئة 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.

مُعالج الخادم 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('Qwen/Qwen3-235B-A22B-Instruct-2507-FP8'),
    system: 'أنت مساعد مفيد. أجب باختصار ومباشرة.',
    messages: convertToModelMessages(messages),
    maxOutputTokens: 8192, // حد Qwen3-235B عبر Gateway
  });

  return result.toUIMessageStreamResponse();
}

على العميل، قم بربط الخطاف useChat من @ai-sdk/react - فهو يتصل بـ /api/chat ويقدم تدفق الرسائل بنفسه. يتصل الواجهة الخلفية بـ 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('Qwen/Qwen3-235B-A22B-Instruct-2507-FP8'),
  prompt: 'اكتب هايكو حول الحوسبة الموزعة',
});

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

معلمات النماذج. تتوفر ثلاث نماذج عبر Gateway، جميعها تحتوي على سياق 128 ألف رمز؛ يختلف حد الإخراج (maxOutputTokens):

• Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 - افتراضي، حتى 8192 رمز إخراج؛
• moonshotai/Kimi-K2.6 - حتى 3072 (Kimi K2.6)؛
• MiniMaxAI/MiniMax-M2.7 - حتى 4096 (MiniMax M2.7).

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

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

الفرق - في مئات وآلاف المرات. بالنسبة لتطبيق بآلاف الطلبات يوميًا، هذا هو الفرق بين فاتورة بمئات الدولارات وفاتورة بالبنسات. تكفي 10 ملايين رمز مجاني لتشغيل وتصحيح المشروع بالكامل قبل إطلاقه للإنتاج.

يصف Vercel AI SDK الأدوات بشكل إعلاني من خلال كائن tools ومخطط zod. يدعم Qwen3-235B استدعاء الوظائف الأصلي، لذلك يتلقى 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('Qwen/Qwen3-235B-A22B-Instruct-2507-FP8'),
  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.00001 دولار عبر Gonka مقابل 0.03-0.10 دولار مع Anthropic أو OpenAI. لتطبيقات الوكيل، حيث يتحول كل طلب مستخدم إلى 5-10 خطوات، يصل التوفير في الإنتاج إلى آلاف الدولارات شهريًا.

إذا كنت تقوم ببناء تطبيق AI في بايثون، فراجع دليل LangChain - هناك نفس النهج عبر فئة متوافقة مع OpenAI.