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

تثبيت الحزم (الأساسي + محول OpenAI الذي يحتوي على openaiCompatible):

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

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

لواجهة الدردشة في React، أضف العميل والربط:

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

مفتاح API الخاص بـ JoinGonka: إذا لم يكن لديك بعد - سجل على gate.joingonka.ai/register، احصل على 10 ملايين رمز مجاني وأنشئ مفتاح jg-xxx في لوحة التحكم -> مفاتيح API. يعمل مفتاح واحد ورصيد واحد لكلا تنسيقَي 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-your-key
  api: 'chat-completions',
  models: [
    'moonshotai/Kimi-K2.6', // الافتراضي
    'MiniMaxAI/MiniMax-M2.7',
  ],
})

دردشة البث (Streaming) على الخادم (على سبيل المثال، معالج المسار في أي إطار عمل fullstack أو 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
  })

  return toServerSentEventsResponse(stream)
}

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

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>
  )
}

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

معلمات النماذج عبر Gateway: سياق (context) كلا النموذجين هو 200K توكن. سقف max_tokens هو 8192 لجميع نماذج الشبكة. إذا لم يتم تحديد max_tokens، فإن الافتراضي لـ non-stream هو 1500، لذا للحصول على استجابات طويلة قم بتحديده بوضوح.

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

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

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

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

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 },
})

أي نموذج تختار:

• moonshotai/Kimi-K2.6 — قوي في البرمجة، الاستدلال، وسيناريوهات الوكلاء. سقف الاستجابة 8192.
• MiniMaxAI/MiniMax-M2.7 — الافتراضي، توازن بين السرعة والجودة، سياق طويل. سقف الاستجابة 8192.

بفضل ميزة runtime adapter switching في TanStack AI، يمكنك الاحتفاظ بكلا النموذجين في مزود واحد والتبديل بينهما أثناء التشغيل — على سبيل المثال، المهام الوكيلة الثقيلة على Kimi، والاستجابات السريعة على MiniMax.