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

בוחרים גרסת תיעוד:

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

כדי להתחיל להשתמש בתוסף, צריך להגדיר את דגל מסד הנתונים google_ml_integration.enable_model_support לערך on.

מידע נוסף זמין במאמר בנושא שימוש בניהול נקודות קצה של מודלים עם AlloyDB Omni למודלים של AI.

מודלים

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

פונקציית google_ml.create_model()

בדוגמה הבאה מוצג איך להפעיל את פונקציית ה-SQL‏ google_ml.create_model() שמשמשת לרישום מטא-נתונים של נקודת קצה של מודל:

  CALL
    google_ml.create_model(
      model_id => 'MODEL_ID',
      model_request_url => 'REQUEST_URL',
      model_provider => 'PROVIDER_ID',
      model_type => 'MODEL_TYPE',
      model_qualified_name => 'MODEL_QUALIFIED_NAME',
      model_auth_type => 'AUTH_TYPE',
      model_auth_id => 'AUTH_ID',
      generate_headers_fn => 'GENERATE_HEADER_FUNCTION',
      model_in_transform_fn => 'INPUT_TRANSFORM_FUNCTION',
      model_out_transform_fn => 'OUTPUT_TRANSFORM_FUNCTION');
פרמטר חובה תיאור
MODEL_ID חובה לכל נקודות הקצה של המודל מזהה ייחודי לנקודת הקצה של המודל שאתם מגדירים.
REQUEST_URL אופציונלי לנקודות קצה אחרות של מודלים להטמעת טקסט עם תמיכה מובנית נקודת הקצה הספציפית למודל כשמוסיפים הטמעת טקסט אחרת ונקודות קצה של מודלים גנריים. ב-AlloyDB ל-PostgreSQL, צריך לציין כתובת URL של https.

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

רשימה של כתובות URL של בקשות לנקודות קצה של מודלי AI ב-Vertex AI זמינה במאמר כתובות URL של בקשות לנקודות קצה של מודלי AI ב-Vertex AI.‫

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

צריך להגדיר אחד מהערכים הבאים:
  • ‫google לנקודות קצה של מודלי AI ב-Vertex AI
  • ‫open_ai עבור נקודות קצה של מודלים של OpenAI
  • ‫hugging_face לנקודות קצה של מודלים ב-Hugging Face
  • ‫anthropic לנקודות קצה של מודלים של Anthropic
  • ‫custom לספקים אחרים
MODEL_TYPE אופציונלי לנקודות קצה של מודלים גנריים סוג המודל.

מגדירים אחת מהאפשרויות הבאות:
  • ‫text_embedding לנקודות קצה של מודלים להטמעת טקסט
  • ‫generic לכל שאר נקודות הקצה של המודל
MODEL_QUALIFIED_NAME חובה למודלים של הטמעת טקסט עם תמיכה מובנית; אופציונלי לנקודות קצה אחרות של מודלים השם המלא של מודלים להטמעת טקסט עם תמיכה מובנית.

לשמות מלאים של Vertex AI שצריך להשתמש בהם במודלים שרשומים מראש, אפשר לעיין בכתובת ה-URL של בקשת נקודות הקצה של מודלים ב-Vertex AI.

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

אפשר להגדיר את המאפיין לערך alloydb_service_agent_iam למודלים של Vertex AI או לערך secret_manager לספקים אחרים, אם הם משתמשים ב-Secret Manager לאימות.

לא צריך להגדיר את הערך הזה אם משתמשים בכותרות אימות.
AUTH_ID אין להגדיר עבור נקודות קצה של מודלי AI ב-Vertex AI. נדרש לכל נקודות הקצה האחרות של מודלי AI שמאחסנות סודות ב-Secret Manager מזהה הסוד שהגדרתם, שמשמש לאחר מכן לרישום נקודת קצה של מודל.
GENERATE_HEADER_FUNCTION אופציונלי שם הפונקציה שיוצרת כותרות בהתאמה אישית.

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

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

google_ml.alter_model()

כך מפעילים את הפונקציה google_ml.alter_model() ב-SQL כדי לעדכן את המטא-נתונים של נקודת הקצה של המודל:

    CALL
    google_ml.alter_model(
      model_id => 'MODEL_ID',
      model_request_url => 'REQUEST_URL',
      model_provider => 'PROVIDER_ID',
      model_type => 'MODEL_TYPE',
      model_qualified_name => 'MODEL_QUALIFIED_NAME',
      model_auth_type => 'AUTH_TYPE',
      model_auth_id => 'AUTH_ID',
      generate_headers_fn => 'GENERATE_HEADER_FUNCTION',
      model_in_transform_fn => 'INPUT_TRANSFORM_FUNCTION',
      model_out_transform_fn => 'OUTPUT_TRANSFORM_FUNCTION');

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

פונקציית google_ml.drop_model()

בדוגמה הבאה מוצג איך להפעיל את פונקציית ה-SQL‏ google_ml.drop_model() שמשמשת להסרת נקודת קצה של מודל:

  CALL google_ml.drop_model('MODEL_ID');
פרמטר תיאור
MODEL_ID מזהה ייחודי לנקודת הקצה של המודל שהגדרתם.

פונקציית google_ml.list_model()

בדוגמה הבאה מוצג איך להפעיל את פונקציית ה-SQL‏ google_ml.list_model() שמשמשת לרישום פרטים של נקודת קצה של מודל:

  SELECT google_ml.list_model('MODEL_ID');
פרמטר תיאור
MODEL_ID מזהה ייחודי לנקודת הקצה של המודל שהגדרתם.

צפייה אחת (google_ml.model_info_view)

כך קוראים לתצוגה google_ml.model_info_view כדי להציג את המידע על כל נקודות הקצה של המודלים:

  SELECT * FROM google_ml.model_info_view;

סודות

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

פונקציית google_ml.create_sm_secret()

בדוגמה הבאה מוצג איך להפעיל את פונקציית ה-SQL‏ google_ml.create_sm_secret() שמשמשת להוספת הסוד שנוצר ב-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 מזהה הסוד שהגדרתם, שמשמש לאחר מכן לרישום נקודת קצה של מודל.
PROJECT_ID מזהה הפרויקט ב- Google Cloud שמכיל את הסוד.
SECRET_MANAGER_SECRET_ID מזהה הסוד שהוגדר ב-Secret Manager כשיצרתם את הסוד.
VERSION_NUMBER מספר הגרסה של המזהה הסודי.

פונקציית google_ml.alter_sm_secret()

כך מפעילים את הפונקציה google_ml.alter_sm_secret() ב-SQL כדי לעדכן את פרטי הסוד:

  CALL
    google_ml.alter_sm_secret(
      secret_id => 'SECRET_ID',
      secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

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

פונקציית google_ml.drop_sm_secret()

כך מפעילים את הפונקציה google_ml.drop_sm_secret() ב-SQL כדי למחוק סוד:

  CALL google_ml.drop_sm_secret('SECRET_ID');
פרמטר תיאור
SECRET_ID מזהה הסוד שהגדרתם ושימש לאחר מכן לרישום נקודת קצה של מודל.

פונקציות חיזוי

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

פונקציית google_ml.embedding()

כך יוצרים הטמעות:

SELECT
  google_ml.embedding(
    model_id => 'MODEL_ID',
    contents => 'CONTENT');
פרמטר תיאור
MODEL_ID מזהה ייחודי לנקודת הקצה של המודל שאתם מגדירים.
CONTENT הטקסט שרוצים לתרגם להטמעה בווקטור.

דוגמאות לשאילתות SQL ליצירת הטמעות טקסט מופיעות במאמר דוגמאות לפונקציות טרנספורמציה ל-AlloyDB Omni.

פונקציית google_ml.predict_row()

כך מפעילים חיזויים:

SELECT
  google_ml.predict_row(
    model_id => 'MODEL_ID',
    request_body => 'REQUEST_BODY');
פרמטר תיאור
MODEL_ID מזהה ייחודי לנקודת הקצה של המודל שאתם מגדירים.
REQUEST_BODY הפרמטרים של פונקציית החיזוי, בפורמט JSON.

דוגמאות לשאילתות SQL להפעלת תחזיות מפורטות במאמר דוגמאות ל-AlloyDB Omni.

פונקציות טרנספורמציה

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

פונקציית שינוי קלט

בהמשך מוצגת החתימה של פונקציית החיזוי לנקודות קצה של מודלים להטמעת טקסט:

  CREATE OR REPLACE FUNCTION INPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;
פרמטר תיאור
INPUT_TRANSFORM_FUNCTION הפונקציה שמשמשת להמרת הקלט של פונקציית החיזוי המתאימה לקלט הספציפי של נקודת הקצה של המודל.

פונקציית שינוי פלט

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

  CREATE OR REPLACE FUNCTION OUTPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), response_json JSON) RETURNS real[];
פרמטר תיאור
OUTPUT_TRANSFORM_FUNCTION הפונקציה שמשמשת להמרת הפלט הספציפי לנקודת הקצה של המודל לפלט של פונקציית החיזוי.

דוגמה לפונקציות של טרנספורמציה

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

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

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
    -H "Content-Type: application/json"
    -d '{"prompt": ["AlloyDB Embeddings"]}'

התגובה הבאה מוחזרת:

[[ 0.3522231  -0.35932037  0.10156056  0.17734447 -0.11606089 -0.17266059
   0.02509351  0.20305622 -0.09787305 -0.12154685 -0.17313677 -0.08075467
   0.06821183 -0.06896557  0.1171584  -0.00931572  0.11875633 -0.00077482
   0.25604948  0.0519384   0.2034983  -0.09952664  0.10347155 -0.11935943
  -0.17872004 -0.08706985 -0.07056875 -0.05929353  0.4177883  -0.14381726
   0.07934926  0.31368294  0.12543282  0.10758053 -0.30210832 -0.02951015
   0.3908268  -0.03091059  0.05302926 -0.00114946 -0.16233777  0.1117468
  -0.1315904   0.13947351 -0.29569918 -0.12330773 -0.04354299 -0.18068913
   0.14445548  0.19481727]]

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

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

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

בדוגמה הבאה מוצגות פונקציות הטרנספורמציה של הקלט והפלט שמשמשות את נקודת הקצה של המודל הזה כשהיא רשומה בניהול נקודות הקצה של המודלים:

פונקציית טרנספורמציה של קלט

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;
$$;

פונקציית טרנספורמציה של פלט

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;
$$;

פונקציה ליצירת שורות כותרת HTTP

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

  CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;

לפונקציית החיזוי google_ml.predict_row(), החתימה היא:

CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id TEXT, input JSON) RETURNS JSON;
פרמטר תיאור
GENERATE_HEADERS הפונקציה ליצירת כותרות בהתאמה אישית. אפשר גם להעביר את כותרת ההרשאה שנוצרה על ידי הפונקציה ליצירת שורות כותרת בזמן רישום נקודת הקצה של המודל.

דוגמה לפונקציה ליצירת שורות כותרת

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

בדוגמה הבאה של בקשת curl מועברת כותרת ה-HTTP‏ version שמשמשת את נקודת הקצה של המודל:

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
      -H "Content-Type: application/json" \
      -H "version: 2024-01-01" \
      -d '{"prompt": ["AlloyDB Embeddings"]}'

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

CREATE OR REPLACE FUNCTION header_gen_fn(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
BEGIN
  RETURN json_build_object('version', '2024-01-01')::JSON;
END;
$$;

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

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

מודל הטמעה

CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  input_text TEXT
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
BEGIN
  RETURN json_build_object('Authorization', 'API_KEY')::JSON;
END;
$$;

מחליפים את הערך API_KEY במפתח ה-API של ספק המודל.

מודל גנרי

CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  response_json JSON
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
DECLARE
transformed_output REAL[];
BEGIN
  -- code to add Auth token to API request
RETURN json_build_object('x-api-key', 'API_KEY', 'anthropic-version', '2023-06-01')::JSON;
END;
$$;

מחליפים את הערך API_KEY במפתח ה-API של ספק המודל.

יצירת כתובת URL של בקשה

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

CREATE OR REPLACE FUNCTION GENERATE_REQUEST_URL(provider google_ml.model_provider, model_type google_ml.MODEL_TYPE, model_qualified_name VARCHAR(100), model_region VARCHAR(100) DEFAULT NULL)
פרמטר תיאור
GENERATE_REQUEST_URL הפונקציה ליצירת כתובת URL של בקשה שנוצרת על ידי התוסף לנקודות קצה של מודלים עם תמיכה מובנית.

מודלים נתמכים

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

מודלי AI רשומים מראש של Vertex AI

סוג המודל מזהה המודל גרסת התוסף
generic
  • gemini-1.5-pro:streamGenerateContent
  • gemini-1.5-pro:generateContent
  • gemini-1.0-pro:generateContent
 גרסה 1.4.2 ואילך
text_embedding
  • textembedding-gecko
  • text-embedding-gecko@001
 גרסה 1.3 ואילך

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

Vertex AI

שם המודל המלא סוג המודל
gemini-embedding-001 text-embedding
text-embedding-gecko@003 text-embedding
text-embedding-004 text-embedding
text-embedding-005 text-embedding
text-embedding-preview-0815 text-embedding
text-multilingual-embedding-002 text-embedding

OpenAI

שם המודל המלא סוג המודל
text-embedding-ada-002 text-embedding
text-embedding-3-small text-embedding
text-embedding-3-large text-embedding

Anthropic

שם המודל המוסמך סוג המודל
claude-3-opus-20240229 generic
claude-3-sonnet-20240229 generic
claude-3-haiku-20240307 generic