API Ollama: رفع اشکال اشتباهات رایج

درک پنجره زمینه ۱۰۰ هزار توکن

جمله اول هر بخش به سوال در سربرگ آن پاسخ می‌دهد.

یک پنجره زمینه ۱۰۰,۰۰۰ توکنی عظیم به نظر می‌رسد، اما به طور مساوی بین پرامپت‌های ورودی و تکمیل‌های خروجی تقسیم می‌شود. وقتی یک پرامپت سیستم طولانی را همراه با تاریخچه مکالمه طولانی ارسال می‌کنید، آن بودجه را سریع‌تر از آنچه انتظار دارید مصرف می‌کنید. بسیاری از توسعه‌دهندگان فرض می‌کنند که محدودیت فقط برای ورودی اعمال می‌شود که منجر به پاسخ‌های بریده‌شده یا شکست‌های خاموش می‌شود وقتی مدل به سقف خود می‌رسد.

سناریویی را در نظر بگیرید که یک سند ۵۰,۰۰۰ توکنی را به عنوان زمینه ارسال می‌کنید. شما فقط ۵۰,۰۰۰ توکن باقی‌مانده برای تولید واقعی دارید. اگر این تعادل را به دقت مدیریت نکنید، مدل در وسط جمله قطع خواهد شد. همیشه تعداد کل توکن‌های ارسال شده در هر درخواست را برای جلوگیری از برش غیرمنتظره نظارت کنید.

توکن‌های حداکثری در مقابل طول خروجی پیش‌فرض

هر بخش باید سوال موجود در عنوان را پاسخ دهد.

مگر اینکه محدودیتی مشخص کنید، اکثر APIها به طول خروجی متواضعانه‌ای به طور پیش‌فرض تنظیم می‌شوند، اغلب حدود ۲,۰۴۸ توکن. این پیش‌فرض برای پرس‌و‌جوهای کوتاه مفید است اما برای تولید کد یا نوشتن طولانی‌مدت فاجعه‌بار است. اگر نیاز دارید که مدل یک فیلم‌نامه کامل یا یک تحلیل دقیق تولید کند، باید پارامتر max_tokens را به صراحت تنظیم کنید.

تنظیم این مقدار بیش از حد بالا می‌تواند بر تأخیر و هزینه تأثیر بگذارد. شما بابت هر توکن تولید شده، چه مفید و چه غیرمفید، هزینه پرداخت می‌کنید. یک رویکرد عمل‌گرایانه این است که یک حد بالایی معقول که با مورد استفاده شما مطابقت دارد تنظیم کنید، به جای اینکه آن را به حالت پیش‌فرض یا یک بی‌نهایت دلخواه واگذار کنید.

مدیریت صحیح قطعات SSE جریان‌سازی

استریمینگ نیاز به مدیریت دقیق رویدادهای ارسالی سرور (SSE) دارد تا از دست رفتن داده جلوگیری شود.

هنگام فعال‌سازی Streaming، API یک سری قطعات کوچک را به جای یک پاسخ کامل واحد برمی‌گرداند. هر قطعه شامل یک دلتای متنی است، اما جزئیات مهمی مانند آمار مصرف توکن اغلب تنها در قطعه نهایی وجود دارد. اگر پردازش را خیلی زود متوقف کنید، داده‌های مصرف مورد نیاز برای صورت‌حساب یا ردیابی محدودیت نرخ را از دست می‌دهید.

علاوه بر این، جریان‌دار کردن (Streaming) پیچیدگی‌هایی در مدیریت خطا ایجاد می‌کند. یک وقفه شبکه ممکن است منجر به باقی ماندن متن ناقص شود. شما به یک تجزیه‌گر قوی نیاز دارید که بتواند پیام کامل را از این قطعات بازسازی کند. این موضوع به‌ویژه زمانی که با اجزای رابط کاربری که متن را به‌صورت بلادرنگ رندر می‌کنند، یکپارچه می‌شوید، صادق است.

خطاهای تعریف ابزار فراخوانی تابع

فراخوانی تابع زمانی شکست می‌خورد که طرح‌واره‌های ابزار با انتظارات مدل مطابقت نداشته باشند.

مدل انتظار دارد یک ساختار JSON خاص برای تعریف ابزارها داشته باشد. اگر فیلدهای ضروری را حذف کنید یا از نوع داده‌های نادرست استفاده کنید، مدل ممکن است ابزار را کاملاً نادیده بگیرد یا پاسخ نامعتبری بازگرداند. این یک نقطه درد رایج برای توسعه‌دهندگانی است که ایجنت‌هایی می‌سازند که نیاز به تعامل با APIهای خارجی دارند.

هملاً طرحواره ابزار خود را مستندات API قبل از ارسال درخواست‌ها اعتبارسنجی کنید. حتی انحرافات کوچک، مانند استفاده از یک عدد صحیح به جای یک رشته برای یک پارامتر، می‌تواند تماس تابع را خراب کند. عیب‌یابی این مورد نیاز به بازرسی پاسخ JSON خام دارد تا ببینید آیا مدل اصلاً تلاش کرده است که ابزار را صدا بزند یا خیر.

مشکلات فرمت پاسخ حالت JSON

حالت JSON مدل را مجبور به خروجی JSON معتبر می‌کند، اما همچنان ممکن است توهم‌زده تولید کند.

هنگام تنظیم response_format روی json_object، مدل به خروجی فقط JSON محدود می‌شود. با این حال، این تضمین نمی‌کند که محتوا از نظر معنایی صحیح باشد. مدل ممکن است سینتکس JSON معتبری تولید کند اما با کلیدهای نادرست یا فیلدهای جاافتاده. شما همچنان به یک پارسر برای اعتبارسنجی ساختار قبل از استفاده از داده نیاز دارید.

علاوه بر این، حالت JSON گاهی اوقات می‌تواند خلاقیت یا انعطاف‌پذیری مدل را کاهش دهد. اگر پرامپت شما خیلی پیچیده باشد، مدل ممکن است در تطبیق روایت با ساختار سخت‌گیرانه JSON دچار مشکل شود. از این حالت عمدتاً برای استخراج داده‌های ساختاریافته یا آرگومان‌های تابع استفاده کنید، جایی که ثبات مهم‌تر از ظرافت است.

محدودیت نرخ و درخواست‌های همزمان

محدودیت نرخ به ازای هر کلید API اعمال می‌شود، نه به ازای کاربر یا آدرس IP.

بیشتر APIها محدودیتی بر درخواست‌های در دقیقه و اتصالات همزمان اعمال می‌کنند. اگر از این محدودیت‌ها فراتر بروید، خطای 429 Too Many Requests دریافت خواهید کرد. این برای اپلیکیشن‌هایی که چندین رشته یا فرآیند برای مدیریت درخواست‌های کاربر ایجاد می‌کنند حیاتی است. یک کلید واحد می‌تواند فقط تعداد محدودی درخواست موازی را مدیریت کند.

برای مدیریت این موضوع، از پیاده‌سازی بازگشت نمایی در کد کلاینت خود استفاده کنید. هنگامی که خطای 429 دریافت کردید، پیش از تلاش مجدد، مدتی کوتاه صبر کنید. این کار از اشباع سرور جلوگیری کرده و تجربه کاربری روان‌تری ایجاد می‌کند. همیشه برای بهینه‌سازی زمان‌های انتظار، هدرهای پاسخ را برای مقادیر retry-after بررسی کنید.

رفتار جایگزینی کلید API

بازتولید یک کلید API، کلید قبلی را بلافاصله نامعتبر می‌کند.

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

این رفتار برای امنیت طراحی شده است، اطمینان حاصل می‌کند که یک کلید لو رفته نمی‌تواند برای همیشه استفاده شود. با این حال، این نیاز به مدیریت دقیق در سیستم‌های توزیع شده دارد. از متغیرهای محیطی یا مدیران راز برای ذخیره کلید خود استفاده کنید، به‌روزرسانی‌ها را آسان‌تر و کمتر مستعد خطا می‌کند.

محدودیت‌های اندازه بدنه درخواست

payloadهای بزرگ می‌توانند از محدودیت بدنه درخواست ۸ مگابایت فراتر روندند.

هنگام ارسال اسناد یا تصاویر طولانی که به صورت Base64 کدگذاری شده‌اند، بدنه درخواست می‌تواند به سرعت بزرگ شود. اگر از محدودیت اندازه فراتر بروید، سرور درخواست را با خطای 413 Payload Too Large رد می‌کند. این یک محدودیت سخت است که در بسیاری از موارد با ارتقای پلن شما قابل افزایش نیست.

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