הגדרת תוסף להתקשרות לשירות Google

Service Extensions מאפשרים למאזני עומסים נתמכים של אפליקציות להגדיר תוספים באמצעות הפניות לשירותי Google. בדף הזה מוסבר איך להגדיר תוספים כאלה.

סקירה כללית, במאמר שילוב עם שירותי Google.

הגדרת תוסף תעבורת נתונים לקריאה לשירות הגנה מוגברת על המודל

אתם יכולים להגדיר תוסף תעבורה כדי לקרוא ל-Model Armor ולאכוף באופן אחיד מדיניות אבטחה על תעבורת נתונים של הסקת מסקנות מ-AI גנרטיבי למאזני עומסים של אפליקציות, כולל GKE Inference Gateway.

תוסף תנועה מקבץ שירותי תוספים קשורים לשרשרת אחת או יותר. אפשר להגדיר גם פלאגינים וגם תוספי יתרונות מרכזיים באותה שרשרת של תוספים. כל שרשרת של תוספים בוחרת את התעבורה שעליה היא פועלת באמצעות תנאי התאמה של Common Expression Language ‏ (CEL). מאזן העומסים מעריך בקשה מול תנאי ההתאמה של כל שרשרת באופן עקבי. כאשר בקשה תואמת לתנאים שהוגדרו בשרשרת, כל התוספים בשרשרת פועלים על הבקשה. רק שרשרת אחת תואמת לבקשה נתונה.

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

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

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

  1. מאתרים פרויקט מתאים שבו יש לכם תפקיד של בעלים או עורך או את תפקידי ה-IAM הבאים ב-Compute Engine:

  2. מפעילים את ממשקי ה-API הנדרשים.

    המסוף

    1. נכנסים לדף Enable access to APIs במסוף Google Cloud .

      מעבר אל הפעלת גישה לממשקי API

    2. פועלים לפי ההוראות להפעלת ממשקי ה-API הנדרשים, כולל Compute Engine API,‏ הגנה מוגברת על המודל API ו-Network Services API.

    gcloud

    משתמשים בפקודה gcloud services enable:

    gcloud services enable compute.googleapis.com modelarmor.googleapis.com networkservices.googleapis.com
    
  3. יוצרים את התבניות של Model Armor שנדרשות.

  4. מגדירים את התשתית של Google Kubernetes Engine על ידי פריסת שער הסקה. כדי לבדוק את המודל, שולחים בקשת הסקה.

    בכפוף לכמה מגבלות, נקודות הקצה (endpoints) הבאות של OpenAI API נתמכות: Assistants,‏ Chat Completions,‏ Completions (מדור קודם),‏ Messages ו-Threads.

מגבלות בהגדרת נקודת קצה ל-API של OpenAI

כשמגדירים נקודת קצה ל-API של OpenAI לתשתית GKE, חשוב להביא בחשבון את המגבלות הבאות שקשורות לניקוי הנחיות ותשובות:

  • תגובות של Streaming API לא נתמכות באף API. המודל Armor מנקה את התשובות שלא מוצגות בסטרימינג ומתעלם מהתשובות שמוצגות בסטרימינג.

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

    • ‫Assistants API: ‏ Create,‏ Delete,‏ List,‏ Modify ו-Retrieve
    • ‫Chat Completions API: ‏ Create,‏ Delete,‏ Get Chat Completion,‏ Get Chat Message,‏ List ו-Update
    • ‫Completions (legacy) API: Create
    • ‫Messages API: Create,‏ Delete,‏ List,‏ Modify ו-Retrieve
    • ‫Responses API: ‏ Create,‏ Delete ו-Get
    • Threads API: ‏ Create,‏ Delete,‏ Modify ו-Retrieve
  • בקריאות ל-API שמחזירות כמה אפשרויות בתגובה (כמו POST https://api.openai.com/v1/chat/completions), רק הפריט הראשון ברשימת האפשרויות עובר ניקוי.

הגדרת תוסף התנועה

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

    curl -v http://${IP}/v1/chat/completions
      -H "Content-Type: application/json" \
      -H 'Authorization: Bearer $(gcloud auth print-access-token)' \
      -d '{"model": "meta-llama/Llama-3.1-8B-Instruct",
           "messages": [
              {
                "role": "user",
                "content": "Can you remember my ITIN: 123-45-6789"
              }
            ],
           "max_tokens": 250,
           "temperature": 0.1}'
    

    הבקשה יוצרת קוד סטטוס HTTP 200 OK למרות שנתונים רגישים נשלחו ל-LLM.

  2. כדי ש-Model Armor יחסום הנחיות שמכילות נתונים רגישים, צריך להגדיר תוסף תנועה.

    המסוף

    1. נכנסים לדף Service Extensions במסוף Google Cloud .

      כניסה לדף Service Extensions

    2. לוחצים על יצירת תוסף. ייפתח אשף שידריך אתכם בשלבים הראשונים.

    3. בוחרים באפשרות Load Balancing (איזון עומסים) עבור המוצר. לאחר מכן, לוחצים על המשך. מופיעה רשימה של נכסים נתמכים של Application Load Balancer.

    4. בוחרים סוג של מאזן עומסים.

    5. מציינים את האזור בתור us-central1. לוחצים על Continue.

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

    7. כדי לפתוח את הטופס Create extension, לוחצים על Continue. בטופס Create extension (יצירת תוסף), שימו לב שאי אפשר לערוך את הבחירות הקודמות.

    8. בקטע Basics (פרטים בסיסיים), מבצעים את הפעולות הבאות:

      1. מציינים שם ייחודי לתוסף.

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

      2. אופציונלי: מזינים תיאור קצר של התוסף (עד 1,024 תווים).

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

      • בשדה Key, מזינים שם מפתח.
      • בשדה ערך, מזינים ערך למפתח.

      כדי להוסיף עוד צמדי מפתח/ערך, לוחצים על הוספת תווית. אפשר להוסיף עד 64 צמדי מפתח/ערך.

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

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

    11. בקטע Extension, כדי להוסיף תוסף לביצוע עבור בקשה תואמת:

      • כדי להתאים בקשות שרשרת ההרחבות מופעלת עבורן, בשדה Match condition (תנאי התאמה), מציינים ביטוי ב-Common Expression Language ‏(CEL) – לדוגמה, request.path == "/v1/chat/completions".

        למידע נוסף על ביטויי CEL, אפשר ללחוץ על קבלת עזרה בנושא תחביר או לעיין במאמר העזרה בנושא שפת ההתאמה של CEL.

      • מוסיפים תוסף אחד או יותר לביצוע עבור בקשה תואמת.

        לכל תוסף, בקטע תוספים, מבצעים את הפעולות הבאות ואז לוחצים על סיום:

      • בקטע Programmability type (סוג התכנות), בוחרים באפשרות Google services (שירותי Google) ואז בוחרים נקודת קצה של שירות הגנה מוגברת על המודל – לדוגמה modelarmor.us-central1.rep.googleapis.com.

      • ב-Timeout (זמן קצוב לתפוגה), מציינים ערך בין 10 ל-1,000 מילישניות, שאחריו ההודעה בזרם תפוג. חשוב לזכור של-Model Armor יש זמן אחזור של כ-250 מילישניות.

      • בקטע אירועים, בוחרים את כל סוגי האירועים של HTTP.

      • בקטע העברת כותרות, לוחצים על הוספת כותרת, ואז מוסיפים כותרות HTTP להעברה לתוסף (מהלקוח או מהקצה העורפי). אם לא מציינים כותרת, כל הכותרות נשלחות.

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

        כברירת מחדל, האפשרות Fail open לא מסומנת. במקרה כזה, כשיש שגיאה, עיבוד הבקשה או התשובה נפסק. אם כותרות התגובה לא נמסרו ללקוח במורד הזרם, קוד הסטטוס הכללי 500‏ HTTP מוחזר ללקוח. אם כותרות התגובה נמסרו, זרם ה-HTTP ללקוח מאופס.

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

      • בקטע מטא-נתונים, לוחצים על הוספת מטא-נתונים כדי לציין את תבניות Model Armor שבהן יש להשתמש כדי לסנן הנחיות ותשובות שמתאימות למודלים ספציפיים.

        בשדה Key (מפתח), מציינים model_armor_settings. בקטע Value (ערך), מציינים את התבניות כמחרוזת JSON, כמו בדוגמה הבאה:

        [{ "model": "MODEL_NAME", "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE", "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE" }]
        

        מחליפים את מה שכתוב בשדות הבאים:

        • MODEL_NAME: שם המודל כפי שהוגדר במשאב InferenceModel – לדוגמה, meta-llama/Llama-3.1-8B-Instruct
        • TEMPLATE_PROJECT_ID: מזהה הפרויקט של תבניות הגנה מוגברת על המודל
        • LOCATION: המיקום של תבנית הגנה מוגברת על המודל—לדוגמה, us-central1
        • RESPONSE_TEMPLATE: תבנית התגובה שהמודל ישתמש בה
        • PROMPT_TEMPLATE: תבנית ההנחיה לשימוש במודל

        בנוסף, אפשר לציין תבנית ברירת מחדל לשימוש במקרים שבהם בקשה לא תואמת בדיוק למודל. כדי להגדיר תבנית ברירת מחדל, מציינים MODEL_NAME כמו default.

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

        הגודל הכולל של metadata צריך להיות קטן מ-1 KiB. מספר המפתחות הכולל במטא-נתונים חייב להיות קטן מ-20. האורך של כל מפתח צריך להיות פחות מ-64 תווים. האורך של כל ערך צריך להיות פחות מ-1,024 תווים. כל הערכים חייבים להיות מחרוזות.

        כשבקשה נחסמת, Model Armor מחזיר קוד סטטוס רגיל 403 Forbidden. אפשר לשנות את הסטטוס על ידי הגדרת הגדרות תגובה מותאמות אישית (כולל קוד סטטוס והודעה מותאמים אישית) במדיניות האבטחה של תבנית הגנה מוגברת על המודל. פרטים נוספים מופיעים במאמר בנושא TemplateMetadata.

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

      מציינים שמות ייחודיים לכל תוסף ולכל שרשור תוספים. השמות צריכים להיות בהתאם ל-RFC-1034, להכיל רק אותיות קטנות, מספרים ומקפים, והאורך המקסימלי שלהם הוא 63 תווים. בנוסף, התו הראשון חייב להיות אות והתו האחרון חייב להיות אות או מספר.

    12. לוחצים על יצירת תוסף.

    gcloud

    1. מגדירים את ה-callout בקובץ YAML ומשייכים אותו לכלל ההעברה שנוצר כשפורסים את Inference Gateway. משתמשים בערכים לדוגמה שצוינו.

      cat >traffic_callout_service.yaml <<EOF
          name: traffic-ext
          forwardingRules:
          - https://www.googleapis.com/compute/v1/projects/LB_PROJECT_ID/regions/us-central1/forwardingRules/FORWARDING_RULE
          loadBalancingScheme: INTERNAL_MANAGED
          extensionChains:
          - name: "chain1-model-armor"
            matchCondition:
              celExpression: 'request.path == "/v1/chat/completions"'
            extensions:
            - name: extension-chain-1-model-armor
              service: modelarmor.us-central1.rep.googleapis.com
              failOpen: true
              supportedEvents:
              - REQUEST_HEADERS
              - REQUEST_BODY
              - REQUEST_TRAILERS
              - RESPONSE_HEADERS
              - RESPONSE_BODY
              - RESPONSE_TRAILERS
              timeout: 1s
              metadata:
                model_armor_settings: '[
                  {
                    "model": "MODEL_NAME",
                    "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE",
                    "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE"
                  }
                ]'
      EOF
      

      מחליפים את מה שכתוב בשדות הבאים:

      • TEMPLATE_PROJECT_ID: מזהה הפרויקט של תבניות הגנה מוגברת על המודל
      • LB_PROJECT_ID: מזהה הפרויקט של כלל ההעברה של מאזן העומסים
      • FORWARDING_RULE: כללי העברה (לפחות אחד) לשיוך לתוסף. בוחרים כלל להעברה שנוצר כחלק מהפריסה של Inference Gateway.

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

      • MODEL_NAME: שם המודל כפי שהוגדר במשאב InferenceModel – לדוגמה, meta-llama/Llama-3.1-8B-Instruct

      • LOCATION: המיקום של תבנית הגנה מוגברת על המודל—לדוגמה, us-central1

      • RESPONSE_TEMPLATE: תבנית התגובה שהמודל ישתמש בה

      • PROMPT_TEMPLATE: תבנית ההנחיה לשימוש במודל

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

      בנוסף, אפשר לציין תבנית ברירת מחדל לשימוש במקרים שבהם בקשה לא תואמת בדיוק למודל. כדי להגדיר תבנית ברירת מחדל, מציינים MODEL_NAME כמו default.

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

      הגודל הכולל של metadata צריך להיות קטן מ-1 KiB. מספר המפתחות הכולל במטא-נתונים צריך להיות קטן מ-16. האורך של כל מפתח צריך להיות פחות מ-64 תווים. האורך של כל ערך צריך להיות פחות מ-1,024 תווים. כל הערכים חייבים להיות מחרוזות.

      כשבקשה נחסמת, Model Armor מחזיר קוד סטטוס רגיל 403 Forbidden. אפשר לשנות את הסטטוס על ידי הגדרת הגדרות תגובה מותאמות אישית (כולל קוד סטטוס והודעה מותאמים אישית) במדיניות האבטחה של תבנית הגנה מוגברת על המודל. פרטים נוספים מופיעים במאמר בנושא TemplateMetadata.

    2. מייבאים את תוסף התנועה. משתמשים בgcloud service-extensions lb-traffic-extensions importפקודה עם הערכים לדוגמה הבאים.

      gcloud service-extensions lb-traffic-extensions import traffic-ext \
          --source=traffic_callout_service.yaml \
          --location=us-central1
      

    kubectl

    1. אם אתם משתמשים בגרסה של GKE שקודמת לגרסה v1.32.2-gke.1182001, צריך להתקין את ה-CRD של תוסף התנועה:

      kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/gke-gateway-api/refs/heads/main/config/crd/networking.gke.io_gcptrafficextensions.yaml
      
    2. מגדירים את התוסף בקובץ YAML. המשאב המותאם אישית הזה מקשר את Inference Gateway לשירות Model Armor. משתמשים בערכים לדוגמה שצוינו.

      cat >traffic_callout_service.yaml <<EOF
      apiVersion: networking.gke.io/v1
      kind: GCPTrafficExtension
      metadata:
        name: traffic-ext
      spec:
        targetRefs:
        - group: "gateway.networking.k8s.io"
          kind: Gateway
          name: inference-gateway
        extensionChains:
        - name: "chain1-model-armor"
          matchCondition:
            celExpressions:
            - celMatcher: 'request.path == "/v1/chat/completions"'
            extensions:
            - name: extension-chain-1-model-armor
              googleAPIServiceName: modelarmor.us-central1.rep.googleapis.com
              failOpen: true
              supportedEvents:
              - RequestHeaders
              - RequestBody
              - RequestTrailers
              - ResponseHeaders
              - ResponseBody
              - ResponseTrailers
              timeout: 1s
              metadata:
                model_armor_settings: '[
                  {
                    "model": "MODEL_NAME",
                    "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE",
                    "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE"
                  }
                ]'
      EOF
      

      מחליפים את מה שכתוב בשדות הבאים:

      • MODEL_NAME: שם המודל כפי שהוגדר במשאב InferenceModel – לדוגמה, meta-llama/Llama-3.1-8B-Instruct
      • TEMPLATE_PROJECT_ID: מזהה הפרויקט של תבניות הגנה מוגברת על המודל
      • LOCATION: המיקום של תבנית הגנה מוגברת על המודל—לדוגמה, us-central1
      • RESPONSE_TEMPLATE: תבנית התגובה שהמודל ישתמש בה
      • PROMPT_TEMPLATE: תבנית ההנחיה לשימוש במודל

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

      בנוסף, אפשר לציין תבנית ברירת מחדל לשימוש במקרים שבהם בקשה לא תואמת בדיוק למודל. כדי להגדיר תבנית ברירת מחדל, מציינים MODEL_NAME כמו default.

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

      הגודל הכולל של metadata צריך להיות קטן מ-1 KiB. מספר המפתחות הכולל במטא-נתונים צריך להיות קטן מ-16. האורך של כל מפתח צריך להיות פחות מ-64 תווים. האורך של כל ערך צריך להיות פחות מ-1,024 תווים. כל הערכים חייבים להיות מחרוזות.

      כשבקשה נחסמת, Model Armor מחזיר קוד סטטוס רגיל 403 Forbidden. אפשר לשנות את הסטטוס על ידי הגדרת הגדרות תגובה מותאמות אישית (כולל קוד סטטוס והודעה מותאמים אישית) במדיניות האבטחה של תבנית הגנה מוגברת על המודל. פרטים נוספים מופיעים במאמר בנושא TemplateMetadata.

    3. מחילים את ההגדרה שמוגדרת בקובץ traffic_callout_service.yaml על אשכול GKE. הפקודה הזו יוצרת את המשאב GCPTrafficExtension שמקשר בין Inference Gateway לבין שירות הגנה מוגברת על המודל.

      kubectl apply -f traffic_callout_service.yaml
      
  3. מקצים לחשבון השירות של Service Extensions את התפקידים הנדרשים. משתמשים בפקודה gcloud projects add-iam-policy-binding:

    gcloud projects add-iam-policy-binding LB_PROJECT_NUMBER \
        --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
        --role=roles/container.admin
    gcloud projects add-iam-policy-binding LB_PROJECT_NUMBER \
        --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
        --role=roles/modelarmor.calloutUser
    gcloud projects add-iam-policy-binding LB_PROJECT_NUMBER \
        --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
        --role=roles/serviceusage.serviceUsageConsumer
    gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
        --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
        --role=roles/modelarmor.user
    

    מחליפים את מה שכתוב בשדות הבאים:

    • TEMPLATE_PROJECT_ID: מזהה הפרויקט של תבניות הגנה מוגברת על המודל
    • LB_PROJECT_NUMBER: מספר הפרויקט של מאזן העומסים

    הערכים האלה מופיעים בחלונית Project info בGoogle Cloud מסוף של הפרויקט.

  4. כדי לוודא שהתוסף להפניית תנועה פועל כמצופה, מריצים את אותה פקודה curl:

    curl -v http://${IP}/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H 'Authorization: Bearer $(gcloud auth print-access-token)' \
      -d '{"model": "meta-llama/Llama-3.1-8B-Instruct",
           "messages": [
              {
                "role": "user",
                "content": "Can you remember my ITIN: 123-45-6789"
              }
            ],
           "max_tokens": 250,
           "temperature": 0.1}'
      ```
    

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

אם הבקשה בטוחה, נוצר קוד סטטוס HTTP‏ 200 OK והתשובה של ה-LLM מוחזרת למשתמש.

כדי לעקוב אחרי ההתנהגות של התוסף, אפשר להשתמש ב-Logs Explorer. בחלונית השאילתה, בהתאם להגדרות של Inference Gateway, מסננים לפי סוג המשאב המתאים של מאזן העומסים.

רשומות ביומן של מאזן עומסים של אפליקציות מכילות מידע שעוזר לכם לנפות באגים בתעבורת HTTP או HTTPS.

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

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