📘 תיעוד 80

פריסת שער LLM עבור הארגון שלך

פרוס מוצר שער (gateway) עבור Claude Code: הגדר אותו להעביר הלאה את מה ש-Claude Code שולח, הנפק פרטי אימות למפתחים, הפץ את ההגדרה באמצעות הגדרות מנוהלות (managed settings), ואמת את הפריסה.

דף זה מנחה מנהל מערכת בפריסת שער LLM עבור Claude Code. ההנחה היא שכבר פרסת מוצר שער שעומד בדרישות השער. פריסה או תפעול של מוצר ספציפי כלשהו אינם מכוסים כאן; פרוס את המוצר שלך בהתאם לתיעוד של הספק שלו.

[!NOTE]

• כדי לחבר את Claude Code במחשב שלך לשער קיים, ראה חיבור Claude Code לשער LLM.
• למידע על מה ש-Claude Code שולח לשער ומה יש להעביר הלאה, ראה את מדריך התאימות לשער.

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

כדי להשלים את הפריסה, תזדקק ל:

• שער שנפרס בתשתית שלך, שמגיש HTTPS בכתובת המדויקת שתפיץ למפתחים, לא בכתובת שמבצעת אליה הפניה מחדש (redirect), ומוגדר לנתב שמות מודלים של Claude לספק שלך.
• פרטי אימות של ספק שהשער יעביר הלאה:
  • עבור ה-API של Anthropic: מפתח API מתוך Claude Console.
  • עבור ספק ענן: פרטי אימות ענן עם גישה למודל. ראה את דרישות הקדם בדף של Amazon Bedrock, Google Cloud's Agent Platform, או Microsoft Foundry.
• דרך להעביר קובצי הגדרות למחשבי המפתחים, כגון MDM או ניהול תצורות (configuration management).
  • אם עדיין אין לך דרך כזו, הדף כיצד הגדרות מגיעות למכשירים משווה בין האפשרויות.

#דרישות השער

לא משנה איזה מוצר מספק את השער, עליו:

• לקבל פורמט API נתמך: אחד הפורמטים המופיעים בטבלת פורמטי ה-API. שלבי הפריסה להלן מניחים שימוש ב-Anthropic Messages API בנתיב POST /v1/messages, שרוב השערים מגישים.
• להזרים תגובות (stream responses): להעביר אירועי שרת (server-sent events) כפי שהם מגיעים, כולל אותות שמירת חיבור (keep-alive pings), במקום לאגור במאגר (buffering) את התגובה כולה; הסעיף הזרמה מכסה מה נשבר עקב אגירה או הסרת פינגים.
• לנתב שמות מודלים של Claude: למפות כל שם שהמפתחים משתמשים בו למודל במעלה הזרם (upstream). Claude Code שולח שם מודל כגון claude-sonnet-4-6 בכל בקשה; ברוב מוצרי השער המיפוי הוא רשימת מודלים או טבלת ניתוב בהגדרה הפנימית של השער.
• להעביר כותרות וגוף בקשה ללא שינוי: להעביר את anthropic-beta, anthropic-version, ואת גוף הבקשה בשני הכיוונים; טבלת העברת התכונות ממפה כל אחד מהם לתכונה שנשברת בלעדיו.
• להחזיר שגיאות של מעלה הזרם ללא שינוי: מנגנון ההתאוששות האוטומטי של Claude Code מבצע התאמה על פי ניסוח השגיאה, ולכן עטיפת שגיאות במעטפת ייעודית של השער שוברת אותו, אלא אם הודעת המעטפת נושאת את אחד מאסימוני capability_rejected: ששער אפליקציות Claude מחליף עבור ניסוח השגיאות של ספקי ענן.
• להחריג את הנתיב מבדיקת גוף בקשה של WAF: הפניות של Claude Code נושאות קוד מקור ותגיות בסגנון XML שתואמות לכללי בדיקת גוף בקשה של cross-site-scripting; מערכת WAF המוצבת לפני השער תחזיר קוד 403 בהפעלות אמיתיות, בעוד שבקשות בדיקה קצרות יעברו בהצלחה.

באופן אופציונלי, הגש את הנתיב GET /v1/models כדי ש-Claude Code יוכל לאכלס את בורר המודלים מתוך השער שלך באמצעות גילוי מודלים.

#שלבי הפריסה

הפריסה כוללת חמישה שלבים, לכל אחד מהם נקודת ביקורת (checkpoint):

1. ודא שהשער מנתב את המודלים שלך
2. הנפק פרטי אימות לכל מפתח
3. בדוק את Claude Code מול השער
4. הפץ את כתובת ה-URL הבסיסית ואת פרטי האימות
5. אימות ממחשב של מפתח

השלבים כוללים שלושה סוגים שונים של פרטי אימות, ונקודות הביקורת מציינות אותם באמצעות שומר מקום (placeholder) כדי שתוכל לדעת איזה מהם גרם לכשל כאשר משהו משתבש:

#ודא שהשער מנתב את המודלים שלך

השער שלך כבר צריך להיות מוגדר עם פרטי האימות של הספק שלך, להאזין בכתובת ה-URL הבסיסית שלו, ולהעביר בקשות ל-API של הספק שלך. בדוק שהנתיב עובד מקצה לקצה באמצעות בקשה מינימלית, תוך החלפת שני ערכים מהפריסה שלך:

• <gateway-key> הוא פרט אימות שמאפשר לך לקרוא לשער כעת: מפתח ניהולי, מפתח בדיקה, או מפתח המפתח שלך אם כבר הנפקת אחד לעצמך. לא לכל מוצר שער יש פרט אימות ניהולי נפרד; אם במוצר שלך אין, הנפק לעצמך תחילה מפתח מפתח בשלב הנפקת פרטי אימות למפתחים.
• model הוא שם מודל Claude שהשער שלך מוגדר לנתב. הדוגמה משתמשת ב-claude-sonnet-4-6; החלף אותו בשם שהגדרת.

Bash או Zsh:

curl -X POST "https://llm-gateway.example.com/v1/messages" \
  -H "Authorization: Bearer <gateway-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

PowerShell:

Invoke-RestMethod -Method Post -Uri "https://llm-gateway.example.com/v1/messages" `
  -Headers @{ "Authorization" = "Bearer <gateway-key>"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

נקודת ביקורת: תגובת 200 עם שדה content פירושה שהשער הגיע לספק עם שם המודל הזה. קוד 404 פירושו שהשם הזה אינו מנותב בשער; קוד 401 מהספק פירושו שפרטי האימות של הספק המוגדרים בשער שגויים.

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

[!NOTE] הימנע מהגשת השער מאחורי הפניה מחדש (redirect). הפניה מחדש עלולה להשמיט את גוף הבקשה או להסיר את כותרת פרטי האימות בבקשות הסקה (inference), וגילוי מודלים מתייחס לכל הפניה מחדש כאל כשל כדי שפרטי האימות לא ידלפו ליעד ההפניה.

#הנפקת פרטי אימות למפתחים

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

ודא שמפתח שהונפק זה עתה פועל מול השער באמצעות אותה בקשה כמו בסעיף ודא שהשער מנתב את המודלים שלך, תוך החלפת <gateway-key> ב-<developer-key> החדש:

Bash או Zsh:

curl -X POST "https://llm-gateway.example.com/v1/messages" \
  -H "Authorization: Bearer <developer-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

PowerShell:

Invoke-RestMethod -Method Post -Uri "https://llm-gateway.example.com/v1/messages" `
  -Headers @{ "Authorization" = "Bearer <developer-key>"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

נקודת ביקורת: תגובת 200 עם שדה content פירושה שמפתח המפתח מגיע לשער והשער מעביר אותו הלאה. קוד 401 כאן, כאשר השלב הקודם הצליח, פירושו שמפתח המפתח שגוי או שעדיין לא נכנס לתוקף בשער.

הנפקת מפתח אחד לכל מפתח במקום מפתח משותף היא מה שמאפשר שיוך שימוש לפי מפתח ותהליך עזיבה (offboarding) פרטני. משתנה הסביבה שמחזיק את המפתח תלוי בכותרת שהשער קורא. עבור שער שבודק פרטי אימות בכותרת Authorization: Bearer, מפתחים מגדירים את המפתח שלהם ב-ANTHROPIC_AUTH_TOKEN. עבור שער שקורא מפתחות מכותרת x-api-key, מפתחים מגדירים במקום זאת את ANTHROPIC_API_KEY; טבלת פרטי האימות מכסה את המיפוי.

#בדיקת Claude Code מול השער

הפעל בעצמך את Claude Code דרך השער לפני הפצת דבר כלשהו, תוך שימוש באותה תצורה שהפריסה תספק לכלל המערכות. הקלד פקודות אלו ישירות בטרמינל, לא בקובץ .env או בקובץ הגדרות; הן תקפות רק עבור הפעלת טרמינל זו, כך שסגירתו תחזיר את המחשב שלך לתצורתו הרגילה. השתמש ב-ANTHROPIC_API_KEY במקום ב-ANTHROPIC_AUTH_TOKEN אם השער שלך קורא את כותרת x-api-key:

Bash או Zsh:

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN="<developer-key>"

PowerShell:

$env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"
$env:ANTHROPIC_AUTH_TOKEN = "<developer-key>"

לאחר מכן שלח פניה חד-פעמית דרך השער:

claude -p "Reply with one word: connected"

נקודת ביקורת: הפניה מחזירה תגובה, והבקשה מופיעה ביומן השער כבקשת POST לנתיב /v1/messages עם סטטוס 200. Claude Code מצרף מחרוזת שאילתה כגון ?beta=true, לכן התאם לפי הנתיב, ולא לפי כתובת ה-URL המלאה. שתי הודעות שגיאה מצביעות על כיוונים שונים:

• Not logged in: בדוק את יומן השער כדי להבדיל בין שני הגורמים. אם היומן ריק, שום פרט אימות לא הגיע להפעלה ושום בקשה לא יצאה מהמחשב; הרץ מחדש את פקודות ה-export במעטפת שממנה אתה בודק. אם מופיעה בקשה שנדחתה עם x-api-key בגוף תגובת ה-401, השער מצפה למפתחות בכותרת זו; עבור ל-ANTHROPIC_API_KEY.
• Failed to authenticate. API Error: 401: פירושו שנשלח פרט אימות והוא נדחה, ויומן השער מראה היכן: שגיאת 401 המציינת את api.anthropic.com או את נקודת הקצה של הספק שלך פירושה שהשער הגיע לספק במעלה הזרם אך פרטי האימות שלו נדחו, כך שמפתח המפתח היה תקין ופרטי האימות של הספק שמוחזקים בשער שגויים או מהווים שומר מקום.

כתובת URL בסיסית שגויה או בלתי נגישה יוצרת תסמין אחר: Claude Code מנסה להתחבר מחדש עם השהיה גדלה (backoff) ויכול להישאר ללא פלט במשך מספר דקות לפני דיווח על שגיאה. אם נראה שהפקודה נתקעת, בדוק את יומן השער במקום להמתין; היעדר בקשה נכנסת פירושו ש-ANTHROPIC_BASE_URL אינו מצביע על השער.

#הפצת ההגדרה

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

#מה להפיץ

אותה קבוצת משתנים חלה בכל דרך שתבחר. רוב הפריסות זקוקות רק ל-ANTHROPIC_BASE_URL ולפרט אימות; כלול את השורות המותנות כאשר תצורת השער שלך דורשת זאת.

#הפצה באמצעות הגדרות מנוהלות

העבר את המשתנים דרך בלוק env של קובץ הגדרות מנוהלות, שמועבר באמצעות MDM, מדיניות רישום (registry policy), או ניהול תצורות:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com"
  },
  "apiKeyHelper": "/usr/local/bin/get-gateway-key"
}

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

אל תכלול את forceLoginMethod או את forceLoginOrgUUID בהגדרות מנוהלות לצד פרטי אימות של שער. כל אחד מהמפתחות הללו, עם כל ערך שהוא, חוסם את ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ו-apiKeyHelper בעת ההפעלה, כך שמפתחים יראו את ההודעה This machine's managed settings require a first-party login ולא יוכלו להמשיך.

הפצה של הגדרות מנוהלות על ידי שרת (Server-managed settings) דורשת חיבור ישיר אל api.anthropic.com, ולכן אינה מגיעה להפעלות המנותבות דרך שער. פריסות שער משתמשות בנתיב זה של הגדרות מנוהלות מבוססות-קובץ, אשר אוכף את אותם המפתחות.

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

סביבות מסוימות דורשות הפצה נפרדת:

• אפליקציית שולחן העבודה (desktop app) קוראת את ניתוב השער מתצורת ההסקה של צד שלישי שלה, ולא מהגדרות מנוהלות; פרוס קובץ זה באמצעות MDM לצד הגדרות מנוהלות כך שגם הפעלות שולחן העבודה ינותבו דרך השער. ראה את תיעוד תצורת צד שלישי בשולחן העבודה ואת תיעוד שער בשולחן העבודה.
• מריצי CI (CI runners) זקוקים להגדרת ANTHROPIC_BASE_URL ופרטי האימות בסביבת המריץ.
• WSL במחשבי Windows מנוהלים קורא את ההגדרות המנוהלות של Windows רק כאשר wslInheritsWindowsSettings מוגדר כ-true.

#מסירת הערכים למפתחים להגדרה עצמית

אם אין לך מנגנון הפצה של הגדרות מנוהלות, שלח לכל מפתח את מה שהוא צריך כדי לפעול לפי דף החיבור:

• כתובת ה-URL של השער.
• פרטי האימות האישיים שלו.
• באיזה משתנה להציב את פרטי האימות: ANTHROPIC_AUTH_TOKEN עבור שער המשתמש ב-bearer token, או ANTHROPIC_API_KEY עבור שער המשתמש ב-x-api-key. הודעה מראש למפתחים באיזה משתנה להשתמש חוסכת מהם את הניסוי והטעייה המתוארים בדף החיבור.
• כל משתנה מותנה מתוך טבלת מה להפיץ, יחד עם ערכו.

הדף חיבור Claude Code לשער LLM מדריך את המפתחים בהגדרת כל אחד מהם.

נקודת ביקורת: במחשב של מפתח, הפקודה claude מתחילה הפעלה מבלי להציג את מסך ההתחברות, מכיוון שפרטי האימות שהופצו מספקים את האימות. לאחר מכן הרץ /status ופתח את הכרטיסייה Status: השורה Anthropic base URL מציגה את כתובת השער, ועבור הפצה מנוהלת השורה Setting sources כוללת הגדרות מנוהלות. מסך התחברות, או שורת Anthropic base URL חסרה, מעידים שההגדרה לא הגיעה למחשב.

#אימות הפריסה

ודא שהכל עובד ממחשב של מפתח, ולא ממארח השער, כדי שהבדיקה תכסה את נתיב הרשת שהמפתחים משתמשים בו. שלח בקשת הזרמה (streaming), הבודקת בו-זמנית את נקודת הקצה, את העברת ההזרמה ואת ניתוב המודל:

Bash או Zsh:

curl -N -X POST "https://llm-gateway.example.com/v1/messages" \
  -H "Authorization: Bearer <developer-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 16, "stream": true, "messages": [{"role": "user", "content": "count to 3"}]}'

PowerShell:

$body = '{"model": "claude-sonnet-4-6", "max_tokens": 16, "stream": true, "messages": [{"role": "user", "content": "count to 3"}]}'
$body | curl.exe -N -X POST "https://llm-gateway.example.com/v1/messages" `
  -H "Authorization: Bearer <developer-key>" `
  -H "anthropic-version: 2023-06-01" `
  -H "content-type: application/json" `
  --data-binary '@-'

אתה אמור לראות שורות data: מגיעות בהדרגה. קבלת התגובה כולה בבת אחת לאחר השהיה פירושה שהשער מבצע אגירה (buffering), מה שמעכב את Claude Code; קוד 404 פירושו ששם המודל אינו מנותב. חזור על הבדיקה עבור כל שם מודל.

לאחר מכן הפעל את claude ושלח הודעה. לכל תסמין בשלב זה יש גורם אחד:

• בקשת התחברות (login prompt) מעידה על פער בפרטי האימות. הרץ /status ופתח את הכרטיסייה Status: כאשר השורה Setting sources אינה כוללת הגדרות מנוהלות, ההפצה לא הגיעה למחשב; כאשר היא כוללת אותן, פרטי האימות של המפתח לא הועברו, לכן הגדר את ANTHROPIC_AUTH_TOKEN או את apiKeyHelper.
• שגיאות מסוג Failed to authenticate מעידות שהשער דוחה בקשות; היומן שלו מפרט איזה פרט אימות נכשל. דחייה שהשער רושם בעצמו ביומן מציינת את מפתח המפתח, בעוד ששגיאת 401 מ-api.anthropic.com או מנקודת הקצה של הספק שלך פירושה שפרטי האימות של הספק שמוחזקים בשער נדחו.
• בקשת אישור חד-פעמית עבור המפתח צפויה בשימוש ראשון כאשר השער מצפה למפתחות בכותרת x-api-key, המוגדרת באמצעות ANTHROPIC_API_KEY. עם ANTHROPIC_AUTH_TOKEN, לא מופיעה בקשת אישור והמשתנה נכנס לתוקף באופן שקט; התחברות קודמת שמורה של claude.ai אינה פעילה באותה הפעלה.

אם הארגון שלך משתמש ב-fast mode, הרץ /fast גם כאן: בדיקת הזמינות פונה ישירות אל api.anthropic.com במקום לעקוב אחר כתובת ה-URL הבסיסית של השער, כך שהפעלה המנותבת דרך שער יכולה לדווח ש-fast mode אינו זמין או מושבת על אף שהסקה פועלת. הסעיף שימוש ב-fast mode מאחורי שרתי פרוקסי ושערי LLM ממפה כל הודעה למשתנה שמשחזר אותה, המופץ עם שאר ההגדרה.

לבסוף, בדוק ביומני השער את ההודעה ששלחת: פרטי האימות מזהים את המפתח, והכותרת x-claude-code-session-id מקבצת בקשות לפי הפעלה. אם תכונות נכשלות עם תסמיני פתרון הבעיות, השער מסיר כותרות או משכתב שגיאות; ראה את דרישות השער לעיל.

#תחזוקת השער

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

בעת קביעת מגבלות קצב (rate limits) לכל מפתח, קח בחשבון שהלקוח מנסה שוב כשלים חולפים, כולל תגובות 429, עד 10 פעמים עם השהיה גדלה (backoff), תוך כיבוד Retry-After. שמור את מדריך התאימות כמקור ייחוס למה שכל גרסה של Claude Code שולחת.

#משאבים קשורים

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