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

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

מודלים

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

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

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

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

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

במקרה של נקודות קצה של מודלים בהתאמה אישית שמתארחים בשרת, צריך לוודא שנקודת הקצה של המודל נגישה דרך האינטרנט.
PROVIDER_ID נדרש לנקודות קצה של מודלים להטמעת טקסט עם תמיכה מובנית הספק של נקודת הקצה של המודל. ערך ברירת המחדל הוא custom. ב-Cloud SQL, מגדירים את הספק ל-google עבור נקודות קצה של מודלים של Vertex AI, ל-open_ai עבור נקודות קצה של מודלים של OpenAI, ל-anthropic עבור נקודות קצה של מודלים של Anthropic, ל-hugging_face עבור נקודות קצה של מודלים של Hugging Face או ל-custom עבור נקודות קצה של מודלים בהוסטינג בהתאמה אישית.
MODEL_TYPE אופציונלי לנקודות קצה של מודלים גנריים סוג המודל. אפשר להגדיר את הערך הזה כ-text_embedding עבור נקודות קצה של מודלים להטמעת טקסט, או כ-generic עבור כל נקודות הקצה של מודלים אחרים.
MODEL_QUALIFIED_NAME חובה לנקודות קצה של מודלים של OpenAI; אופציונלי לנקודות קצה של מודלים אחרים השם המוגדר במלואו אם לנקודת הקצה של המודל יש כמה גרסאות או אם היא מוגדרת על ידי נקודת הקצה של המודל – לדוגמה, textembedding-gecko@001 או textembedding-gecko@002. מכיוון שמודל textembedding-gecko@001 רשום מראש בניהול נקודות קצה של מודלים, אפשר ליצור הטמעות באמצעות textembedding-gecko@001 כמזהה המודל.
AUTH_TYPE אופציונלי, אלא אם לנקודת הקצה של המודל יש דרישת אימות ספציפית סוג האימות שבו נעשה שימוש בנקודת הקצה של המודל. אפשר להגדיר את האפשרות cloudsql_service_agent_iam למודלים של Vertex AI או secret_manager לספקים אחרים.
AUTH_ID לא מגדירים לנקודות קצה של מודלים ב-Vertex AI; נדרש לכל נקודות הקצה האחרות של מודלים שמאחסנים סודות ב-Secret Manager מזהה הסוד שהגדרתם, שמשמש בהמשך לרישום של נקודת קצה של מודל.
GENERATE_HEADER_FUNCTION אופציונלי שם הפונקציה שהגדרתם ליצירת כותרות בהתאמה אישית. החתימה של הפונקציה הזו תלויה בפונקציה google_ml.predict_row(). מידע נוסף זמין במאמר בנושא פונקציה ליצירת כותרת HTTP.
INPUT_TRANSFORM_FUNCTION אופציונלי לנקודות קצה של מודלים להטמעת טקסט עם תמיכה מובנית; לא מגדירים לנקודות קצה של מודלים גנריים הפונקציה להמרת קלט של פונקציית החיזוי המתאימה לקלט ספציפי למודל. ראו פונקציות טרנספורמציה.
OUTPUT_TRANSFORM_FUNCTION אופציונלי לנקודות קצה של מודלים להטמעת טקסט עם תמיכה מובנית; לא מגדירים לנקודות קצה של מודלים גנריים הפונקציה להמרת פלט ספציפי של מודל לפלט של פונקציית החיזוי. ראו פונקציות טרנספורמציה.

google_ml.alter_model()

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

    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 שמכיל את הסוד. הפרויקט הזה יכול להיות שונה מהפרויקט שמכיל את מופע Cloud SQL.
SECRET_MANAGER_SECRET_ID מזהה הסוד שהוגדר ב-Secret Manager כשנוצר הסוד.
VERSION_NUMBER מספר הגרסה של המזהה הסודי.

google_ml.alter_sm_secret()

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

  CALL
    google_ml.alter_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 שמכיל את הסוד. הפרויקט הזה יכול להיות שונה מהפרויקט שמכיל את מופע Cloud SQL.
SECRET_MANAGER_SECRET_ID מזהה הסוד שהוגדר ב-Secret Manager כשנוצר הסוד.
VERSION_NUMBER מספר הגרסה של המזהה הסודי.

google_ml.drop_sm_secret()

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

  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 ליצירת הטמעות טקסט זמינות במאמר דוגמאות.

google_ml.predict_row()

בדוגמה הבאה אפשר לראות איך מפעילים חיזויים:

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

דוגמאות לשאילתות SQL להפעלת תחזיות זמינות במאמר דוגמאות.

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

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

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

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

  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": ["Cloud SQL 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": ["Cloud SQL Embeddings"]}'

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

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

יצירת כתובת 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 לבקשה שנוצרת על ידי התוסף לנקודות קצה של מודלים עם תמיכה מובנית.