SSD Nodes Learn Hosting plans →
מדריכים Matt Connorמאת Matt Connor

אירוח עצמי של LiteLLM כ-Gateway עבור מודלי שפה

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

מה עושה שער LLM באירוח עצמי

LiteLLM הוא שער LLM בקוד פתוח שניתן לארח באופן עצמאי: נקודת קצה (endpoint) אחת מסוג HTTP שכל היישומים שלכם פונים אליה, והיא בתורה מעבירה כל בקשה לספק המתאים שיענה עליה. LLM הוא מודל שפה גדול (Large Language Model). השער מדבר בפורמט ה-API של OpenAI chat completions, כך שכל ספריית לקוח שכבר עובדת מול OpenAI תעבוד מולו לאחר שני שינויים בלבד: ה-base URL והמפתח.

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

להלן מה שמתקבל ברגע שהשירות רץ:

  • נקודת קצה אחת. יישומים פונים ל-https://gateway.example.com/v1 ומבקשים שם מודל שהמצאתם, כגון bulk או strong.
  • מפתחות וירטואליים. כל יישום מקבל מפתח משלו עם רשימת מודלים מורשים ותקרת הוצאות משלו. ניתן לבטל מפתח אחד מבלי להשפיע על האחרים.
  • מנגנוני גיבוי (Fallbacks). קריאה שנכשלה או prompt גדול מדי מבוצעים שוב מול מודל אחר באופן אוטומטי.
  • תיעוד מלא. כל בקשה רושמת שורה הכוללת את העלות שלה, כך שתמיד יש תשובה לשאלה "איזה יישום ביצע את ההוצאה הזו".

למה להריץ את ה-gateway בעצמך

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

דרישות קדם

  • שרת VPS המריץ Ubuntu 24.04, עם Docker ותוסף Compose מותקנים.
  • שם מתחם (domain name) המצביע אל השרת, אם מכונות מחוץ לשרת יתחברו ל־gateway באמצעות TLS (אבטחת שכבת תעבורה).
  • מפתח API של ספק אחד לפחות.

ה־gateway אינו מבצע הסקה (inference). הוא מעביר בקשות ומזרים תשובות בחזרה, לכן עומס ה־CPU שלו תואם לנפח הבקשות ולא לגודל המודל. שרת עם 1 vCPU מסוגל להריץ מספר יישומים פנימיים ללא קושי. מה שגדל הוא מסד הנתונים, כיוון שה־gateway כותב שורת הוצאה עבור כל בקשה.

כתיבת config.yaml תחילה

קובץ התצורה קובע אילו מודלים לקוח רשאי לבקש. ארבע מחלקות ברמה העליונה הן הקובעות: model_list, litellm_settings, router_settings ו־general_settings.

model_list:
  - model_name: bulk
    litellm_params:
      model: anthropic/claude-haiku-4-5
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: strong
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: strong
    litellm_params:
      model: openai/gpt-5.5
      api_key: os.environ/OPENAI_API_KEY

litellm_settings:
  num_retries: 2
  request_timeout: 120
  json_logs: true
  set_verbose: false

router_settings:
  allowed_fails: 3
  cooldown_time: 30
  fallbacks: [{"bulk": ["strong"]}]
  context_window_fallbacks: [{"bulk": ["strong"]}]

general_settings:
  background_health_checks: true
  health_check_interval: 300

model_name הוא השם שהלקוחות שלכם שולחים. litellm_params.model הוא המודל האמיתי, שנכתב בתור provider/model. תנו למודלים שלכם שמות לפי התפקיד שלהם ולא לפי הספק. יישום שמבקש את bulk ימשיך לעבוד גם כשתחליטו בחודש הבא ש־bulk צריך להיות מודל אחר.

api_key: os.environ/ANTHROPIC_API_KEY מורה ל-LiteLLM לקרוא את המשתנה הזה בזמן ריצה. המפתח המילולי לעולם לא מופיע בקובץ, וזה חשוב כיוון ש-config.yaml הוא הקובץ שאתם מבצעים לו commit.

שתי רשומות חולקות את השם strong, וזה מכוון. כאשר יותר מפריסה אחת נושאת את אותו model_name, ה-router מתייחס אליהן כניתנות להחלפה ומפזר את הבקשות עבור שם זה ביניהן. כך strong שורד מצב שבו ספק אחד חווה שעה קשה: ברגע שפריסה נמצאת ב-cooldown (להלן), בקשות חדשות עבור strong מופנות לשנייה.

num_retries: 2 מבצע ניסיונות חוזרים (retries) לשגיאה שניתן לנסות שוב עד פעמיים. ניסיונות אלו יכולים לבחור פריסה זמינה אחרת באותה קבוצת מודלים: תיעוד הארכיטקטורה של LiteLLM, שנבדק ב-2026-10-29, מתאר ניסיונות חוזרים בתוך הקבוצה ומנגנוני fallback בין קבוצות כשלבים נפרדים. לכן, ניסיון חוזר עבור strong יכול להגיע לספק השני מבלי להפעיל weighted failover. מנגנון fallback מופעל רק לאחר שכל הניסיונות החוזרים הללו מוצו.

allowed_fails ו-cooldown_time הם אפשרויות של ה-router, לכן הם ממוקמים תחת router_settings. ה-proxy בונה את ה-router שלו מהמחלקה הזו, ובגרסה v1.95.0, cooldown_time שנכתב תחת litellm_settings לעולם לא מגיע אליו, ולכן זמני ה-cooldown נשארים בשקט על ברירת המחדל של 5 שניות. cooldown_time: 30 קובע כמה זמן פריסה נשארת מחוץ לסבב לאחר שהיא עברה cooldown. תיעוד התצורה מתאר את allowed_fails כמספר הכשלים שפריסה חייבת לעבור בתוך cooldown_time לפני שהיא עוברת cooldown. בקוד המקור של v1.95.0, allowed_fails: 3 הוא ברירת המחדל, ובערך זה ה-router נצמד לטריגרים המובנים הללו; ספירת כשלים נכנסת לפעולה רק כאשר מגדירים מספר אחר. טריגרים אלו כוללים cooldown מיידי בתגובת 429 עבור קבוצה עם יותר מפריסה אחת, יותר מ-50% כשלים בדקה הנוכחית לאחר לפחות 5 בקשות עבור קבוצה כזו, ושגיאות שה-router לא ינסה שוב, כגון 401 ממפתח שגוי. טריגר נפרד גם מעביר פריסה בודדת ל-cooldown כאשר כל הבקשות בדקה הנוכחית נכשלות והתעבורה מגיעה ל-SINGLE_DEPLOYMENT_TRAFFIC_FAILURE_THRESHOLD, שברירת המחדל שלו היא 1000 בקשות. לכן, עבור strong, שיש לו שתי פריסות, ספק שמחזיר 500 בצרורות מפסיק לקבל ניסיונות בכל בקשה בודדת, בעוד שגיאת 500 אקראית כל כמה דקות לעולם לא תפעיל את ה-cooldown. ל-bulk יש רק פריסה אחת, לכן טריגר שיעור הכשלים לא חל עליו: צרור של שגיאות 500 שנשאר מתחת ל-1000 בקשות בדקה משאיר אותו בסבב, ומה שמגן על הקוראים שלו הוא num_retries ואחריו ה-fallback ל-strong.

ל-fallbacks ול-context_window_fallbacks יש טריגרים שונים, והשני הוא השימושי שאנשים מדלגים עליו.

  • fallbacks מופעל כאשר הקריאה הראשית נכשלת.
  • context_window_fallbacks מופעל כאשר הספק דוחה את הבקשה כיוון שהיא ארוכה מחלון ההקשר (context window) של אותו מודל, כך ש-prompt גדול מדי עובר למודל עם מקום עבורו במקום להחזיר שגיאה לקורא.

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

פריסת LiteLLM על שרת VPS באמצעות Docker Compose

צרו ספרייה המכילה שלושה קבצים: config.yaml, docker-compose.yml ו-.env. המדריך המהיר הרשמי מושך את התג latest. מומלץ לקבע תג גרסה ספציפי, כך ששדרוג יתבצע רק כאשר תערכו את הקובץ, וניתן יהיה לבצע שחזור (rollback) בשינוי שורה אחת. תג לבדו אינו ערובה לתוכן זהה, כיוון שתגי תמונה הם ברי-שינוי (mutable) והמפיץ יכול להפנות את התג לתמונה חדשה. אם אתם זקוקים לכך ש-docker compose up -d בחודש הבא יספק לכם בדיוק את אותו ה-gateway שקיבלתם היום, הוסיפו גם את ה-digest של התמונה, בפורמט ghcr.io/berriai/litellm:v1.95.0@sha256:<digest>; הפקודה docker buildx imagetools inspect ghcr.io/berriai/litellm:v1.95.0 תציג אותו עבורכם.

services:
  litellm:
    image: ghcr.io/berriai/litellm:v1.95.0
    restart: unless-stopped
    command: ["--config", "/app/config.yaml", "--num_workers", "1"]
    ports:
      - "127.0.0.1:4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    env_file: .env
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: litellm
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm"]
      interval: 5s
      timeout: 5s
      retries: 10
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

הכלי Compose קורא את .env פעמיים במקרה זה. פעם אחת כדי להחליף את ${POSTGRES_PASSWORD} בתוך קובץ ה-compose עצמו, ופעם שנייה דרך env_file כדי להעביר את כל המשתנים לתוך המכולה.

v1.95.0 הייתה הגרסה העדכנית באוגוסט 2026. בדקו את דף ה-releases של הפרויקט וקבעו את הגרסה העדכנית ביותר בעת הפריסה. כל גרסה מפרסמת חתימה, כך שניתן לאמת את התמונה לפני שנותנים בה אמון:

cosign verify --key https://raw.githubusercontent.com/BerriAI/litellm/v1.95.0/cosign.pub ghcr.io/berriai/litellm:v1.95.0

שורת הפורט היא 127.0.0.1:4000:4000, אשר מפרסמת את הפורט על ממשק ה-loopback בלבד. אם תכתבו 4000:4000 במקום זאת, ה-gateway שלכם יהיה נגיש מכל רחבי האינטרנט, כיוון ש-Docker מוסיפה חוקים משלה לשרשרת ה-FORWARD ב-iptables, וחוקים אלו מוערכים לפני החוקים של ufw, כך ש-ufw deny 4000 לא יחסום זאת. זוהי הדרך הנפוצה ביותר שבה gateway מאוחסן עצמית נחשף בטעות: ראו כיצד Docker מפרסמת פורט של מכולה תוך עקיפת ufw. תעבורה מבחוץ צריכה להגיע דרך ה-reverse proxy במקום זאת.

שמירה על מפתחות הספק מחוץ ל-image

הקובץ .env מכיל את כל הסודות. הוא מוזרק כמשתני סביבה בזמן הריצה, לכן הוא לעולם אינו מוטמע בתוך ה-image ולעולם אינו נשמר ב-commit.

LITELLM_MASTER_KEY=sk-REPLACE_ME
LITELLM_SALT_KEY=sk-REPLACE_ME_TOO
POSTGRES_PASSWORD=REPLACE_ME_AS_WELL
DATABASE_URL=postgresql://litellm:REPLACE_ME_AS_WELL@db:5432/litellm
STORE_MODEL_IN_DB=True
LITELLM_MODE=PRODUCTION
LITELLM_LOG=ERROR
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-proj-...

צרו את שני המפתחות של LiteLLM באמצעות אקראיות אמיתית, ולאחר מכן הגבילו את ההרשאות לקובץ:

printf 'sk-%s\n' "$(openssl rand -hex 32)"
chmod 600 .env

LITELLM_MASTER_KEY הוא פרט הזיהוי של מנהל המערכת. הוא מאמת את ה-API של הניהול ומשמש כסיסמה עבור ה-Admin UI בכתובת /ui. אף יישום לא אמור להחזיק בו.

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

STORE_MODEL_IN_DB=True מאפשר לכם להוסיף ולערוך מודלים מתוך ה-Admin UI מבלי לגעת בקובץ config.yaml. זה נוח, אך זה מפצל את מקור האמת שלכם לשניים. החליטו איזה מהם הוא הסמכותי ותעדו את ההחלטה לצד ה-config.

ההיגיון ששומר על מפתחות מחוץ לקובץ התצורה הוא אותו היגיון ששומר עליהם מחוץ לכלים שאתם מעבירים לסוכן (agent). המאמר שמירה על סודות ספק מחוץ לסוכני AI מכסה את התבנית הזו, ו-קבצי env וסודות ב-Docker Compose מכסה את ההיבטים הטכניים.

העלו את השירות ועקבו אחר האתחול הראשון:

docker compose up -d
docker compose logs -f litellm

בדיקת תקינות הפעולה

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

curl -s http://127.0.0.1:4000/health/liveliness
curl -s http://127.0.0.1:4000/health/readiness

/health/liveliness אינו דורש אימות ומשיב "I'm alive!" כל עוד התהליך רץ. גם /health/readiness אינו דורש אימות. הוא מחזיר אובייקט JSON עם "status": "healthy" ושדה db, או קוד שגיאה 503 כאשר מסד הנתונים אינו נגיש. כוונו את מערכת הניטור שלכם אל ה-readiness, כיוון שה-liveliness נשאר תקין גם ב-gateway שאינו מסוגל לאתר מפתח וירטואלי בודד.

הבדיקה המאומתת היא זו שמתקשרת עם הספקים:

curl -s http://127.0.0.1:4000/health \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

היא משיבה עם מערכים של healthy_endpoints ו-unhealthy_endpoints. מודל שנמצא ב-unhealthy_endpoints עם שגיאת אימות מעיד על כך שמפתח הספק ב-.env שגוי או חסר; זהו הכשל שאתם מחפשים כעת. מכיוון ש-background_health_checks: true מוגדר, ה-proxy מריץ את הבדיקות הללו בעצמו בכל health_check_interval שניות, ו-/health מחזיר את התוצאה האחרונה, כך שביצוע polling לא שולח בקשת בדיקה לספקים שלכם בכל פעם מחדש.

מפתחות וירטואליים ומכסות נפרדות לכל מפתח

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

curl -s http://127.0.0.1:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "key_alias": "nightly-summariser",
    "models": ["bulk"],
    "max_budget": 5,
    "budget_duration": "30d",
    "rpm_limit": 60,
    "tpm_limit": 200000
  }'

התגובה כוללת שדה key שמתחיל ב־sk-. המחרוזת הזו היא מה שהיישום מקבל, וזהו הדבר היחיד שהיישום מקבל אי־פעם.

  • models היא רשימת היתרים של הבקשות שמפתח זה רשאי לשלוח. המפתח שלמעלה יכול לבקש bulk בלבד.
  • max_budget: 5 עם budget_duration: "30d" הם חמישה דולר אמריקאי לחודש קלנדרי. LiteLLM מאפס את המכסה של 30d ב־1 בכל חודש בחצות, לפי UTC אלא אם מגדירים timezone תחת litellm_settings, ולא בחלון נע של 30 ימים. לכן, לאחר שהמפתח צרך חמישה דולר, הוא מפסיק לפעול עד ה־1 בחודש הבא.
  • rpm_limit ו־tpm_limit מגבילים את מספר הבקשות בדקה ואת מספר האסימונים בדקה עבור מפתח זה בלבד.
  • key_alias הוא המזהה שיופיע בלוג צריכת המשאבים גם כעבור שישה שבועות. הגדירו אותו תמיד.

כאשר המכסה נוצלה במלואה, הקריאה נכשלת עם שגיאה מסוג budget_exceeded ועם הודעה במבנה הבא:

Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget>

קוד הסטטוס תלוי בגרסה. בגרסה המקובעת v1.95.0 הקוד הוא HTTP 429. מ־v1.104.0 ברירת המחדל היא HTTP 422, והגדרת budget_exceeded_status_code: 429 תחת litellm_settings מחזירה את הקוד הקודם. חריגה אמיתית של rpm_limit ושל tpm_limit עדיין מחזירה 429 בשתי הגרסאות. בדקו איזה קוד מתקבל לאחר כל שדרוג.

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

בדקו ושנו מפתחות באמצעות אותו API ניהולי:

curl -s "http://127.0.0.1:4000/key/info?key=sk-..." \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

curl -s -X POST http://127.0.0.1:4000/key/update \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"key": "sk-...", "max_budget": 25}'

מכסה שנאכפת בשער נשארת בתוקף גם כאשר הגורם שגרם לבעיה הוא הסוכן עצמו. לכן היא משמשת בסיס לבקרת עלויות עבור סוכני AI ב־VPS.

שליחת עבודה מרוכזת למודל זול

הפנו את הלקוח (client) אל ה-gateway. הגדירו את ה-Base URL, את ה-key ואת שם המודל:

curl -s http://127.0.0.1:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-<the virtual key>" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "bulk",
    "messages": [{"role": "user", "content": "Say hello in five words."}]
  }'

כל ספריית לקוח של OpenAI פועלת באותה דרך, אם כי שמות האפשרויות משתנים בין שפות תכנות. בלקוח ה-Python, הגדירו את base_url ל-https://gateway.example.com/v1 ואת api_key למפתח הווירטואלי. בלקוחות ה-JavaScript וה-TypeScript, שתי האפשרויות הללו נקראות baseURL ו-apiKey.

מדיניות הניתוב מתוך config.yaml חלה כעת מבלי שהקוד הקורא יהיה מודע לכך. בקשה עבור bulk מופנית למודל הזול. אם קריאה זו נכשלת לאחר הניסיונות החוזרים שלה, הבקשה מבוצעת שוב מול strong. אם ה-prompt ארוך מדי עבור bulk, ה-context_window_fallbacks שולח אותו ל-strong במקום להחזיר שגיאה. עבודה מרוכזת, כגון סבב סיווג או סיכום של backlog, רצה כברירת מחדל בעלות נמוכה, ורק בקשות מורכבות עולות יותר.

זהו גם המקום שבו ה-gateway מוכיח את ערכו עבור סוכנים (agents) המשתמשים בכלים. ניתן להפנות גם שרת MCP (model context protocol) על אותו VPS וגם את הסוכן שמפעיל אותו לנקודת קצה אחת, כך שהמודל שמאחוריהם משתנה ללא צורך בפריסה מחדש של אף אחד מהם.

איך יודעים שבוצע fallback?

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

המידע קיים ב־response headers. בקשו אותם:

curl -s -D - -o /dev/null http://127.0.0.1:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-<the virtual key>" \
  -H 'Content-Type: application/json' \
  -d '{"model":"bulk","messages":[{"role":"user","content":"ping"}]}' \
  | grep -i '^x-litellm'
  • x-litellm-model-group הוא שם המודל שאליו נותבה הבקשה, למשל bulk. x-litellm-model-id הוא מזהה ה־deployment שהחזיר את התשובה, ואפשר לחפש אותו באמצעות /v1/model/info?litellm_model_id=.... כאשר המזהה אינו שייך לאחד מה־bulk deployments שלכם, בוצע fallback.
  • x-litellm-attempted-fallbacks ו־x-litellm-attempted-retries סופרים אותם. בקריאה תקינה, אף אחד מהם אינו מציג ערך גדול מ־0.
  • x-litellm-response-cost הוא העלות של אותה קריאה בדולרים אמריקאיים.
  • x-litellm-call-id הוא המזהה שבו משתמשים כדי למצוא את אותה קריאה בלוגים.

תעדו את x-litellm-attempted-fallbacks בכל בקשה והגדירו התראה בכל פעם שהערך שלו גדול מ־0. המספר האחד הזה מבדיל בין מדיניות ניתוב שפועלת כראוי לבין מדיניות ניתוב שהפכה בשקט ל״השתמש תמיד במודל היקר״.

הגרסה המלאה של היכולת הזו היא tracing, והיא ראויה להגדרה נפרדת משלה: Langfuse ב־self-hosted למעקב אחר קריאות של סוכנים. LiteLLM מספק את ה־callback, ולכן החיבור שלו דורש שתי שורות ועוד פרטי התחברות.

litellm_settings:
  success_callback: ["langfuse"]
  failure_callback: ["langfuse"]
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://langfuse.example.com

ב־Langfuse v3 ומעלה, דף Langfuse של LiteLLM ממליץ כעת על ה־preset langfuse_otel; ה־callback langfuse שלמעלה עדיין מתועד. הגדירו גם את failure_callback וגם את success_callback. אם תדלגו עליו, העקבות היחידים שתשמרו יהיו אלה שבהם שום דבר לא השתבש. בנפרד מכל זה, LiteLLM כותב רשומת spend לכל בקשה אל Postgres, ו־Admin UI ב־/ui קורא את הטבלה הזו. הטבלה גדלה בהתאם לנפח התעבורה, לכן עקבו אחריה כאשר שטח הדיסק קטן.

הצבת ה-gateway מאחורי reverse proxy

שום גורם מחוץ לשרת לא צריך להגיע לפורט 4000. בצעו TLS termination ב-nginx או ב-Caddy והעבירו את התעבורה לכתובת ה-loopback.

location / {
    proxy_pass http://127.0.0.1:4000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    proxy_read_timeout 600s;
}

שתיים מהשורות הללו הן אלו שאנשים נוטים להשמיט. proxy_buffering off חשובה מכיוון ש-streaming completion הוא רצף של server-sent events, וכאשר ה-buffering פעיל, nginx אוסף את הנתונים במאגרים לפני העברתם, מה שמעכב את הגעתם ללקוח. proxy_read_timeout 600s חשובה מכיוון שברירת המחדל של nginx, העומדת על 60 שניות, היא משך הזמן המקסימלי להמתנה בין שתי קריאות מה-gateway, ולא הגבלה על כל התגובה. completion שאינו מבוסס streaming לא שולח דבר עד לסיום היצירה, לכן תהליך ארוך יעבור את ה-60 שניות ללא הגעת בתים, והלקוח יקבל שגיאת 504 בעוד לוג השגיאות יתעד upstream timed out (110: Connection timed out) while reading response header from upstream. completion מבוסס streaming שממשיך לשלוח נתונים יכול להימשך זמן רב הרבה יותר מ-60 שניות; הוא יפעיל את ה-timeout רק אם המודל ישתוק למשך זמן זה.

עבור התעודה, Certbot עם Let's Encrypt ב-nginx הוא הדרך הקצרה ביותר. אם השרת כבר מריץ כמה מכולות, Traefik לפני כמה יישומי Compose יטפל בניתוב ובתעודות במקום אחד.

השער הפך לנקודת כשל יחידה

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

  • תצורה שגויה משביתה את הכל בבת אחת. restart: unless-stopped מבצע הפעלה מחדש לאחר קריסה, והוא מפעיל מחדש מכולה שאינה מסוגלת לפענח את config.yaml, שוב ושוב. קראו את docker compose logs litellm לאחר כל שינוי בתצורה, ובצעו שינויים כאלו רק כשיש לכם זמן להשגיח עליהם.
  • Postgres נמצא בנתיב הבקשה במקרה של החמצה בזיכרון המטמון (cache miss). חיפוש מפתח וירטואלי משתמש בו כאשר המפתח אינו בזיכרון המטמון; רישום ההוצאות מתבצע באופן אסינכרוני לאחר התגובה. /health/readiness שמחזיר 503 הוא האזהרה שלכם לכך שהשער פועל אך אינו מסוגל לבצע אף אחד מהם.
  • נצלו את הליבות תחילה, ורק אז הוסיפו מופעים (instances). הנחיית הייצור של הפרויקט לגבי עובד (worker) אחד לכל מופע (--num_workers 1) מיועדת ל-Kubernetes או לכל autoscaler של פודים שמוסיף מופעים עבורכם. עבור מכונה וירטואלית יחידה או מכולה בודדת כמו זו, ההנחיה הפוכה: הגדירו את מספר העובדים כמספר ה-vCPU של המכונה. במכונה עם 1 vCPU כמו זו שלעיל, זה עדיין --num_workers 1; במכונה גדולה יותר העלו את המספר, וזכרו שכל עובד צורך זיכרון משלו. שער שני מאחורי load balancer מסיר את המכולה הבודדת מהמשוואה. הוא אינו מסיר את מסד הנתונים.
  • גבו את מה שאינכם יכולים לשחזר. מדובר ב-config.yaml וב-.env, יחד עם pg_dump של מסד הנתונים. אובדן LITELLM_SALT_KEY הופך את אישורי הספק המוצפנים בתוך ה-dump לחסרי תועלת, לכן קובץ ה-env וה-dump שייכים לאותה משימת גיבוי: גיבויים של restic לאחסון חיצוני.

שדרוג מתבצע על ידי עריכת תג התמונה והרצת docker compose up -d. LiteLLM מריץ prisma migrate deploy בעת העלייה כברירת מחדל, כך שהמכולה החדשה מבצעת מיגרציה לסכימת מסד הנתונים בהפעלה הראשונה שלה. בצעו dump לפני שינוי התג, מכיוון שהחזרת התמונה הישנה לא מבטלת מיגרציה שכבר בוצעה.

קראו את הערות השחרור של כל גרסה שאתם מדלגים עליה, לא רק של זו שאליה אתם מגיעים. מעבר מ-v1.95.0 ל-v1.104.0 ומעלה כולל כמה שינויים שוברים: קוד הסטטוס של התקציב שהוזכר לעיל, proxy שמסרב לעלות עם מפתח ראשי (master key) לא מוגדר, ריק או ידוע לציבור, ו-proxy שנסגר כאשר הגדרת מסד הנתונים נכשלת בעלייה, מה שמופיע תחת restart: unless-stopped כלולאת הפעלה מחדש. במעבר מ-v1.102.x או מוקדם יותר, הערות הגרסה של v1.104.0 דורשות מכם לבנות שני אינדקסים של LiteLLM_SpendLogs בעצמכם.

FAQ

האם LiteLLM מוסיף שיהוי מורגש לכל קריאה?

הפרויקט מפרסם נתון של 8 ms באחוזון ה-95 תחת עומס של 1000 בקשות בשנייה, כפי שצוין ב-README שלו בנובמבר 2026. יש להתייחס לנתון זה כאל נתון ספק. הגורם המשפיע בפועל על השיהוי הוא המרחק ברשת בין היישומים שלך לבין ה-gateway, כיוון שהוספת סבב תקשורת (round trip) אחד לכל קריאה. הרץ את ה-gateway באותו אזור (region) שבו נמצאים היישומים שקוראים לו, ולאחר מכן מדוד את ה-overhead האישי שלך באמצעות ה-header מסוג x-litellm-overhead-duration-ms על תגובה אמיתית.

מדוע הזרמת נתונים (streaming) הפסיקה לעבוד לאחר שהצבתי את nginx בחזית?

מכיוון ש-nginx מבצע buffering לתגובות מה-upstream כברירת מחדל, בעוד ש-streaming של השלמת טקסט הוא סדרה של אירועים שנשלחים מהשרת (server-sent events). כאשר proxy_buffering מופעל, nginx אוסף מקטעים בתוך buffers לפני העברתם, מה שמעכב את הגעתם ללקוח. הגדר proxy_buffering off; בתוך בלוק ה-location. הגדל גם את proxy_read_timeout באותו בלוק. כברירת מחדל, nginx מוותר לאחר 60 שניות ללא נתונים מה-gateway, זמן שייצור טקסט ארוך ללא streaming מגיע אליו בקלות, והלקוח מקבל שגיאת 504.

מה קורה כאשר מפתח וירטואלי מסיים את התקציב שלו?

הקריאה נכשלת עם שגיאה מסוג budget_exceeded והודעה במבנה של Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget>. בגרסה המקובעת v1.95.0 הסטטוס הוא HTTP 429; החל מגרסה v1.104.0 ברירת המחדל היא HTTP 422. אף אחד מהקודים הללו לא מציין "תקציב", וזו המלכודת: ספריית לקוח מדווחת על 429 כעל הגבלת קצב (rate limit) ועשויה לנסות לבצע את הקריאה שוב, לכן אנשים מתחילים לחפש בעיות של throttling במקום לקרוא את ההודעה. תעד את גוף התגובה לצד קוד הסטטוס. אשר את המיקום האמיתי של המפתח באמצעות /key/info?key=sk-... מול מפתח ה-master, והעלה את התקרה באמצעות /key/update אם התקציב הוגדר נמוך מדי.

האם ה-gateway יכול לנתב למודל מקומי בנוסף למודלים מאוחסנים?

כן, וזו כניסה נוספת ב-model_list. השתמש בקידומת ollama_chat/ עם api_base, לדוגמה model: ollama_chat/llama3.1 לצד api_base: http://ollama:11434. ברשת ברירת המחדל של Compose, הכתובת localhost בתוך מכולה מצביעה על אותה מכולה, לכן השתמש בשם שירות ה-Compose או בכתובת המארח ברשת ה-Docker, לעולם לא ב-127.0.0.1. רשת מארח (host networking), שבה המכולה חולקת את מחסנית הרשת של המארח, היא היוצא מן הכלל. הקמת המודל המקומי היא משימה נפרדת: ראו אירוח עצמי של LLM עם Ollama על גבי VPS.

האם המאמר הזה היה מועיל?