آموزش احراز هویت API کلود: Anthropic، Bedrock و Vertex

چهار مسیر احراز هویت API کلود

احراز هویت API کلود به یک تصمیم نهایی ختم می‌شود: کلاینت شما کدام اعتبارنامه را در شبکه ارسال می‌کند. چهار پاسخ برای این پرسش وجود دارد و این‌ها صرفاً نسخه‌های متفاوتی از یک مکانیزم نیستند. API مستقیم Anthropic یک کلید ایستا را در هدر x-api-key ارسال می‌کند. Amazon Bedrock هر درخواست را با اعتبارنامه‌های AWS امضا می‌کند و در آن تنظیمات، هیچ کلید Anthropic وجود ندارد. Google Cloud یک توکن دسترسی کوتاه‌مدت گوگل ارسال می‌کند. Microsoft Foundry یک کلید صادرشده توسط Azure یا یک توکن Microsoft Entra دریافت می‌کند.

این راهنما برای متصل کردن یک SDK (کیت توسعه نرم‌افزار) به سرویسی است که روی یک سرور لینوکسی اجرا می‌شود. اگر در حال پیکربندی ابزار خط فرمان Claude Code هستید، متغیرها و جریان کار متفاوت است: به اشاره دادن Claude Code به Bedrock یا Vertex مراجعه کنید. اگر سرویس هنوز وجود ندارد، ابتدا آن را با اولین برنامه API کلود روی یک VPS بسازید و سپس برای دریافت اعتبارنامه به اینجا بازگردید.

تمام موارد زیر در اوت 2026 با مستندات پلتفرم Anthropic مطابقت داده شده است. شناسه‌های مدل، قیمت‌ها، نسخه‌های SDK و ساختار endpointها همگی تغییر می‌کنند، بنابراین این راهنما به جای درج مقادیری که قدیمی می‌شوند، به صفحات ارائه‌دهندگان برای این موارد لینک می‌دهد.

مسیر 1: کلید API شرکت Anthropic

این مسیر مستقیم‌ترین راه است و تنها روشی است که در آن Anthropic کلید محرمانه (secret) را صادر می‌کند. درخواست‌ها به endpoint مربوط به Messages در میزبان API شرکت Anthropic ارسال می‌شوند و هر درخواست باید شامل سه هدر باشد.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "MODEL_ID", "max_tokens": 64, "messages": [{"role": "user", "content": "Hello"}]}'

عبارت MODEL_ID را با یک شناسه فعلی از نمای کلی مدل‌ها در سایت Anthropic جایگزین کنید. پاسخ صحیح، یک JSON است که شامل یک آرایه content و یک شیء usage می‌باشد. کلید اشتباه یا منقضی‌شده، خطای HTTP 401 را به همراه authentication_error برمی‌گرداند. نبود هدر anthropic-version یک خطای مجزا محسوب می‌شود، زیرا این هدر در هر درخواست الزامی است؛ SDKها این هدر را به‌طور خودکار برای شما تنظیم می‌کنند.

ساخت کلاینت در این روش کوتاه‌ترین حالت در میان چهار مسیر است، زیرا هیچ چیزی برای ساختن وجود ندارد. هر SDK رسمی، مقدار ANTHROPIC_API_KEY را به‌طور خودکار از محیط (environment) می‌خواند.

import os
from anthropic import Anthropic

client = Anthropic()  # reads ANTHROPIC_API_KEY from the environment

message = client.messages.create(
    model=os.environ["CLAUDE_MODEL"],
    max_tokens=64,
    messages=[{"role": "user", "content": "Hello"}],
)
print(message.usage)

نگهداری شناسه مدل در محیط (environment) در کنار کلید، کار عاقلانه‌ای است. نام مدل‌ها طبق زمان‌بندی‌هایی تغییر می‌کنند که شما کنترلی روی آن‌ها ندارید و استقرار مجدد کد فقط برای ویرایش یک رشته متنی، کاری غیرضروری است.

کلیدها در Console ساخته می‌شوند، جایی که شما در زمان ایجاد، یک تاریخ انقضا برای آن تعیین می‌کنید: گزینه‌های پیش‌فرض شامل 3 ساعت، 1 روز، 7 روز یا 30 روز، یک مدت‌زمان سفارشی، یا گزینه «هرگز» (Never) هستند. تاریخ انقضا در زمان ساخت ثابت می‌شود و بعداً قابل تغییر نیست. شرکت Anthropic پیش از انقضای کلیدهای بلندمدت به سازنده کلید ایمیل می‌زند، اما کلیدهایی با طول عمر کوتاه بدون هیچ هشدار ایمیلی منقضی می‌شوند. کلید منقضی‌شده خطای 401 برمی‌گرداند و قابل فعال‌سازی مجدد نیست، بنابراین تنها راه حل، ساخت یک کلید جدید است.

در API مستقیم، هیچ منطقه‌ای (region) برای انتخاب وجود ندارد و صورت‌حساب مستقیماً برای سازمان شما در Anthropic صادر می‌شود. Workspaces کلید را به یک پروژه خاص محدود می‌کنند که تمیزترین راه برای مشاهده میزان هزینه یک سرویس واحد است. برای محاسبات پشت این صورت‌حساب، به نحوه مقایسه قیمت‌گذاری API بر اساس توکن با اشتراک مراجعه کنید.

یک گزینه دیگر نیز در اینجا جای می‌گیرد، زیرا نیاز به کلید محرمانه ثابت را به‌طور کامل حذف می‌کند. Workload Identity Federation به یک workload اجازه می‌دهد تا یک توکن OpenID Connect (OIDC) را از یک ارائه‌دهنده هویت که به آن اعتماد دارید، با یک توکن کوتاه‌مدت Anthropic در POST /v1/oauth/token مبادله کند و SDK پیش از انقضای توکن، آن را به‌طور خودکار تمدید می‌کند. در این حالت، هیچ رشته sk-ant-api... ساخته یا کپی نمی‌شود. این روش برای Kubernetes، GitHub Actions و ماشین‌های مجازی ابری که از قبل دارای هویت پلتفرم هستند، مناسب است. یک VPS معمولی معمولاً چنین صادرکننده‌ای (issuer) ندارد، بنابراین در آن محیط، استفاده از کلید API در یک فایل، پاسخ صادقانه‌ای است و باقی این راهنما نیز بر همین اساس پیش می‌رود.

مسیر 2: استفاده از اعتبارنامه‌های AWS در Amazon Bedrock

در Bedrock شما هیچ کلید Anthropic در اختیار ندارید. SDK هر درخواست HTTP را با استفاده از AWS Signature Version 4 (SigV4) و با به‌کارگیری اعتبارنامه‌های معمولی AWS امضا می‌کند و AWS تصمیم می‌گیرد که آیا آن فراخوان‌کننده اجازه دارد مدل را اجرا کند یا خیر.

pip install -U "anthropic[bedrock]"
aws sts get-caller-identity

aws sts get-caller-identity شماره حساب و ARN (Amazon Resource Name) هویتی که اعتبارنامه‌های شما به آن اشاره دارند را چاپ می‌کند. پیش از هر کار دیگری آن را اجرا کنید. اگر این دستور با خطا مواجه شود، فراخوانی Claude نیز شکست خواهد خورد، زیرا SDK از همان زنجیره پیروی می‌کند: ابتدا آرگومان‌های سازنده (constructor)، سپس متغیرهای محیطی AWS_ACCESS_KEY_ID، AWS_SECRET_ACCESS_KEY، AWS_SESSION_TOKEN و AWS_REGION، و در نهایت فایل پیکربندی AWS و بقیه زنجیره استاندارد (SSO، نقش‌های فرض‌شده، نقش وظیفه ECS، و سرویس متادیتای instance).

آنچه در ساخت کلاینت تغییر می‌کند، کلاس و یک آرگومان است.

from anthropic import AnthropicBedrock

client = AnthropicBedrock(aws_region="us-east-1")

در اینجا، Region دیگر صرفاً یک تزئین نیست. Endpointهای Bedrock مختص هر منطقه (region) هستند، دسترسی به مدل در کنسول AWS برای هر منطقه به‌صورت جداگانه اعطا می‌شود و منطقه بخشی از امضای SigV4 است؛ بنابراین امضایی که برای یک منطقه محاسبه شده باشد، توسط منطقه دیگر رد می‌شود. مقدار AWS_REGION را به‌طور صریح در محیط سرویس تنظیم کنید. Anthropic مستند کرده است که کلاینت AnthropicBedrock مقدار AWS_REGION را می‌خواند و در صورت تنظیم نبودن، به us-east-1 بازمی‌گردد و اینکه این کلاینت برای منطقه، ~/.aws/config را نمی‌خواند. به همین دلیل است که AWS CLI می‌تواند مدل‌های Claude را در همان سیستمی که پردازش Python شما شکست می‌خورد، با موفقیت لیست کند: CLI فایل پیکربندی شما را خوانده است اما کلاینت این کار را نکرده است.

روی یک EC2 instance، شما یک نقش IAM (مدیریت هویت و دسترسی) متصل می‌کنید و هیچ secretای روی دیسک قرار نمی‌گیرد، زیرا سرویس متادیتای instance اعتبارنامه‌های موقت را به SDK تحویل می‌دهد. یک VPS خارج از AWS نه نقش instance دارد و نه سرویس متادیتا. در این حالت، شما باید بین یک جفت کلید دسترسی بلندمدت کاربر IAM که روی سیستم ذخیره شده (که همان کلاس secretای است که کلید Anthropic دارد) و فدراسیون (federation) یکی را انتخاب کنید: احراز هویت در برابر ارائه‌دهنده هویت خود، فراخوانی AWS STS (سرویس توکن امنیتی) و استفاده از اعتبارنامه‌های موقتی که بازمی‌گرداند. Bedrock همچنین یک bearer token را از طریق AWS_BEARER_TOKEN_BEDROCK می‌پذیرد که سقف زمانی 12 ساعته برای آن مستند شده و توسط AWS به عنوان کم‌اولویت‌ترین مسیر توصیف شده است.

صورت‌حساب به جای Anthropic، روی حساب AWS شما منظور می‌شود که معمولاً دلیل اصلی استفاده از این سرویس است. طبق مستندات اوت 2026، endpointهای منطقه‌ای 10٪ گران‌تر از endpoint جهانی هستند. یک خطای Bedrock ارزش شناختن دارد زیرا شبیه به مشکل دسترسی است اما چنین نیست: Invocation of model ID ... with on-demand throughput isn't supported. Retry your request with the ID or ARN of an inference profile that contains this model.. این خطا مربوط به مسیریابی مدل (model routing) است و هیچ تغییری در اعتبارنامه‌ها آن را برطرف نخواهد کرد.

مسیر 3: اعتبارسنجی Google در Vertex AI

Google Cloud از Application Default Credentials (ADC) استفاده می‌کند؛ یک ترتیب جستجوی ثابت که کتابخانه‌های احراز هویت Google از آن پیروی می‌کنند تا بدون نیاز به معرفی دستی، اعتبارنامه را پیدا کنند. ADC ابتدا GOOGLE_APPLICATION_CREDENTIALS را بررسی می‌کند، سپس فایلی که توسط gcloud auth application-default login نوشته شده است و در نهایت سرویس اکانتی که از طریق metadata server متصل شده باشد.

pip install -U "anthropic[vertex]"
gcloud auth application-default login

در یک ایستگاه کاری، لاگین کردن باعث ایجاد $HOME/.config/gcloud/application_default_credentials.json می‌شود و کار تمام است. در یک سرور، این ابزار مناسبی نیست، زیرا اعتبارنامه‌ای که ذخیره می‌کند متعلق به یک انسان است و با حساب آن شخص از بین می‌رود. خارج از Google Cloud نیز metadata server وجود ندارد، بنابراین ADC به سراغ GOOGLE_APPLICATION_CREDENTIALS می‌رود که به یک فایل کلید سرویس اکانت اشاره دارد. آن فایل JSON یک secret با طول عمر زیاد است و دقیقاً به همان مدیریتی نیاز دارد که در ادامه این راهنما توضیح داده شده است. داخل Google Cloud، کافی است یک سرویس اکانت به VM متصل کنید تا دیگر نیازی به محافظت از هیچ فایلی نباشد.

from anthropic import AnthropicVertex

client = AnthropicVertex(project_id="my-project", region="global")

اگر از سطح SDK پایین‌تر بروید و از HTTP خام استفاده کنید، دو مورد تغییر می‌کند. شناسه مدل از بدنه درخواست خارج شده و به مسیر URL منتقل می‌شود و anthropic_version از هدر خارج شده و به بدنه می‌رود، جایی که باید به صورت vertex-2023-10-16 خوانده شود. این اعتبارنامه یک توکن دسترسی معمولی Google است.

curl https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/publishers/anthropic/models/${MODEL_ID}:rawPredict \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"anthropic_version": "vertex-2023-10-16", "max_tokens": 64, "messages": [{"role": "user", "content": "Hello"}]}'

منطقه (Region) یک آرگومان درجه یک است. global برای دسترسی‌پذیری به‌صورت پویا مسیریابی می‌کند، us و eu شناسه‌های چندمنطقه‌ای هستند و نامی مانند us-east5 یک منطقه واحد را مشخص می‌کند. طبق مستندات اوت 2026، استفاده از endpointهای چندمنطقه‌ای و منطقه‌ای 10% گران‌تر از حالت جهانی (global) است. صورت‌حساب از طریق پروژه Google Cloud صادر می‌شود، بنابراین سهمیه (quota) و فاکتورها متعلق به Google هستند.

مسیر 4: Microsoft Foundry همان مسیر Azure است

اگر به دنبال Claude در Azure هستید، این همان بخشی است که به آن نیاز دارید و یک مسیر پشتیبانی‌شده وجود دارد. Claude در Microsoft Foundry (که قبلاً با نام Azure AI Foundry شناخته می‌شد) اجرا می‌شود و هزینه آن از طریق Azure Marketplace و در قالب Claude Consumption Units محاسبه می‌گردد. شما یک منبع Foundry ایجاد می‌کنید، یک مدل Claude را درون آن مستقر (deploy) می‌کنید و یک endpoint میزبانی‌شده در Azure را در https://{resource}.services.ai.azure.com/anthropic/v1/* فراخوانی می‌کنید.

دو نوع اعتبارنامه کار می‌کند. اولی، یک کلید صادرشده توسط Azure است که از تب Details در استقرار (deployment) در پورتال Foundry قابل دریافت است و در هدر api-key یا x-api-key ارسال می‌شود. دومی، یک توکن Microsoft Entra است که در سرور انتخاب بهتری محسوب می‌شود، زیرا در این حالت کنترل دسترسی مبتنی بر نقش (RBAC) در Azure تعیین می‌کند که چه کسی مجاز به فراخوانی endpoint است.

ACCESS_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)

curl https://${RESOURCE}.services.ai.azure.com/anthropic/v1/messages \
  -H "content-type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model": "DEPLOYMENT_NAME", "max_tokens": 64, "messages": [{"role": "user", "content": "Hello"}]}'

فیلد model شامل نام استقرار (deployment name) شماست، نه شناسه مدل. این دو به‌صورت پیش‌فرض یکسان هستند، اما به محض اینکه خودتان نامی برای استقرار انتخاب کنید، دیگر با هم مطابقت نخواهند داشت؛ این موضوع معمولاً علت اصلی خطای Deployment not found در درخواست‌هایی است که از نظر ساختاری صحیح هستند. SDKهای Python و TypeScript مقادیر ANTHROPIC_FOUNDRY_API_KEY و ANTHROPIC_FOUNDRY_RESOURCE را از محیط (environment) می‌خوانند. پشتیبانی از Foundry در همه SDKها وجود ندارد: طبق مستندات اوت 2026، این پشتیبانی شامل C#، Java، PHP، Python و TypeScript می‌شود، در حالی که SDKهای Go و Ruby نیاز دارند که کلاینت عمومی (generic client) به سمت URL پایه Foundry هدایت شود.

این راهکار یک نکته حساس دارد. اگر ANTHROPIC_API_KEY همچنان در محیط تنظیم شده باشد، کلاینت عمومی آن را شناسایی کرده و کلید Anthropic شما را به یک endpoint مایکروسافت ارسال می‌کند. این متغیر را حذف (unset) کنید یا پیش‌فرض‌های محیطی را در کلاینت غیرفعال نمایید. توکن‌های Entra پس از حدود یک ساعت منقضی می‌شوند، بنابراین یک پردازش طولانی‌مدت باید به‌جای دریافت توکن در زمان شروع، آن را به‌صورت دوره‌ای بازنشانی (refresh) کند.

اعتبارنامه‌های روی سرور شما تا چه زمانی معتبر هستند؟

[
  {
    "label": "Anthropic key, 30-day preset",
    "max_lifetime_hours": 720
  },
  {
    "label": "Anthropic key, 7-day preset",
    "max_lifetime_hours": 168
  },
  {
    "label": "AWS STS assumed role",
    "max_lifetime_hours": 12
  },
  {
    "label": "Bedrock bearer token",
    "max_lifetime_hours": 12
  },
  {
    "label": "Entra ID access token",
    "max_lifetime_hours": 1
  },
  {
    "label": "Federated Anthropic token",
    "max_lifetime_hours": 1
  }
]

این مقادیر، سقف‌های مجاز و تنظیمات پیش‌فرضی هستند که توسط هر ارائه‌دهنده منتشر شده و در اوت 2026 خوانده شده‌اند؛ این‌ها ارقام اندازه‌گیری‌شده نیستند. اهمیت این مقادیر تنها به یک دلیل است: آن‌ها به شما می‌گویند که اگر یک اعتبارنامه لو برود، تا زمانی که شما متوجه نشت آن شوید، چه مدت همچنان کار می‌کند. توکن‌های کوتاه‌مدت در انتهای جدول هر کدام 1 ساعت اعتبار دارند و SDK به‌طور خودکار آن‌ها را تمدید می‌کند، بنابراین این عمر کوتاه هیچ هزینه عملیاتی برای شما ندارد. یک نقش (role) فرض‌شده 12 ساعت اعتبار دارد. کلیدی که با پیش‌فرض 30 روزه ایجاد شده باشد، برای 720 ساعت معتبر باقی می‌ماند و این همان اعتبارنامه‌ای است که به مدت یک ماه در فایلی روی سرور شما باقی می‌ماند.

محل نگهداری اعتبارنامه‌ها در VPS

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

sudo useradd --system --home /opt/claude-app --shell /usr/sbin/nologin claudeapp
sudo install -d -m 700 -o root -g root /etc/claude-app
sudo install -m 600 -o root -g root /dev/null /etc/claude-app/env
sudoedit /etc/claude-app/env

این فایل شامل خطوط ساده KEY=value است. بدون export، بدون کوتیشن و بدون سینتکس shell؛ زیرا systemd خودش فایل را پردازش می‌کند و آن را از طریق shell اجرا نمی‌کند.

ANTHROPIC_API_KEY=sk-ant-api03-REPLACE-ME
CLAUDE_MODEL=REPLACE-ME

[Unit]
Description=Claude API service
After=network-online.target

[Service]
User=claudeapp
EnvironmentFile=/etc/claude-app/env
ExecStart=/opt/claude-app/venv/bin/python -m claude_app
Restart=on-failure

[Install]
WantedBy=multi-user.target

systemd فایل EnvironmentFile= را با دسترسی root می‌خواند، پیش از آنکه سطح دسترسی را به User=claudeapp کاهش دهد؛ بنابراین حساب کاربری سرویس نیازی به دسترسی خواندن فایل ندارد. حالت 600 با مالکیت root کافی است، به همین دلیل دستور install در بالا آن را به همین شکل تنظیم می‌کند. سرویس را با sudo systemctl enable --now claude-app شروع کنید و سپس با systemctl status claude-app تأیید کنید که unit به وضعیت active (running) رسیده است و در حلقه restart گیر نکرده است.

چهار مورد را که می‌توانید خودتان بررسی کنید، رعایت کنید:

• کلید را با Environment= داخل فایل unit ننویسید. یک unit در مسیر /etc/systemd/system برای همه کاربران قابل خواندن است، بنابراین systemctl cat claude-app می‌تواند اطلاعات محرمانه را برای هر کاربر محلی نمایش دهد.
• آن را commit نکنید. .gitignore فایل جدید را از commit دور نگه می‌دارد، اما تأثیری بر فایلی که قبلاً commit شده ندارد، زیرا تاریخچه git هر چیزی را که به آن داده شده حفظ می‌کند.
• آن را در image کانتینر قرار ندهید. خطوط ENV و مقادیر --build-arg در لایه‌های image ثبت می‌شوند و docker history --no-trunc آن‌ها را نمایش می‌دهد. حذف فایل در لایه‌های بعدی، آن را از لایه‌های قبلی پاک نمی‌کند. اطلاعات محرمانه را در زمان اجرا با --env-file یا از طریق یک فایل mount شده ارسال کنید.
• محیط پردازش (environment) را از دید root خصوصی فرض نکنید. sudo tr '\\0' '\\n' < /proc/$(pgrep -u claudeapp -f claude_app | head -1)/environ کلید را نمایش می‌دهد. هدف این است که اطلاعات محرمانه از دسترس سایر حساب‌های کاربری روی سیستم خارج شود، نه از دسترس root که در هر صورت می‌تواند آن را بخواند.

نکته آخر، مرز کارایی این طراحی را مشخص می‌کند. متغیر محیطی (environment variable) زمانی ظرف مناسبی برای اطلاعات محرمانه است که تنها سرویس و root امکان خواندن آن را داشته باشند. اگر پردازش کدی را اجرا می‌کند که شما ننوشته‌اید، این روش اشتباه است؛ زیرا هر چیزی که پردازش بتواند اجرا کند، قادر به خواندن محیط خودش نیز هست. دور نگه داشتن اطلاعات محرمانه از دسترس عامل هوش مصنوعی این مورد را پوشش می‌دهد که مسئله‌ای متفاوت با راهکاری متفاوت است.

چگونه کلید را بدون قطعی سرویس چرخش (rotate) دهم؟

ابتدا چرخش را انجام دهید و سپس کلید قبلی را ابطال کنید.

1. کلید جدید را در Console، در همان workspace کلید قدیمی ایجاد کنید.
2. آن را با استفاده از sudoedit در /etc/claude-app/env بنویسید.
3. دستور sudo systemctl restart claude-app را اجرا کنید.
4. اطمینان حاصل کنید که سرویس به درخواست‌ها پاسخ می‌دهد، سپس کلید قدیمی را در Console ابطال کنید.

فایل EnvironmentFile هنگام شروع unit خوانده می‌شود، بنابراین فرآیندی که در حال اجراست، مقداری را که در زمان راه‌اندازی دریافت کرده حفظ می‌کند. دستور systemctl daemon-reload فایل‌های unit را مجدداً می‌خواند اما تغییری در محیط فرآیند در حال اجرا ایجاد نمی‌کند، بنابراین فقط با restart کردن، کلید جدید اعمال می‌شود. ابطال کلید در مرحله 1 به جای مرحله 4، باعث قطعی سرویس تا زمان اجرای مرحله 3 خواهد شد.

سه روش دیگر در سمت ارائه‌دهنده (provider) چرخش می‌یابند. یک IAM user از دو کلید دسترسی فعال به‌طور همزمان پشتیبانی می‌کند، بنابراین کلید دوم را ایجاد و مستقر کنید، سپس کلید اول را حذف نمایید. کلید Google service account نیز به همین روش چرخش می‌یابد. کلید Foundry در پورتال بازتولید می‌شود که بلافاصله کلید قدیمی را نامعتبر می‌کند، بنابراین پیش از کلیک کردن، مقدار جدید را یادداشت کنید. توکن‌های Entra و توکن‌های فدرال Anthropic اصلاً نیازی به چرخش ندارند و این قوی‌ترین دلیل برای استفاده از آن‌ها در هر جای ممکن است.

زمانی که در Console هستید، یک سقف هزینه (spend limit) برای workspace تعیین کنید. کلید لو رفته پیش از هر چیز دیگری، هزینه‌بر است و محدود کردن هزینه‌های یک agent روی VPS شما را با این کنترل‌ها آشنا می‌کند.

چرا کلاینت من خطای 401 یا 403 برمی‌گرداند؟

خطای 401 با authentication_error در API مستقیم. کلید اشتباه است، ابطال شده یا تاریخ انقضای آن گذشته است. تاریخ انقضا موردی است که معمولاً نادیده گرفته می‌شود، زیرا کد تغییری نکرده و درخواست دیروز به‌درستی کار می‌کرده است. ستون انقضای کلید را در Console بررسی کنید یا expires_at را از Admin API بخوانید؛ جایی که برای کلیدهای بدون انقضا، مقدار null درج شده است.

SDK تنظیمات فدراسیون شما را نادیده می‌گیرد و به‌جای آن از یک کلید استفاده می‌کند. ANTHROPIC_API_KEY و ANTHROPIC_AUTH_TOKEN در اولویت اعتبارنامه‌ها بالاتر از فدراسیون قرار دارند، بنابراین هر کدام از آن‌ها، فدراسیون را تحت‌الشعاع قرار می‌دهد. نکتهٔ دقیق اینجاست: متغیری که به‌عنوان یک رشتهٔ خالی (empty string) صادر (export) شده، همچنان جایگاه خود را اشغال می‌کند، بنابراین ANTHROPIC_API_KEY="" باعث می‌شود SDK به‌جای عبور از این مرحله، با یک کلید خالی احراز هویت کند. از unset ANTHROPIC_API_KEY استفاده کنید.

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

خطای 403 در Foundry. توکن احراز هویت شده است، اما حساب Azure شما فاقد نقشی است که اجازهٔ این فراخوانی را بدهد. یک نقش Azure RBAC مانند Foundry User (که قبلاً Azure AI User نامیده می‌شد) یا Cognitive Services User را به هویتی که درخواست را ارسال می‌کند، اختصاص دهید.

هر خطایی در Bedrock. ابتدا دستور aws sts get-caller-identity را به‌عنوان کاربر سرویس اجرا کنید. این دستور مشخص می‌کند که آیا سرور اصلاً اعتبارنامه‌های AWS قابل‌استفاده دارد یا خیر؛ این کار مشکل اعتبارنامه را از مشکل دسترسی به مدل یا عدم تطابق منطقه (region) جدا می‌کند. دسترسی به مدل در کنسول AWS به‌صورت منطقه‌ای اعطا می‌شود و فعال کردن آن در یک منطقه و فراخوانی منطقهٔ دیگر بسیار رایج است.

FAQ

آیا برای استفاده از Claude در Bedrock یا Vertex به API key شرکت Anthropic نیاز دارم؟

خیر. در Amazon Bedrock، کیت توسعه نرم‌افزار (SDK) هر درخواست را با استفاده از اعتبارنامه‌های AWS و پروتکل SigV4 امضا می‌کند. در Google Cloud نیز درخواست‌ها با استفاده از توکن دسترسی Google که از طریق Application Default Credentials پیدا می‌شود، ارسال می‌گردند. در هیچ‌کدام از این دو حالت، secret صادرشده توسط Anthropic وجود ندارد و هزینه‌ها به‌جای Anthropic، به حساب ابری شما منظور می‌شود. به همین دلیل است که باقی ماندن یک کلید Anthropic در ANTHROPIC_API_KEY روی این میزبان‌ها یک ریسک امنیتی محسوب می‌شود: یک کلاینت عمومی که به سمت یک endpoint ابری تنظیم شده باشد، به‌راحتی آن کلید را به آنجا ارسال می‌کند.

آیا Claude در Azure در دسترس است؟

بله، از طریق Microsoft Foundry که قبلاً با نام Azure AI Foundry شناخته می‌شد. شما یک منبع Foundry ایجاد می‌کنید، یک مدل Claude را در آن مستقر (deploy) می‌کنید و با استفاده از یک کلید صادرشده توسط Azure در هدر api-key یا یک توکن bearer از Microsoft Entra، متد https://{resource}.services.ai.azure.com/anthropic/v1/messages را فراخوانی می‌کنید. هزینه‌ها از طریق Azure Marketplace و با واحد Claude Consumption Units محاسبه می‌شود. فیلد model در بدنه درخواست باید شامل نام deployment شما باشد؛ این نام تنها زمانی با شناسه مدل یکسان است که شما deployment را تغییر نام نداده باشید.

کلید API مربوط به Claude را کجا در یک سرور Linux ذخیره کنم؟

در فایلی که مالک آن root است و دسترسی آن روی 600 تنظیم شده باشد؛ این فایل باید از طریق EnvironmentFile= در یک unit فایل systemd بارگذاری شود. systemd پیش از آنکه کاربر را به User= مربوط به unit تغییر دهد، فایل را با دسترسی root می‌خواند؛ بنابراین حساب کاربری سرویس نیازی به دسترسی مستقیم به آن فایل ندارد. کلید را خارج از مخزن کد، خارج از خودِ unit فایل (که برای همه قابل خواندن است و توسط systemctl cat نمایش داده می‌شود) و خارج از لایه‌های image کانتینر نگه دارید، زیرا docker history --no-trunc هر چیزی را که با ENV یا --build-arg تنظیم شده باشد، نمایش می‌دهد.

چرا درخواست API من به Claude بدون هیچ تغییری، خطای 401 برمی‌گرداند؟

شایع‌ترین علت، رسیدن کلید به تاریخ انقضایی است که هنگام ایجاد آن تعیین شده بود. تاریخ انقضا در زمان ساخت کلید تنظیم می‌شود، پس از آن قابل ویرایش نیست و کلیدهای کوتاه‌مدت بدون ارسال ایمیل هشدار منقضی می‌شوند. یک کلید منقضی‌شده قابل فعال‌سازی مجدد نیست؛ بنابراین یک کلید جایگزین بسازید، آن را در فایل محیطی (environment file) بنویسید، سرویس را restart کنید و سپس کلید قدیمی را باطل کنید. اگر از معتبر بودن کلید اطمینان دارید، بررسی کنید که یک اعتبارنامه قدیمی باعث تداخل نشده باشد: متغیر ANTHROPIC_API_KEY حتی اگر روی یک رشته خالی تنظیم شده باشد، بر تمام منابع دیگر اعتبارنامه اولویت دارد.