הגדרת הרשאות לפונקציות של AI גנרטיבי שמפעילות מודלים גדולים של שפה (LLM) בפלטפורמת הסוכנים של Gemini Enterprise

במסמך הזה מוסבר איך מגדירים הרשאות להרצת שאילתות של AI גנרטיבי. שאילתות של AI גנרטיבי מכילות פונקציות AI.* שקוראות למודלים בסיסיים ב-Gemini Enterprise Agent Platform, לדוגמה, AI.GENERATE.

יש שתי דרכים להגדיר הרשאות להרצת שאילתות שמשתמשות בפונקציות AI.*:

• מריצים את השאילתה באמצעות פרטי הכניסה של משתמש הקצה
• יצירת חיבור ל-BigQuery כדי להריץ את השאילתה באמצעות חשבון שירות

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

הפעלת שאילתות של AI גנרטיבי באמצעות פרטי כניסה של משתמשי קצה

כדי להריץ שאילתות של AI גנרטיבי באמצעות פרטי כניסה של משתמשי קצה, צריך להגדיר את ההרשאות הנדרשות באמצעות Google Cloud המסוף. הערה: אם אתם בעלי הפרויקט, כבר יש לכם את כל ההרשאות הנדרשות, כך שלא צריך לעשות שום דבר.

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

כדי לקבל את ההרשאות שדרושות להרצת שאילתה שקוראת למודל Vertex AI, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרויקט:

• הפעלת משימות של שאילתות: BigQuery Job User (roles/bigquery.jobUser)
• גישה למודל בסיסי ב-Gemini Enterprise Agent Platform: משתמש Agent Platform (roles/aiplatform.user)

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

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

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

אתם יכולים להשתמש במסוף Google Cloud או ב-SQL כדי להעניק את התפקידים הנדרשים לישות מורשית. הישות המורשית היא המשתמש או הקבוצה שמריצים את השאילתה שמשתמשת בפונקציות AI.* כדי לקרוא למודל בסיס של Gemini Enterprise Agent Platform.

המסוף

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

   כניסה לדף IAM

2. בוחרים את הפרויקט הרצוי.

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

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

      כניסה לדף IAM & Admin

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

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

   3. בשדה New principals, מזינים את מזהה החשבון הראשי – לדוגמה, [e-mail] או //iam.googleapis.com/locations/global/workforcePools/example-pool/group/[e-mail].

   4. בקטע Assign roles (הקצאת תפקידים), לוחצים על החץ של התפריט הנפתח Select a role (בחירת תפקיד).

   5. מחפשים את התפקיד Agent Platform User ובוחרים אותו.

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

   7. בקטע Assign roles (הקצאת תפקידים), לוחצים על החץ של התפריט הנפתח Select a role (בחירת תפקיד).

   8. מחפשים את התפקיד BigQuery Job User ובוחרים אותו.

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

      

SQL

משתמשים בהצהרה GRANT:

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

   כניסה ל-BigQuery

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

   GRANT `roles/aiplatform.user`, `roles/bigquery.jobUser`
   ON PROJECT `PROJECT_ID`
   TO "USER_OR_GROUP";

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

   • ‫PROJECT_ID: הפרויקט שבו אתם מתכננים להשתמש בפונקציות של AI.*.
   • ‫USER_OR_GROUP: המשתמש או הקבוצה שרוצים להעניק להם גישה, בפורמט user:USER@DOMAIN או group:GROUP@DOMAIN.

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

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

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

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

הרצת שאילתות של AI גנרטיבי באמצעות חיבור ל-BigQuery

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

יצירת חיבור

אתם יכולים להגדיר קישור למשאבים ב-Cloud כדי להריץ את כל השאילתות של AI גנרטיבי שמכילות פונקציות של AI.*. כשיוצרים חיבור, נותנים הרשאות להפעלת שאילתות לחשבון שירות.

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

המסוף

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

   כניסה ל-BigQuery

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

   

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

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. במסוף Google Cloud , עוברים לדף 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. לוחצים על הפעלה.

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

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": "[e-mail]"}
   

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

Terraform

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

הערה: כדי ליצור אובייקטים של BigQuery באמצעות Terraform, צריך להפעיל את Cloud Resource Manager API.

כדי לבצע אימות ב-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. מגדירים את פרויקט ברירת המחדל שבו רוצים להחיל את ההגדרות של Terraform. Google Cloud

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

   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.

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

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

הענקת גישה לחשבון השירות

כדי להריץ שאילתות שמשתמשות בפונקציות גנרטיביות של AI.* שקוראות למודלים של Gemini Enterprise Agent Platform, צריך לתת הרשאות מתאימות לחשבון השירות שנוצר כשיוצרים את החיבור. כדי להריץ פונקציות שקוראות למודל בסיס של Gemini Enterprise Agent Platform, צריך את תפקיד המשתמש ב-Agent Platform (roles/aiplatform.user).

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

המסוף

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

   כניסה לדף IAM & Admin

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

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

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

4. בקטע הקצאת תפקידים, לוחצים על הוספת תפקידים.

5. מחפשים את התפקיד Agent Platform User, בוחרים אותו ולוחצים על Apply.

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

SQL

משתמשים בהצהרה GRANT:

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

   כניסה ל-BigQuery

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

   GRANT `roles/aiplatform.user`
   ON PROJECT `PROJECT_ID`
   TO "connection:CONNECTION_NAME";

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

   • ‫PROJECT_ID: הפרויקט שבו אתם מתכננים להשתמש ב-Agent Platform.
   • ‫CONNECTION_NAME: השם של החיבור בפורמט PROJECT_ID.LOCATION.CONNECTION_ID או LOCATION.CONNECTION_ID. אם לא מציינים פרויקט, המערכת מסיקה אותו מהפרויקט שבו מריצים את ההצהרה.

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

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

gcloud

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

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:$(bq show --format=prettyjson --connection $PROJECT_ID.$REGION.$CONNECTION_ID | jq -r .cloudResource.serviceAccountId)"
--role=roles/aiplatform.user

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

• ‫PROJECT_ID: שם הפרויקט.
• REGION: המיקום שבו נוצר החיבור.
• ‫CONNECTION_ID: השם של החיבור שיצרתם.

Terraform

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

הערה: כדי ליצור אובייקטים של BigQuery באמצעות Terraform, צריך להפעיל את Cloud Resource Manager API.

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

בדוגמה הבאה מוקצית גישה לתפקיד IAM לחשבון השירות של חיבור משאב ה-Cloud:

## This grants IAM role access to the service account of the connection created in the previous step.
resource "google_project_iam_member" "aiplatformpermission" {
  project = data.google_project.default.project_id
  role    = "roles/aiplatform.user"
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

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

הכנת Cloud Shell

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

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

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

   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.

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