رفتن به محتوا
Claude Code Docs غیر رسمی

Google Vertex AI

پیش‌نیازها

Section titled “پیش‌نیازها”

پیش از پیکربندی Claude Code با Vertex AI، مطمئن شو این‌ها را داری:

  • یک حساب Google Cloud Platform (GCP) با billing فعال
  • یک پروژه‌ی GCP با Vertex AI API فعال
  • دسترسی به مدل‌های موردنظر Claude (برای مثال، Claude Sonnet 4.6)
  • Google Cloud SDK (gcloud) نصب و پیکربندی‌شده
  • quota تخصیص‌داده‌شده در منطقه‌ی GCP موردنظر

برای ورود با اعتبارنامه‌های Vertex AI خودت، ورود با Vertex AI را در پایین دنبال کن. برای استقرار Claude Code در سراسر یک تیم، از گام‌های راه‌اندازی دستی استفاده کن و پیش از عرضه نسخه‌های مدلت را pin کن.

ورود با Vertex AI

Section titled “ورود با Vertex AI”

اگر اعتبارنامه‌های Google Cloud داری و می‌خواهی استفاده از Claude Code را از طریق Vertex AI شروع کنی، wizardِ ورود تو را قدم‌به‌قدم پیش می‌برد. پیش‌نیازهای سمت-GCP را یک بار به‌ازای هر پروژه کامل می‌کنی؛ wizard سمت Claude Code را مدیریت می‌کند.

فعال‌کردن مدل‌های Claude در پروژه‌ی GCP‌ات

Vertex AI API را فعال کن برای پروژه‌ات، بعد در Vertex AI Model Garden درخواست دسترسی به مدل‌های Claude موردنظرت را بده. برای دسترسی‌هایی که حسابت نیاز دارد پیکربندی IAM را ببین.

راه‌اندازی Claude Code و انتخاب Vertex AI

claude را اجرا کن. در پرامپت ورود، 3rd-party platform را انتخاب کن، بعد Google Vertex AI.

دنبال‌کردن پرامپت‌های wizard

انتخاب کن چطور به Google Cloud احراز هویت می‌کنی: Application Default Credentials از gcloud، یک فایل کلید service account، یا اعتبارنامه‌هایی که از قبل در محیطت هستند. wizard پروژه و منطقه‌ات را تشخیص می‌دهد، راستی‌آزمایی می‌کند پروژه‌ات کدام مدل‌های Claude را می‌تواند فرابخواند، و می‌گذارد pin‌شان کنی. نتیجه را در بلاک env از فایل تنظیمات کاربرت ذخیره می‌کند، پس لازم نیست خودت متغیرهای محیطی را export کنی.

پس از این‌که وارد شدی، هر وقت خواستی /setup-vertex را اجرا کن تا wizard را دوباره باز کنی و اعتبارنامه‌ها، پروژه، منطقه، یا pinهای مدلت را عوض کنی.

پیکربندی منطقه

Section titled “پیکربندی منطقه”

Claude Code از endpointهای global، چندمنطقه‌ای، و منطقه‌ایِ Vertex AI پشتیبانی می‌کند. CLOUD_ML_REGION را روی global، یک محل چندمنطقه‌ای مثل eu یا us، یا یک منطقه‌ی مشخص مثل us-east5 تنظیم کن. Claude Code برای هر شکل، hostname درست Vertex AI را انتخاب می‌کند، از جمله host‌های aiplatform.eu.rep.googleapis.com و aiplatform.us.rep.googleapis.com برای محل‌های چندمنطقه‌ای.

راه‌اندازی دستی

Section titled “راه‌اندازی دستی”

برای پیکربندی Vertex AI از طریق متغیرهای محیطی به‌جای wizard، برای مثال در CI یا یک عرضه‌ی سازمانیِ اسکریپتی، گام‌های زیر را دنبال کن.

۱. فعال‌کردن Vertex AI API

Section titled “۱. فعال‌کردن Vertex AI API”

Vertex AI API را در پروژه‌ی GCP‌ات فعال کن:

Terminal window
# Set your project ID
gcloud config set project YOUR-PROJECT-ID


# Enable Vertex AI API
gcloud services enable aiplatform.googleapis.com

۲. درخواست دسترسی به مدل

Section titled “۲. درخواست دسترسی به مدل”

درخواست دسترسی به مدل‌های Claude در Vertex AI را بده:

  1. به Vertex AI Model Garden برو
  2. مدل‌های «Claude» را جست‌وجو کن
  3. درخواست دسترسی به مدل‌های Claude موردنظر را بده (برای مثال، Claude Sonnet 4.6)
  4. منتظر تأیید بمان (ممکن است ۲۴ تا ۴۸ ساعت طول بکشد)

۳. پیکربندی اعتبارنامه‌های GCP

Section titled “۳. پیکربندی اعتبارنامه‌های GCP”

Claude Code از احراز هویت استاندارد Google Cloud استفاده می‌کند.

برای اطلاعات بیشتر، مستندات احراز هویت Google Cloud را ببین.

Claude Code نسخه‌ی v2.1.121 یا بالاتر از Workload Identity Federation مبتنی‌بر-گواهیِ X.509 از طریق همان زنجیره‌ی Application Default Credentials پشتیبانی می‌کند. GOOGLE_APPLICATION_CREDENTIALS را روی مسیر فایل پیکربندیِ اعتبارنامه‌ات تنظیم کن.

پیکربندی پیشرفته‌ی اعتبارنامه

Section titled “پیکربندی پیشرفته‌ی اعتبارنامه”

Claude Code از تازه‌سازیِ خودکار اعتبارنامه برای GCP از طریق تنظیم gcpAuthRefresh پشتیبانی می‌کند. وقتی Claude Code تشخیص دهد اعتبارنامه‌های GCP‌ات منقضی شده‌اند یا نمی‌توان بارگذاری‌شان کرد، پیش از تلاش دوباره‌ی درخواست، دستور پیکربندی‌شده را اجرا می‌کند تا اعتبارنامه‌های جدید بگیرد.

{
  "gcpAuthRefresh": "gcloud auth application-default login",
  "env": {
    "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
  }
}

خروجی دستور به کاربر نمایش داده می‌شود، ولی ورودیِ تعاملی پشتیبانی نمی‌شود. این برای جریان‌های احراز هویتِ مبتنی‌بر-مرورگر که در آن CLI یک URL نشان می‌دهد و تو احراز هویت را در مرورگر کامل می‌کنی خوب کار می‌کند. دستور تازه‌سازی اگر احراز هویت کامل نشود پس از سه دقیقه time out می‌شود. اگر gcpAuthRefresh را در تنظیمات پروژه مثل .claude/settings.json بگذاری، دستور فقط پس از پذیرش پرامپتِ trust workspace اجرا می‌شود.

۴. پیکربندی Claude Code

Section titled “۴. پیکربندی Claude Code”

متغیرهای محیطی زیر را تنظیم کن:

Terminal window
# Enable Vertex AI integration
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID


# Optional: Override the Vertex endpoint URL for custom endpoints or gateways
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com


# Optional: Disable prompt caching if needed
export DISABLE_PROMPT_CACHING=1


# Optional: Request 1-hour prompt cache TTL instead of the 5-minute default
export ENABLE_PROMPT_CACHING_1H=1


# When CLOUD_ML_REGION=global, override region for models that don't support global endpoints
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

بیشترِ نسخه‌های مدل یک متغیر VERTEX_REGION_CLAUDE_* متناظر دارند. برای فهرست کامل مرجع متغیرهای محیطی را ببین. Vertex Model Garden را بررسی کن تا تشخیص دهی کدام مدل‌ها از endpointهای global پشتیبانی می‌کنند در برابر فقط-منطقه‌ای.

Prompt caching به‌صورت خودکار فعال است. برای غیرفعال‌کردنش DISABLE_PROMPT_CACHING=1 را تنظیم کن. برای درخواست یک cache TTLِ یک‌ساعته به‌جای پیش‌فرض پنج‌دقیقه‌ای، ENABLE_PROMPT_CACHING_1H=1 را تنظیم کن؛ نوشتن‌های cache با TTLِ یک‌ساعته با نرخ بالاتری حساب می‌شوند. برای rate limitهای بالاتر، با پشتیبانی Google Cloud تماس بگیر. هنگام استفاده از Vertex AI، دستور /logout در دسترس نیست چون احراز هویت از طریق اعتبارنامه‌های Google Cloud مدیریت می‌شود.

Claude Code به‌صورت پیش‌فرض MCP tool search را روی Vertex AI غیرفعال می‌کند، پس تعاریف ابزار MCP از پیش بارگذاری می‌شوند. Vertex AI از tool search برای Claude Sonnet 4.5 و بالاتر و Claude Opus 4.5 و بالاتر پشتیبانی می‌کند. ENABLE_TOOL_SEARCH=true را تنظیم کن تا روی آن مدل‌ها فعالش کنی. مدل‌های قدیمی‌تر روی Vertex AI هدر بتای موردنیاز را نمی‌پذیرند، و اگر tool search را با آن‌ها فعال کنی درخواست‌ها شکست می‌خورند.

۵. Pin‌کردن نسخه‌های مدل

Section titled “۵. Pin‌کردن نسخه‌های مدل”

این متغیرهای محیطی را روی model IDهای مشخص Vertex AI تنظیم کن.

بدون ANTHROPIC_DEFAULT_OPUS_MODEL، نام مستعار opus روی Vertex به Opus 4.6 حل می‌شود. آن را روی شناسه‌ی Opus 4.8 تنظیم کن تا از تازه‌ترین مدل استفاده کنی:

Terminal window
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

برای model IDهای فعلی و قدیمی، مرور کلی مدل‌ها را ببین. برای فهرست کامل متغیرهای محیطی پیکربندی مدل را ببین.

Claude Code وقتی هیچ متغیر pin تنظیم نشده باشد از این مدل‌های پیش‌فرض استفاده می‌کند:

نوع مدلمقدار پیش‌فرض
مدل اصلیclaude-sonnet-4-5@20250929
مدل کوچک/سریعهمان مدل اصلی

کارهای پس‌زمینه مثل تولید عنوان نشست از مدل کوچک/سریع استفاده می‌کنند، که معمولاً یک مدل کلاس-Haiku است. روی Vertex AI، Claude Code این را به مدل اصلی پیش‌فرض می‌گذارد چون Haiku ممکن است در هر پروژه یا منطقه فعال نباشد. برای استفاده از Haiku برای کارهای پس‌زمینه، ANTHROPIC_DEFAULT_HAIKU_MODEL را روی یک model ID که در پروژه‌ات در دسترس است تنظیم کن.

برای سفارشی‌سازیِ بیشترِ مدل‌ها:

Terminal window
export ANTHROPIC_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

بررسی‌های مدل هنگام راه‌اندازی

Section titled “بررسی‌های مدل هنگام راه‌اندازی”

وقتی Claude Code با Vertex AI پیکربندی‌شده راه‌اندازی می‌شود، راستی‌آزمایی می‌کند که مدل‌هایی که قصد استفاده‌شان را دارد در پروژه‌ات قابل‌دسترس‌اند. این بررسی به Claude Code نسخه‌ی v2.1.98 یا بالاتر نیاز دارد.

اگر یک نسخه‌ی مدل را pin کرده‌ای که قدیمی‌تر از پیش‌فرض فعلی Claude Code است، و پروژه‌ات می‌تواند نسخه‌ی جدیدتر را فرابخواند، Claude Code از تو می‌خواهد pin را به‌روز کنی. پذیرفتن، model ID جدید را در فایل تنظیمات کاربرت می‌نویسد و Claude Code را ری‌استارت می‌کند. رد‌کردن تا تغییر بعدیِ نسخه‌ی پیش‌فرض به‌خاطر سپرده می‌شود.

اگر مدلی را pin نکرده‌ای و پیش‌فرض فعلی در پروژه‌ات در دسترس نیست، Claude Code برای نشست جاری به نسخه‌ی قبلی fallback می‌کند و یک اعلان نشان می‌دهد. این fallback ماندگار نمی‌شود. مدل جدیدتر را در Model Garden فعال کن یا یک نسخه pin کن تا انتخاب را دائمی کنی.

پیکربندی IAM

Section titled “پیکربندی IAM”

دسترسی‌های IAM موردنیاز را تخصیص بده:

نقش roles/aiplatform.user شامل دسترسی‌های موردنیاز است:

  • aiplatform.endpoints.predict - برای فراخوانی مدل و token counting موردنیاز است

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

برای جزئیات، مستندات IAM Vertex را ببین.

کانتکست ویندوی ۱M توکنی

Section titled “کانتکست ویندوی ۱M توکنی”

Claude Opus 4.6 و بالاتر، و Sonnet 4.6، از کانتکست ویندوی ۱M توکنی روی Vertex AI پشتیبانی می‌کنند. Claude Code وقتی یک گونه‌ی مدل ۱M انتخاب می‌کنی، کانتکست ویندوی گسترش‌یافته را به‌صورت خودکار فعال می‌کند.

wizardِ راه‌اندازی هنگام pin‌کردن مدل‌ها یک گزینه‌ی کانتکست ۱M پیشنهاد می‌دهد. برای فعال‌کردنش روی یک مدلِ به‌صورت دستی pin‌شده، [1m] را به model ID اضافه کن. برای جزئیات Pin‌کردن مدل‌ها برای استقرارهای شخص-ثالث را ببین.

عیب‌یابی

Section titled “عیب‌یابی”

اگر با خطاهای «Could not load the default credentials» مواجه شدی:

  • gcloud auth application-default login را اجرا کن تا Application Default Credentials را راه‌اندازی کنی
  • GOOGLE_APPLICATION_CREDENTIALS را روی مسیر فایل کلید یک service account تنظیم کن
  • برای همه‌ی گزینه‌ها پیکربندی اعتبارنامه‌های GCP را ببین

اگر با مشکلات quota مواجه شدی:

  • quotaهای فعلی را بررسی کن یا از طریق Cloud Console درخواست افزایش quota بده

اگر با خطاهای 404ِ «model not found» مواجه شدی:

  • تأیید کن مدل در Model Garden Enabled است
  • راستی‌آزمایی کن مدل در محلی که مشخص کردی در دسترس است. برخی مدل‌ها فقط روی محل‌های global یا چندمنطقه‌ای مثل eu و us ارائه می‌شوند، نه در مناطق مشخص
  • اگر از CLOUD_ML_REGION=global استفاده می‌کنی، در Model Garden زیر «Supported features» بررسی کن که مدل‌هایت از endpointهای global پشتیبانی می‌کنند. برای مدل‌هایی که از endpointهای global پشتیبانی نمی‌کنند، یکی از این دو کار را بکن:
    • از طریق ANTHROPIC_MODEL یا ANTHROPIC_DEFAULT_HAIKU_MODEL یک مدل پشتیبانی‌شده مشخص کن، یا
    • با متغیرهای محیطی VERTEX_REGION_<MODEL_NAME> یک منطقه یا محل چندمنطقه‌ای تنظیم کن

اگر با خطاهای 429 مواجه شدی:

  • برای endpointهای منطقه‌ای، مطمئن شو مدل اصلی و مدل کوچک/سریع در منطقه‌ی انتخابی‌ات پشتیبانی می‌شوند
  • سوئیچ به CLOUD_ML_REGION=global را برای در دسترس‌بودن بهتر در نظر بگیر

منابع بیشتر

Section titled “منابع بیشتر”