יצירת הטמעות טקסט באמצעות הפונקציה AI.GENERATE_EMBEDDING

במאמר הזה מוסבר איך ליצור מודל מרוחק ב-BigQuery ML שמפנה למודל הטמעה. אחר כך משתמשים במודל הזה עם הפונקציה AI.GENERATE_EMBEDDING כדי ליצור הטמעות טקסט באמצעות נתונים מטבלה רגילה ב-BigQuery.

אפשר להשתמש בסוגים הבאים של מודלים מרוחקים:

התפקידים הנדרשים

כדי ליצור מודל מרוחק ולהשתמש בפונקציה AI.GENERATE_EMBEDDING, צריך את התפקידים הבאים בממשק לניהול הזהויות והרשאות הגישה (IAM):

  • יצירה ושימוש במערכי נתונים, בטבלאות ובמודלים של BigQuery: התפקיד "עריכת נתונים ב-BigQuery" (roles/bigquery.dataEditor) בפרויקט.

  • יצירה, הקצאה ושימוש בחיבורים ל-BigQuery: התפקיד "אדמין של חיבורים ל-BigQuery" (roles/bigquery.connectionsAdmin) בפרויקט.

    אם לא הגדרתם חיבור כברירת מחדל, אתם יכולים ליצור ולהגדיר חיבור כחלק מהרצת ההצהרה CREATE MODEL. כדי לעשות את זה, צריך להיות לכם תפקיד אדמין ב-BigQuery (roles/bigquery.admin) בפרויקט. מידע נוסף זמין במאמר הגדרת החיבור שמוגדר כברירת מחדל.

  • נותנים הרשאות לחשבון השירות של החיבור: אדמין של IAM בפרויקט (roles/resourcemanager.projectIamAdmin) בפרויקט שמכיל את נקודת הקצה של Gemini Enterprise Agent Platform. זה הפרויקט הנוכחי של מודלים מרוחקים שיוצרים על ידי ציון שם המודל כנקודת קצה. זה הפרויקט שמזוהה בכתובת ה-URL של מודלים מרוחקים שאתם יוצרים על ידי ציון כתובת URL כנקודת קצה.

  • יצירת משימות ב-BigQuery: התפקיד "משתמש במשימות BigQuery" (roles/bigquery.jobUser) בפרויקט.

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

ההרשאות הנדרשות

  • יצירת מערך נתונים: bigquery.datasets.create
  • יצירה, הקצאה ושימוש בחיבור: bigquery.connections.*
  • מגדירים את ההרשאות של חשבון השירות: resourcemanager.projects.getIamPolicy ו-resourcemanager.projects.setIamPolicy
  • יוצרים מודל ומריצים הסקה:
    • bigquery.jobs.create
    • bigquery.models.create
    • bigquery.models.getData
    • bigquery.models.updateData
    • bigquery.models.updateMetadata
  • נתוני טבלת השאילתות: bigquery.tables.getData

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

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

  1. בדף לבחירת הפרויקט במסוף Google Cloud , בוחרים פרויקט ב- Google Cloud או יוצרים אותו.

    התפקידים שנדרשים כדי לבחור או ליצור פרויקט

    • בחירת פרויקט: כדי לבחור פרויקט לא נדרש תפקיד IAM ספציפי – אתם יכולים לבחור כל פרויקט שקיבלתם בו תפקיד.
    • יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד "יצירת פרויקטים" (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים?

    כניסה לדף לבחירת הפרויקט

  2. מוודאים שהחיוב מופעל בפרויקט ב- Google Cloud .

  3. מפעילים את ממשקי ה-API של BigQuery, של BigQuery Connection ושל Agent Platform API, אם הם עדיין לא מופעלים.

    התפקידים שנדרשים כדי להפעיל ממשקי API

    כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

    הפעלת ממשקי ה-API

יצירת קבוצת נתונים

יוצרים מערך נתונים ב-BigQuery שיכיל את המשאבים:

המסוף

  1. נכנסים לדף BigQuery במסוף Google Cloud .

    כניסה ל-BigQuery

  2. בחלונית השמאלית, לוחצים על Explorer:

    כפתור מודגש לחלונית Explorer.

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

  3. בחלונית Explorer, לוחצים על שם הפרויקט.

  4. לוחצים על View actions > Create dataset.

  5. בדף Create dataset, מבצעים את הפעולות הבאות:

    1. בשדה Dataset ID, מקלידים שם למערך הנתונים.

    2. בקטע Location type, בוחרים באפשרות Region או Multi-region.

      • אם בחרתם באפשרות Region, בוחרים מיקום מהרשימה Region.
      • אם בחרתם באפשרות מספר אזורים, בחרו באפשרות US או Europe מהרשימה מספר אזורים.

    3. לוחצים על Create dataset.

BQ

  1. כדי ליצור קבוצת נתונים חדשה, משתמשים בפקודה bq mk עם הדגל --location:

    bq --location=LOCATION mk -d DATASET_ID

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

    • ‫LOCATION: המיקום של מערך הנתונים.
    • ‫DATASET_ID: המזהה של מערך הנתונים שאתם יוצרים.

  2. מוודאים שמערך הנתונים נוצר:

    bq ls

יצירת חיבור

יוצרים קישור למשאבים ב-Cloud ומקבלים את חשבון השירות של הקישור. יוצרים את החיבור באותו מיקום של מערך הנתונים שיצרתם בשלב הקודם.

אם הגדרתם חיבור כברירת מחדל או שיש לכם את התפקיד אדמין ב-BigQuery, אתם יכולים לדלג על השלב הזה.

בוחרים באחת מהאפשרויות הבאות:

המסוף

  1. נכנסים לדף BigQuery.

    כניסה ל-BigQuery

  2. בחלונית הימנית, לוחצים על Explorer:

    כפתור מודגש לחלונית Explorer.

    אם החלונית הימנית לא מוצגת, לוחצים על Expand left pane כדי לפתוח אותה.

  3. בחלונית Explorer, מרחיבים את שם הפרויקט ולוחצים על Connections.

  4. בדף Connections, לוחצים על Create connection.

  5. בשדה Connection type, בוחרים באפשרות Vertex AI remote models, remote functions, BigLake and Spanner (Cloud Resource).

  6. בשדה מזהה החיבור, נותנים שם לחיבור.

  7. בשדה Location type, בוחרים מיקום לחיבור. החיבור צריך להיות באותו מיקום כמו המשאבים האחרים, למשל מערכי נתונים.

  8. לוחצים על יצירת חיבור.

  9. לוחצים על מעבר לחיבור.

  10. בחלונית Connection info, מעתיקים את מזהה חשבון השירות כדי להשתמש בו בשלב מאוחר יותר.

SQL

משתמשים בהצהרה CREATE CONNECTION:

  1. נכנסים לדף BigQuery במסוף Google Cloud .

    כניסה ל-BigQuery

  2. בעורך השאילתות, מזינים את ההצהרה הבאה:

    CREATE CONNECTION [IF NOT EXISTS] `CONNECTION_NAME`
OPTIONS (
  connection_type = "CLOUD_RESOURCE",
  friendly_name = "FRIENDLY_NAME",
  description = "DESCRIPTION"
  );

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

    • ‫CONNECTION_NAME: שם החיבור בפורמט PROJECT_ID.LOCATION.CONNECTION_ID,‏ LOCATION.CONNECTION_ID או CONNECTION_ID. אם לא מציינים את הפרויקט או המיקום, הם נגזרים מהפרויקט ומהמיקום שבהם ההצהרה מופעלת.
    • ‫FRIENDLY_NAME (אופציונלי): שם תיאורי לחיבור.
    • ‫DESCRIPTION (אופציונלי): תיאור של החיבור.

  3. לוחצים על הפעלה.

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

BQ

  1. בסביבה של שורת הפקודה, יוצרים חיבור:

    bq mk --connection --location=REGION --project_id=PROJECT_ID \
    --connection_type=CLOUD_RESOURCE CONNECTION_ID

    הפרמטר --project_id מבטל את פרויקט ברירת המחדל.

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

    • ‫REGION: אזור החיבור שלכם
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud
    • ‫CONNECTION_ID: מזהה לחיבור

    כשיוצרים משאב חיבור, BigQuery יוצר חשבון שירות ייחודי של המערכת ומשייך אותו לחיבור.

    פתרון בעיות: אם מופיעה שגיאת החיבור הבאה, עדכנו את Google Cloud SDK:

    Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...

  2. מאחזרים ומעתיקים את מזהה חשבון השירות כדי להשתמש בו בשלב מאוחר יותר:

    bq show --connection PROJECT_ID.REGION.CONNECTION_ID

    הפלט אמור להיראות כך:

    name                          properties
1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}

Python

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

כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח. 

import google.api_core.exceptions
from google.cloud import bigquery_connection_v1

client = bigquery_connection_v1.ConnectionServiceClient()


def create_connection(
    project_id: str,
    location: str,
    connection_id: str,
):
    """Creates a BigQuery connection to a Cloud Resource.

    Cloud Resource connection creates a service account which can then be
    granted access to other Google Cloud resources for federated queries.

    Args:
        project_id: The Google Cloud project ID.
        location: The location of the connection (for example, "us-central1").
        connection_id: The ID of the connection to create.
    """

    parent = client.common_location_path(project_id, location)

    connection = bigquery_connection_v1.Connection(
        friendly_name="Example Connection",
        description="A sample connection for a Cloud Resource.",
        cloud_resource=bigquery_connection_v1.CloudResourceProperties(),
    )

    try:
        created_connection = client.create_connection(
            parent=parent, connection_id=connection_id, connection=connection
        )
        print(f"Successfully created connection: {created_connection.name}")
        print(f"Friendly name: {created_connection.friendly_name}")
        print(
            f"Service Account: {created_connection.cloud_resource.service_account_id}"
        )

    except google.api_core.exceptions.AlreadyExists:
        print(f"Connection with ID '{connection_id}' already exists.")
        print("Please use a different connection ID.")
    except Exception as e:
        print(f"An unexpected error occurred while creating the connection: {e}")

Node.js

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

כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח. 

const {ConnectionServiceClient} =
  require('@google-cloud/bigquery-connection').v1;
const {status} = require('@grpc/grpc-js');

const client = new ConnectionServiceClient();

/**
 * Creates a new BigQuery connection to a Cloud Resource.
 *
 * A Cloud Resource connection creates a service account that can be granted access
 * to other Google Cloud resources.
 *
 * @param {string} projectId The Google Cloud project ID. for example, 'example-project-id'
 * @param {string} location The location of the project to create the connection in. for example, 'us-central1'
 * @param {string} connectionId The ID of the connection to create. for example, 'example-connection-id'
 */
async function createConnection(projectId, location, connectionId) {
  const parent = client.locationPath(projectId, location);

  const connection = {
    friendlyName: 'Example Connection',
    description: 'A sample connection for a Cloud Resource',
    // The service account for this cloudResource will be created by the API.
    // Its ID will be available in the response.
    cloudResource: {},
  };

  const request = {
    parent,
    connectionId,
    connection,
  };

  try {
    const [response] = await client.createConnection(request);

    console.log(`Successfully created connection: ${response.name}`);
    console.log(`Friendly name: ${response.friendlyName}`);

    console.log(`Service Account: ${response.cloudResource.serviceAccountId}`);
  } catch (err) {
    if (err.code === status.ALREADY_EXISTS) {
      console.log(`Connection '${connectionId}' already exists.`);
    } else {
      console.error(`Error creating connection: ${err.message}`);
    }
  }
}

Java

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

כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח. 

import com.google.api.gax.rpc.AlreadyExistsException;
import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.connection.v1.CloudResourceProperties;
import com.google.cloud.bigquery.connection.v1.Connection;
import com.google.cloud.bigquery.connection.v1.CreateConnectionRequest;
import com.google.cloud.bigquery.connection.v1.LocationName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import java.io.IOException;

public class CreateConnection {

  /**
   * Creates a BigQuery connection to a Cloud Resource. A Cloud Resource connection provisions a
   * service account that can be granted access to other Google Cloud resources for federated
   * queries.
   *
   * @param projectId The Google Cloud project ID (for example, "example-project-id").
   * @param location The geographic location of the connection (for example, "us-central1").
   * @param connectionId The ID of the connection to create (for example, "example-connection-id").
   */
  public static void createConnection(String projectId, String location, String connectionId) {
    LocationName parent = LocationName.of(projectId, location);

    // CloudResourceProperties provisions a managed Google Cloud service account on creation.
    CloudResourceProperties cloudResourceProperties = CloudResourceProperties.newBuilder().build();
    Connection connection =
        Connection.newBuilder()
            .setFriendlyName("Example Connection")
            .setDescription("Cloud Resource connection for federated queries.")
            .setCloudResource(cloudResourceProperties)
            .build();

    CreateConnectionRequest request =
        CreateConnectionRequest.newBuilder()
            .setParent(parent.toString())
            .setConnectionId(connectionId)
            .setConnection(connection)
            .build();

    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      Connection response = client.createConnection(request);

      System.out.printf("Successfully created connection: %s%n", response.getName());
      System.out.printf("Friendly name: %s%n", response.getFriendlyName());
      System.out.printf(
          "Service Account: %s%n", response.getCloudResource().getServiceAccountId());
    } catch (AlreadyExistsException err) {
      System.err.printf(
          "error: connection '%s' already exists in location '%s' for project '%s': %s%n",
          connectionId, location, projectId, err.getMessage());
    } catch (ApiException | IOException err) {
      System.err.printf(
          "error: failed to create connection '%s' in location '%s' for project '%s': %s%n",
          connectionId, location, projectId, err.getMessage());
    }
  }

Terraform

משתמשים במשאב google_bigquery_connection.

כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

בדוגמה הבאה נוצר קישור למשאבים ב-Cloud בשם my_cloud_resource_connection באזור US:


# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

כך מחילים את ההגדרות של Terraform בפרויקט ב- Google Cloud :

הכנת Cloud Shell

  1. מפעילים את Cloud Shell.

  2. מגדירים את פרויקט ברירת המחדל ב- Google Cloud שבו רוצים להחיל את ההגדרות של Terraform.

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

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

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

הכנת הספרייה

לכל קובץ תצורה של Terraform צריכה להיות ספרייה משלו (שנקראת גם מודול ברמה הבסיסית).

  1. יוצרים ספרייה חדשה ב-Cloud Shell ובה יוצרים קובץ חדש. שם הקובץ חייב לכלול את הסיומת .tf, למשל main.tf. במדריך הזה, הקובץ נקרא main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. אם אתם עוקבים אחרי המדריך, תוכלו להעתיק את הקוד לדוגמה בכל קטע או שלב.

    מעתיקים את הקוד לדוגמה בקובץ main.tf החדש שיצרתם.

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

  3. בודקים את הפרמטרים לדוגמה ומשנים אותם בהתאם לסביבה שלכם.
  4. שומרים את השינויים.
  5. מפעילים את Terraform. צריך לעשות זאת רק פעם אחת לכל ספרייה. 
    terraform init

    אופציונלי: תוכלו לכלול את האפשרות -upgrade, כדי להשתמש בגרסה העדכנית ביותר של הספק של Google: 

    terraform init -upgrade

החלה של השינויים

  1. בודקים את ההגדרות ומוודאים שהמשאבים שמערכת Terraform תיצור או תעדכן תואמים לציפיות שלכם: 
    terraform plan

    מתקנים את ההגדרות לפי הצורך.

  2. מריצים את הפקודה הבאה ומזינים yes בהודעה שמופיעה, כדי להחיל את הגדרות Terraform: 
    terraform apply

    ממתינים עד שב-Terraform תוצג ההודעה "Apply complete!‎".

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

הקצאת תפקיד לחשבון השירות של החיבור למודל המרוחק

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

אם אתם מתכננים לציין את נקודת הקצה ככתובת URL כשאתם יוצרים את המודל המרוחק, למשל endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/text-embedding-005', אתם צריכים להקצות את התפקיד הזה באותו פרויקט שציינתם בכתובת ה-URL.

אם אתם מתכננים לציין את נקודת הקצה באמצעות שם המודל כשאתם יוצרים את המודל המרוחק, למשל endpoint = 'text-embedding-005', הקצו את התפקיד הזה באותו פרויקט שבו אתם מתכננים ליצור את המודל המרוחק.

אם מקצים את התפקיד בפרויקט אחר, מופיעה השגיאה bqcx-1234567890-wxyz@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource.

כדי להקצות את התפקיד:

המסוף

  1. נכנסים לדף IAM & Admin.

    כניסה לדף IAM & Admin

  2. לוחצים על Grant access.

    תיבת הדו-שיח Add principals נפתחת.

  3. בשדה New principals, מזינים את מזהה חשבון השירות שהעתקתם קודם.

  4. בשדה Select a role, מחפשים את Agent Platform User.

  5. לוחצים על Save.

gcloud

משתמשים בפקודה gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/aiplatform.user' --condition=None

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

  • ‫PROJECT_NUMBER: מספר הפרויקט
  • ‫MEMBER: מזהה חשבון השירות שהעתקתם קודם

בחירת שיטת פריסה של מודל פתוח

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

יצירת מודל מרוחק של BigQuery ML

יוצרים מודל מרוחק:

מודלים של Agent Platform

  1. נכנסים לדף BigQuery במסוף Google Cloud .

    כניסה ל-BigQuery

  2. יוצרים מודל מרוחק באמצעות עורך ה-SQL:

    CREATE OR REPLACE MODEL
`PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
OPTIONS (ENDPOINT = 'ENDPOINT');

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

    • PROJECT_ID: מזהה הפרויקט.
    • ‫DATASET_ID: המזהה של קבוצת הנתונים שתכיל את המודל. מערך הנתונים הזה צריך להיות באותו מיקום של החיבור שבו אתם משתמשים.
    • ‫MODEL_NAME: שם המודל.
    • ‫REGION: האזור שבו משתמשים בחיבור.
    • ‫CONNECTION_ID: המזהה של החיבור ל-BigQuery.

      כדי לקבל את הערך הזה, מציגים את פרטי החיבור במסוף Google Cloud ומעתיקים את הערך בקטע האחרון של מזהה החיבור המלא שמוצג ב-Connection ID. לדוגמה, projects/myproject/locations/connection_location/connections/myconnection.

    • ‫ENDPOINT: השם של מודל ההטמעה שבו רוצים להשתמש. מידע נוסף זמין במאמר ENDPOINT.

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

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

  1. נכנסים לדף BigQuery במסוף Google Cloud .

    כניסה ל-BigQuery

  2. יוצרים מודל מרוחק באמצעות עורך ה-SQL:

    CREATE OR REPLACE MODEL
`PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
OPTIONS (
  {HUGGING_FACE_MODEL_ID = 'HUGGING_FACE_MODEL_ID' |
     MODEL_GARDEN_MODEL_NAME = 'MODEL_GARDEN_MODEL_NAME'}
  [, HUGGING_FACE_TOKEN = 'HUGGING_FACE_TOKEN' ]
  [, MACHINE_TYPE = 'MACHINE_TYPE' ]
  [, MIN_REPLICA_COUNT = MIN_REPLICA_COUNT ]
  [, MAX_REPLICA_COUNT = MAX_REPLICA_COUNT ]
  [, RESERVATION_AFFINITY_TYPE = {'NO_RESERVATION' | 'ANY_RESERVATION' | 'SPECIFIC_RESERVATION'} ]
  [, RESERVATION_AFFINITY_KEY = 'compute.googleapis.com/reservation-name' ]
  [, RESERVATION_AFFINITY_VALUES = RESERVATION_AFFINITY_VALUES ]
  [, ENDPOINT_IDLE_TTL = ENDPOINT_IDLE_TTL ]
);

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

    • PROJECT_ID: מזהה הפרויקט.
    • ‫DATASET_ID: המזהה של קבוצת הנתונים שתכיל את המודל. מערך הנתונים הזה צריך להיות באותו מיקום של החיבור שבו אתם משתמשים.
    • ‫MODEL_NAME: שם המודל.
    • ‫REGION: האזור שבו משתמשים בחיבור.
    • ‫CONNECTION_ID: המזהה של החיבור ל-BigQuery.

      כדי לקבל את הערך הזה, מציגים את פרטי החיבור במסוף Google Cloud ומעתיקים את הערך בקטע האחרון של מזהה החיבור המלא שמוצג ב-Connection ID. לדוגמה, projects/myproject/locations/connection_location/connections/myconnection.

    • ‫HUGGING_FACE_MODEL_ID: ערך STRING שמציין את מזהה המודל של מודל Hugging Face נתמך, בפורמט provider_name/model_name. לדוגמה, deepseek-ai/DeepSeek-R1. כדי לקבל את מזהה המודל, לוחצים על שם המודל ב-Hugging Face Model Hub ומעתיקים את מזהה המודל מהחלק העליון של כרטיס המודל.
    • ‫MODEL_GARDEN_MODEL_NAME: ערך מסוג STRING שמציין את מזהה המודל ואת גרסת המודל של מודל נתמך ב-Model Garden של Gemini Enterprise Agent Platform, בפורמט publishers/publisher‎/models/model_name@model_version. לדוגמה, publishers/openai/models/gpt-oss@gpt-oss-120b. כדי לקבל את מזהה המודל, לוחצים על כרטיס המודל ב-Agent Platform Model Garden ואז מעתיקים את מזהה המודל מהשדה Model ID. כדי לקבל את גרסת ברירת המחדל של המודל, מעתיקים אותה מהשדה Version בכרטיס המודל. כדי לראות גרסאות אחרות של המודל שאפשר להשתמש בהן, לוחצים על Deploy model ואז על השדה Resource ID.
    • ‫HUGGING_FACE_TOKEN: ערך STRING שמציין את טוקן הגישה של המשתמש ב-Hugging Face שבו רוצים להשתמש. אפשר לציין ערך לאפשרות הזו רק אם מציינים גם ערך לאפשרות HUGGING_FACE_MODEL_ID.

      האסימון חייב להיות לפחות עם התפקיד read, אבל אפשר גם להשתמש באסימונים עם היקף רחב יותר. האפשרות הזו נדרשת כשהמודל שזוהה על ידי הערך HUGGING_FACE_MODEL_ID הוא מודל פרטי או מודל עם גישה מוגבלת (gated) של Hugging Face.

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

      1. עוברים לדף של המודל באתר Hugging Face.
      2. מוצאים את התנאים וההגבלות של המודל וקוראים אותם. בדרך כלל, קישור להסכם השירות מופיע בכרטיס המודל.
      3. מאשרים את התנאים שמופיעים בדף.
    • ‫MACHINE_TYPE: ערך STRING שמציין את סוג המכונה שבה משתמשים כשפורסים את המודל ב-Agent Platform. למידע על סוגי המכונות הנתמכים, קראו את המאמר סוגי מכונות. אם לא מציינים ערך לאפשרות MACHINE_TYPE, המערכת משתמשת בסוג המכונה שמוגדר כברירת מחדל למודל ב-Agent Platform Model Garden.
    • ‫MIN_REPLICA_COUNT: ערך INT64 שמציין את המספר המינימלי של רפליקות של מכונות שבהן נעשה שימוש כשפורסים את המודל בנקודת קצה (endpoint) של Agent Platform. השירות מגדיל או מקטין את מספר הרפליקות לפי הצורך, בהתאם לעומס ההסקה בנקודת הקצה. מספר הרפליקות שבהן נעשה שימוש אף פעם לא נמוך מהערך של MIN_REPLICA_COUNT ואף פעם לא גבוה מהערך של MAX_REPLICA_COUNT. הערך של MIN_REPLICA_COUNT חייב להיות בטווח [1, 4096]. ערך ברירת המחדל הוא 1.
    • ‫MAX_REPLICA_COUNT: ערך INT64 שמציין את המספר המקסימלי של רפליקות של מכונות שבהן נעשה שימוש כשפורסים את המודל בנקודת קצה (endpoint) של Agent Platform. השירות מגדיל או מקטין את מספר הרפליקות לפי הצורך, בהתאם לעומס ההסקה בנקודת הקצה. מספר הרפליקות שבהן נעשה שימוש אף פעם לא נמוך מהערך של MIN_REPLICA_COUNT ואף פעם לא גבוה מהערך של MAX_REPLICA_COUNT. הערך של MAX_REPLICA_COUNT חייב להיות בטווח [1, 4096]. ערך ברירת המחדל הוא הערך של MIN_REPLICA_COUNT.
    • ‫RESERVATION_AFFINITY_TYPE: קובע אם המודל שנפרס משתמש בהזמנות של Compute Engine כדי להבטיח את הזמינות של המכונה הווירטואלית (VM) בזמן הצגת החיזויים, ומציין אם המודל משתמש במכונות וירטואליות מכל ההזמנות הזמינות או רק מהזמנה ספציפית אחת. מידע נוסף זמין במאמר הגדרת מאפייני הזמנת מקום ב-Compute Engine.

      אפשר להשתמש רק בהזמנות של Compute Engine שמשותפות עם Agent Platform. מידע נוסף זמין במאמר אישור לשימוש בהזמנה.

      הערכים הנתמכים הם:

      • ‫NO_RESERVATION: לא נעשה שימוש בהזמנה כשפורסים את המודל בנקודת קצה של Agent Platform. הגדרת NO_RESERVATION זהה לאי-הגדרה של זיקה להזמנה.
      • ‫ANY_RESERVATION: פריסת המודל של Agent Platform צורכת מכונות וירטואליות (VM) מהזמנות של Compute Engine שנמצאות בפרויקט הנוכחי או שמשותפות עם הפרויקט, ומוגדרות לצריכה אוטומטית. רק מכונות וירטואליות שעומדות בדרישות הבאות משמשות למשימה:
        • הם משתמשים בסוג המכונה שצוין בערך MACHINE_TYPE.
        • אם מערך הנתונים ב-BigQuery שבו אתם יוצרים את המודל המרוחק נמצא באזור אחד, ההזמנה צריכה להיות באותו אזור. אם מערך הנתונים נמצא באזור US, ההזמנה חייבת להיות באזור us-central1. אם מערך הנתונים נמצא באזור EU, ההזמנה צריכה להיות באזור europe-west4.

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

      • ‫SPECIFIC_RESERVATION: פריסת המודל של Agent Platform צורכת מכונות וירטואליות רק מההזמנה שציינתם בערך RESERVATION_AFFINITY_VALUES. צריך להגדיר את הבקשה לשימוש ספציפי. הפריסה תיכשל אם אין מספיק קיבולת בהזמנה שצוינה.
    • ‫RESERVATION_AFFINITY_KEY: המחרוזת compute.googleapis.com/reservation-name. צריך לציין את האפשרות הזו כשהערך של RESERVATION_AFFINITY_TYPE הוא SPECIFIC_RESERVATION.
    • ‫RESERVATION_AFFINITY_VALUES: ערך ARRAY<STRING> שמציין את שם המשאב המלא של ההזמנה ב-Compute Engine, בפורמט הבא:

      projects/myproject/zones/reservation_zone/reservations/reservation_name

      לדוגמה, RESERVATION_AFFINITY_values = ['projects/myProject/zones/us-central1-a/reservations/myReservationName'].

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

      צריך לציין את האפשרות הזו כשהערך של RESERVATION_AFFINITY_TYPE הוא SPECIFIC_RESERVATION.

    • ‫ENDPOINT_IDLE_TTL: ערך מסוג INTERVAL שמציין את משך הזמן של חוסר הפעילות שאחריו המודל הפתוח יוסר באופן אוטומטי מנקודת הקצה של Agent Platform.

      כדי להפעיל ביטול פריסה אוטומטי, מציינים ערך של ליטרל מרווח בין 390 דקות (6.5 שעות) ל-7 ימים. לדוגמה, אם מציינים INTERVAL 8 HOUR, פריסת המודל תבוטל אחרי 8 שעות של חוסר פעילות. ערך ברירת המחדל הוא 390 דקות (6.5 שעות).

      חוסר פעילות של מודל מוגדר כמשך הזמן שחלף מאז שבוצעה אחת מהפעולות הבאות במודל:

      כל אחת מהפעולות האלה מאפסת את טיימר חוסר הפעילות לאפס. האיפוס מופעל בתחילת המשימה ב-BigQuery שמבצעת את הפעולה.

      אחרי ביטול הפריסה של המודל, בקשות להסקת מסקנות שנשלחות למודל מחזירות שגיאה. האובייקט של המודל ב-BigQuery לא משתנה, כולל המטא-נתונים של המודל. כדי להשתמש שוב במודל להסקת מסקנות, צריך לפרוס אותו מחדש על ידי הפעלת ההצהרה ALTER MODEL במודל והגדרת האפשרות DEPLOY_MODEL ל-TRUE.

מודלים פתוחים שנפרסו

  1. נכנסים לדף BigQuery במסוף Google Cloud .

    כניסה ל-BigQuery

  2. יוצרים מודל מרוחק באמצעות עורך ה-SQL:

    CREATE OR REPLACE MODEL
`PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
OPTIONS (
  ENDPOINT = 'https://ENDPOINT_REGION-aiplatform.googleapis.com/v1/projects/ENDPOINT_PROJECT_ID/locations/ENDPOINT_REGION/endpoints/ENDPOINT_ID'
);

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

    • PROJECT_ID: מזהה הפרויקט.
    • ‫DATASET_ID: המזהה של קבוצת הנתונים שתכיל את המודל. מערך הנתונים הזה צריך להיות באותו מיקום של החיבור שבו אתם משתמשים.
    • ‫MODEL_NAME: שם המודל.
    • ‫REGION: האזור שבו משתמשים בחיבור.
    • ‫CONNECTION_ID: המזהה של החיבור ל-BigQuery.

      כדי לקבל את הערך הזה, מציגים את פרטי החיבור במסוף Google Cloud ומעתיקים את הערך בקטע האחרון של מזהה החיבור המלא שמוצג ב-Connection ID. לדוגמה, projects/myproject/locations/connection_location/connections/myconnection.

    • ‫ENDPOINT_REGION: האזור שבו נפרס המודל הפתוח.
    • ‫ENDPOINT_PROJECT_ID: הפרויקט שבו נפרס המודל הפתוח.
    • ‫ENDPOINT_ID: המזהה של נקודת הקצה (endpoint) מסוג HTTPS שמשמשת את המודל הפתוח. כדי לקבל את מזהה נקודת הקצה, מאתרים את המודל הפתוח בדף Online prediction ומעתיקים את הערך בשדה ID.

יצירת הטמעות טקסט

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

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

טקסט ב-Agent Platform

כדי ליצור הטמעות טקסט באמצעות מודל מרוחק במודל הטמעת טקסט של Agent Platform:

SELECT *
FROM AI.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  {TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (CONTENT_QUERY)},
  STRUCT(TASK_TYPE AS task_type,
    OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

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

  • PROJECT_ID: מזהה הפרויקט.
  • ‫DATASET_ID: המזהה של קבוצת הנתונים שמכילה את המודל.
  • ‫MODEL_NAME: השם של המודל המרוחק מעל מודל הטמעה.
  • ‫TABLE_NAME: שם הטבלה שמכילה את הטקסט להטמעה. בטבלה הזו חייבת להיות עמודה בשם content, או שאפשר להשתמש בכינוי כדי להשתמש בעמודה עם שם אחר.
  • ‫CONTENT_QUERY: שאילתה שהתוצאה שלה מכילה עמודה מסוג STRING בשם content.
  • ‫TASK_TYPE: ערך מילולי מסוג STRING שמציין את האפליקציה הבאה בתור, כדי לעזור למודל ליצור הטמעות באיכות טובה יותר. ‫TASK_TYPE מקבל את הערכים הבאים:
    • ‫RETRIEVAL_QUERY: מציין שהטקסט שניתן הוא שאילתה בהגדרה של חיפוש או אחזור.
    • ‫RETRIEVAL_DOCUMENT: מציין שהטקסט הנתון הוא מסמך בהגדרה של חיפוש או אחזור.

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

            SELECT *
      FROM
        AI.GENERATE_EMBEDDING(
          MODEL mydataset.embedding_model,
          (SELECT abstract as content, header as title, publication_number
          FROM mydataset.publications),
          STRUCT('RETRIEVAL_DOCUMENT' as task_type)
      );

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

    • ‫SEMANTIC_SIMILARITY: מציין שהטקסט שצוין ישמש ל-Semantic Textual Similarity ‏ (STS).
    • ‫CLASSIFICATION: מציין שההטמעות ישמשו לסיווג.
    • ‫CLUSTERING: מציין שההטמעות ישמשו לאשכולות.
    • ‫QUESTION_ANSWERING: מציין שההטמעות ישמשו למענה על שאלות.
    • ‫FACT_VERIFICATION: מציין שההטמעות ישמשו לאימות עובדות.
    • ‫CODE_RETRIEVAL_QUERY: מציין שההטמעות ישמשו לאחזור קוד.
  • ‫OUTPUT_DIMENSIONALITY: ערך מסוג INT64 שמציין את מספר המאפיינים שבהם צריך להשתמש כשיוצרים הטמעות. לדוגמה, אם מציינים 256 AS output_dimensionality, עמודת הפלט embedding מכילה הטמעה של 256 ממדים לכל ערך קלט.

    במודלים מרוחקים מסוג gemini-embedding-2-preview או gemini-embedding-001, הערך של OUTPUT_DIMENSIONALITY צריך להיות בטווח [1, 3072]. ערך ברירת המחדל הוא 3072. במודלים מרוחקים של text-embedding, הערך של OUTPUT_DIMENSIONALITY חייב להיות בטווח [1, 768]. ערך ברירת המחדל הוא 768.

דוגמה: הטמעת טקסט בטבלה

בדוגמה הבאה מוצגת בקשה להטמעת העמודה content בטבלה text_data:

SELECT *
FROM
  AI.GENERATE_EMBEDDING(
    MODEL `mydataset.embedding_model`,
    TABLE mydataset.text_data,
    STRUCT('CLASSIFICATION' AS task_type)
  );

טקסט חופשי

הערה: כדי לשלוח משוב או לבקש תמיכה לגבי התכונה הזו, אפשר לפנות לכתובת bqml-feedback@google.com.

יצירת הטמעות טקסט באמצעות מודל מרוחק על מודל הטמעה פתוח:

SELECT *
FROM AI.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  {TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (CONTENT_QUERY)},
);

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

  • PROJECT_ID: מזהה הפרויקט.
  • ‫DATASET_ID: המזהה של קבוצת הנתונים שמכילה את המודל.
  • ‫MODEL_NAME: השם של המודל המרוחק מעל מודל הטמעה.
  • ‫TABLE_NAME: שם הטבלה שמכילה את הטקסט להטמעה. בטבלה הזו חייבת להיות עמודה בשם content, או שאפשר להשתמש בכינוי כדי להשתמש בעמודה עם שם אחר.
  • ‫CONTENT_QUERY: שאילתה שהתוצאה שלה מכילה עמודה מסוג STRING בשם content.

מודל מולטי-מודאלי ב-Agent Platform

כדי ליצור הטמעות טקסט באמצעות מודל מרוחק על מודל הטמעה מולטי-מודאלי של Agent Platform:

SELECT *
FROM AI.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  {TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (CONTENT_QUERY)},
  STRUCT(OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

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

  • PROJECT_ID: מזהה הפרויקט.
  • ‫DATASET_ID: המזהה של קבוצת הנתונים שמכילה את המודל.
  • ‫MODEL_NAME: השם של המודל המרוחק מעל מודל multimodalembedding@001.
  • ‫TABLE_NAME: שם הטבלה שמכילה את הטקסט להטמעה. בטבלה הזו חייבת להיות עמודה בשם content, או שאפשר להשתמש בכינוי כדי להשתמש בעמודה עם שם אחר.
  • ‫CONTENT_QUERY: שאילתה שהתוצאה שלה מכילה עמודה מסוג STRING בשם content.
  • ‫OUTPUT_DIMENSIONALITY: ערך INT64 שמציין את מספר המאפיינים שבהם צריך להשתמש כשיוצרים הטמעות. הערכים התקינים הם 128,‏ 256,‏ 512 ו-1408. ערך ברירת המחדל הוא 1408. לדוגמה, אם מציינים את הערך 256 AS output_dimensionality, עמודת הפלט embedding מכילה הטמעה של 256 ממדים לכל ערך קלט.

דוגמה: שימוש בהטמעות כדי לדרג דמיון סמנטי

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

מידע נוסף על חיפוש וקטורי ואינדקס וקטורי זמין במאמר מבוא לחיפוש וקטורי.

CREATE TEMPORARY TABLE movie_review_embeddings AS (
  SELECT *
  FROM
    AI.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (
        SELECT "This movie was fantastic" AS content
        UNION ALL
        SELECT "This was the best movie I've ever seen!!" AS content
        UNION ALL
        SELECT "This movie was just okay..." AS content
        UNION ALL
        SELECT "This movie was terrible." AS content
      )
    )
);

WITH average_review_embedding AS (
  SELECT embedding
  FROM
    AI.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (SELECT "This movie was average" AS content)
    )
)
SELECT
  base.content AS content,
  distance AS distance_to_average_review
FROM
  VECTOR_SEARCH(
    TABLE movie_review_embeddings,
    "embedding",
    (SELECT embedding FROM average_review_embedding),
    distance_type=>"COSINE",
    top_k=>-1
  )
ORDER BY distance_to_average_review;

התוצאה אמורה להיראות כך:

+------------------------------------------+----------------------------+
| content                                  | distance_to_average_review |
+------------------------------------------+----------------------------+
| This movie was just okay...              | 0.062789813467745592       |
| This movie was fantastic                 |  0.18579561313064263       |
| This movie was terrible.                 |  0.35707466240930985       |
| This was the best movie I've ever seen!! |  0.41844932504542975       |
+------------------------------------------+----------------------------+

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