TanStack AI + Gonka — 低成本的 TypeScript AI 应用程序

安装包（核心 + 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 密钥：如果还没有密钥 — 请在 gate.joingonka.ai/register 注册，获取 3M 免费 token，并在 Dashboard → API Keys 中创建 jg-xxx 密钥。一个密钥和一个余额可同时用于 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', // 推理模型
  ],
})

服务器端的流式聊天（例如 任何全栈框架 或 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 hook —— 将服务器的响应流式传输到 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 的模型参数：上下文 —— MiniMax M2.7 为 200K token，DeepSeek V4 Flash 为 380K，GLM-5.3 Flash 为 390K。max_tokens 限制 —— MiniMax M2.7 和 GLM-5.3 Flash 为 8192，DeepSeek V4 Flash 为 32768。如果不指定 max_tokens，非流式请求的默认值为 1500，因此对于长回复，请明确指定该值。

TanStack AI 通过 OpenAI/Anthropic 直连费率或通过 Gonka 运行的效果完全一致，唯一需要更改的是 baseURL。但成本却有数量级的差异。让我们比较一下 TanStack AI 应用在生产环境下的典型负载：

TanStack AI 的与供应商无关的架构意味着切换到 Gonka 只需修改一行代码（baseURL），而无需重写代码。同时，你的类型安全工具、结构化输出和 React Hooks 将保持不变。对于拥有数千名用户的应用来说，这每月能节省数万美元的成本。

Gonka 定价：输入每 1M tokens 约 $0.0069，输出价格 ×3。这比 OpenAI 和 Anthropic 的直接费率便宜了数百到数千倍。

TanStack AI 的核心特色是统一的 toolDefinition() 契约：只需定义一次工具（通过 Zod、ArkType、Valibot 或 JSON Schema 进行输入/输出定义），即可在服务端或客户端绑定实现。MiniMax M2.7、DeepSeek V4 Flash 和 GLM-5.3 Flash 通过 Gonka 支持原生 tool calling，因此 Agent 的运行非常稳定——无需解析文本回复。

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），大 Prompt 成本低。回复上限 32768。
• zai-org/GLM-5.3-Flash — 推理模型：回答前进行思考，擅长复杂逻辑；网络中最长上下文（390K）。回复上限 8192；推理过程会消耗部分 max_tokens。

借助 TanStack AI 的运行时 adapter switching，您可以将三个模型保留在同一个 Provider 中并即时切换——例如，使用 GLM-5.3 Flash 处理推理任务，使用 MiniMax 处理快速响应。