چرا استریم LLM من خالی است؟ راهنمای تشخیص پاسخ‌های خراب SSE

اگر تا به حال با API سازگار با OpenAI و استریم کار کرده باشید و هیچ خروجی نگرفته باشید، تنها نیستید. پس از دیباگ ده‌ها مورد از این دست (و ساخت ابزار agent-stream-doctor برای خودکارسازی آن)، همیشه چهار حالت خرابی تکراری می‌بینم.

1. پاسخ‌های فقط-استدلالی: برخی مدل‌ها کل پاسخ را در کانال reasoning می‌فرستند و کانال content را خالی می‌گذارند. استریم «کار می‌کند» ولی رابط کاربری شما چیزی نشان نمی‌دهد. همیشه فیلدهای delta را بررسی کنید.

2. فقدان finish_reason: وقتی پراکسی چانک آخر را قطع می‌کند، finish_reason حذف می‌شود و خیلی از کلاینت‌ها بی‌صدا پیام را دور می‌ریزند. نبودِ finish_reason را یک زنگ خطر جدی بدانید.

3. فریم‌بندی خراب SSE: چندبایتی بودن UTF-8 روی مرز چانک‌ها یا بازنویسی پیشوند data: توسط پراکسی، پارسرها را بی‌صدا می‌شکند. قبل از پارس، فریم‌های خام را لاگ کنید.

4. فراخوانی ابزار ناقص: دلتاهای نیمه‌کاره tool_call که هرگز کامل نمی‌شوند، ایجنت شما را معلق می‌گذارند. قبل از اجرا، آرگومان‌ها را جمع‌آوری و اعتبارسنجی کنید.

راه‌حل همیشه یکی است: اول استریم خام را ببین، بعد درباره پروتکل فکر کن. جعبه‌ابزار تشخیصی من دقیقاً همین کار را می‌کند — روی گیت‌هاب ببینید.