راهنمای OpenAI Node.js SDK با API پیکو هوش

با stream_options.include_usage در آخرین رویداد ممکن است choices خالی و فقط usage باشد؛ به همین دلیل از ?. استفاده شده است. می‌توانید با stream.controller.abort() استریم را قطع کنید.

سرور Express با استریم به مرورگر

import express from 'express';
import { client } from './client.js';

const app = express();
app.use(express.json());

app.post('/chat', async (req, res) => {
  res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('X-Accel-Buffering', 'no');

  try {
    const stream = await client.chat.completions.create({
      model: 'claude-haiku-5-5',
      messages: req.body.messages,
      stream: true,
      max_tokens: 500,
    });
    req.on('close', () => stream.controller.abort());
    for await (const chunk of stream) {
      const delta = chunk.choices[0]?.delta?.content;
      if (delta) res.write(`data: ${JSON.stringify({ delta })}\n\n`);
    }
    res.write('data: [DONE]\n\n');
  } catch (err) {
    res.write(`event: error\ndata: ${JSON.stringify({ message: 'خطا در پردازش' })}\n\n`);
  } finally {
    res.end();
  }
});

app.listen(3000);

اگر کاربر صفحه را ببندد، abort از ادامه‌ی تولید و مصرف بی‌مورد جلوگیری می‌کند. حتماً احراز هویت و محدودیت نرخ برای این مسیر بگذارید.

مدیریت خطا

import OpenAI from 'openai';

try {
  await client.chat.completions.create({
    model: 'gpt-6-sol',
    messages: [{ role: 'user', content: 'سلام' }],
  });
} catch (e) {
  if (e instanceof OpenAI.APIError) {
    console.error(e.status, e.code, e.message);
    if (e.status === 429) {
      // بسته به نسخه‌ی SDK، headers شیء ساده یا Headers استاندارد است
      const h: any = e.headers;
      console.error('Retry-After:', h?.get ? h.get('retry-after') : h?.['retry-after']);
    }
  } else {
    throw e;
  }
}

زیرکلاس‌هایی مثل OpenAI.BadRequestError، OpenAI.AuthenticationError، OpenAI.PermissionDeniedError، OpenAI.NotFoundError، OpenAI.RateLimitError، OpenAI.InternalServerError، OpenAI.APIConnectionError و OpenAI.APIConnectionTimeoutError هم وجود دارند (طبق README رسمی). تلاش مجدد پیش‌فرض ۲ بار برای خطای اتصال و وضعیت‌های 408، 409، 429 و 5xx است و timeout پیش‌فرض SDK ۱۰ دقیقه است. بدنه‌ی خطای پیکو هوش error.code مثل insufficient_balance دارد؛ جدول کامل در کدهای خطا.

تنظیم برای هر درخواست

await client.chat.completions.create(
  { model: 'gpt-6-luna', messages: [{ role: 'user', content: 'سلام' }] },
  { maxRetries: 5, timeout: 120_000 },
);

از آنجا که درخواست ناموفق هزینه ندارد، تلاش مجدد از نظر مالی بی‌خطر است.

Function calling و JSON

پارامتر tools را همان‌طور که در مستندات OpenAI آمده بفرستید؛ مثال کامل در راهنمای Function Calling است. برای تصویر و گفتار می‌توانید client.images.generate و client.audio.speech.create را با مدل‌های مربوطه به کار ببرید (جزئیات در مستندات). client.embeddings پشتیبانی نمی‌شود.

نکات تولید

1. یک نمونه‌ی کلاینت بسازید و مشترکاً استفاده کنید.
2. max_tokens و timeout را حتماً بگذارید.
3. مصرف usage را لاگ کنید؛ تخمین هزینه.
4. در Next.js کلید را فقط در Route Handler یا Server Action بخوانید. (برای استفاده‌ی آماده‌تر: Vercel AI SDK).
5. خطاهای 429 را با backoff و Retry-After مدیریت کنید.

عیب‌یابی

نمونه‌ی ماژول سرویس در TypeScript

// services/ai.ts
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: process.env.PICO_BASE_URL ?? 'https://api.picoai.ir/v1',
  apiKey: process.env.PICO_API_KEY,
  maxRetries: 3,
});

export async function classify(text: string): Promise<'positive' | 'negative' | 'neutral'> {
  const r = await client.chat.completions.create({
    model: 'claude-haiku-5-5',
    messages: [
      { role: 'system', content: 'فقط یکی از کلمات positive, negative, neutral را بنویس.' },
      { role: 'user', content: text.slice(0, 4000) },
    ],
    max_tokens: 5,
    temperature: 0,
  });
  const out = r.choices[0].message.content?.trim().toLowerCase();
  return out === 'positive' || out === 'negative' ? out : 'neutral';
}

این الگو برای کارهای ساده‌ی دسته‌بندی بسیار ارزان است چون خروجی فقط چند توکن دارد. ورودی را کوتاه کنید و خروجی را اعتبارسنجی کنید.

Next.js و Server Actions

در Next.js (App Router) کلاینت را فقط در فایل‌های سروری (Route Handler، Server Action) import کنید و متغیر محیطی را بدون پیشوند NEXT_PUBLIC_ بگذارید تا به باندل مرورگر نرود. برای استریم آماده‌تر و هوک‌های React می‌توانید Vercel AI SDK را استفاده کنید.

تست

برای تست واحد، کلاینت را تزریق (inject) کنید یا ماژول را mock کنید تا آزمون‌ها درخواست پولی نفرستند. برای تست یکپارچه از مدل اقتصادی و max_tokens کم استفاده کنید و یک سقف ماهانه‌ی کوچک برای کلید CI بگذارید.

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

فرق baseURL و base_url؟

همان مفهوم است؛ نام گزینه در Node baseURL و در Python base_url است.

آیا در مرورگر مستقیم می‌توان استفاده کرد؟

نه؛ کلید لو می‌رود. همیشه از سرور واسط استفاده کنید.

آیا Claude هم پشتیبانی می‌شود؟

بله، claude-sonnet-5-5 از همین مسیر.

مرجع؟

OpenAI Node در یکپارچه‌سازی‌ها، pricing، مستندات.