چک‌لیست تولید API DeepSeek

پیکربندی نقطه پایانی و URL پایه

اولین مرحله اشاره مشتری شما به URL پایه صحیح است. ما از ساختار سازگار با OpenAI استاندارد استفاده میکنیم، به این معنی که SDKهای موجود شما بدون بازسازی عمده کار میکنند. Set the base_url به https://api.deepseekunrestricted.com/v1 و کلید API خود را در هدر احراز هویت پیکربندی کنید. این تنظیم تضمین می‌کند که تمام نقاط پایانی استاندارد مانند /v1/chat/completions behave exactly as documented. نیازی به بازنویسی منطق مسیریابی خود ندارید.

• URL پایه: https://api.deepseekunrestricted.com/v1
• هدر Auth: Authorization: Bearer YOUR_API_KEY
• شناسه مدل: uncensored

این پیکربندی به شما امکان می‌دهد اگر بعداً گسترش دادید، بین مدل‌های مختلف جابه‌جا شوید، اما در حال حاضر، به یک مدل uncensored واحد بچسبید. endpoint برای عملیات متن-ورودی، متن-خروجی طراحی شده است. از پارامترهای استاندارد مانند دما و top_p پشتیبانی می‌کند. پیکربندی خود را متمرکز نگه دارید تا از hardcoding URLها در مکان‌های مختلف جلوگیری کنید. این موضوع هزینه نگهداری را هنگامی که نسخه API را به‌روزرسانی می‌کنیم، کاهش می‌دهد.

محاسبه و برآورد هزینه توکن

برآورد هزینه بر پایه ردیو مجزای توکن‌های ورودی و خروجی استوار است. ساختار قیمت‌گذاری ساده است: $0.15 به ازای هر 1M توکن ورودی و $0.50 به ازای هر 1M توکن خروجی. خطاها و رد شدن درخواست‌ها اعتبار مصرف نمی‌کنند، بنابراین شما فقط بپرداز پردازش موفق پرداخت می‌کنید. این مدل پیش‌پرداخت تضمین می‌کند که بودجه شما به دقت کنترل شود. می‌توانید با ارزهای دیجیتال و با دریافت پاداش برای مبالغ بالاتر، حساب خود را شارژ کنید.

• هزینه ورودی: ۰.۱۵ دلار به ازای هر ۱M توکن
• هزینه خروجی: $0.50 per 1M tokens
• وجه‌بازگرداندن: هیچ‌کدام، اما اعتبار هرگز منقضی نمی‌شود

همیشه usage field in the response to track your spend accurately. Implement a local counter to estimate costs before sending large batches. This prevents unexpected depletion of your prepaid balance. Remember that the credit never expires, so you can top up when prices are favorable. Use the bonus tiers to maximize your purchasing power. A $100 top-up gives you 10% extra credit, which effectively lowers your per-token rate.

مدیریت کارآمد پاسخ‌های جریان‌سازی

پاسخ‌های استریم‌شده تجربه کاربری را با تحویل افزایشی محتوا بهبود می‌بخشند. ما از رویدادهای سرور-ارسالی (SSE) برای تحویل بلادرنگ توکن‌ها پشتیبانی می‌کنیم. هر قطعه شامل متن ناقص و متادیتا است. این قطعات را پارس کنید تا رابط کاربری خود را به نرمی به‌روزرسانی کنید. قطعه نهایی شامل مجموع مصرف توکن برای درخواست است.

• استریمینگ را با تنظیم stream: true
• فرمت SSE را برای به‌روزرسانی‌های جزئی تجزیه کنید
• استخراج داده‌های استفاده از آخرین قطعه

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

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

محدودیت‌های نرخ برای اطمینان از عملکرد پایدار برای تمام کاربران اعمال می‌شوند. هر کلید API به ۳۰۰ درخواست در دقیقه محدود است. می‌توانید تا حداکثر هشت درخواست همزمان را در هر لحظه فعال نگه دارید. تجاوز از این محدودیت‌ها منجر به خطای 429 می‌شود. بازگشت نمایی را پیاده‌سازی کنید تا تلاش‌های مجدد را به طور موثر مدیریت کنید.

• محدودیت: ۳۰۰ درخواست در دقیقه برای هر کلید
• همزمانی: 8 درخواست همزمان
• اندازه بدنه: حداکثر ۸ مگابایت

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

مدیریت خطا و منطق تلاش مجدد

مدیریت خطای قوی از سقوط اپلیکیشن شما در حین فراخوانی API جلوگیری می‌کند. ما کدهای وضعیت HTTP استاندارد را برای نشان دادن موفقیت یا شکست برمی‌گردانیم. خطای 4xx معمولاً به معنای مشکل سمت کلاینت است، مانند کلید نامعتبر یا درخواست نامعتبر. خطای 5xx نشان‌دهنده مشکل سمت سرور است که ممکن است به‌طور خودکار حل شود.

• 4xx: خطاهای کلاینت (درخواست خود را بررسی کنید)
• ۵xx: خطاهای سرور (تلاش مجدد با بازگشت نمایی)
• 429: تجاوز از محدودیت نرخ (صبر کنید و دوباره تلاش کنید)

یک مکانیزم تلاش مجدد با افزایش بازگشتی (exponential backoff) برای خطاهای گذرا پیاده‌سازی کنید. در خطاهای 4xx تلاش مجدد نکنید مگر اینکه مربوط به محدودیت نرخ باشند. جزئیات خطا را برای اشکال‌زدایی ثبت کنید. شناسه درخواست را در لاگ‌های خود بگنجانید تا به تیم‌های پشتیبانی کمک کند. این به تشخیص سریع مشکلات کمک می‌کند. همیشه زمان‌های انتظار شبکه را جدا از خطاهای HTTP مدیریت کنید. یک درخواست شکست‌خورده نباید موجودی توکن شما را مصرف کند اگر توکنی پردازش نشده باشد.

حالت JSON برای خروجی داده‌های ساختاریافته

حالت JSON تضمین می‌کند که مدل ساختارهای JSON معتبر تولید می‌کند. این مورد برای یکپارچه‌سازی با سیستم‌های دیگر که داده‌های ساختاریافته انتظار دارند حیاتی است. Set the response_format پارامتر روی {"type": "json_object"}. این موضوع مدل را ملزم می‌کند تا از قوانین سینتکس JSON پیروی کند.

• تنظیم response_format به json_object
• خروجی را با یک JSON parser اعتبارسنجی کنید
• نقض‌های طرحواره (schema) را به‌خوبی مدیریت کنید

در حالی که حالت JSON ثبات را بهبود می‌بخشد، اما انطباق با طرحواره (schema) را تضمین نمی‌کند. همیشه خروجی را با طرحواره مورد انتظار خود اعتبارسنجی کنید. اگر خروجی نامعتبر باشد، درخواست را با یک پرامپت سخت‌گیرانه‌تر تکرار کنید. این نیاز به پردازش پس از اجرا را کاهش می‌دهد. از این ویژگی برای کارهایی مانند استخراج داده یا تولید پیکربندی استفاده کنید. این تضمین می‌کند که سیستم‌های downstream شما ورودی‌های قابل پیش‌بینی دریافت می‌کنند. منطق تجزیه JSON خود را به دقت برای مدیریت موارد مرزی آزمایش کنید.

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

فراخوانی تابع به مدل اجازه می‌دهد اقدامات خاصی را بر اساس ورودی کاربر اجرا کند. توابع خود را در tools پارامتر. مدل یک شیء فراخوانی تابع را به جای متن ساده بازگردانی می‌کند. سپس برنامه شما تابع را اجرا کرده و نتیجه را به مدل بازمی‌گرداند.

• توابع را در tools آرایه
• پاسخ فراخوانی تابع را تجزیه کنید
• نتایج را برای ادامه مکالمه بازگردانید

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

مدیریت پنجره زمینه

پنجره زمینه تعیین می‌کند که مدل چقدر متن را می‌تواند در یک نوبت پردازش کند. API ما از پنجره زمینه ۱۰۰,۰۰۰ توکنی پشتیبانی می‌کند. این مقدار شامل هم متن ورودی (prompt) و هم خروجی (completion) می‌شود. به محدودیت حداکثر خروجی ۱۶,۰۰۰ توکن در هر درخواست توجه داشته باشید. اگر از این حد تجاوز کنید، مدل پاسخ را قطع می‌کند.

• پنجره زمینه: ۱۰۰,۰۰۰ توکن
• حداکثر خروجی: ۱۶,۰۰۰ توکن
• خروجی حداکثر پیش‌فرض: 2,048 توکن

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

امنیت و چرخش کلید

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

• کلیدها را در متغیرهای محیطی ذخیره کنید
• کلیدها را به طور منظم بچرخانید
• مصرف را برای ناهنجاری‌ها پایش کنید

لاگ‌گذاری را پیاده‌سازی کنید تا استفاده از API و فعالیت‌های غیرعادی ردیابی شود. برای درخواست‌های حجیم، هشدارها را تنظیم کنید. این کار به شناسایی سوءاستفاده یا حملات احتمالی کمک می‌کند. نسخه‌های SDK خود را به‌روز نگه دارید تا از پچ‌های امنیتی بهره‌مند شوید. از HTTPS برای تمام ارتباطات API استفاده کنید. این اطمینان حاصل می‌کند که داده‌های شما در حین انتقال رمزنگاری می‌شوند. حسابرسی‌های منظم از استفاده API به حفظ بهداشت امنیتی کمک می‌کنند.