📘 תיעוד 67

Claude Code ב-Google Cloud's Agent Platform

למדו על הגדרת Claude Code באמצעות Google Cloud's Agent Platform, לשעבר Vertex AI, כולל התקנה, הגדרת IAM ופתרון בעיות.

פורסים את Claude Code ברחבי הארגון שלכם? שוחחו עם מחלקת המכירות על תוכניות ארגוניות, SSO וחיוב מרכזי: צפייה בתוכניות, יצירת קשר עם המכירות.

#דרישות מוקדמות

לפני הגדרת Claude Code עם Google Cloud's Agent Platform, לשעבר Vertex AI, ודאו שיש לכם:

• חשבון Google Cloud Platform (GCP) עם חיוב מופעל (billing enabled)
• פרויקט GCP שבו ה-API של Google Cloud's Agent Platform מופעל
• גישה למודלי Claude הרצויים (לדוגמה, Claude Sonnet 4.6)
• Google Cloud SDK (gcloud) מותקן ומוגדר
• מכסה (quota) שהוקצתה באזור ה-GCP הרצוי

כדי להתחבר עם פרטי הגישה שלכם ב-Google Cloud's Agent Platform, פעלו לפי התחברות באמצעות Google Cloud's Agent Platform להלן. כדי לפרוס את Claude Code בצוות, השתמשו בשלבי ההגדרה הידנית וקבעו את גרסאות המודלים שלכם לפני ההפצה.

#התחברות באמצעות Agent Platform

אם יש לכם פרטי גישה ל-Google Cloud ואתם רוצים להתחיל להשתמש ב-Claude Code דרך Google Cloud's Agent Platform, אשף ההתחברות מדריך אתכם בתהליך. משלימים את דרישות הקדם בצד GCP פעם אחת לכל פרויקט, והאשף מטפל בצד של Claude Code.

1. הפעלת מודלי Claude בפרויקט ה-GCP שלכם: הפעילו את ה-API של Google Cloud's Agent Platform עבור הפרויקט שלכם, ולאחר מכן בקשו גישה למודלי Claude שאתם רוצים ב-Google Cloud's Agent Platform Model Garden. ראו הגדרת IAM לגבי ההרשאות שהחשבון שלכם צריך.
2. הפעלת Claude Code ובחירה ב-Google Cloud's Agent Platform: הריצו claude. בחלון בקשת ההתחברות, בחרו ב-3rd-party platform, ולאחר מכן ב-Google Vertex AI, התווית שבה חלון ההתחברות עדיין משתמש עבור Google Cloud's Agent Platform. אם אתם כבר מחוברים, הריצו /login כדי לפתוח את אותו התפריט.
3. מעקב אחר הנחיות האשף: בחרו כיצד תבצעו אימות מול Google Cloud: Application Default Credentials מ-gcloud, קובץ מפתח של service account, או פרטי גישה שכבר קיימים בסביבה שלכם. האשף מזהה את הפרויקט והאזור שלכם, מאמת אילו מודלי Claude הפרויקט שלכם מורשה להפעיל, ומאפשר לכם לקבע אותם. הוא שומר את התוצאה בבלוק ה-env של קובץ הגדרות המשתמש שלכם, כך שאינכם צריכים לייצא משתני סביבה בעצמכם.

לאחר שהתחברתם, הריצו /setup-vertex בכל עת כדי לפתוח מחדש את האשף ולשנות את פרטי הגישה, הפרויקט, האזור או קיבועי המודלים שלכם. שלב קיבוע המודלים מתחיל מהמודלים המקובעים הנוכחיים שלכם. האשף כותב אל ~/.claude/settings.json, או אל $CLAUDE_CONFIG_DIR/settings.json כאשר CLAUDE_CONFIG_DIR מוגדר.

#הגדרת אזור

Claude Code תומך בנקודות קצה גלובליות (global), רב אזוריות (multi-region), ואזוריות (regional) של Google Cloud's Agent Platform. הגדירו את CLOUD_ML_REGION ל-global, למיקום רב אזורי כגון eu או us, או לאזור ספציפי כגון us-east5. Claude Code בוחר את ה-hostname הנכון של Google Cloud's Agent Platform עבור כל תצורה, כולל השרתים aiplatform.eu.rep.googleapis.com ו-aiplatform.us.rep.googleapis.com עבור מיקומים רב אזוריים.

הערה: ייתכן ש-Google Cloud's Agent Platform לא תתמוך במודלי ברירת המחדל של Claude Code בכל סוג נקודת קצה. זמינות המודלים משתנה בין אזורים ספציפיים, מיקומים רב אזוריים, לבין נקודות קצה גלובליות. ייתכן שתצטרכו לעבור למיקום נתמך או לציין מודל נתמך.

#הגדרה ידנית

כדי להגדיר את Google Cloud's Agent Platform באמצעות משתני סביבה במקום האשף, למשל ב-CI או בהפצה ארגונית באמצעות סקריפט, פעלו לפי השלבים הבאים.

#1. הפעלת ה-API של Agent Platform

הפעילו את ה-API של Google Cloud's Agent Platform בפרויקט ה-GCP שלכם. החליפו את YOUR-PROJECT-ID במזהה פרויקט ה-GCP שלכם כאן ובשלב ההגדרה להלן:

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

# Enable Agent Platform API
gcloud services enable aiplatform.googleapis.com

#2. בקשת גישה למודלים

בקשו גישה למודלי Claude ב-Google Cloud's Agent Platform:

1. נווטו אל Google Cloud's Agent Platform Model Garden
2. חפשו מודלי "Claude"
3. בקשו גישה למודלי Claude הרצויים (לדוגמה, Claude Sonnet 4.6)
4. המתינו לאישור (עשוי להימשך 24 עד 48 שעות)

#3. הגדרת פרטי גישה של GCP

Claude Code משתמש באימות סטנדרטי של Google Cloud.

למידע נוסף, ראו תיעוד האימות של Google Cloud.

Claude Code תומך ב-Workload Identity Federation מבוסס תעודות X.509 דרך אותה שרשרת של Application Default Credentials. הגדירו את GOOGLE_APPLICATION_CREDENTIALS לנתיב של קובץ הגדרות פרטי הגישה שלכם.

הערה: Claude Code משתמש ב-ANTHROPIC_VERTEX_PROJECT_ID כמזהה הפרויקט עבור בקשות אל Google Cloud's Agent Platform. משתני הסביבה GCLOUD_PROJECT ו-GOOGLE_CLOUD_PROJECT וקובץ פרטי הגישה שאליו מפנה GOOGLE_APPLICATION_CREDENTIALS מקבלים עדיפות עליו. אם אף אחד מאלה אינו מוגדר, מזהה הפרויקט נקבע לפי הגדרות gcloud שלכם או מ-service account המשויך.

#הגדרת פרטי גישה מתקדמת

Claude Code תומך ברענון אוטומטי של פרטי גישה עבור GCP באמצעות ההגדרה gcpAuthRefresh. הוסיפו אותה אל קובץ ההגדרות של Claude Code, לדוגמה ~/.claude/settings.json. כאשר Claude Code מזהה שפרטי הגישה שלכם ל-GCP פגו או שאינם ניתנים לטעינה, הוא מריץ את הפקודה שהוגדרה כדי להשיג פרטי גישה חדשים לפני ניסיון חוזר של הבקשה.

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

Claude Code מציג לכם את פלט הפקודה, אך אינו יכול לשלוח לפקודה קלט אינטראקטיבי. הדבר פועל היטב עבור תהליכי אימות מבוססי דפדפן שבהם ה-CLI מציג כתובת URL ואתם משלימים את האימות בדפדפן. לפקודת הרענון מוקצב זמן קצוב של שלוש דקות אם האימות אינו מושלם. אם הגדרתם את gcpAuthRefresh בהגדרות פרויקט כגון .claude/settings.json, Claude Code מריץ אותה תחת אותו כלל אמון סביבת עבודה כמו hooks בקובצי הגדרות, הכולל הפעלות עם הדגל -p בתיקיות שמעולם לא נתתם בהן אמון.

#4. הגדרת Claude Code

הגדירו את משתני הסביבה הבאים:

# Enable Agent Platform integration
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

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

# 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_* תואם. ראו את מדריך משתני הסביבה לרשימה המלאה. בדקו ב-Google Cloud's Agent Platform Model Garden כדי לקבוע אילו מודלים תומכים בנקודות קצה גלובליות לעומת אזוריות בלבד.

אם ערך האזור אינו במבנה של שם אזור או מיקום, Claude Code מתייחס אליו כלא מוגדר. לדוגמה, Claude Code מתייחס לערך המכיל לוכסן, נקודה או רווח כלא מוגדר. Claude Code מבצע נסיגה (fallback) למקור אחר עבור כל משתנה:

• VERTEX_REGION_CLAUDE_*: Claude Code נסוג ל-CLOUD_ML_REGION.
• CLOUD_ML_REGION: Claude Code נסוג ל-us-east5.

שמירת הנחיות במטמון (Prompt caching) מופעלת אוטומטית. כדי להשבית אותה, הגדירו DISABLE_PROMPT_CACHING=1. כדי לבקש זמן שמירה במטמון (TTL) של שעה אחת במקום ברירת המחדל של 5 דקות, הגדירו ENABLE_PROMPT_CACHING_1H=1. כתיבות למטמון עם TTL של שעה מחויבות בתעריף גבוה יותר. כדי להגדיר ערכי TTL שונים עבור השיחה הראשית שלכם ועבור הבקשות ש-Claude Code מבצע מחוצה לה, בחרו את ה-TTL בעצמכם.

כדי להעלות את מגבלות הקצב שלכם, פנו לתמיכה של Google Cloud. בעת שימוש ב-Google Cloud's Agent Platform, הפקודה /logout אינה זמינה מכיוון שהאימות מנוהל באמצעות פרטי הגישה של Google Cloud.

Claude Code מכריע בין חיפוש כלי MCP לבין טעינה מראש לפי דור המודל:

• Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 ואילך: Claude Code מפעיל חיפוש כלים כברירת מחדל.
• מודלים מוקדמים יותר, כולל כל מודלי Claude 3.x: Claude Code טוען הגדרות כלי MCP מראש, מכיוון שמערכי השירות שלהם ב-Agent Platform דוחים את כותרת הבטא הנדרשת. הגדרת ENABLE_TOOL_SEARCH=true אינה עוקפת זאת.

הגדירו ENABLE_TOOL_SEARCH=false כדי להשבית את חיפוש הכלים בכל מודל. לפני גרסה v2.1.221, Claude Code השבית את חיפוש הכלים עבור כל המודלים ב-Google Cloud's Agent Platform אלא אם הגדרתם ENABLE_TOOL_SEARCH=true.

#5. קיבוע גרסאות מודלים

אזהרה: קבעו גרסאות מודלים ספציפיות בעת פריסה למשתמשים מרובים. ללא קיבוע, כינויי מודלים כגון sonnet ו-opus מנותבים לברירת המחדל המובנית של Claude Code עבור Google Cloud's Agent Platform, אשר עשויה לפגר אחרי הגרסה החדשה ביותר וייתכן שטרם הופעלה בפרויקט שלכם. Claude Code נסוג למודל מוקדם יותר או מרמה נמוכה יותר בעת ההפעלה כאשר ברירת המחדל אינה זמינה, אך קיבוע מאפשר לכם לשלוט מתי המשתמשים שלכם יעברו למודל חדש.

הגדירו את משתני הסביבה הללו למזהי מודלים ספציפיים ב-Google Cloud's Agent Platform.

ללא ANTHROPIC_DEFAULT_OPUS_MODEL, הכינוי opus ב-Google Cloud's Agent Platform מנותב ל-Opus 5, וללא ANTHROPIC_DEFAULT_SONNET_MODEL, הכינוי sonnet מנותב ל-Sonnet 4.5. דוגמה זו מקבעת כל כינוי לגרסה ספציפית:

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

עבור מזהי מודלים נוכחיים ומזהים ישנים, ראו סקירת מודלים. ראו הגדרת מודלים לרשימה המלאה של משתני הסביבה.

Claude Code משתמש במודלי ברירת המחדל הבאים כאשר לא מוגדרים משתני קיבוע:

משימות רקע כגון יצירת כותרת להפעלה משתמשות במודל הקטן/מהיר, בדרך כלל מודל מסוג Haiku. ב-Google Cloud's Agent Platform, Claude Code משתמש במודל Sonnet המשמש כברירת מחדל עבור משימות רקע מכיוון ש-Haiku עשוי לא להיות מופעל בכל פרויקט או אזור. שתי בחירות משנות איזה מודל מבצע אותן:

• כאשר אתם בוחרים מודל ראשי באמצעות --model, ANTHROPIC_MODEL או ההגדרה model, משימות רקע משתמשות במודל זה. כאשר Claude Code מתחיל את ההפעלה עם המודל שהגדרתם באמצעות ANTHROPIC_DEFAULT_MODEL, משימות רקע משתמשות גם הן במודל זה. הגדרת ANTHROPIC_DEFAULT_OPUS_MODEL ללא ANTHROPIC_DEFAULT_SONNET_MODEL נחשבת גם היא כבחירה, מכיוון שמודל Sonnet המובנה עשוי לא להיות מופעל בפרויקט שמנתב בעצמו את Opus.
• כדי להשתמש ב-Haiku עבור משימות רקע, הגדירו את ANTHROPIC_DEFAULT_HAIKU_MODEL למזהה מודל שזמין בפרויקט שלכם.

אזהרה: למודלי Opus יש מחיר גבוה יותר לכל אסימון מאשר למודלי Sonnet, ולכן פריסה שאינה מקבעת מודל ראשי מחויבת בתעריף של Opus ברגע שהיא מתעדכנת לגרסה v2.1.207 ואילך. כדי להשאיר את Sonnet 4.5 כמודל הראשי, הגדירו את ANTHROPIC_MODEL למזהה המודל המלא שלו. פריסה שמכוונת את ברירת המחדל באמצעות ANTHROPIC_DEFAULT_SONNET_MODEL ואינה מגדירה את ANTHROPIC_DEFAULT_OPUS_MODEL שומרת על מודל ה-Sonnet המכוון שלה כברירת המחדל.

בגרסאות v2.1.207 עד v2.1.218, המודל הראשי ב-Google Cloud's Agent Platform היה כברירת מחדל Opus 4.8 והכינוי opus נותב ל-Opus 4.8. לפני גרסה v2.1.207, המודל הראשי היה כברירת מחדל Sonnet 4.5, הכינוי opus נותב ל-Opus 4.6, ומשימות רקע תמיד השתמשו במודל הראשי.

להתאמה אישית נוספת של המודלים:

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

#6. אימות ההגדרה שלכם

הפעילו את Claude Code והריצו /status כדי לאמת את ההגדרה. השורה API provider מציגה Google Vertex AI, והשורות GCP project, Default region ו-Model מציגות את מזהה הפרויקט, האזור והמודל שנבחר. אם שורת הספק חסרה, משתני הסביבה אינם מגיעים לתהליך. ודאו שהם מיוצאים במעטפת שבה הפעלתם את claude, או הגדירו אותם בבלוק env של קובץ ההגדרות שלכם.

#בדיקות מודל בעת ההפעלה

כאשר Claude Code מופעל כש-Google Cloud's Agent Platform מוגדר, הוא מוודא שהמודלים שבכוונתו להשתמש בהם נגישים בפרויקט שלכם.

אם קיבעתם גרסת מודל ישנה יותר מברירת המחדל הנוכחית של Claude Code, והפרויקט שלכם יכול להפעיל את הגרסה החדשה יותר, Claude Code יציע לכם לעדכן את הקיבוע. אישור ההצעה כותב את מזהה המודל החדש לתוך קובץ הגדרות המשתמש שלכם ומפעיל מחדש את Claude Code. דחיית ההצעה נזכרת עד לשינוי גרסת ברירת המחדל הבא.

אם לא קיבעתם מודל וברירת המחדל הנוכחית אינה זמינה בפרויקט שלכם, Claude Code מבצע נסיגה עבור ההפעלה הנוכחית ומציג הודעה. הוא מנסה תחילה גרסאות מוקדמות יותר של מודל ברירת המחדל, וכאשר ברירת המחדל היא מודל מסוג Opus ואף גרסת Opus אינה זמינה, הוא נסוג למודל ברירת המחדל מסוג Sonnet. הנסיגה אינה נשמרת לצמיתות. הפעילו את המודל החדש יותר ב-Model Garden או קבעו גרסה כדי להפוך את הבחירה לקבועה.

כאשר אתם מתחילים את ההפעלה בגרסת Sonnet או Opus ספציפית, למשל עם --model, ANTHROPIC_MODEL או ההגדרה model, גרסה זו משמשת כברירת מחדל מקובעת של אותה הפעלה עבור הכינוי התואם sonnet או opus. Claude Code מדלג על בדיקת הזמינות עבור ברירת המחדל המובנית שהמודל שלכם מחליף ומתחיל עם המודל שהגדרתם, ללא הודעת נסיגה.

כינויי מודלים כגון opus אינם פועלים כקיבועים, וכך גם מזהה מודל ש-Claude Code אינו מזהה.

#הגדרת IAM

הקצו את התפקיד roles/aiplatform.user, הכולל את ההרשאות הנדרשות:

• aiplatform.endpoints.predict: נדרש עבור הפעלת מודלים וספירת אסימונים

להרשאות מגבילות יותר, צרו תפקיד מותאם אישית (custom role) עם ההרשאות שלעיל בלבד.

לפרטים, ראו תיעוד IAM של Google Cloud's Agent Platform.

הערה: צרו פרויקט GCP ייעודי עבור Claude Code כדי לפשט את מעקב העלויות ובקרת הגישה.

#חלון הקשר של מיליון אסימונים (1M token context window)

Claude Sonnet 5, Opus 4.6 ואילך, ו-Sonnet 4.6 תומכים ב-חלון הקשר של מיליון אסימונים ב-Google Cloud's Agent Platform. מודל Sonnet 5 תמיד רץ עם חלון של 1M, ללא גרסת [1m] שצריך לבחור. עבור המודלים האחרים, Claude Code מפעיל אוטומטית את חלון ההקשר המורחב כאשר אתם בוחרים גרסת מודל של 1M.

אשף ההתקנה מציע אפשרות להקשר של 1M כאשר הוא מקבע מודלים. כדי להפעיל זאת עבור מודל שקובע ידנית, הוסיפו [1m] בסוף מזהה המודל. לפרטים ראו קיבוע מודלים עבור פריסות צד שלישי.

#פתרון בעיות

אם אתם נתקלים בשגיאות "Could not load the default credentials":

• הריצו gcloud auth application-default login כדי להגדיר Application Default Credentials
• הגדירו את GOOGLE_APPLICATION_CREDENTIALS לנתיב של קובץ מפתח של service account
• ראו הגדרת פרטי גישה של GCP לכל האפשרויות

אם אתם נתקלים בבעיות מכסה:

• בדקו מכסות נוכחיות או בקשו הגדלת מכסה דרך Cloud Console

אם אתם נתקלים בשגיאות 404 של "model not found":

• ודאו שהמודל במצב מופעל (Enabled) ב-Model Garden
• ודאו שהמודל זמין במיקום שציינתם. חלק מהמודלים מוצעים רק ב-global או במיקומים רב אזוריים כגון eu ו-us, ולא באזורים ספציפיים
• אם משתמשים ב-CLOUD_ML_REGION=global, בדקו שהמודלים שלכם תומכים בנקודות קצה גלובליות ב-Model Garden תחת "Supported features". עבור מודלים שאינם תומכים בנקודות קצה גלובליות, בצעו אחת מהפעולות הבאות:
  • ציינו מודל נתמך באמצעות ANTHROPIC_MODEL או ANTHROPIC_DEFAULT_HAIKU_MODEL, או
  • הגדירו אזור או מיקום רב אזורי באמצעות משתני הסביבה VERTEX_REGION_<MODEL_NAME>

אם אתם נתקלים בשגיאות 429:

• עבור נקודות קצה אזוריות, ודאו שהמודל הראשי והמודל הקטן/מהיר נתמכים באזור שבחרתם
• שקלו לעבור אל CLOUD_ML_REGION=global לזמינות טובה יותר

#מקורות נוספים

• תיעוד Google Cloud's Agent Platform
• תמחור Google Cloud's Agent Platform
• מכסות ומגבלות של Google Cloud's Agent Platform