במאמר הזה מתוארת גרסה 17.5.0 של AlloyDB Omni באמצעות אפשרות הפריסה containers. בוחרים אפשרות פריסה אחרת.

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

בחירת גרסה של מאמר העזרה:

בדף הזה מפורטים פרמטרים של פונקציות שונות שזמינות בתוסף 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, צריך לציין `https` כתובת URL. כתובת ה-URL של הבקשה שהפונקציה יוצרת עבור נקודות קצה של מודלים מובנים מתייחסת לפרויקט ולאזור או למיקום של האשכול. אם רוצים להתייחס לפרויקט אחר, צריך לציין את `model_request_url` במפורש. רשימה של כתובות URL של בקשות לנקודות קצה של מודלים ב-Vertex AI זמינה במאמר כתובות URL של בקשות לנקודות קצה של מודלים ב-Vertex AI. בנקודות קצה של מודלים בהתאמה אישית שמתארחים בשרת, מוודאים שאפשר לגשת לנקודת הקצה של המודל מהרשת שבה ממוקם AlloyDB.
`PROVIDER_ID`	נדרש לנקודות קצה של מודלים להטמעת טקסט עם תמיכה מובנית	הספק של נקודת הקצה של המודל. ערך ברירת המחדל הוא `custom`. אפשר להגדיר את הערך לאחת מהאפשרויות הבאות: ‫`google` לנקודות קצה של מודלים ב-Vertex AI ‫`open_ai` עבור נקודות קצה של מודלים של OpenAI ‫`hugging_face` לנקודות קצה של מודלים של Hugging Face ‫`anthropic` לנקודות קצה של מודלים של Anthropic `custom` לספקים אחרים
`MODEL_TYPE`	אופציונלי לנקודות קצה של מודלים גנריים	סוג המודל. מוגדר לאחת מהאפשרויות הבאות: ‫`text_embedding` לנקודות קצה של מודלים להטמעת טקסט ‫`generic` לכל שאר נקודות הקצה של המודלים
`MODEL_QUALIFIED_NAME`	נדרש למודלים של הטמעת טקסט עם תמיכה מובנית; אופציונלי לנקודות קצה אחרות של מודלים	השם המלא של מודלים להטמעת טקסט עם תמיכה מובנית. לשמות מלאים שצריך להשתמש בהם במודלים שעברו רישום מראש ב-Vertex AI, אפשר לעיין במאמר בנושא מודלים שעברו רישום מראש ב-Vertex AI. לשמות מלאים שצריך להשתמש בהם במודלים של OpenAI עם תמיכה מובנית, אפשר לעיין במאמר בנושא מודלים עם תמיכה מובנית.
`AUTH_TYPE`	אופציונלי, אלא אם לנקודת הקצה של המודל יש דרישת אימות ספציפית	סוג האימות שבו נעשה שימוש בנקודת הקצה של המודל. אפשר להגדיר את זה ל-`alloydb_service_agent_iam` עבור מודלים של Vertex AI או ל-`secret_manager` עבור ספקים אחרים, אם הם משתמשים ב-Secret Manager לאימות. אין צורך להגדיר את הערך הזה אם משתמשים בכותרות אימות.
`AUTH_ID`	לא מגדירים לנקודות קצה של מודלים ב-Vertex AI; נדרש לכל נקודות הקצה האחרות של מודלים שמאחסנים סודות ב-Secret Manager	מזהה הסוד שהגדרתם, שמשמש בהמשך לרישום של נקודת קצה של מודל.
`GENERATE_HEADER_FUNCTION`	אופציונלי	השם של הפונקציה שיוצרת כותרות בהתאמה אישית. ‫ במודלים של Anthropic, ניהול נקודות הקצה של המודלים מספק פונקציה `google_ml.anthropic_claude_header_gen_fn` שאפשר להשתמש בה לגרסאות ברירת מחדל. החתימה של הפונקציה הזו תלויה בפונקציית החיזוי שבה משתמשים. ראו פונקציה ליצירת כותרות.
`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 שמכיל את הסוד.
`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');

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

פונקציית `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 ליצירת הטמעות טקסט זמינות במאמר דוגמאות לפונקציות המרה ל-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 שרשומים מראש ומודלים עם תמיכה מובנית. מידע נוסף על סוגי מודלים שונים זמין במאמר סוג מודל.

מודלים שנרשמו מראש ב-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

שם המודל	סוג המודל
`text-embedding-gecko@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`

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

מודלים

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

google_ml.alter_model()

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

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

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

סודות

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

מודל הטמעה

מודל גנרי

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

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

מודלים שנרשמו מראש ב-Vertex AI

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

Vertex AI

OpenAI

Anthropic

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

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

`google_ml.alter_model()`

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

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

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

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

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

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

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

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