متغیرهای محیطی را تنظیم کنید
PAASTA_AI_BASE_URL=https://console.paasta.cloud/api/ai/v1
PAASTA_AI_KEY=YOUR_SERVER_SIDE_API_KEY
PAASTA_AI_MODEL=MODEL_ID_FROM_LIVE_CATALOG
DEMO_ACCESS_TOKEN=YOUR_SEPARATE_RANDOM_TEST_TOKEN
این مقادیر باید در فایل محلی نادیدهگرفتهشده توسط Git یا تنظیمات Secret سرور قرار بگیرند. از پیشوند NEXT_PUBLIC_ برای هیچکدام از کلیدها استفاده نکنید. برای تولید توکن آزمایشی، یک مقدار تصادفی بلند بسازید و آن را با کلید اصلی مدل یکی نگیرید. مدل را از کاتالوگ API هوش مصنوعی انتخاب کنید و دسترسی همان مدل را روی کلید فعال نگه دارید.
برای شروع با مدلهای رایگان، صفحه API هوش مصنوعی رایگان را بررسی کنید. رایگان به معنی نامحدود یا همیشه در دسترس نیست. برنامه باید نبود ظرفیت، محدودیت نرخ و خطای سهمیه را بهصورت قابل فهم مدیریت کند. در شروع کار، خروجی کوتاه و یک کار مشخص، تشخیص خطا را آسانتر میکند.
Route Handler را اضافه کنید
فایل کامل handler.mjs را در پوشه src/lib پروژه قرار دهید. سپس فایل src/app/api/chat/route.js را با محتوای زیر بسازید. اگر پروژه پوشه src ندارد، مسیرها را مطابق ساختار خودش تغییر دهید.
import { createHandler } from '../../../lib/handler.mjs';
export const runtime = 'nodejs';
export const POST = createHandler();
در ساختار بالا، مسیر نسبی از src/app/api/chat به src/lib میرسد. تابع کامل پیش از تماس با مدل، پیکربندی، توکن دسترسی، نوع محتوا، حجم واقعی بدنه و طول prompt را بررسی میکند. فقط تکیهکردن به Content-Length کافی نیست؛ مقدار اعلامشده توسط کلاینت قابل اعتماد نیست.
هسته فراخوانی مدل در فایل نمونه چنین است:
const result = streamText({
model: provider.chatModel(env.PAASTA_AI_MODEL),
prompt: body.prompt,
maxOutputTokens: 400,
maxRetries: 0,
abortSignal: AbortSignal.any([
request.signal,
AbortSignal.timeout(60000)
])
});
return result.toTextStreamResponse({
headers: { 'Cache-Control': 'no-store' }
});
اعداد این نمونه انتخاب آموزشیاند، نه سقف رسمی سرویس. خروجی محدود، زمان انتظار مشخص و نبود تلاش مجدد خودکار کمک میکند هزینه آزمایش قابل کنترل بماند. افزایش سقف خروجی باید همراه با بررسی قیمت و ظرفیت باشد. جزئیات پاسخ جریانی را در مرجع streamText بررسی کنید.
اولین درخواست آزمایشی
برنامه را محلی اجرا کنید و از یک ترمینال Bash درخواست زیر را بفرستید. متغیر توکن باید در محیط همان ترمینال تنظیم شده باشد. خروجی مورد انتظار، متن تدریجی است؛ متن دقیق به مدل انتخابی بستگی دارد و پاسخ ثابتی برای آن وعده نمیدهیم.
curl --no-buffer http://localhost:3000/api/chat \
-H "Authorization: Bearer $DEMO_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"prompt":"در دو جمله کاربرد تست واحد را توضیح بده."}'
همین درخواست را بدون هدر دسترسی تکرار کنید؛ باید پیش از تماس با مدل رد شود. سپس JSON نامعتبر و متن بیش از حد مجاز بفرستید. تست فقط زمانی مفید است که مسیر شکست را هم بررسی کند. یک پاسخ موفق با یک prompt کوتاه، بهتنهایی امنیت یا آمادگی برنامه را ثابت نمی‌کند.
تست بدون هزینه مدل
فایلهای package.json نمونه و آزمون smoke را کنار handler قرار دهید. در یک پوشه جدا نصب و تست کنید؛ فایل package.json برنامه اصلی را با نمونه جایگزین نکنید. آزمون، URL درخواست، کلید آزمایشی، شناسه مدل و متن خروجی جریان را کنترل میکند.
npm install
npm test
این روش برای تشخیص خطای اتصال کتابخانه مناسب است، اما وضعیت حساب و شبکه واقعی را نمیسنجد. بعد از قبولی، یک درخواست زنده با بودجه محدود اجرا کنید و مصرف ثبتشده در پاستا را ببینید. کلید، prompt حساس یا پاسخ کامل مشتری را برای رفع اشکال در لاگ عمومی قرار ندهید.
استقرار روی هاست Next.js پاستا
پروژه را همراه فایل قفل و اسکریپتهای build و start منتشر کنید. در هاست Next.js پاستا متغیرهای سمت سرور را وارد کنید و بعد از آمادهشدن برنامه، ابتدا صفحه عادی و سپس مسیر چت را آزمایش کنید. کلید نباید برای ساخت bundle مرورگر استفاده شود. تغییر Secret ممکن است به اجرای مجدد سرویس نیاز داشته باشد؛ وضعیت انتشار را در کنسول بررسی کنید.
آدرس دامنه و HTTPS را پیش از ارائه به کاربر نهایی کنترل کنید. در شبکه واقعی، پاسخ جریانی را با curl نیز ببینید تا معلوم شود پاسخ تا پایان در یک واسط جمع نمیشود. اگر همه متن یکجا میرسد، صرفاً از روی ظاهر رابط نتیجه نگیرید که مدل استریم ندارد؛ مسیر HTTP و رفتار برنامه را جدا بررسی کنید.
خطاهای متداول و ترتیب عیب‌یابی
خطای ۴۰۱ از مسیر آزمایشی معمولاً به توکن دسترسی برنامه مربوط است؛ آن را با خطای اعتبار کلید upstream اشتباه نگیرید. برای خطای مدل، شناسه و دسترسی کلید را بررسی کنید. برای ۴۲۹، نرخ درخواست و سهمیه را ببینید. تکرار سریع درخواست‌های ناموفق ممکن است مشکل را بدتر کند. برای timeout نیز زمان شبکه، زمان مدل و سقف برنامه را جدا ثبت کنید.
بعد از شروع استریم، هدر HTTP قبلاً ارسال شده و دیگر نمیتوان همان پاسخ را به یک خطای JSON با وضعیت جدید تبدیل کرد. رابط باید قطعشدن جریان را تشخیص دهد و پاسخ ناقص را کامل نمایش ندهد. نمونه دانلودی یک مسیر آموزشی است؛ برای محصول، پیام خطای امن، شناسه درخواست و امکان تلاش مجدد آگاهانه کاربر را اضافه کنید.
قبل از عمومی‌کردن چه چیزهایی باقی می‌ماند؟
نشست معتبر، محدودیت نرخ مشترک بین replicaها، سقف مصرف کاربر، ثبت رویداد بدون داده حساس و آزمایش قطع ارتباط لازماند. مدل و کلید را از بدنه درخواست نپذیرید. تاریخچه را بدون محدودیت رشد ندهید و خروجی مدل را بهعنوان HTML قابل اعتماد رندر نکنید. اگر ابزار اضافه می‌کنید، هر ابزار باید مجوز مستقل و اعتبارسنجی ورودی داشته باشد.
برای ادامه به آموزش RAG در Next.js بروید؛ این نمونه عمداً حافظه و بازیابی سند ندارد. ابتدا مسیر ساده را قابل مشاهده و قابل کنترل کنید، سپس قابلیت بعدی را اضافه کنید. جداکردن هزینه مدل از هاست و نگهداشتن تنظیمات در سرور، تغییر مدل و بررسی هزینه را بدون بازنویسی رابط ممکن میکند.
