📘 תיעוד 118

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

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

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

הערה

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

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

כדי להשלים את הפריסה, תצטרך:

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

#דרישות השער

כל מוצר שמספק את השער חייב:

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

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

#שלבי הפריסה

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

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

השלבים כוללים שלושה אישורים שונים, ונקודות הביקורת מכנות אותם לפי מציין מקום כדי שתוכל לדעת איזה מהם אשם כשמשהו נכשל:

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

השער שלך אמור כבר להיות מוגדר עם אישור הספק שלך, להאזין בכתובת הבסיס שלו, ולהעביר בקשות ל-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 לכל מפתח שבוחר אותו, לכן בדוק כל שם לפני הפריסה.

הערה

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

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

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

אשר שמפתח שהונפק זה עתה עובד מול השער עם אותה בקשה כמו באישור שהשער מנתב את המודלים שלך, תוך החלפת <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 כאן, כאשר השלב הקודם הצליח, אומר שמפתח המפתחים שגוי או שעדיין לא נכנס לתוקף בשער.

הנפקת מפתח אחד לכל מפתח, במקום מפתח משותף, היא מה שמאפשר ייחוס שימוש לפי מפתח והשבתה פרטנית. משתנה הסביבה שמחזיק את המפתח תלוי בכותרת שהשער קורא. עבור שער שבודק אישורים בכותרת 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 או את נקודת הקצה של הספק שלך אומר שהשער הגיע ל-upstream אבל אישור הספק שלו נדחה, כך שמפתח המפתחים עבד ואישור הספק שהשער מחזיק שגוי או שהוא מציין מקום

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

#הפצת התצורה

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

#מה להפיץ

אותה קבוצת משתנים חלה בכל נתיב שתבחרו. רוב הפריסות צריכות רק את ANTHROPIC_BASE_URL ואישור. כללו את השורות המותנות כאשר הגדרת השער שלכם דורשת אותן.

#הפצה דרך הגדרות מנוהלות

מסרו את המשתנים דרך בלוק env של קובץ הגדרות מנוהלות, שנדחף על ידי MDM, מדיניות רישום, או ניהול תצורה:

{
  "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, או את forceLoginGatewayUrl בהגדרות מנוהלות לצד אישור של השער. forceLoginMethod או forceLoginOrgUUID, בכל ערך, חוסמים את ANTHROPIC_API_KEY, את ANTHROPIC_AUTH_TOKEN, ואת apiKeyHelper בהפעלה, והמפתחים לא יכולים להמשיך. הם רואים את This machine's managed settings require a first-party login, או את Administrator policy requires a Cloud gateway sign-in כאשר הקובץ מגדיר את forceLoginMethod ל-"gateway" או מגדיר את forceLoginGatewayUrl.

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

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

חלק מהסביבות צריכות מסירה נפרדת:

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

#תצורת HIPAA מאחורי שער

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

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

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

אל תשתמשו ב-CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC במקום המפתחות האלה. הוא מכבה חלק מהיכולות האלה, אבל הוא גם מכבה את המעדכן האוטומטי, והוא משאיר את WebFetch פעיל.

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

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

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

דף החיבור מלווה את המפתחים בהגדרת כל אחד מהם.

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

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

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

Bash or 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: שמגיעות בהדרגה. כל התשובה שמגיעה בבת אחת אחרי השהיה אומרת שהשער אוגר במאגר, וזה עוצר את Claude Code. 404 אומר ששם המודל לא מנותב. חזרו על כך לכל שם מודל.

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

• בקשת התחברות אומרת שיש פער באישור. הריצו /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: בדיקת הזמינות קוראת אל api.anthropic.com ישירות ולא עוקבת אחרי כתובת הבסיס של השער, כך שהפעלה שמנותבת דרך השער יכולה לדווח שמצב מהיר אינו זמין או מושבת אף על פי שההסקה עובדת. שימוש במצב מהיר מאחורי פרוקסי ושערי LLM ממפה כל הודעה אל המשתנה שמשחזר אותה, שמופץ עם שאר התצורה.

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

#תחזוקת השער

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

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

#תכנון שדרוגי גרסת Claude Code

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

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

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

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