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 وقائمة النماذج مرّة واحدة، ثم تختار النموذج في كل استدعاء. بوابةنا تتحدّث بصيغة Chat Completions، لذلك نُبقي api: 'chat-completions' (وهي القيمة الافتراضية).

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

// Gonka provider: configured once
export const gonka = openaiCompatible({
  name: 'gonka',
  baseURL: 'https://gate.joingonka.ai/v1',
  apiKey: process.env.GONKA_API_KEY!, // jg-your-key
  api: 'chat-completions',
  models: [
    'MiniMaxAI/MiniMax-M2.7', // default
    'deepseek-ai/DeepSeek-V4-Flash-0731',
    'zai-org/GLM-5.3-Flash', // reasoning model
  ],
})

محادثة بثّية على الخادم (مثلًا معالج مسار في أي إطار عمل متكامل أو TanStack Start). نضبط طول الإجابة عبر modelOptions — وهي النقطة الوحيدة لمعاملات wire الأصلية (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 output cap
  })

  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('What is Gonka?')}>
        Ask
      </button>
    </div>
  )
}

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

معاملات النماذج عبر Gateway: السياق — 180K رمز لدى MiniMax M2.7، و380K لدى DeepSeek V4 Flash، و390K لدى GLM-5.3 Flash. سقف max_tokens — 8192 لدى MiniMax M2.7 وGLM-5.3 Flash، و32768 لدى DeepSeek V4 Flash. إذا لم يُحدَّد max_tokens، فالافتراضي لغير البثّ هو 1500، لذا للإجابات الطويلة حدّده صراحةً.

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

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

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

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

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

const getWeather = toolDefinition({
  name: 'getWeather',
  description: 'Get the weather in a city',
  inputSchema: z.object({ city: z.string() }),
  outputSchema: z.object({ tempC: z.number() }),
}).server(async ({ city }) => {
  return { tempC: 21 } // your real API call
})

const stream = chat({
  adapter: gonka('MiniMaxAI/MiniMax-M2.7'),
  messages: [{ role: 'user', content: 'What is the weather in Moscow?' }],
  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 — نموذج استدلال: يفكر قبل الرد، وقوي في المنطق المعقّد؛ الأطول سياقاً في الشبكة (390K). سقف الرد 8192؛ ويستهلك التفكير جزءاً من max_tokens.

بفضل تبديل المحوّلات في وقت التشغيل ضمن TanStack AI، يمكنك الاحتفاظ بالنماذج الثلاثة لدى مزوّد واحد والتبديل بينها فوراً — مثلاً، مهام الاستدلال على GLM-5.3 Flash، والردود السريعة على MiniMax.