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

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

מודלים

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

mysql.ml_create_model_registration()

כך משתמשים בפונקציה mysql.ml_create_model_registration() כדי לרשום את המטא-נתונים של נקודת הקצה של המודל:

  CALL
    mysql.ml_create_model_registration(
      'MODEL_ID',
      'REQUEST_URL',
      'PROVIDER_ID',
      'MODEL_TYPE',
      'MODEL_QUALIFIED_NAME',
      'AUTH_TYPE',
      'AUTH_ID',
      'GENERATE_HEADER_FUNCTION',
      'INPUT_TRANSFORM_FUNCTION',
      'OUTPUT_TRANSFORM_FUNCTION');

mysql.ml_alter_model_registration()

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

    CALL
    mysql.ml_alter_model_registration(
      'MODEL_ID',
      'REQUEST_URL',
      'PROVIDER_ID',
      'MODEL_TYPE',
      'MODEL_QUALIFIED_NAME',
      'AUTH_TYPE',
      'AUTH_ID',
      'GENERATE_HEADER_FUNCTION',
      'INPUT_TRANSFORM_FUNCTION',
      'OUTPUT_TRANSFORM_FUNCTION');

mysql.ml_drop_model_registration()

כך מפעילים את הפונקציה mysql.ml_drop_model_registration() ב-SQL כדי להסיר נקודת קצה של מודל:

  CALL mysql.ml_drop_model_registration('MODEL_ID');

mysql.ml_list_registered_model()

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

  SELECT mysql.ml_list_registered_model('MODEL_ID');

mysql.cloudsql_ml_models

כך שולחים שאילתה לטבלה mysql.cloudsql_ml_models כדי להציג את פרטי נקודות הקצה של כל המודלים:

  SELECT * FROM mysql.cloudsql_ml_models;

סודות

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

mysql.ml_create_sm_secret_registration()

כך מפעילים את פונקציית ה-SQL‏ mysql.ml_create_sm_secret_registration() שמשמשת להוספת הסוד שנוצר ב-Secret Manager:

    CALL
    mysql.ml_create_sm_secret_registration(
      'SECRET_ID',
      'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

mysql.ml_alter_sm_secret_registration()

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

  CALL
    mysql.ml_alter_sm_secret_registration(
      'SECRET_ID',
      'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

mysql.ml_drop_sm_secret_registration()

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

  CALL mysql.ml_drop_sm_secret_registration('SECRET_ID');

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

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

mysql.ml_embedding()

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

SELECT
  mysql.ml_embedding(
    'MODEL_ID',
    'CONTENT');

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

mysql.ml_predict_row()

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

SELECT
  mysql.ml_predict_row(
    'MODEL_ID',
    'REQUEST_BODY');

בקטע דוגמאות מופיעות דוגמאות לשאילתות SQL להפעלת חיזויים.

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

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

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

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

  CREATE FUNCTION IF NOT EXISTS
  INPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), input_text TEXT) RETURNS JSON DETERMINISTIC;

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

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

  CREATE FUNCTION IF NOT EXISTS
  OUTPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), response_json JSON) RETURNS BLOB DETERMINISTIC;

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

כדי להבין טוב יותר איך ליצור פונקציות טרנספורמציה לנקודת הקצה של המודל, נבחן נקודת קצה של מודל הטמעת טקסט שמתארח בצד הלקוח, שדורש קלט ופלט בפורמט 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. בשדה הזה אפשר להזין מערך של קלטים. ‫mysql.ml_embedding() היא פונקציה ברמת השורה, ולכן היא מצפה לקבל קלט טקסט אחד בכל פעם. לכן צריך ליצור פונקציית טרנספורמציה של קלט שיוצרת מערך עם רכיב אחד.

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

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

DELIMITER $$
CREATE FUNCTION IF NOT EXISTS cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
DETERMINISTIC

BEGIN
  RETURN JSON_OBJECT('prompt', JSON_ARRAY(input_text));
END $$

CREATE FUNCTION IF NOT EXISTS cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON)
RETURNS BLOB
DETERMINISTIC

BEGIN
  RETURN STRING_TO_VECTOR(
         JSON_EXTRACT(
              content,
              '$.predictions[0].embeddings.values'
            )
    );

END $$
DELIMITER ;

Default included transform functions

Model Endpoint Management provides in-built support for two common text embedding model families, Google's Gemini embedding models and OpenAI's text embedding models. The input and output transforms are preloaded when these models are registered, for convenience. They can be overwritten by specifying your own transform functions during registration, or by calling mysql.ml_alter_model_registration().

HTTP header generation function

The following shows signature for the header generation function that can be used with the `mysql.ml_embedding()` prediction function when registering other text embedding model endpoints.

  CREATE FUNCTION IF NOT EXISTS GENERATE_HEADERS(model_id VARCHAR(100), input_text TEXT) RETURNS JSON DETERMINISTIC;

For the mysql.ml_predict_row() prediction function, the signature is as follows:

CREATE FUNCTION IF NOT EXISTS GENERATE_HEADERS(model_id TEXT, input JSON) RETURNS JSON DETERMINISTIC;

Header generation function example

To better understand how to create a function that generates output in JSON key value pairs that are used as HTTP headers, consider a custom-hosted text embedding model endpoint.

The following example curl request passes the version HTTP header, which is used by the model endpoint:

  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"]}'

The model expects text input through the version field and returns the version value in JSON format. The following example shows the header generation function that is used for this text embedding model endpoint when it is registered with model endpoint management:

DELIMITER $$
CREATE FUNCTION IF NOT EXISTS header_gen_fn(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
DETERMINISTIC
BEGIN
  RETURN JSON_OBJECT('version', '2024-01-01');
END;
$$
DELIMITER ;