Vercel AI SDK با پیکو هوش؛ streamText و generateText

streamText

import { streamText } from 'ai';

const result = streamText({
  model: pico('claude-haiku-5-5'),
  prompt: 'پنج نکته درباره‌ی امنیت API بنویس.',
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

Route Handler در Next.js (App Router)

// app/api/chat/route.ts
import { streamText, convertToModelMessages, type UIMessage } from 'ai';
import { pico } from '@/lib/pico';

export const maxDuration = 60;

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();
  const result = streamText({
    model: pico('claude-sonnet-5-5'),
    system: 'تو دستیار فنی مودب هستی.',
    messages: convertToModelMessages(messages), // نسخه‌ی ۵ (در نسخه‌ی ۶ ممکن است async باشد؛ با await هم بی‌ضرر است)
  });
  return result.toUIMessageStreamResponse(); // نسخه‌ی ۴: toDataStreamResponse() و messages بدون تبدیل
}

در کلاینت می‌توانید از هوک useChat در بسته‌ی @ai-sdk/react استفاده کنید. نام متدهای پاسخ و هوک بین نسخه‌ها متفاوت است (مستند مهاجرت v5: toDataStreamResponse به toUIMessageStreamResponse و CoreMessage به ModelMessage تغییر کرد)؛ نسخه‌ی نصب‌شده را بررسی کنید.

ابزار (Tool)

import { generateText, tool, stepCountIs } from 'ai';
import { z } from 'zod';

const { text } = await generateText({
  model: pico('gpt-6-sol'),
  tools: {
    celsiusToF: tool({
      description: 'تبدیل سانتی‌گراد به فارنهایت',
      inputSchema: z.object({ c: z.number() }), // نسخه‌ی ۴: parameters
      execute: async ({ c }) => c * 9 / 5 + 32,
    }),
  },
  stopWhen: stepCountIs(3), // نسخه‌ی ۴: maxSteps: 3 ؛ در مستندات جدیدتر نام این تابع isStepCount ثبت شده
  prompt: 'سی درجه‌ی سانتی‌گراد چند فارنهایت است؟',
});

اجرای ابزار بر پایه‌ی function calling مدل است؛ اصول پروتکل در راهنمای Function Calling آمده است. پشتیبانی هر مدل از ابزار را آزمایش کنید.

نکات تولید

• سقف خروجی را همیشه تنظیم کنید.
• خطاها: APICallError شامل statusCode و در صورت وجود responseHeaders است؛ برای 429 و 503 از maxRetries (پیش‌فرض ۲) و تأخیر استفاده کنید. جزئیات: کدهای خطا و Retry.
• Edge: Route Handler روی Edge هم کار می‌کند، اما برای پاسخ طولانی maxDuration را تنظیم کنید.
• احراز هویت و نرخ: مسیر /api/chat عمومی هزینه‌ی شما را می‌سوزاند؛ محدودیت نرخ و ورود کاربر بگذارید.
• هزینه: تخمین هزینه و pricing.

محدودیت: embeddings

تابع embed و embedMany در SDK برای مدل‌های embedding است. پیکو هوش اندپوینت embeddings ندارد، پس این توابع را به آن وصل نکنید.

عیب‌یابی

خروجی ساخت‌یافته با generateObject

برای دریافت خروجی با schema مشخص:

import { generateObject } from 'ai';
import { z } from 'zod';

const { object } = await generateObject({
  model: pico('gpt-6-sol'),
  schema: z.object({
    title: z.string(),
    tags: z.array(z.string()).max(5),
  }),
  prompt: 'برای مقاله‌ای درباره‌ی کش HTTP عنوان و برچسب پیشنهاد بده.',
});
console.log(object);

در مستندات جدید، روش پیشنهادی generateText با output: Output.object({ schema }) (import از ai) و خواندن output از نتیجه است؛ generateObject در نسخه‌های ۴ و ۵ وجود دارد، اما برای نسخه‌ی جدید مستندات خود را ببینید. پشتیبانی از حالت JSON/ابزار در openai-compatible ممکن است نیاز به گزینه‌ی supportsStructuredOutputs داشته باشد؛ در صورت خطا، آن را تنظیم یا مدل دیگری امتحان کنید.

چت کامل با useChat

سمت کلاینت در React:

'use client';
import { useState } from 'react';
import { useChat } from '@ai-sdk/react';

export default function Chat() {
  const [input, setInput] = useState('');
  const { messages, sendMessage, status } = useChat(); // مسیر پیش‌فرض: /api/chat
  return (
    <form
      dir="rtl"
      onSubmit={(e) => {
        e.preventDefault();
        sendMessage({ text: input });
        setInput('');
      }}
    >
      {messages.map((m) => (
        <p key={m.id}>
          {m.role}: {m.parts.map((p) => (p.type === 'text' ? p.text : '')).join('')}
        </p>
      ))}
      <input value={input} onChange={(e) => setInput(e.target.value)} disabled={status !== 'ready'} />
    </form>
  );
}

این قطعه برای نسخه‌ی ۵ است: در v5 مقادیر input، handleInputChange و handleSubmit حذف شده‌اند، state ورودی را خودتان نگه می‌دارید، sendMessage جایگزین append شده و محتوای پیام در message.parts است. در نسخه‌ی ۴ همان input/handleSubmit/m.content درست است.

امنیت مسیر چت

مسیر /api/chat را بدون محدودیت منتشر نکنید. حداقل: احراز هویت کاربر، محدودیت نرخ بر اساس کاربر یا IP، سقف طول پیام و سقف maxOutputTokens. این کنترل‌ها جلوی مصرف ناخواسته‌ی موجودی شما را می‌گیرند. همچنین تعداد پیام‌های تاریخچه را در سرور کوتاه کنید تا هزینه‌ی هر درخواست از کنترل خارج نشود.

سوالات متداول

آیا بسته‌ی @ai-sdk/openai هم کار می‌کند؟

بله، با createOpenAI({ baseURL, apiKey }). اما openai-compatible برای سرویس‌های غیر رسمی سازگارتر است.

آیا با Claude کار می‌کند؟

بله، با pico('claude-sonnet-5-5').

مرجع؟

Vercel AI SDK در یکپارچه‌سازی‌ها، مستندات.