‏AI SDK ورسل و مهار خروجی مدل با Zod

آدام رکیس تو بلاگ master.dev سراغ موضوعی رفته که با استفاده از Cursor و Claude Code فرق داره: اضافه‌کردن قابلیت AI داخل خود نرم‌افزار. ابزارش هم AI SDK ورسله، یه پکیج TypeScript که با npm i ai نصب می‌شه و model-agnostic هست، یعنی از Claude Sonnet تا GPT-5 رو تقریباً یه‌جور صدا می‌زنی. مثال پست هم به‌جای چت‌بات، ساختن برنامهٔ تمرین ورزشیه.

قبل از فراخوانی، مدل باید یه جایی میزبانی شه و نویسنده کم‌دردسرترین گزینه رو AI Gateway ورسل می‌دونه: یه نقطهٔ مرکزی که درخواست رو به هر مدلی از هر ارائه‌دهنده‌ای می‌فرسته و fallback هم قبول می‌کنه، مثلاً اول Claude Sonnet 5 و اگه نشد Sonnet 4.6. صورت‌حساب هم فقط از ورسله، به گفتهٔ نویسنده با نرخ خود ارائه‌دهنده و بدون مارک‌آپ. کلید تو AI_GATEWAY_API_KEY می‌شینه و چون پول بهش وصله، فراخوانی باید سمت سرور انجام شه.

قسمت اصلی پست از جایی شروع می‌شه که یه دیوار متن آزاد به درد ذخیره تو دیتابیس نمی‌خوره. نویسنده می‌گه اپش از قبل فرم، کامپوننت و server function برای ثبت دستی تمرین داشته، پس بهتره مدل هم دقیقاً همون ساختار رو تولید کنه تا همون کدها دوباره استفاده شن. AI SDK این کارو با فیلد output و یه اسکیمای Zod ممکن می‌کنه:

output: Output.object({
  schema: z.object({
    commentary: z.string().describe("The output from the llm, explaining what it did and why"),
    workouts: z.array(workoutTemplateValidator),
  }),
}),

نتیجه بعدش از پراپرتی output خونده می‌شه و از قبل با اسکیما اعتبارسنجی شده. روی prompt هم نویسنده یه تذکر امنیتی داره: ورودی خام کاربر رو مستقیم دست مدل نده، چون یکی می‌تونه با یه درخواست سنگین توکن‌هاتو بسوزونه. پراپرتی system حالا deprecated شده و جاشو instructions گرفته؛ اونجا صریح می‌نویسه که کار مدل فقط ساختن برنامهٔ تمرینه و دستورهای نامرتبط کاربر رو نادیده بگیره.

آخر پست چند تا هشدار عملی هم اومده. حالت رایگان AI Gateway پنج دلار اعتبار می‌ده و هر درخواست کامل حدود ۰.۰۳ تا ۰.۰۵ دلار درمیاد، ولی فعلاً مدل‌های Anthropic تو حالت رایگان در دسترس نیستن و برای بازکردنشون باید حداقل ۱۰ دلار اعتبار بخری. یه دردسر دیگه هم فیلدهای optional تو اسکیمای Zod بوده که با مدل‌های OpenAI مدام ارور می‌داد، پس یا حذفشون کن یا اجباریشون کن.

موقع اجرای مدل‌های OpenAI نویسنده خطاهایی از سمت Azure هم گرفته و برای همین ارائه‌دهنده‌ها رو محدود کرده تا فقط صاحب‌های اصلی مدل بمونن:

providerOptions: {
  gateway: {
    only: ["openai", "anthropic"],
  },
},

نکات کلیدی:

• نصب با npm i ai؛ SDK به مدل خاصی گره نخورده و از Claude تا GPT-5 رو پوشش می‌ده
• فیلد output با اسکیمای Zod، جواب مدل رو به همون ساختار دادهٔ خود اپ قفل می‌کنه
• پراپرتی system منسوخ شده و جاشو instructions گرفته
• حالت رایگان AI Gateway ۵ دلار اعتبار داره ولی مدل‌های Anthropic توش باز نیستن؛ حداقل خرید اعتبار ۱۰ دلاره
• هزینهٔ هر درخواست کامل تو تجربهٔ نویسنده ۰.۰۳ تا ۰.۰۵ دلار بوده
• فیلدهای optional تو اسکیمای Zod با مدل‌های OpenAI باعث ارور می‌شدن