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-مفتاحك
  api: 'chat-completions',
  models: [
    'Qwen/Qwen3-235B-A22B-Instruct-2507-FP8', // الافتراضي
    'moonshotai/Kimi-K2.6',
    'MiniMaxAI/MiniMax-M2.7',
  ],
})

دردشة متدفقة على الخادم (على سبيل المثال، مُعالج مسار في أي إطار عمل كامل المكدس أو 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('Qwen/Qwen3-235B-A22B-Instruct-2507-FP8'),
    messages,
    modelOptions: { max_tokens: 8192 }, // حد Qwen عبر 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>
  )
}

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

معلمات النماذج عبر بوابة Gateway: السياق لجميع النماذج الثلاثة - 128 ألف رمز. الحد الأقصى لـ max_tokens: Qwen3-235B - 8192، Kimi K2.6 - 3072، MiniMax-M2.7 - 4096. إذا لم يتم تحديد max_tokens، فإن الافتراضي لغير البث هو 1500، لذا حدده صراحةً للإجابات الطويلة.

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

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

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

الميزة الرئيسية لـ TanStack AI هي عقد toolDefinition() الموحد: يتم وصف الأداة مرة واحدة (المدخل/المخرج عبر Zod أو ArkType أو Valibot أو JSON Schema)، ويتم ربط التنفيذ بالخادم أو العميل. يدعم Qwen3-235B و Kimi K2.6 و MiniMax-M2.7 استدعاء الأدوات الأصلية عبر 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('Qwen/Qwen3-235B-A22B-Instruct-2507-FP8'),
  messages: [{ role: 'user', content: 'ما هو الطقس في موسكو؟' }],
  tools: [getWeather],
  modelOptions: { max_tokens: 8192 },
})

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

• Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 — الافتراضي. أكبر سقف للاستجابة (8192) واستدعاء أدوات قوي. مناسب للوكلاء والإخراج المنظم.
• moonshotai/Kimi-K2.6 — ممتاز للحوارات الطويلة والتفكير. سقف الاستجابة 3072.
• MiniMaxAI/MiniMax-M2.7 — توازن بين السرعة والجودة، سقف 4096.

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