کلید API در 1ai: امنیت، محدودیت‌ها و کنترل هزینه
چطور کلیدهای API را امن نگه دارید و هزینه را مهار کنید: مدل‌های مجاز، سقف اعتبار ماهانه، محدودیت نرخ، تاریخ انقضا، کلیدهای تیمی و گزارش مصرف.
کلید API مثل کلید کیف پول است: هر کس آن را داشته باشد، می‌تواند از اعتبار شما خرج کند. خبر خوب این است که در 1ai برای هر کلید می‌توانید دقیق تعیین کنید چه کاری، با چه مدلی و تا چه سقفی انجام دهد. این مقاله روش درست ساختن، نگهداری و محدود کردن کلیدها را مرور می‌کند.
ساختن کلید
در پنل به «توسعه‌دهندگان ← کلیدها» بروید و کلید جدید بسازید. چند نکته:
- برای هر پروژه یا محیط یک کلید جدا بسازید (مثلاً «سایت فروشگاه - production» و «آزمایش محلی»). اگر یکی افشا شد، فقط همان را باطل می‌کنید و گزارش مصرف هر پروژه هم جدا می‌ماند.
- کلید فقط یک‌بار نمایش داده می‌شود. 1ai کلید را به‌صورت هش‌شده نگه می‌دارد و خودمان هم نمی‌توانیم دوباره آن را ببینیم؛ پس همان لحظه آن را در مدیر رمز یا متغیرهای محیطی سرور ذخیره کنید.
- در فهرست کلیدها فقط پیشوند هر کلید و زمان آخرین استفاده‌اش نمایش داده می‌شود تا کلیدها را از هم تشخیص دهید.
محدودیت‌هایی که برای هر کلید می‌توانید بگذارید
مدل‌های مجاز
فهرستی از مدل‌هایی که این کلید اجازه‌ی استفاده از آن‌ها را دارد. اگر برنامه‌ی شما فقط به یک مدل سبک نیاز دارد، همان را مجاز کنید؛ درخواست به مدل‌های دیگر با خطای 403 رد می‌شود و یک باگ یا کلید افشاشده نمی‌تواند سراغ مدل‌های گران برود.
سقف اعتبار ماهانه
بیشترین اعتباری که این کلید در هر ماه می‌تواند خرج کند. ماه‌ها ماه‌های شمسی به وقت تهران‌اند. وقتی سقف پر شود، درخواست‌ها با خطای 402 (key_cap_reached) رد می‌شوند تا ماه بعد یا تا وقتی سقف را بالا ببرید.
محدودیت نرخ
می‌توانید برای هر کلید تعداد درخواست و توکن در دقیقه و همچنین تعداد درخواست و توکن در روز را محدود کنید. این محدودیت‌ها روی محدودیت کلی حساب شما اعمال می‌شوند و جلوی حلقه‌های بی‌پایان در کد یا سوءاستفاده را می‌گیرند. با رسیدن به حد، پاسخ 429 همراه با هدر retry-after برمی‌گردد.
تاریخ انقضا
برای کلیدهای موقت (مثلاً برای یک پیمانکار یا یک دمو) تاریخ انقضا بگذارید تا خودبه‌خود از کار بیفتند.
همه‌ی این تنظیمات را بعداً هم می‌توانید تغییر دهید یا بردارید.
اگر کلید افشا شد
- فوراً از فهرست کلیدها آن را باطل کنید؛ ابطال بلافاصله اعمال می‌شود.
- کلید تازه بسازید و جایگزین کنید.
- گزارش درخواست‌ها را برای دوره‌ی افشا بررسی کنید.
- اگر مصرف مشکوکی دیدید، از بخش پشتیبانی تیکت با دسته‌ی «API و توسعه‌دهندگان» ثبت کنید.
کلیدهای تیمی
اگر عضو یک تیم هستید، می‌توانید کلیدی بسازید که از کیف اعتبار تیم خرج کند. اگر عضوی تیم را ترک کند یا حذف شود، کلیدهای تیمی‌ای که ساخته باطل می‌شوند؛ پس دسترسی همکار سابق به اعتبار تیم خودکار قطع می‌شود. سقف مصرف ماهانه‌ای که مدیر تیم برای هر عضو گذاشته، روی کلیدهای او هم اعمال می‌شود.
گزارش مصرف و رفع اشکال
در بخش «توسعه‌دهندگان» دو ابزار دارید:
- مصرف: نمودار روزانه‌ی درخواست‌ها، خطاها، توکن‌ها و اعتبار، به تفکیک مدل و کلید.
- گزارش درخواست‌ها: تک‌تک درخواست‌ها با وضعیت، کد خطا، توکن‌ها، تأخیر، وضعیت کش و هزینه. هر پاسخ API یک
x-request-idدارد؛ آن را در لاگ‌های برنامه‌ی خود ذخیره کنید تا درخواست مشکل‌دار را سریع پیدا کنید.
ترفندهای کاهش هزینه
- مدل مناسب کار: برای دسته‌بندی، استخراج اطلاعات و پاسخ‌های کوتاه، مدل سبک معمولاً کافی است.
- محدود کردن طول پاسخ: با
max_tokens(یاmax_completion_tokens) سقف خروجی را تعیین کنید. - کوتاه نگه داشتن تاریخچه: لازم نیست کل گفتگو را در هر درخواست بفرستید؛ پیام‌های قدیمی را خلاصه یا حذف کنید.
- کش پاسخ: درخواست‌های کاملاً تکراری ممکن است از کش پاسخ داده شوند که هزینه‌ی کمتری دارد. هدر
x-1ai-cache-statusنشان می‌دهد پاسخ از کش آمده یا نه. اگر پاسخ تازه لازم دارید، هدرx-1ai-cache-force-refresh: trueرا بفرستید. - هشدار موجودی: وقتی موجودی کیف اعتبار کم شود، اعلان می‌گیرید؛ پیش از تمام شدن اعتبار، آن را شارژ کنید تا سرویس شما متوقف نشود.
چک‌لیست امنیت کلید
- کلید فقط در سمت سرور و در متغیر محیطی است.
- کلید در مخزن کد (حتی خصوصی) ثبت نشده است.
- هر محیط و پروژه کلید جدا دارد.
- مدل‌های مجاز و سقف ماهانه تعیین شده است.
- کلیدهای موقت تاریخ انقضا دارند.
- کلیدهای بلااستفاده باطل شده‌اند.
پرسش‌های کوتاه
آیا 1ai می‌تواند کلید گم‌شده‌ی من را دوباره نشان دهد؟ خیر. کلیدها هش‌شده ذخیره می‌شوند و قابل بازیابی نیستند؛ کلید تازه بسازید و قبلی را باطل کنید.
اگر اعتبار تمام شود، درخواست‌های در جریان چه می‌شوند؟ اعتبار هر درخواست پیش از اجرا رزرو می‌شود؛ پس درخواستی که شروع شده تمام می‌شود و درخواست‌های بعدی با خطای 402 رد می‌شوند.
