چطور Claude API را در اپ خود یکپارچه کنیم
برای یکپارچه‌سازی Claude API، یک کلید API در Claude Console متعلق به Anthropic بسازید، آن را به‌عنوان یک راز سمت سرور ذخیره کنید (معمولاً ANTHROPIC_API_KEY) و Messages API را از یک مسیر روی سرور خودتان با یکی از SDKهای رسمی Anthropic فراخوانی کنید. هر درخواست یک model را نام می‌برد، max_tokens (بلندترین پاسخی که می‌پذیرید) را تعیین می‌کند و گفت‌وگو را به‌صورت messages می‌فرستد، در حالی که دستورهای شما در یک پرامپت system جداگانه قرار دارند. سقف هزینه تعیین کنید، پاسخ‌های طولانی را استریم کنید و خطاهای محدودیت نرخ (429) و اضافه‌بار (529) را با تلاش مجدد مدیریت کنید.
این راهنما راه‌اندازی، جریان امن درخواست، پرامپت برای یک ساخت‌دهنده هوش مصنوعی و خطاهایی که باید برای آن‌ها برنامه داشته باشید را پوشش می‌دهد. جزئیات Anthropic بر اساس مستندات آن تا سپتامبر ۲۰۲۶ است. برای فهم کلی توکن‌ها و قیمت‌گذاری، ابتدا چطور از API های LLM استفاده کنیم را بخوانید.
با آن چه می‌توانید بسازید
- دستیارهای گفت‌وگو و ویجت‌های راهنما (چطور یک اپ چت‌بات هوش مصنوعی بسازیم)
- خلاصه‌سازی، بازنویسی و پیش‌نویس پاسخ
- استخراج فیلدها از اسناد، ایمیل‌ها و فرم‌ها
- پاسخ به سؤال‌ها بر اساس محتوای خودتان
- عامل‌هایی که از طریق tool use توابع اپتان را صدا می‌زنند
ایده‌های بیشتر در چطور قابلیت‌های هوش مصنوعی را به اپ خود اضافه کنیم هست.
نگاهی کوتاه به Messages API
طبق مرجع API از Anthropic، یک درخواست یک POST به https://api.anthropic.com/v1/messages است با این اجزا:
| بخش | توضیح |
|---|---|
هدر x-api-key | کلید API شما |
هدر anthropic-version | نسخه API، برای مثال 2023-06-01 |
model (الزامی) | کدام مدل Claude استفاده شود |
max_tokens (الزامی) | بیشترین توکنی که پاسخ می‌تواند داشته باشد؛ مدل ممکن است زودتر متوقف شود |
messages (الزامی) | گفت‌وگو: نوبت‌های متناوب user و assistant |
system (اختیاری) | دستورهایی که برای کل گفت‌وگو اعمال می‌شوند |
stream (اختیاری) | با true پاسخ را همان‌طور که نوشته می‌شود از طریق server-sent events دریافت می‌کنید |
این API بدون وضعیت (stateless) است: برای ادامه گفت‌وگو، نوبت‌های قبلی را با هر درخواست دوباره می‌فرستید. به همین دلیل گفت‌وگوهای طولانی هزینه بیشتری برای هر پیام دارند.
Anthropic SDKهای رسمی برای Python، TypeScript، C#، Go، Java، PHP و Ruby منتشر کرده است. این SDKها هدرها را تنظیم می‌کنند، پاسخ‌ها را تجزیه می‌کنند و از استریم پشتیبانی می‌کنند. مگر دلیل خاصی داشته باشید، به‌جای HTTP خام از یکی از آن‌ها استفاده کنید.
انتخاب مدل
Anthropic چند مدل Claude ارائه می‌دهد که بین توانایی، سرعت و قیمت تفاوت دارند و این خط محصولات تغییر می‌کند. کوچک‌ترین مدلی را انتخاب کنید که کارتان را خوب انجام دهد، آن را روی نمونه‌های واقعی بیازمایید و شناسه مدل را در تنظیمات نگه دارید تا بدون تغییر کد بتوانید عوضش کنید. برای گزینه‌ها و نرخ‌های فعلی، صفحات مدل‌ها و قیمت‌گذاری Anthropic را ببینید.
راه‌اندازی حساب
- وارد Claude Console شوید در platform.claude.com و صورتحساب اضافه کنید.
- یک کلید API بسازید. برای هر محیط (آزمایش و تولید) یک کلید جدا نگه دارید تا بتوانید یکی را باطل کنید بدون اینکه دیگری خراب شود.
- سقف هزینه تنظیم کنید. صفحه خطاهای Anthropic می‌گوید وقتی مصرف به سقفی که تعیین کرده‌اید برسد، API خطای 400 برمی‌گرداند؛ پس اپ شما باید در آن حالت پیام واضحی نشان دهد.
- محدودیت‌های نرخ را بررسی کنید در Console؛ این محدودیت‌ها برای هر سازمان اندازه‌گیری می‌شوند.
جریان درخواست
- کاربر در اپ کاری می‌کند: پیام می‌فرستد یا روی «خلاصه کن» کلیک می‌کند.
- مرورگر مسیر سرور خودتان را صدا می‌زند، نه مستقیم Anthropic را.
- سرور شما بررسی می‌کند کاربر وارد شده و مجاز به استفاده از قابلیت است و یک محدودیت برای هر کاربر اعمال می‌کند.
- درخواست را می‌سازد: یک پرامپت system با قوانین شما، ورودی کاربر و هر داده‌ای که کار لازم دارد از پایگاه داده.
- Messages API را با کلید از متغیر محیطی و یک
max_tokensمنطقی صدا می‌زند. - پاسخ را به مرورگر استریم می‌کند و مصرف توکن را از پاسخ ثبت می‌کند.
گزینه‌ها و مصالحه‌ها
| تصمیم | انتخاب ساده | وقتی بیشتر بروید |
|---|---|---|
| استریم | صبر برای پاسخ کامل | برای چت و هر پاسخ طولانی استریم کنید؛ Anthropic برای درخواست‌های طولانی استریم یا batch را پیشنهاد می‌کند |
| قالب خروجی | متن ساده | خروجی JSON ساخت‌یافته وقتی کدتان باید فیلدها را بخواند |
| داده‌های شما | گنجاندن رکورد مرتبط | بازیابی از محتوای شما وقتی داده زیاد است (RAG چیست) |
| اقدام‌ها | مدل فقط متن می‌نویسد | tool use، که در آن مدل از کد شما می‌خواهد تابعی را که تعریف کرده‌اید اجرا کند |
| کار انبوه و غیرفوری | حلقه روی آیتم‌ها | Message Batches API که نتایج را بعداً می‌گیرید |
پرامپت‌هایی برای ساخت‌دهنده هوش مصنوعی
اولین قابلیت:
یک پنل «درباره این سند بپرس» اضافه کن. این پنل مسیر سرور POST /api/ask را صدا می‌زند که بررسی می‌کند کاربر وارد شده و مالک سند است، سپس Claude Messages API را با SDK رسمی Anthropic و راز ANTHROPIC_API_KEY صدا می‌زند. نام مدل را از راز CLAUDE_MODEL بخوان. پرامپت system: «فقط بر اساس سند ارائه‌شده جواب بده. اگر جواب در آن نیست، همین را بگو.» متن سند و سؤال را بفرست، max_tokens را ۸۰۰ بگذار، پاسخ را به صفحه استریم کن و کلید را هرگز به مرورگر نفرست.
محافظ‌ها و خطاها:
هر کاربر را به ۲۰ سؤال در ساعت محدود کن و این را در پایگاه داده ثبت کن. توکن‌های ورودی و خروجی هر پاسخ را همراه با شناسه کاربر و شناسه درخواست ثبت کن. برای خطاهای ۴۲۹ یا ۵۲۹، تا ۳ بار با تأخیر نمایی دوباره تلاش کن و هدر retry-after را رعایت کن؛ بعد پیام «دستیار الان شلوغ است، کمی بعد دوباره امتحان کنید» را نشان بده. اگر API خطای سقف هزینه داد، پیام «قابلیت‌های هوش مصنوعی موقتاً متوقف شده‌اند» را نشان بده و به ادمین هشدار بده.
خطاهایی که باید برایشان برنامه داشته باشید
طبق مستندات خطای Anthropic، این‌ها خطاهایی هستند که اپ شما واقعاً با آن‌ها مواجه می‌شود:
| کد | نوع | چه کنید |
|---|---|---|
| 400 | invalid_request_error | درخواست را اصلاح کنید؛ وقتی به سقف هزینه‌ای که خودتان تعیین کرده‌اید برسید هم برگردانده می‌شود |
| 401 | authentication_error | بررسی کنید کلید وجود دارد، درست است و باطل نشده |
| 413 | request_too_large | کمتر بفرستید؛ Messages API تا ۳۲ مگابایت برای هر درخواست می‌پذیرد |
| 429 | rate_limit_error | عقب‌نشینی و تلاش مجدد، با رعایت retry-after |
| 500 | api_error | با تأخیر دوباره امتحان کنید؛ اگر ادامه داشت، با شناسه درخواست به پشتیبانی بگویید |
| 529 | overloaded_error | ترافیک بالای موقت در تمام کاربران؛ عقب‌نشینی و تلاش مجدد |
مستندات Anthropic می‌گوید SDKهای رسمی خطاهای گذرا (خطای اتصال، محدودیت نرخ و خطاهای 5xx) را به‌طور پیش‌فرض دو بار با تأخیر نمایی خودکار دوباره امتحان می‌کنند و می‌توانید این رفتار را تنظیم کنید. هر پاسخ یک هدر request-id دارد؛ آن را ثبت کنید تا پشتیبانی بتواند مشکلات را دنبال کند.
اشتباه‌های رایج
- فراخوانی API از مرورگر. کلید شما عمومی می‌شود. همیشه از سرور خودتان عبور دهید. چطور کلیدهای API را امن نگه داریم را ببینید.
- فراموش کردن اینکه
max_tokensسقف است، نه هدف. آن را به نیاز قابلیت تنظیم کنید؛ خیلی کم باشد پاسخ‌ها قطع می‌شوند و خیلی زیاد باشد پاسخ‌های طولانی و پرهزینه می‌گیرید. - گذاشتن قوانین در پیام کاربر. دستورهای ثابت باید در پرامپت
systemباشند؛ دسترسی‌ها در کد شما. - فرستادن کل گفت‌وگو برای همیشه. وقتی گفت‌وگوها بلند می‌شوند، نوبت‌های قدیمی را کوتاه یا خلاصه کنید.
- نبود سقف هزینه یا سقف برای هر کاربر.
- ثابت کردن شناسه مدل در کد. مدل‌ها به‌روز و بازنشسته می‌شوند.
- نادیده گرفتن دلیل توقف. اگر پاسخ به
max_tokensرسیده و متوقف شده، به کاربر بگویید یا سقف را بالا ببرید.
چک‌لیست
- کلید API در Claude Console ساخته و به‌عنوان راز سمت سرور ذخیره شده
- کلیدهای جدا برای آزمایش و تولید
- سقف هزینه تنظیم شده؛ پیام واضح وقتی به آن می‌رسید
- همه درخواست‌ها از سرور شما با بررسی دسترسی عبور می‌کنند
- قوانین در پرامپت system است؛ شناسه مدل قابل تنظیم است
-
max_tokensبرای هر قابلیت تنظیم شده؛ پاسخ‌های طولانی استریم می‌شوند - محدودیت نرخ برای هر کاربر در اپ
- خطاهای 429 و 529 با عقب‌نشینی مدیریت شده؛ شناسه‌های درخواست ثبت می‌شوند
- حالت خطای دوستانه که صفحه را خراب نمی‌کند
- با ورودی خالی، بسیار طولانی و خصمانه آزمایش شده
استفاده از Claude API در Mythex
در اپ‌هایی که با Mythex می‌سازید، قابلیت‌های Claude از کلید Anthropic خودتان استفاده می‌کنند و هزینه‌شان به حساب Anthropic شما می‌رود، نه به اعتبار ساخت Mythex. این با عاملی که کد شما را می‌نویسد جداست. ANTHROPIC_API_KEY را از طریق /secrets، تنظیمات پروژه یا کارت راز در گفت‌وگو به‌عنوان راز پروژه اضافه کنید، و سپس قابلیت را با پرامپتی مثل نمونه‌های بالا توضیح دهید. بعد از تغییر راز روی اپ منتشرشده، دوباره منتشر کنید. برای یک پرامپت شروع، افزودن قابلیت‌های هوش مصنوعی با کلیدهای API خودتان را ببینید. اگر بین ارائه‌دهنده‌ها مقایسه می‌کنید، چطور OpenAI API را یکپارچه کنیم همین موضوع را برای OpenAI پوشش می‌دهد.
پرسش‌ها
چطور کلید Claude API بگیرم؟
با Claude Console در platform.claude.com وارد شوید، صورتحساب را تنظیم کنید و یک کلید API بسازید. آن را به‌عنوان یک راز سمت سرور ذخیره کنید که معمولاً ANTHROPIC_API_KEY نامیده می‌شود و هرگز آن را در کد مرورگر نگذارید.
یک درخواست به Claude API چه چیزهایی لازم دارد؟
طبق مرجع Messages API از Anthropic تا سپتامبر ۲۰۲۶، سه فیلد الزامی بدنه درخواست عبارت‌اند از model، max_tokens و messages. فراخوانی مستقیم HTTP به هدرهای x-api-key و anthropic-version هم نیاز دارد؛ SDKهای رسمی این‌ها را برای شما تنظیم می‌کنند.
خطای ۵۲۹ از Claude API یعنی چه؟
صفحه خطاهای Anthropic توضیح می‌دهد که ۵۲۹ یعنی overloaded_error: API به‌خاطر ترافیک بالا در تمام کاربران موقتاً شلوغ است. با تأخیر نمایی دوباره تلاش کنید. SDKهای رسمی برخی خطاهای گذرا را خودکار دوباره امتحان می‌کنند.
آیا می‌توانم از Claude با کدی استفاده کنم که برای SDK مربوط به OpenAI نوشته شده؟
Anthropic یک لایه سازگاری SDK مربوط به OpenAI را مستند کرده که امکان استفاده از Claude از طریق سطح SDK مربوط به OpenAI را می‌دهد. برای کد جدید، SDKهای خود Anthropic به قابلیت‌های مخصوص Claude دسترسی می‌دهند و معمولاً نقطه شروع بهتری هستند.