הגדרת ניתוב מודלים

בדף הזה מוסבר איך להגדיר, לפרוס ולבדוק ניתוב מודלים ב-API Gateway באמצעות מפרטים של OpenAPI 3.x.

לפני שמתחילים

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

1. בדיקת הרשאות IAM: צריך לוודא שיש לכם גישה ל-API Gateway Management Plane ול-Vertex AI Model Garden. כדי ליצור הגדרות ושערים של API, צריך להיות בתפקיד אדמין של API Gateway‏ (roles/apigateway.admin). בנוסף, לחשבון השירות שבו משתמש שער ה-API – חשבון השירות שמוגדר כברירת מחדל ב-Compute Engine או חשבון שירות שמנוהל על ידי המשתמש והוגדר כשיוצרים את הגדרת ה-API – צריכה להיות מוקצית הרשאת Vertex AI User ‏ (roles/aiplatform.user) כדי לגשת למודלים של היעד.
2. בדיקת הזמינות של המודל והגישה לנקודת הקצה: צריך לוודא שהמודלים הניתנים לניתוב הם מודלים פתוחים שנפרסו מראש לצורך Model as a Service (MaaS) ב-Vertex AI Model Garden. כל המודלים שאליהם מפנה נתב יחיד חייבים להיות באותו שם מארח בדיוק. בוחרים נקודת קצה גלובלית (aiplatform.googleapis.com) או נקודת קצה אזורית אחת (לדוגמה, us-central1-aiplatform.googleapis.com) לכל מודל שמפנים אליו בנתב.
3. בדיקת הזכאות לפריסת שער: אי אפשר לעדכן שער קיים שנפרס ללא ניתוב מודלים כדי להפעיל ניתוב מודלים, ואי אפשר לעדכן שער שנפרס עם ניתוב מודלים כדי להשבית או להסיר את ניתוב המודלים. כדי להחליף בין מצבי ניתוב, צריך ליצור ולפרוס קובץ הגדרות API חדש ומופע שער חדש.
4. בדיקת התאימות של VPC Service Controls ונקודות קצה: שערים של ניתוב מודלים לא תומכים ב-VPC Service Controls או בהגדרות של נקודות קצה של Private Service Connect ‏ (PSC). צריך לוודא שהפרויקט והמופעים של API Gateway לא מוגבלים על ידי VPC Service Controls perimeters, ושהמודלים משתמשים בנקודות קצה אזוריות או גלובליות ציבוריות.

אימות ההגדרות

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

בדיקות מבנה ומיקום

• התוסף x-google-api-management והבלוקים שמשויכים אליו (backends,‏ ai.models.routing.routers, נתבים נפרדים ו-rules) צריכים להיות בנויים בצורה תקינה. המפתחות צריכים להתאים לסוגי הנתונים הצפויים שלהם (מיפוי, רשימה או מחרוזת). מישור הניהול דוחה אי התאמות בסוגים עם שגיאה expected map/list/string.
• אם מופעלת הפניית תנועה למודל, התוסף x-google-api-management חייב להכיל בלוק backends תקין.
• ההרחבה x-google-model-router נתמכת רק במפרטים של OpenAPI 3.x (היא לא נתמכת ב-OpenAPI 2.0 / Swagger).
• אפשר לציין את התוסף x-google-model-router רק ברמת הפעולה. מישור הניהול דוחה במפורש הגדרות של x-google-model-router שמוצבות ברמת הנתיב או ברמת הבסיס (העליונה).
• חובה להגדיר את הבלוק ai.models.routing.routers בתוך x-google-api-management בכל פעם שפעולה כלשהי מפנה אל x-google-model-router.
• אי אפשר לציין את x-google-model-router ואת x-google-backend באותה פעולת API.
• מפרט OpenAPI לא יכול להכיל שילוב של פעולות ניתוב מודל ופעולות ניתוב לא מודל. אי אפשר לציין תוספים סטנדרטיים לניתוב (כמו x-google-backend) בפעולות מסוימות בזמן השימוש ב-x-google-model-router בפעולות אחרות באותו מפרט API.

בדיקת שיטת HTTP

• אפשר להחיל את התוסף x-google-model-router רק על פעולות שמשתמשות בשיטת ה-HTTP‏ POST. מישור הניהול דוחה ניתוב מודלים בכל שיטת HTTP אחרת (כמו GET,‏ PUT או DELETE).

תוקף בקצה העורפי

• כל קצה עורפי שמוגדר ב-x-google-api-management.backends חייב לכלול שדה address לא ריק.
• הערך של מאפיין ה-Backend‏ address חייב להיות כתובת URL תקינה עם סכימת http או https. כדי להגן על מטען ייעודי (payload) של הנחיות ועל פרטי אימות בזמן ההעברה בין נקודות קצה ציבוריות או מרוחקות, צריך תמיד לציין את הסכימה https כשמגדירים את השדה address.
• כל קצה עורפי שמוגדר ב-x-google-api-management.backends ומופנה על ידי נתב מודל חייב להשתמש ב-pathTranslation: CONSTANT_ADDRESS. מישור הניהול דוחה הגדרות שמשתמשות ב-pathTranslation: APPEND_PATH_TO_ADDRESS עבור עורפי קצה של ניתוב מודלים, כי המערכת מתעלמת מתרגום הנתיב בנתיב זמן הריצה של נתב המודלים.
• בק-אנדים של ניתוב מודלים לא תומכים ב-VPC Service Controls או בהגדרות של נקודות קצה (endpoint) של Private Service Connect ‏(PSC). כל השדות של address ה-Backend צריכים להפנות לנקודות קצה של מודלים פתוחים של MaaS אזוריים או גלובליים שגלויים לכולם.

הפניה לנתב

• השם של הנתב שאליו מתייחסת פעולה ב-x-google-model-router חייב להיות זהה למפתח נתב תקין שמוגדר ב-ai.models.routing.routers.
• הערך של backend שאליו מתייחס defaultModel של נתב חייב להיות זהה לערך של קצה עורפי חוקי שהוגדר ב-x-google-api-management.backends.
• ה-backend שאליו מפנה כל כלל בנתב חייב להתאים לשרת קצה עורפי תקין שהוגדר ב-x-google-api-management.backends.

תכנים שקשורים לנתב

• בכל נתב צריך להגדיר defaultModel.
• הפרמטר defaultModel חייב לכלול שדה backend תקין.
• התג defaultModel חייב לכלול שדה targetModel שלא ריק.
• כל רשומה בקטע rules חייבת לכלול שדה model לא ריק. הערך של המחרוזת default שמור ואי אפשר להשתמש בו כערך של model בכלל.
• כל רשומה בקטע rules חייבת לכלול שדה targetModel לא ריק.
• הערכים של model שמוגדרים בכל הכללים בנתב יחיד חייבים להיות ייחודיים. מישור הניהול דוחה ערכים כפולים של model באותו נתב.

עקביות בין המארח והסכמה של ה-Backend

• כל ה-backends שאליהם מתייחס נתב יחיד (כולל defaultModel.backend וכל backend של כל כלל) חייבים להיות בעלי אותו שם מארח וסכימת URL. מישור הניהול דוחה הגדרות עם שמות מארחים שונים או סכימות לא עקביות (http לעומת https) באותו נתב, כדי לוודא שהנתב ישלח את כל הבקשות לנקודת קצה עקבית של שירות במעלה הזרם.

אימות מודל היעד

• החלק <provider> במחרוזת targetModel (google,‏ openai או anthropic) ופורמט המזהה <provider>/<model> עוברים אימות בזמן יצירת ההגדרה (פריסה). מישור הניהול דוחה targetModel שלא מעוצב כ-<provider>/<model> או שהספק שלו הוא לא google,‏ openai או anthropic עם שגיאה InvalidArgument: unsupported publisher במהלך הפריסה.

שלב 1: זיהוי מודלים של יעדים

מזהים את המודלים הבסיסיים של היעד ואת כתובות ה-URL התואמות של נקודות הקצה ב-Vertex AI. לכל המודלים שניתן לנתב בנתב צריך להיות שם מארח משותף (עבור מודלים פתוחים של MaaS, שם המארח הוא aiplatform.googleapis.com).

נתיבי כתובות ה-URL של נקודות הקצה משתנים בהתאם לספק המודל:

• ‫Google Gemini: משתמש בשיטת :generateContent.
• ‫Anthropic Claude: משתמש בשיטה :rawPredict.
• ‫OpenAI: משתמש בנתיב נקודת הקצה /endpoints/openapi/chat/completions.

בטבלה הבאה מפורטות נקודות הקצה של MaaS שמשמשות בדוגמה למפרט OpenAPI שמופיעה בהמשך הקטע הזה:

מחליפים את YOUR_PROJECT_ID במזהה הפרויקט ב- Google Cloud .

שלב 2: הגדרת מפרט OpenAPI 3.x

יוצרים או מעדכנים את מפרט OpenAPI 3.x כדי להגדיר את נקודות הקצה של ה-Backend ואת הגדרות הניתוב של המודל.

בדוגמה הבאה מוצג מפרט OpenAPI 3.0.3 שמגדיר שני נתבי מודלים נפרדים. כדי למנוע גלילה אופקית, כתובות URL ארוכות של כתובות קצה בעורף משתמשות בהמשך של מחרוזת מרובת שורות עם מירכאות כפולות ב-YAML (``):

openapi: 3.0.3

info:
  title: OpenAPI 3.x spec using Model Routing
  description: Using Model Routing in an OAS 3.x spec
  version: 1.0.0

x-google-api-management:
  backends:
    gemini-35-flashlite:
      address: "https://aiplatform.googleapis.com/v1/projects/\
        YOUR_PROJECT_ID/locations/global/publishers/google/\
        models/gemini-3.5-flash-lite:generateContent"
      deadline: 60.0
      pathTranslation: CONSTANT_ADDRESS

    anthropic-claude-opus-47:
      address: "https://aiplatform.googleapis.com/v1/projects/\
        YOUR_PROJECT_ID/locations/global/publishers/anthropic/\
        models/claude-opus-4-7:rawPredict"
      deadline: 60.0
      pathTranslation: CONSTANT_ADDRESS

    openai-gpt-oss-120b:
      address: "https://aiplatform.googleapis.com/v1/projects/\
        YOUR_PROJECT_ID/locations/global/endpoints/openapi/\
        chat/completions"
      deadline: 60.0
      pathTranslation: CONSTANT_ADDRESS

  ai:
    models:
      routing:
        routers:
          # Router 1: route between Gemini (default) and Claude.
          gemini-claude-router:
            defaultModel:
              backend: gemini-35-flashlite
              targetModel: google/gemini-3.5-flash-lite
            rules:
              - model: "claude-opus-4-7"
                backend: anthropic-claude-opus-47
                targetModel: anthropic/claude-opus-4-7

          # Router 2: route between OpenAI GPT (default) and Gemini.
          openai-gemini-router:
            defaultModel:
              backend: openai-gpt-oss-120b
              targetModel: openai/gpt-oss-120b-maas
            rules:
              - model: "gemini-3.5-flash-lite"
                backend: gemini-35-flashlite
                targetModel: google/gemini-3.5-flash-lite

servers:
  - url: "https://my-gateway-url.com"

paths:
  /v1/chat/gemini-claude:
    post:
      summary: "Endpoint:defaults to Gemini & Claude as an option."
      operationId: "chatGeminiClaude"
      x-google-model-router: gemini-claude-router
      responses:
        '200':
          description: "OK"

  /v1/chat/openai-gemini:
    post:
      summary: "Endpoint:defaults to OpenAI & Gemini as an option."
      operationId: "chatOpenAIGemini"
      x-google-model-router: openai-gemini-router
      responses:
        '200':
          description: "OK"

מאפייני ההגדרה

1. ‫backends: אובייקט backends בקטע x-google-api-management מגדיר את כל נקודות הקצה של המודלים שאפשר להפנות אליהם בקשות. כל שם של קצה עורפי מייצג שם מודל סמלי (לדוגמה, gemini-35-flashlite) שמכיל את היעד address. השדה backends הוא תוסף Google OpenAPI קיים.
2. ‫ai.models.routing: הגדרת ניתוב המודלים נמצאת ב-x-google-api-management בתור ai.models.routing, ומכילה מיפוי של נתבים עם שמות. כל רשומה במפה מגדירה נתב מודל אחד, כאשר המפתח מייצג את שם הנתב (לדוגמה, gemini-claude-router) והערך מכיל:
   • ‫defaultModel: יעד מודל ברירת המחדל שנדרש לשימוש כשמטען ייעודי (payload) של בקשה נכנסת לא תואם לאף כלל מפורש. היא כוללת את המבנה המדויק של רשומה בכלל, אבל לא כוללת את שדה ההתאמה model. במסלולים שתואמים ל-OpenAI, אם בקשה חוזרת ל-defaultModel, הערך של targetModel מועבר כמאפיין היוצא model בגוף הבקשה שנשלחת אל Vertex AI.
   • ‫rules: מערך אופציונלי שבו כל רכיב ממפה מחרוזת של מודל מטען ייעודי (payload) של לקוח אל קצה עורפי (backend) יעד ומודל יעד.
3. מאפייני הכלל: כל רשומה ב-rules (וב-defaultModel) מגדירה את המאפיינים הבאים:
   • ‫model (כללים בלבד): ערך המחרוזת שתואם למאפיין model במטען הייעודי (payload) של הנחיית JSON הנכנסת של הלקוח. הנתב משווה את הערך model של מטען הייעודי (payload) הנכנס למחרוזת הזו. אם אין כלל מתאים, הנתב בוחר את defaultModel. במסלולים שתואמים ל-OpenAI (כשהקצה העורפי של היעד הוא /openapi/chat/completions), המחרוזת הזו מועברת ישירות כמאפיין model היוצא בגוף הבקשה שנשלחת אל Vertex AI. לכן, במסלולים שתואמים ל-OpenAI, הבורר model חייב להיות מזהה מודל תקף של בעל תוכן דיגיטלי (לדוגמה, openai/gpt-oss-120b-maas). שימוש בכינוי כמו gpt-oss יגרום לשגיאה 400 Malformed publisher model מ-Vertex AI.
   • ‫backend: השם הסמלי של העורף האחורי שמוגדר בקטע x-google-api-management.backends, שאליו השער שולח את ההנחיה.
   • ‫targetModel: מזהה מודל היעד בפורמט <provider>/<model-id>. נתב המודלים משתמש במחרוזת הזו כדי לתרגם בקשות ותשובות למודל היעד. הקידומת <provider> חייבת להיות בדיוק google, openai או anthropic. הערך של <model-id> חייב להיות מזהה תקף של מודל שפורסם ב-Vertex AI Model Garden. השער מחזיר את המחרוזת הזו בשדה model של התגובה שמוחזרת ללקוח. ערכים לדוגמה:
     • google/gemini-3.5-flash-lite
     • google/gemini-2.5-pro
     • openai/gpt-oss-120b-maas
     • anthropic/claude-opus-4-7
4. ‫x-google-model-router: כדי לצרף נתב מודלים לנתיב של פעולת API, מציינים את שם הנתב באמצעות המאפיין x-google-model-router. בדוגמה הקודמת, בקשת POST שנשלחה אל /v1/chat/gemini-claude מפעילה את gemini-claude-router, שמנתב את ההנחיה על סמך שם המודל שצוין במטען הייעודי (payload) של ה-JSON.

שלב 3: יוצרים ומפעילים את הגדרת ה-API

יוצרים הגדרת API באמצעות מפרט OpenAPI 3.x שכתבתם ופורסים את ההגדרה למופע של API Gateway, כמו שמתואר במאמר פריסת API לשער.

מישור הניהול של API Gateway מעבד את הגדרת ניתוב המודלים ומפעיל את שכבת הניתוב. כשהפריסה של השער מסתיימת, השער מוכן לקבל בקשות מהירות בפורמט של מטען ייעודי (payload) ב-JSON שתואם ל-OpenAI.

שלב 4: בודקים את התנהגות הניתוב

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

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GATEWAY_LOCATION \
  --project=PROJECT_ID \
  --format='value(defaultHostname)'

במהלך תקופת ה-Public Preview, שערים של ניתוב מודלים מחזירים שם מארח *.run.app. אחזור שם המארח מתבצע רק אחרי שהשער הוא ACTIVE. הערך שמדווח בזמן יצירת השער הוא לא כתובת ה-URL הסופית.

כדי לבדוק את התנהגות הניתוב של השער, משתמשים ב-curl כדי לשלוח בקשות להנחיות שתואמות ל-OpenAI לכתובת ה-URL של השער (https://GATEWAY_URL). בדוגמאות הבאות, $TOKEN מייצג אסימון אימות תקין שהתקבל באמצעות אחת מהשיטות שמתוארות במאמר בחירה של שיטת אימות.

בדיקת ניתוב של כלל מפורש

שולחים הנחיה שמבקשת את מודל Claude anthropic/claude-opus-4-7:

curl https://GATEWAY_URL/v1/chat/gemini-claude \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "model": "claude-opus-4-7",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Explain the concept of recursion in one sentence."
      }
    ]
  }'

שליחת הבקשה אל /v1/chat/gemini-claude מפעילה את gemini-claude-router. המאפיין "model": "claude-opus-4-7" במטען הייעודי (payload) של JSON תואם לכלל המפורש ב-gemini-claude-router, ומנחה את שער הכניסה לנתב את הבקשה אל קצה העורפי (backend) anthropic-claude-opus-47.

בדיקת החזרה למצב הראשוני (fallback) של מודל ברירת המחדל

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

curl https://GATEWAY_URL/v1/chat/gemini-claude \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "model": "unrecognized-model",
    "messages": [
      {
        "role": "user",
        "content": "Write a short poem about the ocean."
      }
    ],
    "stream": true
  }'

שליחת הבקשה אל /v1/chat/gemini-claude מפעילה את gemini-claude-router. מכיוון שהמאפיין "model": "unrecognized-model" לא תואם לאף כלל מפורש, שער הכניסה שולח את הבקשה לנתב שהוגדר defaultModel – קצה העורפי gemini-35-flashlite.

בדיקת נתיב חלופי לנתב

שליחת פרומפט עם בקשה ל-Gemini דרך נקודת הקצה של הנתב המשני:

curl https://GATEWAY_URL/v1/chat/openai-gemini \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "model": "gemini-3.5-flash-lite",
    "messages": [
      {
        "role": "user",
        "content": "List the three largest cities in the world."
      }
    ]
  }'

שליחת הבקשה אל /v1/chat/openai-gemini מפעילה את openai-gemini-router. המאפיין "model": "gemini-3.5-flash-lite" תואם לכלל המפורש בנתב הזה, ומפנה את השער לנתב את הבקשה אל קצה העורף gemini-35-flashlite. אפשר להפנות למספר נתבים אל קצה עורפי יחיד. בהגדרה הזו, gemini-35-flashlite משמש כיעד כלל מפורש ב-openai-gemini-router וכברירת מחדל ב-defaultModel ב-gemini-claude-router.

ניראות (observability)

נתב המודלים מוגדר כך שתוכלו לוודא שהשער משרת תעבורה, לבדוק את המטא-נתונים של כל בקשה באמצעות Cloud Logging ולאבחן כשלים באמצעות Cloud Monitoring.

Cloud Logging

כל בקשה שמנותבת דרך השער יוצרת רשומה ביומן הבקשות הרגיל של API Gateway, שנמצא בפרויקט Google Cloud בכתובת:

projects/YOUR_PROJECT_ID/logs/apigateway.googleapis.com%2Frequests

כל רשומה ביומן כוללת את השדות הבאים:

• httpRequest.requestUrl, httpRequest.status, httpRequest.latency
• api, apiConfig, apiMethod
• ‫backendRequest.hostname: שם המארח של העורף האחורי של Vertex AI שאליו הבקשה הועברה באמצעות פרוקסי.
• ‫responseDetails: מאוכלס בקטגוריית שגיאות ממותגת בשגיאות בנתב המודלים (ראו פתרון בעיות בנתב המודלים מיד למטה).

כדי למצוא בקשות שנשלחו לאחרונה לשער מסוים, משתמשים במסנן השאילתות הבא של Cloud Logging:

(resource.type="apigateway.googleapis.com/Gateway" OR resource.type="api")
logName="projects/YOUR_PROJECT_ID/logs/apigateway.googleapis.com%2Frequests"

Cloud Monitoring

מדד שער ה-API הרגיל apigateway.googleapis.com/proxy/request_count (בטא) מציג את נפח התנועה בשער לפי:

• ‫response_code_class: אחד מהערכים 2xx,‏ 3xx,‏ 4xx או 5xx.
• ‫api_config: שם הגדרת ה-API שבה נעשה שימוש בשער.

המדד הזה מאפשר לכם לאמת את נפח התנועה הכולל ואת שיעורי השגיאות. מדדים ספציפיים לנתב מודלים (כמו פירוטים לפי נתב או לפי מודל יעד) יתווספו בגרסה עתידית.

כדי לעקוב אחרי זמן הטעינה המצטבר של הבקשות, אפשר ליצור מדד מבוסס-יומן מהשדה httpRequest.latency ביומן הבקשות.

פתרון בעיות בכשלים בנתב של המודל

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

המאמרים הבאים

• חשוב לעיין בארכיטקטורת הניתוב של המודל ובמושגים שקשורים אליה
• מידע נוסף על תוספים של OpenAPI 3.x