تولید و استریم متن با AI SDK
مدلهای زبانی بزرگ (LLMها) قادرند در پاسخ به یک prompt، متن تولید کنند؛ این پرامپت میتواند شامل دستورالعملها و اطلاعاتی برای پردازش باشد. به عنوان مثال، میتوان از یک مدل خواست که یک دستور پخت ارائه دهد، پیشنویس یک ایمیل را تهیه کند، یا یک داکیومنت را خلاصه نماید.
هستهی AI SDK دو تابع برای تولید متن و استریم آن از LLMها فراهم میکند:
- generateText: متنی را با توجه به پرامپت و مدل، تولید میکند
- streamText: متن را با یک پرامپت و مدل مشخص، بهصورت stream ارائه میدهد
قابلیتهای پیشرفتهی LLMها، مانند فراخوانی toolها و تولید دادههای ساختارمند، بر پایهی همین قابلیت تولید متن ساخته شدهاند.
تابع generateText
شما میتوانید با استفاده از تابع generateText متن تولید کنید. این تابع برای موارد غیرتعاملی ایدهآل است؛ مانند زمانی که نیاز به تولید متن دارید (برای مثال: تهیهی پیشنویس یک ایمیل یا خلاصهسازی صفحات وب) و همچنین برای agentهایی که از toolها استفاده میکنند.
میتوانید از پرامپتهای پیشرفتهتر نیز، برای تولید متنی با دستورالعملها و محتوای پیچیدهتر، استفاده کنید.
آبجکت result که از تابع generateText بازگردانده میشود، شامل چندین promise است و زمانی که تمامی دادههای مورد نیاز در دسترس قرار گیرند، مقداردهی میشوند:
- result.text: متن تولید شده
- result.reasoning: استدلال کاملی که مدل در مرحله آخر، تولید کرده است
- result.sources: منابعی که به عنوان مرجع در مرحله آخر، استفاده شدهاند (موجود فقط برای برخی مدلها)
- result.finishReason: دلیلی که مدل تولید متن را متوقف کرده است
- result.usage: میزان مصرف مدل طی مرحله آخر تولید متن
دسترسی به هدرهای response و body
در برخی موارد، نیاز است به پاسخ کامل ارائهشده از سوی ارائهدهنده مدل دسترسی داشته باشید؛ برای مثال، جهت مشاهدهی برخی هدرها یا محتوای بدنه که بهصورت خاص توسط ارائهدهنده ارسال میشوند. میتوانید با استفاده از ویژگی response به هدرها و بدنهی خام پاسخ دسترسی پیدا کنید.
تابع streamText
بسته به مدل مورد استفاده و نوع prompt، ممکن است تولید پاسخ توسط یک LLM تا یک دقیقه طول بکشد. این تأخیر در موارد استفادهی تعاملی، مانند چتباتها یا برنامههای بلادرنگ (real-time)، جایی که کاربران انتظار پاسخهای فوری دارند، غیرقابلقبول است.
هستهی AI SDK تابعی به نام streamText دارد که stream متن از LLM را ساده میسازد.
result.textStream هم ReadableStream و هم AsyncIterable است.
تابع streamText بلافاصله استریم متن را آغاز میکند و برای جلوگیری از کرش کردن سرور، خطاها را نادیده میگیرد. برای لاگگرفتن از خطاها، از یک callback به نام onError استفاده کنید.
میتوانید از streamText بهصورت مستقل یا در ترکیب با AI SDK UI و AI SDK RSC استفاده کنید. آبجکت result شامل چندین تابع کمکی است که ادغام با AI SDK UI را سادهتر میسازند:
- ()result.toDataStreamResponse: این تابع یک HTTP respone مبتنی بر UI Message stream (با فراخوانی tool و ...)، تولید میکند که میتواند در API Route برنامههای NextJS App Router مورد استفاده قرار بگیرد
- ()result.pipeDataStreamToResponse: این تابع delta output مربوط به UI Message Stream را به یک آبجکت مشابه response در NodeJS قرار میدهد
- ()result.toTextStreamResponse: یک پاسخ HTTP ساده برای استریم متن ایجاد میکند
- ()result.pipeTextStreamToResponse: این تابع delta output متنی را به یک آبجکت مشابه respone در NodeJS مینویسد
تابع streamText از backpressure استفاده میکند و تنها زمانی توکنها را تولید میکند که مورد درخواست قرار گیرند. برای پایان یافتن فرآیند، لازم است که stream را مصرف (consume) کنید
تابع streamText شامل چندین promise است که زمانی که تمامی دادههای مورد نیاز در دسترس قرار گیرند، مقداردهی میشوند:
- ()result.toDataStreamResponse: این تابع یک HTTP respone مبتنی بر UI Message stream (با فراخوانی tool و ...)، تولید میکند که میتواند در API Route برنامههای NextJS App Router مورد استفاده قرار بگیرد
- ()result.pipeDataStreamToResponse: این تابع delta output مربوط به UI Message Stream را به یک آبجکت مشابه response در NodeJS قرار میدهد
- ()result.toTextStreamResponse: یک پاسخ HTTP ساده برای استریم متن ایجاد میکند
- ()result.pipeTextStreamToResponse: این تابع delta output متنی را به یک آبجکت مشابه respone در NodeJS مینویسد
onError callback
تابع streamText بلافاصله فرآیند streaming را آغاز میکند تا امکان ارسال داده بدون انتظار فراهم شود. در این روش، خطاها بهصورت بخشی از استریم در نظر گرفته میشوند و throw نمیشوند، تا از بروز مشکلاتی مانند کرش کردن سرور جلوگیری شود.
برای log کردن خطاها، میتوانید یک callback به نام onError تعریف کنید که در زمان وقوع خطا فعال (trigger) میشود.
onChunk callback
هنگام استفاده از تابع streamText، میتوانید یک callback به نام onChunk تعریف کنید که برای هر بخش (chunk) از استریم فراخوانی میشود. این callback، انواع chunkهای زیر را دریافت میکند:
- text-delta
- reasoning
- source
- tool-call
- tool-result
- tool-call-streaming-start (وقتی که toolCallStreaming فعال است)
- tool-call-delta (وقتی که toolCallStreaming فعال است)
onFinish callback
هنگام استفاده از تابع streamText، میتوانید یک callback به نام onFinish تعریف کنید که زمانی که استریم به پایان میرسد، فراخوانی میشود. این callback شامل اطلاعات جامعی از فرآیند تولید متن است، از جمله متن، اطلاعات مصرف توکن، علت توقف، پیامها، مراحل، مصرف کلی توکنها و ...