רישום של מודלים של AI מרוחקים והפעלתם באמצעות ניהול נקודות קצה של מודלים

ניהול נקודות קצה של מודלי AI ב-AlloyDB ל-PostgreSQL מאפשר לכם לרשום נקודות קצה של מודלי AI מרוחקים, כדי שתוכלו ליצור הטמעות וקטוריות ולהפעיל חיזויים ישירות משאילתות SQL. אתם יכולים לרשום מודלים שמתארחים ב-Gemini Enterprise Agent Platform, אצל ספקי צד שלישי כמו OpenAI ו-Anthropic, או בנקודות קצה (endpoints) באירוח מותאם אישית.

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

הגדרת התוסף

  1. מתחברים למסד הנתונים באמצעות psql או AlloyDB Studio באמצעות המשתמש postgres.

  2. אופציונלי: נותנים למשתמש PostgreSQL שאינו סופר-משתמש הרשאה לנהל את המטא-נתונים של המודל:

      GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA google_ml TO NON_SUPER_USER;

    מחליפים את המשתנה הבא:

    • ‫NON_SUPER_USER: שם המשתמש ב-PostgreSQL שהוא לא משתמש-על.

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

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

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

שילוב עם Gemini Enterprise Agent Platform והתקנת התוסף

כדי להשתמש בנקודות הקצה של המודל ב-Agent Platform, צריך להוסיף הרשאות של Agent Platform לחשבון השירות של AlloyDB שמבוסס על ניהול זהויות והרשאות גישה (IAM), שבו אתם משתמשים כדי להתחבר למסד הנתונים.

  1. להגדיר את הגישה של המשתמשים למודלים של Agent Platform.
  2. מוודאים שמותקנת הגרסה העדכנית של google_ml_integration.

    1. כדי לבדוק את הגרסה המותקנת, מריצים את הפקודה הבאה:

      SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
extversion 
------------
1.5.2
(1 row)

    2. אם התוסף לא מותקן או שהגרסה המותקנת היא גרסה קודמת ל-1.5.2, צריך לעדכן את התוסף.

      CREATE EXTENSION IF NOT EXISTS google_ml_integration;
ALTER EXTENSION google_ml_integration UPDATE;

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

  3. כדי להשתמש בפונקציונליות של מנוע השאילתות של AlloyDB AI, מגדירים את הדגל google_ml_integration.enable_ai_query_engine לערך on.

    SQL

    1. הפעלת מנוע השאילתות מבוסס ה-AI לסשן הנוכחי.
      SET google_ml_integration.enable_ai_query_engine = on;
    2. הפעלת תכונות במסד נתונים ספציפי בכל הסשנים.
      ALTER DATABASE DATABASE_NAME SET google_ml_integration.enable_ai_query_engine = 'on';
    3. להפעיל את מנוע השאילתות מבוסס ה-AI למשתמש ספציפי בכל הסשנים ומסדי הנתונים.
      ALTER ROLE postgres SET google_ml_integration.enable_ai_query_engine = 'on';

    המסוף

    כדי לשנות את הערך של הדגל google_ml_integration.enable_ai_query_engine, פועלים לפי השלבים שמפורטים במאמר הגדרת דגלים לניהול מסד נתונים של מכונה.

    gcloud

    כדי להשתמש ב-CLI של gcloud, אתם יכולים להתקין ולהפעיל את Google Cloud CLI או להשתמש ב-Cloud Shell.

    אפשר לשנות את הערך של הדגל google_ml_integration.enable_ai_query_engine. מידע נוסף זמין במאמר הגדרת דגלים לניהול מסד נתונים של מכונה. 

    gcloud alloydb instances update INSTANCE_ID \
  --database-flags google_ml_integration.enable_ai_query_engine=on \
  --region=REGION_ID \
  --cluster=CLUSTER_ID \
  --project=PROJECT_ID

הגדרת אימות באמצעות Secret Manager

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

השלב הזה אופציונלי אם נקודת הקצה של המודל לא מטפלת באימות דרך Secret Manager – לדוגמה, אם נקודת הקצה של המודל משתמשת בכותרות HTTP כדי להעביר פרטי אימות או לא משתמשת באימות בכלל.

כדי ליצור מפתח API או טוקן למוכ"ז ולהשתמש בהם:

  1. יוצרים את הסוד ב-Secret Manager. מידע נוסף זמין במאמר יצירת סוד וגישה לגרסת סוד.

    הנתיב של הסוד משמש בפונקציית ה-SQL‏ google_ml.create_sm_secret().

  2. נותנים לאשכול AlloyDB הרשאות גישה לסוד.

      gcloud secrets add-iam-policy-binding 'SECRET_NAME' \
      --member="serviceAccount:SERVICE_ACCOUNT_ID" \
      --role="roles/secretmanager.secretAccessor"

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

    • ‫SECRET_NAME: שם הסוד ב-Secret Manager.

    • ‫SERVICE_ACCOUNT_ID: המזהה של חשבון השירות שמבוסס על IAM בפורמט serviceAccount:service-PROJECT_ID@gcp-sa-alloydb.. לדוגמה: service-212340152456@gcp-sa-alloydb..

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

הגדרת אימות באמצעות כותרות

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

  CREATE OR REPLACE FUNCTION HEADER_GEN_FUNCTION(
    model_id VARCHAR(100),
    input_text TEXT
  )
  RETURNS JSON
  LANGUAGE plpgsql
  AS $$
  #variable_conflict use_variable
  DECLARE
    api_key VARCHAR(255) := 'API_KEY';
    header_json JSON;
  BEGIN
    header_json := json_build_object(
      'Content-Type', 'application/json',
      'Authorization', 'Bearer ' || api_key
    );
    RETURN header_json;
  END;
  $$;

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

  • ‫HEADER_GEN_FUNCTION: השם של הפונקציה ליצירת שורות כותרת שאפשר להשתמש בה כשרושמים מודל.

  • ‫API_KEY: מפתח ה-API של ספק המודל.

פריסת מודלים של Model Garden בנקודת קצה של Agent Platform

בנוסף ל-Gemini או למודלים אחרים של Agent Platform שזמינים כברירת מחדל, אתם יכולים לארח מודלים מ-Model Garden שמותאמים למשימות ספציפיות. התהליך הנפוץ הוא לפרוס קודם מודל מ-Model Garden לנקודת קצה ציבורית של Agent Platform, ואז לרשום את נקודת הקצה הזו ב-AlloyDB. המודלים הספציפיים האלה רשומים עם model_type תואם, כמו ts_forecasting במקרה של המודל TimesFM, ומשמשים עם פונקציות SQL מיוחדות.

כדי לפרוס מודל שמתארח ב-Model Garden בנקודת קצה של Agent Platform:

  1. נכנסים לדף Model Garden במסוף Google Cloud :

    כניסה ל-Model Garden

  2. מוצאים את המודל ולוחצים על Deploy.

  3. בהגדרות הפריסה, בקטע Endpoint access בוחרים באפשרות Public (Shared endpoint) כדי שנקודת הקצה תהיה נגישה באופן ציבורי ו-AlloyDB יוכל להגיע אליה.

  4. בסיום הפריסה, עוברים לדף הפרטים של נקודת הקצה ומעתיקים את כתובת ה-URL של הבקשה למודל מהחלונית Sample request.

מודלים להטמעת טקסט

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

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

מוודאים שהמודל gemini-embedding-001 זמין באזור שלכם. מידע נוסף זמין במאמר אזורים נתמכים.

לדוגמה, כדי לקרוא למודל gemini-embedding-001 שנרשם מראש, אתם יכולים לקרוא ישירות למודל באמצעות פונקציית ההטמעה:

SELECT
      embedding(
        model_id => 'gemini-embedding-001',
        content => 'AlloyDB is a managed, cloud-hosted SQL database service');

אם אשכול AlloyDB ונקודת הקצה של Agent Platform נמצאים בפרויקטים שונים, צריך להגדיר את model_id לנתיב המלא של נקודת הקצה, לדוגמה projects/PROJECT_ID/locations/REGION_ID/publishers/google/models/gemini-embedding-001.

כדי ליצור הטמעות, קראו את המאמר יצירת הטמעות טקסט.

מודלים של הטמעת טקסט עם תמיכה מובנית

הכלי לניהול נקודות קצה של מודלים מספק תמיכה מובנית בחלק מהמודלים של Agent Platform ו-OpenAI. רשימת המודלים עם תמיכה מובנית

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

מודלים להטמעה ב-Agent Platform

בשלבים הבאים מוסבר איך לרשום מודלים של Agent Platform עם תמיכה מובנית. נקודת הקצה של המודל gemini-embedding-001 ו-text-multilingual-embedding-002 משמשת כדוגמה.

חשוב לוודא שאשכול AlloyDB והמודל של Agent Platform שאתם שולחים אליו שאילתות נמצאים באותו אזור.

  1. מתחברים למסד הנתונים באמצעות psql.

  2. מגדירים את התוסף google_ml_integration.

  3. מפעילים את הפונקציה create model כדי להוסיף את נקודת הקצה של המודל:

    gemini-embedding-001 

      CALL
    google_ml.create_model(
      model_id => 'gemini-embedding-001',
      model_request_url => 'publishers/google/models/gemini-embedding-001',
      model_provider => 'google',
      model_qualified_name => 'gemini-embedding-001',
      model_type => 'text_embedding',
      model_auth_type => 'alloydb_service_agent_iam');

    text-multilingual-embedding-002 

      CALL
    google_ml.create_model(
      model_id => 'text-multilingual-embedding-002',
      model_request_url => 'publishers/google/models/text-multilingual-embedding-002',
      model_provider => 'google',
      model_qualified_name => 'text-multilingual-embedding-002',
      model_type => 'text_embedding',
      model_auth_type => 'alloydb_service_agent_iam',
      model_in_transform_fn => 'google_ml.vertexai_text_embedding_input_transform',
      model_out_transform_fn => 'google_ml.vertexai_text_embedding_output_transform');

אם המודל מאוחסן בפרויקט ובאזור שונים מאלה של אשכול AlloyDB, צריך להגדיר את כתובת ה-URL של הבקשה ל-projects/PROJECT_ID/locations/REGION_ID/publishers/google/models/MODEL_ID, כאשר REGION_ID הוא האזור שבו המודל מתארח ו-MODEL_ID הוא השם המלא של המודל.

בנוסף, מקצים את התפקיד "משתמש בפלטפורמת הסוכנים" (roles/aiplatform.user) לחשבון השירות של AlloyDB בפרויקט שבו נמצא המכונה של AlloyDB, כדי ש-AlloyDB יוכל לגשת למודל שמתארח בפרויקט השני.

מודל הטמעת טקסט של OpenAI

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

בדוגמה הבאה מוסיפים את נקודת הקצה של המודל text-embedding-ada-002 של OpenAI. כדי לרשום את נקודות הקצה של המודלים text-embedding-3-small ו-text-embedding-3-large של OpenAI, פועלים לפי אותם שלבים ומגדירים את השמות המלאים הספציפיים למודלים.

  1. מתחברים למסד הנתונים באמצעות psql.
  2. מגדירים את התוסף google_ml_integration.
  3. מוסיפים את מפתח ה-API של OpenAI כסוד ל-Secret Manager לצורך אימות.

  4. קוראים לסוד ששמור ב-Secret Manager:

    CALL
google_ml.create_sm_secret(
  secret_id => 'SECRET_ID',
  secret_path => 'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

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

    • ‫SECRET_ID: מזהה הסוד שהגדרתם, שמשמש לאחר מכן לרישום נקודת קצה של מודל. לדוגמה, key1.
    • ‫SECRET_MANAGER_SECRET_ID: מזהה הסוד שהוגדר ב-Secret Manager כשיצרתם את הסוד.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫VERSION_NUMBER: מספר הגרסה של מזהה הסוד.

  5. מפעילים את הפונקציה ליצירת מודל כדי לרשום את נקודת הקצה של המודל text-embedding-ada-002:

    CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_provider => 'open_ai',
    model_type => 'text_embedding',
    model_qualified_name => 'text-embedding-ada-002',
    model_auth_type => 'secret_manager',
    model_auth_id => 'SECRET_ID');

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

    • ‫MODEL_ID: מזהה ייחודי לנקודת הקצה של המודל שאתם מגדירים. מזהה המודל הזה משמש כהפניה למטא-נתונים שנקודת הקצה של המודל צריכה כדי ליצור הטמעות או להפעיל חיזויים.
    • ‫SECRET_ID: מזהה הסוד שבו השתמשתם קודם בתהליך google_ml.create_sm_secret().

כדי ליצור הטמעות, קראו את המאמר יצירת הטמעות טקסט.

מודל הטמעת טקסט באירוח מותאם אישית

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

בדוגמה הבאה מוסיפים את נקודת הקצה של המודל בהתאמה אישית custom-embedding-model, שמתארחת ב-Cymbal. פונקציות הטרנספורמציה cymbal_text_input_transform ו-cymbal_text_output_transform משמשות להמרת פורמט הקלט והפלט של המודל לפורמט הקלט והפלט של פונקציית החיזוי.

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

  1. מתחברים למסד הנתונים באמצעות psql.

  2. מגדירים את התוסף google_ml_integration.

  3. אופציונלי: מוסיפים את מפתח ה-API כסוד ל-Secret Manager לצורך אימות.

  4. קוראים לסוד ששמור ב-Secret Manager:

    CALL
  google_ml.create_sm_secret(
    secret_id => 'SECRET_ID',
    secret_path => 'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

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

    • ‫SECRET_ID: מזהה הסוד שהגדרתם, שמשמש לאחר מכן לרישום נקודת קצה של מודל. לדוגמה, key1.
    • ‫SECRET_MANAGER_SECRET_ID: מזהה הסוד שהוגדר ב-Secret Manager כשיצרתם את הסוד.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫VERSION_NUMBER: מספר הגרסה של מזהה הסוד.

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

    הדוגמאות הבאות הן פונקציות טרנספורמציה שספציפיות לנקודת הקצה של מודל הטמעת הטקסט custom-embedding-model:

    -- Input Transform Function corresponding to the custom model endpoint
CREATE OR REPLACE FUNCTION cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_input JSON;
  model_qualified_name TEXT;
BEGIN
  SELECT json_build_object('prompt', json_build_array(input_text))::JSON INTO transformed_input;
  RETURN transformed_input;
END;
$$;
-- Output Transform Function corresponding to the custom model endpoint
CREATE OR REPLACE FUNCTION cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON)
RETURNS REAL[]
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_output REAL[];
BEGIN
  SELECT ARRAY(SELECT json_array_elements_text(response_json->0)) INTO transformed_output;
  RETURN transformed_output;
END;
$$;

  6. קוראים לפונקציה create model כדי לרשום את נקודת הקצה של מודל ההטמעה בהתאמה אישית:

    CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_request_url => 'REQUEST_URL',
    model_provider => 'custom',
    model_type => 'text_embedding',
    model_auth_type => 'secret_manager',
    model_auth_id => 'SECRET_ID',
    model_qualified_name => 'MODEL_QUALIFIED_NAME',
    model_in_transform_fn => 'cymbal_text_input_transform',
    model_out_transform_fn => 'cymbal_text_output_transform');

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

    • ‫MODEL_ID: חובה. מזהה ייחודי לנקודת הקצה של המודל שאתם מגדירים, לדוגמה custom-embedding-model. מזהה המודל הזה משמש כהפניה למטא-נתונים שנקודת הקצה של המודל צריכה כדי ליצור הטמעות או להפעיל חיזויים.
    • ‫REQUEST_URL: חובה. נקודת הקצה הספציפית למודל כשמוסיפים הטמעת טקסט בהתאמה אישית ונקודות קצה של מודל גנרי – לדוגמה, https://cymbal.com/models/text/embeddings/v1. מוודאים שאפשר לגשת לנקודת הקצה של המודל דרך כתובת IP פנימית. בניהול נקודות הקצה של המודל אין תמיכה בכתובות IP ציבוריות.
    • ‫MODEL_QUALIFIED_NAME: נדרש אם נקודת הקצה של המודל משתמשת בשם מלא. השם המלא, אם לנקודת הקצה של המודל יש כמה גרסאות.
    • ‫SECRET_ID: מזהה הסוד שבו השתמשתם קודם בתהליך google_ml.create_sm_secret().

מודל מולטי-מודאלי עם תמיכה מובנית

שילוב עם Vertex AI והתקנת התוסף

  1. להגדיר את הגישה של המשתמשים למודלים של Agent Platform.
  2. מוודאים שמותקנת הגרסה העדכנית של google_ml_integration.

    1. כדי לבדוק את הגרסה המותקנת, מריצים את הפקודה הבאה:

      SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
extversion 
------------
1.5.2
(1 row)

    2. אם התוסף לא מותקן או שהגרסה המותקנת היא גרסה קודמת ל-1.5.2, צריך לעדכן את התוסף.

      CREATE EXTENSION IF NOT EXISTS google_ml_integration;
ALTER EXTENSION google_ml_integration UPDATE;

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

  3. כדי להשתמש בפונקציונליות של מנוע השאילתות של AlloyDB AI, מגדירים את הדגל google_ml_integration.enable_ai_query_engine לערך on.

    SQL

    1. הפעלת מנוע השאילתות מבוסס ה-AI לסשן הנוכחי.
      SET google_ml_integration.enable_ai_query_engine = on;
    2. הפעלת תכונות במסד נתונים ספציפי בכל הסשנים.
      ALTER DATABASE DATABASE_NAME SET google_ml_integration.enable_ai_query_engine = 'on';
    3. להפעיל את מנוע השאילתות מבוסס ה-AI למשתמש ספציפי בכל הסשנים ומסדי הנתונים.
      ALTER ROLE postgres SET google_ml_integration.enable_ai_query_engine = 'on';

    המסוף

    כדי לשנות את הערך של הדגל google_ml_integration.enable_ai_query_engine, פועלים לפי השלבים שמפורטים במאמר הגדרת דגלים לניהול מסד נתונים של מכונה.

    gcloud

    כדי להשתמש ב-CLI של gcloud, אתם יכולים להתקין ולהפעיל את Google Cloud CLI או להשתמש ב-Cloud Shell.

    אפשר לשנות את הערך של הדגל google_ml_integration.enable_ai_query_engine. מידע נוסף זמין במאמר הגדרת דגלים לניהול מסד נתונים של מכונה. 

    gcloud alloydb instances update INSTANCE_ID \
  --database-flags google_ml_integration.enable_ai_query_engine=on \
  --region=REGION_ID \
  --cluster=CLUSTER_ID \
  --project=PROJECT_ID

קריאה למודל כדי ליצור הטמעות מולטי-מודאליות

מכיוון שהכלי לניהול נקודות קצה של מודלים מספק תמיכה מובנית במודל multimodalembedding@001 של Vertex AI, אתם יכולים לקרוא ישירות למודל כדי ליצור הטמעות מולטי-מודאליות.

בדוגמה הבאה, שם המודל המלא multimodalembedding@001 משמש כמזהה המודל ליצירת הטמעות של תמונות מולטי-מודאליות:

  1. מתחברים למסד הנתונים באמצעות psql.
  2. מגדירים את התוסף google_ml_integration.

  3. יוצרים הטמעות של תמונות מולטי-מודאליות:

    SELECT
  ai.image_embedding(
    model_id => 'multimodalembedding@001',
    image => 'IMAGE_PATH_OR_TEXT',
    mimetype => 'MIMETYPE');

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

  • ‫IMAGE_PATH_OR_TEXT: הנתיב ב-Cloud Storage לתמונה – לדוגמה, gs://cymbal_user_data/image-85097193-cd9788aacebb.jpeg – כדי לתרגם להטמעת וקטורים, או מחרוזת base64 של התמונה.

  • ‫MIMETYPE: סוג ה-MIME של התמונה.

מודלים של דירוג

מודלים לדירוג ב-Vertex AI

אתם יכולים להשתמש במודלים של Vertex AI שמוזכרים בקטע מודלים נתמכים בלי להירשם.

במאמר דירוג תוצאות החיפוש מוסבר איך לדרג את תוצאות החיפוש באמצעות מודל דירוג של Agent Platform.

רישום מודל דירוג של צד שלישי

בדוגמה הבאה מוסבר איך לרשום מודל דירוג מחדש מ-Cohere.

CREATE OR REPLACE FUNCTION cohere_rerank_input_transform(
    model_id VARCHAR(100),
    search_string TEXT,
    documents TEXT[],
    top_n INT DEFAULT NULL
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
DECLARE
  transformed_input JSONB;
BEGIN
  -- Basic Input Validation
  IF search_string IS NULL OR search_string = '' THEN
    RAISE EXCEPTION 'Invalid input: search_string cannot be NULL or empty.';
  END IF;

  IF documents IS NULL OR array_length(documents, 1) IS NULL OR array_length(documents, 1) = 0 THEN
    RAISE EXCEPTION 'Invalid input: documents array cannot be NULL or empty.';
  END IF;

  IF top_n IS NOT NULL AND top_n < 0 THEN
    RAISE EXCEPTION 'Invalid input: top_n must be greater than or equal to zero. Provided value: %', top_n;
  END IF;

  -- Construct the base JSON payload for Cohere Rerank API
  transformed_input := jsonb_build_object(
    'model', google_ml.model_qualified_name_of(model_id),
    'query', search_string,
    'documents', to_jsonb(documents), -- Convert TEXT[] directly to JSON array
    'return_documents', false -- Explicitly set to false (optional, as its default)
  );

  -- Add top_n to the payload only if it's provided and valid
  IF top_n IS NOT NULL THEN
     transformed_input := transformed_input || jsonb_build_object('top_n', top_n);
  END IF;

  -- Return the final JSON payload
  RETURN transformed_input::JSON;

END;
$$;

CREATE OR REPLACE FUNCTION cohere_rerank_output_transform(
    model_id VARCHAR(100),
    response_json JSON
)
RETURNS TABLE (index INT, score REAL)
LANGUAGE plpgsql
AS $$
DECLARE
  result_item JSONB;
  response_jsonb JSONB;
  cohere_index INT; -- 0-based index from Cohere response
BEGIN
  -- Validate response_json
  IF response_json IS NULL THEN
    RAISE EXCEPTION 'Invalid model response: response cannot be NULL.';
  END IF;

  -- Convert JSON to JSONB for easier processing
  response_jsonb := response_json::JSONB;

  -- Check top-level structure
  IF jsonb_typeof(response_jsonb) != 'object' THEN
    RAISE EXCEPTION 'Invalid model response: response must be a JSON object. Found: %', jsonb_typeof(response_jsonb);
  END IF;

  -- Check for the 'results' array
  IF response_jsonb->'results' IS NULL OR jsonb_typeof(response_jsonb->'results') != 'array' THEN
    -- Check for potential Cohere error structure
    IF response_jsonb->'message' IS NOT NULL THEN
       RAISE EXCEPTION 'Cohere API Error: %', response_jsonb->>'message';
    ELSE
       RAISE EXCEPTION 'Invalid model response: response does not contain a valid "results" array.';
    END IF;
  END IF;

  -- Loop through the 'results' array (JSONB array indices are 0-based)
  FOR i IN 0..jsonb_array_length(response_jsonb->'results') - 1 LOOP
    result_item := response_jsonb->'results'->i;

    -- Validate individual result item structure
    IF result_item IS NULL OR jsonb_typeof(result_item) != 'object' THEN
      RAISE WARNING 'Skipping invalid result item at array index %.', i;
      CONTINUE;
    END IF;

    IF result_item->'index' IS NULL OR jsonb_typeof(result_item->'index') != 'number' THEN
       RAISE WARNING 'Missing or invalid "index" field in result item at array index %.', i;
       CONTINUE;
    END IF;

    IF result_item->'relevance_score' IS NULL OR jsonb_typeof(result_item->'relevance_score') != 'number' THEN
       RAISE WARNING 'Missing or invalid "relevance_score" field in result item at array index %.', i;
       CONTINUE;
    END IF;

    -- Extract values
    BEGIN
      cohere_index := (result_item->>'index')::INT;
      -- Assign values to the output table columns
      -- Cohere returns 0-based index, map it to 1-based for consistency
      -- with input document array position
      index := cohere_index + 1;
      score := (result_item->>'relevance_score')::REAL;
      RETURN NEXT; -- Return the current row
    EXCEPTION WHEN others THEN
      RAISE WARNING 'Error processing result item at array index %: %', i, SQLERRM;
      CONTINUE; -- Skip this item and continue with the next
    END;
  END LOOP;

  RETURN; -- End of function
END;
$$;

CALL
  google_ml.create_sm_secret(
    '<SECRET_ID>',
    'projects/<PROJECT_NUMBER>/secrets/<SECRET_ID>/versions/latest');

CALL
  google_ml.create_model(
    model_id => 'cohere-reranker',
    model_type => 'reranking',
    model_provider => 'custom',
    model_request_url => 'https://api.cohere.com/v2/rerank',
    model_qualified_name => 'rerank-v3.5',
    model_auth_type => 'secret_manager',
    model_auth_id => '<SECRET_ID>',
    model_in_transform_fn => 'cohere_rerank_input_transform',
    model_out_transform_fn => 'cohere_rerank_output_transform'
  );

מודלים גנריים

בקטע הזה מוסבר איך לרשום נקודת קצה (endpoint) של מודל גנרי שזמינה אצל ספק מודלים, כמו Hugging Face, ‏ OpenAI, ‏ Agent Platform, ‏ Anthropic או כל ספק אחר. בקטע הזה מוצגות דוגמאות לרישום של נקודת קצה של מודל כללי שמתארח ב-Hugging Face, מודל Gemini כללי מ-Agent Platform Model Garden ונקודת הקצה של המודל claude-haiku.

אפשר לרשום כל נקודת קצה (endpoint) של מודל גנרי, כל עוד הקלט והפלט הם בפורמט JSON. בהתאם למטא-נתונים של נקודת הקצה של המודל, יכול להיות שתצטרכו ליצור כותרות HTTP או להגדיר כתובות URL של בקשות.

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

מודלים גנריים של Gemini

בקטע הזה מוסבר איך לרשום מודלים גנריים של Gemini.

מודל gemini-3.5-flash

ב-AlloyDB יש מודלים של Gemini שרשומים מראש ומוכנים לשימוש. עם זאת, יכול להיות שדגמים חדשים יותר לא יירשמו כברירת מחדל. כדי לרשום מודלים חדשים של Gemini כשהם יהיו זמינים, צריך לבצע את השלבים הבאים:

בדוגמה הבאה משתמשים בנקודת הקצה של המודל gemini-3.5-flash:generateContent מ-Model Garden.

  1. מתחברים למסד הנתונים באמצעות psql.
  2. מגדירים את התוסף google_ml_integration.

  3. רושמים את המודל:

    CALL google_ml.create_model(
  model_id             => 'gemini-3.5-flash:generateContent',
  model_request_url    => 'https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent',
  model_qualified_name => 'gemini-3.5-flash',
  model_provider       => 'google',
  model_type           => 'llm',
  model_auth_type      => 'alloydb_service_agent_iam'
);

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

  4. מפעילים חיזויים באמצעות מזהה המודל הרשום:

    SELECT
  google_ml.predict_row(
    model_id     => 'gemini-3.5-flash:generateContent',
    request_body => '{
      "contents": [
        {
          "role": "user",
          "parts": [
            {
              "text": "For TPCH database schema as mentioned here https://www.tpc.org/TPC_Documents_Current_Versions/pdf/TPC-H_v3.0.1.pdf , generate a SQL query to find all supplier names that are located in India."
            }
          ]
        }
      ]
    }'
  ) -> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 ->> 'text' AS response;

מודל כללי ב-Hugging Face

בדוגמה הבאה מוסיפים את נקודת הקצה של מודל מסווג התוכן המותאם אישית facebook/bart-large-mnli שמתארח ב-Hugging Face.

  1. מתחברים למסד הנתונים באמצעות psql.

  2. מגדירים את התוסף google_ml_integration.

  3. מוסיפים את טוקן ה-API של Hugging Face כסוד ל-Secret Manager לצורך אימות.

  4. קוראים לסוד ששמור ב-Secret Manager:

    CALL
  google_ml.create_sm_secret(
    secret_id => 'SECRET_ID',
    secret_path => 'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

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

    • ‫SECRET_ID: מזהה הסוד שהגדרתם, שמשמש לאחר מכן לרישום נקודת קצה של מודל.
    • ‫SECRET_MANAGER_SECRET_ID: מזהה הסוד שהוגדר ב-Secret Manager כשיצרתם את הסוד.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫VERSION_NUMBER: מספר הגרסה של מזהה הסוד.

  5. מפעילים את הפונקציה ליצירת מודל כדי לרשום את נקודת הקצה של המודל facebook/bart-large-mnli:

    CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_provider => 'hugging_face',
    model_request_url => 'REQUEST_URL',
    model_qualified_name => 'MODEL_QUALIFIED_NAME',
    model_auth_type => 'secret_manager',
    model_auth_id => 'SECRET_ID');

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

    • ‫MODEL_ID: מזהה ייחודי לנקודת הקצה של המודל שאתם מגדירים, לדוגמה custom-classification-model. מזהה המודל הזה משמש כהפניה למטא-נתונים שנקודת הקצה של המודל צריכה כדי ליצור הטמעות או להפעיל חיזויים.
    • ‫REQUEST_URL: נקודת הקצה הספציפית למודל כשמוסיפים הטמעת טקסט בהתאמה אישית ונקודות קצה של מודל גנרי, לדוגמה https://api-inference.huggingface.co/models/facebook/bart-large-mnli.
    • ‫MODEL_QUALIFIED_NAME: השם המלא של גרסת נקודת הקצה של המודל, לדוגמה facebook/bart-large-mnli.
    • ‫SECRET_ID: מזהה הסוד שבו השתמשתם קודם בתהליך google_ml.create_sm_secret().

מודל כללי של Anthropic

בדוגמה הבאה מוסיפים את נקודת הקצה של המודל claude-3-opus-20240229. כדי לרשום מודלים של Anthropic, צריך להשתמש בפונקציית הכותרת של ניהול נקודות הקצה של המודלים.

  1. מתחברים למסד הנתונים באמצעות psql.

  2. יוצרים ומפעילים את התוסף google_ml_integration.

    Secret Manager

    1. מוסיפים את הטוקן למוכ"ז כסוד ל-Secret Manager לצורך אימות.

    2. קוראים לסוד ששמור ב-Secret Manager:

      CALL
  google_ml.create_sm_secret(
    secret_id => 'SECRET_ID',
    secret_path => 'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

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

      • ‫SECRET_ID: מזהה הסוד שהגדרתם, שמשמש לאחר מכן לרישום נקודת קצה של מודל.
      • ‫SECRET_MANAGER_SECRET_ID: מזהה הסוד שהוגדר ב-Secret Manager כשיצרתם את הסוד.
      • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
      • ‫VERSION_NUMBER: מספר הגרסה של מזהה הסוד.

    3. מפעילים את הפונקציה ליצירת מודל כדי לרשום את נקודת הקצה של המודל claude-3-opus-20240229.

      CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_provider => 'anthropic',
    model_request_url => 'REQUEST_URL',
    model_auth_type => 'secret_manager',
    model_auth_id => 'SECRET_ID',
    generate_headers_fn => 'google_ml.anthropic_claude_header_gen_fn');

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

      • ‫MODEL_ID: מזהה ייחודי לנקודת הקצה של המודל שאתם מגדירים, לדוגמה anthropic-opus. מזהה המודל הזה משמש כהפניה למטא-נתונים שנקודת הקצה של המודל צריכה כדי ליצור הטמעות או להפעיל חיזויים.
      • ‫REQUEST_URL: נקודת הקצה הספציפית למודל כשמוסיפים הטמעת טקסט בהתאמה אישית ונקודות קצה של מודל גנרי, לדוגמה https://api.anthropic.com/v1/messages.

    כותרת אימות

    1. משתמשים בפונקציה שמוגדרת כברירת מחדל ליצירת שורות כותרת ב-google_ml.anthropic_claude_header_gen_fn או יוצרים פונקציה ליצירת שורות כותרת.

        CREATE OR REPLACE FUNCTION anthropic_sample_header_gen_fn(model_id VARCHAR(100), request_body JSON)
  RETURNS JSON
  LANGUAGE plpgsql
  AS $$
  #variable_conflict use_variable
  BEGIN
        RETURN json_build_object('x-api-key', 'ANTHROPIC_API_KEY', 'anthropic-version', 'ANTHROPIC_VERSION')::JSON;
  END;
  $$;

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

      • ‫ANTHROPIC_API_KEY: מפתח ה-API של Anthropic.
      • ‫ANTHROPIC_VERSION (אופציונלי): גרסת המודל הספציפית שבה רוצים להשתמש, לדוגמה 2023-06-01.

    2. מפעילים את הפונקציה ליצירת מודל כדי לרשום את נקודת הקצה של המודל claude-3-opus-20240229.

      CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_provider => 'anthropic',
    model_request_url => 'REQUEST_URL',
    generate_headers_fn => 'google_ml.anthropic_claude_header_gen_fn');

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

      • ‫MODEL_ID: מזהה ייחודי לנקודת הקצה של המודל שאתם מגדירים, לדוגמה anthropic-opus. מזהה המודל הזה משמש כהפניה למטא-נתונים שנקודת הקצה של המודל צריכה כדי ליצור הטמעות או להפעיל חיזויים.
      • ‫REQUEST_URL: נקודת הקצה הספציפית למודל כשמוסיפים הטמעת טקסט בהתאמה אישית ונקודות קצה של מודל גנרי, לדוגמה https://api.anthropic.com/v1/messages.

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

מודלים של תחזיות

בנוסף למודלים כלליים, אתם יכולים לרשום מודלים לחיזוי מ-Model Garden.

חיזוי סדרות זמנים באמצעות מודל TimesFM

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

כדי לפרוס ולרשום את המודל:

  1. פורסים את המודל TimesFM מ-Model Garden לנקודת קצה של Agent Platform כדי לקבל כתובת URL של בקשת מודל שנגישה לכולם. מידע נוסף זמין במאמר פריסת מודלים של Model Garden בנקודת קצה של Agent Platform.

  2. כדי לרשום את מודל TimesFM שנפרס ב-AlloyDB, משתמשים בפונקציה google_ml.create_model. כדי לחזות סדרות זמנים, הערך של model_type צריך להיות ts_forecasting:

CALL
google_ml.create_model(
  model_id => 'vertex_timesfm',
  model_qualified_name => 'timesfm_v2',
  model_type => 'ts_forecasting',
  model_provider => 'google',
  model_request_url => 'https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/endpoints/ENDPOINT_ID:predict',
  model_auth_type => 'alloydb_service_agent_iam'
);

אחרי שרושמים את המודל, אפשר להשתמש בפונקציה ai.forecast() או google_ml.forecast() כדי ליצור חיזויים.

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