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

تثبيت الحزم (النواة + محول OpenAI، حيث يعيش openaiCompatible):

# pnpm
pnpm add @tanstack/ai @tanstack/ai-openai

# npm
npm install @tanstack/ai @tanstack/ai-openai

لواجهة المحادثة في React أضف العميل والخطافات (hooks):

pnpm add @tanstack/ai-client @tanstack/ai-react

JoinGonka API-key: إذا لم يكن لديك واحد بعد — سجل في gate.joingonka.ai/register، واحصل على 3M توكن مجاني وأنشئ مفتاح jg-xxx في Dashboard → API Keys. مفتاح واحد ورصيد واحد يعملان مع كل من صيغتي OpenAI و Anthropic.

في TanStack AI، يتم تكوين مزود مخصص متوافق مع OpenAI باستخدام وظيفة openaiCompatible(): تحدد baseURL و apiKey وقائمة النماذج مرة واحدة، ثم تختار النموذج لكل استدعاء. بوابة (Gateway) الخاصة بنا تستخدم تنسيق Chat Completions، لذلك نترك api: 'chat-completions' (هذه هي القيمة الافتراضية).

import { openaiCompatible } from '@tanstack/ai-openai'

// مزود Gonka — يتم تكوينه مرة واحدة
export const gonka = openaiCompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY!, // jg-مفتاحك
  api: 'chat-completions',
  models: [
    'MiniMaxAI/MiniMax-M2.7', // الافتراضي
    'deepseek-ai/DeepSeek-V4-Flash-0731',
    'zai-org/GLM-5.3-Flash', // نموذج استنتاجي
  ],
})

محادثة البث على الخادم (على سبيل المثال، معالج المسار في أي إطار عمل fullstack أو TanStack Start). نحدد طول الاستجابة عبر modelOptions — وهي النقطة الوحيدة لمعلمات الشبكة الأصلية (max_tokens، temperature):

import { chat, toServerSentEventsResponse } from '@tanstack/ai'
import { gonka } from './gonka'

export async function POST(request: Request) {
  const { messages } = await request.json()

  const stream = chat({
    adapter: gonka('MiniMaxAI/MiniMax-M2.7'),
    messages,
    modelOptions: { max_tokens: 8192 }, // سقف الإخراج عبر Gateway
  })

  return toServerSentEventsResponse(stream)
}

عميل React عبر الخطاف useChat — يبث الردود من الخادم إلى واجهة المستخدم:

import { useChat } from '@tanstack/ai-react'

function Chat() {
  const { messages, sendMessage, status } = useChat({ api: '/api/chat' })

  return (
    <div>
      {messages.map((m) => (
        <p key={m.id}><b>{m.role}:</b> {m.content}</p>
      ))}
      <button onClick={() => sendMessage('ما هو Gonka؟')}>
        اسأل
      </button>
    </div>
  )
}

بدون خادم: يعمل نفس المزود في نص برمجي أو backend مباشرة — استدعِ chat() واقرأ التدفق. الاتصال بـ Gonka موحد لجميع الخيارات.

معلمات النماذج عبر Gateway: السياق — 200 ألف رمز لـ MiniMax M2.7، و380 ألف لـ DeepSeek V4 Flash، و390 ألف لـ GLM-5.3 Flash. سقف max_tokens — 8192 لـ MiniMax M2.7 وGLM-5.3 Flash، و32768 لـ DeepSeek V4 Flash. إذا لم يتم تحديد max_tokens، فإن الافتراضي لـ non-stream هو 1500، لذا بالنسبة للردود الطويلة، حددها بشكل صريح.

يعمل TanStack AI بنفس الكفاءة سواء عبر أسعار OpenAI/Anthropic المباشرة أو عبر Gonka — التغيير الوحيد هو في baseURL. لكن السعر يختلف بشكل كبير. لنقارن أحمال العمل النموذجية لتطبيق إنتاجي باستخدام TanStack AI:

نهج TanStack AI المستقل عن المزود يعني أن الانتقال إلى Gonka يتطلب تعديل سطر واحد فقط (baseURL) دون إعادة كتابة الكود. في الوقت نفسه، تظل أدواتك الآمنة نوعياً ومخرجاتك المهيكلة وخطافات React كما هي. بالنسبة لتطبيق يضم آلاف المستخدمين، يمثل هذا الفرق عشرات الآلاف من الدولارات شهرياً.

سعر Gonka: الإدخال ~$0.0069 لكل مليون رمز، والإخراج ×3. وهذا أرخص بمئات إلى آلاف المرات من الأسعار المباشرة لـ OpenAI و Anthropic.

الميزة الرئيسية لـ TanStack AI هي العقد الموحد toolDefinition(): يتم وصف الأداة مرة واحدة (المدخلات/المخرجات عبر Zod، ArkType، Valibot أو JSON Schema)، بينما يتم ربط التنفيذ على الخادم أو العميل. تدعم MiniMax M2.7 وDeepSeek V4 Flash وGLM-5.3 Flash خاصية native tool calling عبر Gonka، لذلك تعمل الوكلاء بشكل موثوق — دون تحليل الاستجابات النصية.

import { chat, toolDefinition } from '@tanstack/ai'
import { gonka } from './gonka'
import { z } from 'zod'

const getWeather = toolDefinition({
  name: 'getWeather',
  description: 'معرفة حالة الطقس في المدينة',
  inputSchema: z.object({ city: z.string() }),
  outputSchema: z.object({ tempC: z.number() }),
}).server(async ({ city }) => {
  return { tempC: 21 } // استدعاء API الفعلي الخاص بك
})

const stream = chat({
  adapter: gonka('MiniMaxAI/MiniMax-M2.7'),
  messages: [{ role: 'user', content: 'ما حالة الطقس في موسكو؟' }],
  tools: [getWeather],
  modelOptions: { max_tokens: 8192 },
})

كيفية اختيار النموذج:

• MiniMaxAI/MiniMax-M2.7 — الافتراضي، توازن بين السرعة والجودة، سياق طويل. الحد الأقصى للاستجابة 8192.
• deepseek-ai/DeepSeek-V4-Flash-0731 — أحد أطول سياقات الشبكة (380K)، مطالبات كبيرة رخيصة. الحد الأقصى للاستجابة 32768.
• zai-org/GLM-5.3-Flash — نموذج reasoning: يفكر قبل الإجابة، قوي في المنطق المعقد؛ أطول سياق في الشبكة (390K). الحد الأقصى للاستجابة 8192؛ تستهلك عمليات التفكير جزءاً من max_tokens.

بفضل runtime adapter switching في TanStack AI، يمكنك الاحتفاظ بجميع النماذج الثلاثة في موفر واحد والتبديل بينها فوراً — على سبيل المثال، المهام التي تتطلب تفكيراً على GLM-5.3 Flash، والإجابات السريعة على MiniMax.