استفاده تیمی و Production

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

Production-ready برای سرویس AI یعنی چه؟

اتصال production باید در برابر افشای کلید، افزایش ناگهانی مصرف، خطای موقت provider و رفتار غیرمنتظره agent قابل‌کنترل باشد. این آمادگی فقط به کد API محدود نیست؛ چرخه عمر secret، سطح دسترسی ابزار، مشاهده‌پذیری، بودجه، فرایند انتشار و امکان بازگشت را نیز شامل می‌شود.

این راهنما برای backendهای متصل به SDK، workflowهای n8n، رابط‌های اشتراکی Open WebUI و coding agentهای تیمی کاربرد دارد. شدت کنترل‌ها یکسان نیست: یک اسکریپت محلی آزمایشی می‌تواند کلید کوتاه‌عمر و سقف کم داشته باشد، اما سرویس مشتری‌محور به secret manager، alert، retry کنترل‌شده و runbook رخداد نیاز دارد.

۱. تفکیک کلیدها

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

توسعه‌دهنده یا سرویس
├── local / development
├── CI
├── staging
└── production

برای هر شاخه کلید مجزا بسازید. نام کلید باید مصرف‌کننده و محیط را مشخص کند؛ مانند n8n-production یا team-a-claude-code.

مزایا:

• لغو یک کلید بدون قطع کل سامانه؛
• گزارش مصرف قابل‌تفکیک؛
• سقف هزینه متناسب با workload؛
• rotation مرحله‌ای و کم‌ریسک.

۲. نگهداری secret

ترتیب ترجیح:

1. Secret manager زیرساخت؛
2. credential store خود ابزار؛
3. environment تزریق‌شده هنگام اجرا؛
4. فایل .env محلی خارج از Git.

کلید را در source code، Docker image، workflow export، screenshot، ticket یا log قرار ندهید. فایل نمونه فقط نام متغیر را داشته باشد:

CHABOKAN_AI_API_KEY=
CHABOKAN_AI_MODEL=

۳. سقف مصرف و چرخه عمر

• برای کلیدهای شخصی و آزمایشی سقف کوچک تعیین کنید.
• برای production سقف را بر اساس اندازه واقعی workload و alert عملیاتی تعیین کنید.
• تاریخ انقضا برای کلیدهای موقت و پیمانکاران الزامی باشد.
• rotation را ابتدا در staging آزمایش و سپس production را جابه‌جا کنید.
• پس از تأیید کلید جدید، کلید قدیمی را لغو کنید.
• برای خروج عضو تیم، کلیدهای منتسب به او را فوراً بازبینی و لغو کنید.

۴. مجوز عامل با مجوز API متفاوت است

API Key چابکان اجازه فراخوانی مدل می‌دهد؛ اجازه خواندن فایل، اجرای shell، push کردن Git یا دسترسی به دیتابیس را خود ابزار agent تعیین می‌کند.

برای agentها:

• پیش‌فرض را read-only بگذارید؛
• تأیید انسانی را برای write، shell، network و عملیات خارجی فعال کنید؛
• repository و working directory را محدود کنید؛
• credentialهای cloud و production را از نشست agent دور نگه دارید؛
• command allowlist و sandbox ابزار را در صورت وجود فعال کنید.

۵. timeout، retry و هم‌زمانی

نوع خطا	رفتار پیشنهادی
400	retry نکنید؛ payload یا قابلیت مدل اشتباه است
401	retry نکنید؛ کلید یا ارسال credential را اصلاح کنید
402	اعتبار یا سقف ماهانه را بررسی کنید
404	endpoint یا Model ID را اصلاح کنید
429	exponential backoff همراه jitter و کاهش concurrency
5xx یا timeout	retry محدود با backoff؛ سپس circuit breaker یا صف

برای کارهای غیر idempotent، قبل از retry بررسی کنید که اجرای دوباره اثر جانبی تکراری نسازد.

۶. Logging و حریم خصوصی

موارد مفید برای ثبت:

• زمان و نام سرویس داخلی؛
• Model ID و endpoint؛
• status code، latency و تعداد retry؛
• token usage و هزینه در صورت نیاز؛
• شناسه درخواست برای ارتباط با گزارش پنل.

مواردی که نباید ثبت شوند:

• API Key یا header کامل Authorization؛
• prompt و پاسخ دارای اطلاعات شخصی یا secret؛
• محتوای کامل فایل‌های خصوصی؛
• آرگومان ابزارهای حساس بدون redaction.

برای لاگ prompt و response، سیاست نگهداری، دسترسی و حذف مشخص داشته باشید.

۷. انتشار مرحله‌ای

cURL smoke test → یک توسعه‌دهنده → تیم کوچک → staging → production محدود → rollout کامل

در هر مرحله این موارد را بسنجید:

• نرخ موفقیت درخواست و tool call؛
• latency صدکی، نه فقط میانگین؛
• مصرف توکن و هزینه هر کار کامل؛
• retry و loopهای agent؛
• کیفیت خروجی و نیاز به اصلاح انسانی؛
• امکان برگشت به config یا مدل قبلی.

۸. چک‌لیست Production

• کلید مخصوص همان سرویس و محیط است.
• secret خارج از source و image نگهداری می‌شود.
• سقف مصرف، تاریخ انقضا و مالک کلید مشخص‌اند.
• Model ID و قابلیت‌های موردنیاز در pilot تأیید شده‌اند.
• timeout، retry محدود و concurrency کنترل شده است.
• مجوز ابزارهای agent حداقلی است.
• لاگ‌ها secret و داده حساس ندارند.
• alert مصرف و خطا مسئول مشخص دارد.
• runbook لغو کلید و rollback مدل وجود دارد.
• آزمون staging پیش از تغییر production انجام شده است.