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

המסוף

1. במסוף Cloud de Confiance , עוברים לדף BigQuery.

   כניסה ל-BigQuery

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

   

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

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

4. לוחצים על more_vert View actions > Create dataset (הצגת פעולות > יצירת מערך נתונים).

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

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

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

      • אם בחרתם באפשרות אזור, בוחרים מיקום מהרשימה אזור.
      • אם בחרתם באפשרות Multi-region, בוחרים באפשרות US או Europe מהרשימה Multi-region.

   3. לוחצים על יצירת מערך נתונים.

BQ

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

   bq --location=LOCATION mk -d DATASET_ID

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

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

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

   bq ls

המסוף

1. עוברים לדף BigQuery.

   כניסה ל-BigQuery

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

   

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

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

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

5. בשדה Connection type (סוג החיבור), בוחרים באפשרות Vertex AI remote models, remote functions, BigLake and Spanner (Cloud Resource) (מודלים מרוחקים של Vertex AI, פונקציות מרוחקות, BigLake ו-Spanner (משאב בענן)).

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

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

8. לוחצים על יצירת קישור.

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

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

SQL

משתמשים בפקודה CREATE CONNECTION:

1. במסוף Cloud de Confiance , עוברים לדף BigQuery.

   כניסה ל-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. לוחצים על play_circle הפעלה.

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

BQ

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

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

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

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

   • ‫REGION: אזור החיבור
   • ‫PROJECT_ID: מזהה הפרויקט ב- Cloud de Confiance
   • ‫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.s3ns-system.iam.gserviceaccount.com"}
   

Python

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

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}`);
    }
  }
}

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 בפרויקט ב- Cloud de Confiance , מבצעים את השלבים בקטעים הבאים.

הכנת Cloud Shell

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

2. מגדירים את Cloud de Confiance פרויקט ברירת המחדל שבו רוצים להחיל את ההגדרות של 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. פותחים את Cloud de Confiance הפרויקט כדי לראות את התוצאות. במסוף Cloud de Confiance , נכנסים למשאבים בממשק המשתמש כדי לוודא שהם נוצרו או עודכנו ב-Terraform.

המסוף

1. עוברים לדף IAM & Admin.

   כניסה לדף IAM & Admin

2. לוחצים על person_add הוספה.

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

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

4. בשדה Select a role (בחירת תפקיד), מחפשים את Agent Platform User (משתמש בפלטפורמת הסוכנים).

5. לוחצים על הוספת תפקיד נוסף.

6. בשדה Select a role, בוחרים באפשרות Cloud Storage ואז באפשרות Storage Object Viewer.

7. לוחצים על 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
gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/storage.objectViewer' --condition=None

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

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

SQL

משתמשים בהנחיה CREATE EXTERNAL TABLE.

1. במסוף Cloud de Confiance , עוברים לדף BigQuery.

   כניסה ל-BigQuery

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

   CREATE EXTERNAL TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME`
   WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID`| DEFAULT}
   OPTIONS(
     object_metadata = 'SIMPLE',
     uris = ['BUCKET_PATH'[,...]],
     max_staleness = STALENESS_INTERVAL,
     metadata_cache_mode = 'CACHE_MODE');

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

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

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

     כדי להשתמש ב חיבור שמוגדר כברירת מחדל, מציינים DEFAULT במקום מחרוזת החיבור שמכילה PROJECT_ID.REGION.CONNECTION_ID.

   • ‫BUCKET_PATH: הנתיב לקטגוריית Cloud Storage שמכילה את התמונות, בפורמט ['gs://bucket_name/[folder_name/]*'].

     קטגוריית Cloud Storage שבה אתם משתמשים צריכה להיות באותו פרויקט שבו אתם מתכננים ליצור את המודל ולקרוא לפונקציה AI.GENERATE_EMBEDDING. אם רוצים להפעיל את הפונקציה AI.GENERATE_EMBEDDING בפרויקט אחר מזה שמכיל את קטגוריית Cloud Storage שמשמשת את טבלת האובייקטים, צריך להעניק את התפקיד 'אדמין אחסון' ברמת הקטגוריה לחשבון השירות service-A@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com.

   • ‫STALENESS_INTERVAL: מציין אם פעולות שמתבצעות בטבלת האובייקטים משתמשות במטא-נתונים שנשמרו במטמון, ומה רמת העדכניות של המטא-נתונים שנשמרו במטמון שנדרשת כדי שהפעולה תוכל להשתמש בהם. מידע נוסף על שיקולים לגבי שמירת מטא-נתונים במטמון זמין במאמר שמירת מטא-נתונים במטמון לשיפור הביצועים.

     כדי להשבית את שמירת המטא-נתונים במטמון, מציינים את הערך 0. (זוהי ברירת המחדל)

     כדי להפעיל שמירת מטא-נתונים במטמון, צריך לציין ערך של מרווח זמן בין 30 דקות ל-7 ימים. לדוגמה, כדי להגדיר מרווח של 4 שעות, מציינים INTERVAL 4 HOUR. אם הערך הזה מוגדר, פעולות שמתבצעות בטבלה משתמשות במטא-נתונים שנשמרו במטמון, אם הם רעננו ב-4 השעות האחרונות. אם המטא-נתונים במטמון ישנים יותר, הפעולה מאחזרת מטא-נתונים מ-Cloud Storage.

   • ‫CACHE_MODE: מציין אם מטמון המטא-נתונים מתעדכן באופן אוטומטי או ידני. מידע נוסף על שיקולים בנוגע לשמירת מטא-נתונים במטמון זמין במאמר שמירת מטא-נתונים במטמון לשיפור הביצועים.

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

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

     חובה להגדיר את CACHE_MODE אם הערך של STALENESS_INTERVAL גדול מ-0.

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

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

BQ

משתמשים בפקודה bq mk.

bq mk --table \
--external_table_definition=BUCKET_PATH@REGION.CONNECTION_ID \
--object_metadata=SIMPLE \
--max_staleness=STALENESS_INTERVAL \
--metadata_cache_mode=CACHE_MODE \
PROJECT_ID:DATASET_ID.TABLE_NAME

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

• ‫BUCKET_PATH: הנתיב לקטגוריית Cloud Storage שמכילה את התמונות, בפורמט ['gs://bucket_name/[folder_name/]*'].

  קטגוריית Cloud Storage שבה אתם משתמשים צריכה להיות באותו פרויקט שבו אתם מתכננים ליצור את המודל ולקרוא לפונקציה AI.GENERATE_EMBEDDING. אם רוצים להפעיל את הפונקציה AI.GENERATE_EMBEDDING בפרויקט אחר מזה שמכיל את קטגוריית Cloud Storage שמשמשת את טבלת האובייקטים, צריך להעניק את התפקיד 'אדמין אחסון' ברמת הקטגוריה לחשבון השירות service-A@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com.

• ‫REGION: האזור או מספר האזורים שכוללים את החיבור.
• ‫CONNECTION_ID: המזהה של החיבור שיצרתם.

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

• ‫STALENESS_INTERVAL: מציין אם פעולות שמתבצעות בטבלת האובייקטים משתמשות במטא-נתונים שנשמרו במטמון, ומה רמת העדכניות של המטא-נתונים שנשמרו במטמון שנדרשת כדי שהפעולה תוכל להשתמש בהם. מידע נוסף על שיקולים לגבי שמירת מטא-נתונים במטמון זמין במאמר שמירת מטא-נתונים במטמון לשיפור הביצועים.

  כדי להשבית את שמירת המטא-נתונים במטמון, מציינים את הערך 0. (זוהי ברירת המחדל)

  כדי להפעיל שמירת מטא-נתונים במטמון, צריך לציין ערך של מרווח זמן בין 30 דקות ל-7 ימים. לדוגמה, כדי להגדיר מרווח של 4 שעות, מציינים INTERVAL 4 HOUR. אם הערך הזה קיים, פעולות שמתבצעות בטבלה משתמשות במטא-נתונים ששמורים במטמון אם הם רעננו ב-4 השעות האחרונות. אם המטא-נתונים במטמון ישנים יותר, הפעולה מאחזרת מטא-נתונים מ-Cloud Storage.

• ‫CACHE_MODE: מציין אם מטמון המטא-נתונים מתעדכן באופן אוטומטי או ידני. מידע נוסף על שיקולים בנוגע לשמירת מטא-נתונים במטמון זמין במאמר שמירת מטא-נתונים במטמון לשיפור הביצועים.

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

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

  חובה להגדיר את CACHE_MODE אם הערך של STALENESS_INTERVAL גדול מ-0.

• PROJECT_ID: מזהה הפרויקט.
• ‫DATASET_ID: המזהה של מערך הנתונים שיצרתם.
• ‫TABLE_NAME: השם של טבלת האובייקטים.