خروجی ساختاریافته و استریم اون با TanStack AI
خلاصهٔ کاملتر
نویسنده تو این قسمت سراغ structured output میره، یعنی مجبور کردن مدل زبانی به اینکه جوابش رو با یه ساختار مشخص برگردونه، نه یه متن خام. مثالش یه اپ تمرین ورزشیه که برنامههای تمرینی رو با یه Zod schema تعریف کرده: هر workout چند segment داره، هر segment یک یا چند تمرین، و هر تمرین برای هر ست یه سری اندازهگیری. به گفتهی نویسنده این ساختار عمداً نرمالشدهست تا بشه دادهها رو کوئری گرفت و نمودار پیشرفت کشید.
سمت سرور تقریباً همون کد قسمت اوله. فقط یه فیلد outputSchema به تابع chat اضافه میشه که به TanStack AI میگه جواب باید چه شکلی باشه. نویسنده یه systemPrompts هم گذاشته که مدل فقط برنامهی تمرینی بسازه و دستورهای بیربط کاربر رو نادیده بگیره. به نظرش این کار تقریباً همیشه لازمه، وگرنه آدمها میتونن با پرامپتهای سوءاستفادهگر توکنهات رو بسوزونن.
سمت کلاینت همون هوک useChat استفاده میشه و همون outputSchema بهش داده میشه. فرقش اینه که حالا از هر message part یه آبجکت data گرفته میشه که تایپش دقیقاً همون schemaیی هست که روی سرور تعریف شده. قبل از دسترسی به data باید چک کنی که part.status برابر "complete" باشه.
برای روشن کردن استریم باید سمت سرور stream: true رو صریحاً اضافه کنی، chat رو بدون await صدا بزنی و جواب رو با toServerSentEventsResponse برگردونی. سمت کلاینت هم به جای fetchJson از fetchServerSentEvents استفاده میشه:
const payload = useChat({
connection: fetchServerSentEvents("/api/ai/chat-structured-output"),
outputSchema: promptOutputSchema,
});سؤال اصلی اینه که با یه JSON نصفه چیکار کنیم که هنوز parse نمیشه. نویسنده توضیح میده که TanStack این کارو خودش انجام میده: هر جا مدل وایستاده، رشتهها و آبجکتها و آرایههای باز رو میبنده و یه نسخه از schema بهت میده که همهی فیلدهاش اختیاریه. یعنی کامپوننتهات باید با undefined بودن هر فیلدی کنار بیان. برای تایپ این حالت، خود کتابخونه یه utility به اسم DeepPartial داره:
import type { DeepPartial } from "@tanstack/ai";
type DisplayRepsProps = {
segment: DeepPartial<TemplateSegmentWithExercises>;
};نویسنده یه کپی از کامپوننت نمایش تمرین ساخته به اسم DisplayWorkoutTemplateStreaming که ورودیش partial هست و قبل از نمایش هر مقدار چک میکنه وجود داره یا نه. وقتی status کامل نیست، داده از part.partial خونده میشه و وقتی کامل شد، همون آبجکت کامل قبلی میرسه.
نکات کلیدی:
- با فیلد outputSchema هم روی chat سرور و هم روی useChat کلاینت، جواب مدل به یه Zod schema محدود میشه.
- تایپ part.data سمت کلاینت دقیقاً همون تایپ schema سمت سروره.
- برای استریم structured output باید stream: true رو صریحاً بذاری و از toServerSentEventsResponse و fetchServerSentEvents استفاده کنی.
- TanStack AI یه JSON نیمهکاره رو با بستن رشتهها و آبجکتها و آرایههای باز قابل استفاده میکنه.
- تایپ DeepPartial از @tanstack/ai همهی فیلدها رو به صورت عمیق اختیاری میکنه.




