מדריך בנושא פונקציות מרוחקות ו-Translation API

אתם יכולים לשלב פונקציות מרוחקות של BigQuery עם Cloud Translation API כדי לתרגם תוכן מכל שפה ישירות באמצעות SQL ו-Python. תרגום הנתונים ב-BigQuery מאפשר לכם לתרגם תגובות של משתמשים באתר או לאחד בקשות תמיכה בשפות שונות לשפה משותפת, כדי שהעובדים שמטפלים בפניות יוכלו להבין אותן.

מטרות

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

עלויות

במסמך הזה משתמשים ברכיבים הבאים של Google Cloud, והשימוש בהם כרוך בתשלום:

בעזרת מחשבון העלויות אתם יכולים להעריך את העלויות בהתאם לשימוש הצפוי.

משתמשים חדשים של Google Cloud ? יכול להיות שאתם זכאים לתקופת ניסיון בחינם.

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

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

הגדרת פרויקט ב- Google Cloud

כדי להגדיר פרויקט ב- Google Cloud בשביל המדריך הזה, מבצעים את השלבים הבאים:

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the BigQuery, BigQuery Connection, Cloud Translation, Cloud Run functions, Cloud Build, Cloud Logging, Cloud Pub/Sub, Artifact Registry, and Cloud Run Admin APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

התפקידים הנדרשים בחשבון

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

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

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

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

כדי לבצע את המשימות במדריך הזה, נדרשות ההרשאות הבאות:

  • bigquery.datasets.create
  • bigquery.connections.create
  • bigquery.connections.get
  • cloudfunctions.functions.create

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

התפקידים הנדרשים לחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine

כשהפעלתם את ה-API לפונקציות Cloud Run, נוצר חשבון שירות שמוגדר כברירת מחדל ב-Compute Engine. כדי להשלים את המדריך, צריך לתת לחשבון השירות הזה את התפקיד "משתמש ב-Cloud Translation API".

  1. מאתרים את המזהה שהוקצה לפרויקט.

  2. מעתיקים את חשבון השירות שמוגדר כברירת מחדל ב-Compute Engine. חשבון השירות שמוגדר כברירת מחדל נראה כך:

    PROJECT_NUMBER-compute@

    מחליפים את PROJECT_NUMBER במזהה הפרויקט.

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

    כניסה לדף IAM

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

  5. לוחצים על Grant access, ובשדה New principals מדביקים את חשבון השירות שמוגדר כברירת המחדל של Compute Engine שהעתקתם קודם.

  6. ברשימה Assign roles, מחפשים את התפקיד Cloud Translation API User ובוחרים אותו.

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

יצירת פונקציית Cloud Run

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

  1. יוצרים פונקציית Cloud Run עם המפרט הבא:

    • בשדה Environment, בוחרים באפשרות 2nd gen.
    • בשדה Function name, מזינים translation-handler.
    • בשדה Region, בוחרים באפשרות us-central1.

    • בשדה Maximum number of instances, מזינים 10.

      ההגדרה הזו נמצאת בקטע Runtime, build, connections and security settings.

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

    • בשדה Runtime, בוחרים באפשרות Python 3.10.

    • בשדה Entry point, מזינים handle_translation.

  2. ברשימת הקבצים, בוחרים באפשרות main.py ומדביקים את הקוד הבא.

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

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

    from __future__ import annotations


import flask
import functions_framework
from google.api_core.retry import Retry
from google.cloud import translate

# Construct a Translation Client object
translate_client = translate.TranslationServiceClient()


# Register an HTTP function with the Functions Framework
@functions_framework.http
def handle_translation(request: flask.Request) -> flask.Response:
    """BigQuery remote function to translate input text.

    Args:
        request: HTTP request from BigQuery
        https://cloud.google.com/bigquery/docs/reference/standard-sql/remote-functions#input_format

    Returns:
        HTTP response to BigQuery
        https://cloud.google.com/bigquery/docs/reference/standard-sql/remote-functions#output_format
    """
    try:
        # Parse request data as JSON
        request_json = request.get_json()
        # Get the project of the query
        caller = request_json["caller"]
        project = extract_project_from_caller(caller)
        if project is None:
            return flask.make_response(
                flask.jsonify(
                    {
                        "errorMessage": (
                            'project can\'t be extracted from "caller":' f" {caller}."
                        )
                    }
                ),
                400,
            )
        # Get the target language code, default is Spanish ("es")
        context = request_json.get("userDefinedContext", {})
        target = context.get("target_language", "es")

        calls = request_json["calls"]
        translated = translate_text([call[0] for call in calls], project, target)

        return flask.jsonify({"replies": translated})
    except Exception as err:
        return flask.make_response(
            flask.jsonify({"errorMessage": f"Unexpected error {type(err)}:{err}"}),
            400,
        )


def extract_project_from_caller(job: str) -> str:
    """Extract project id from full resource name of a BigQuery job.

    Args:
        job: full resource name of a BigQuery job, like
          "//bigquery.googleapi.com/projects/<project>/jobs/<job_id>"

    Returns:
        project id which is contained in the full resource name of the job.
    """
    path = job.split("/")
    return path[4] if len(path) > 4 else None


def translate_text(
    calls: list[str], project: str, target_language_code: str
) -> list[str]:
    """Translates the input text to specified language using Translation API.

    Args:
        calls: a list of input text to translate.
        project: the project where the translate service will be used.
        target_language_code: The ISO-639 language code to use for translation
          of the input text. See
          https://cloud.google.com/translate/docs/advanced/discovering-supported-languages-v3#supported-target
            for the supported language list.

    Returns:
        a list of translated text.
    """
    location = "<your location>"
    parent = f"projects/{project}/locations/{location}"
    # Call the Translation API, passing a list of values and the target language
    response = translate_client.translate_text(
        request={
            "parent": parent,
            "contents": calls,
            "target_language_code": target_language_code,
            "mime_type": "text/plain",
        },
        retry=Retry(),
    )
    # Convert the translated value to a list and return it
    return [translation.translated_text for translation in response.translations]

    מעדכנים את <your location> באמצעות us-central1.

  3. ברשימת הקבצים, בוחרים באפשרות requirements.txt ומדביקים את הטקסט הבא:

    Flask==3.1.3; python_version >= '3.9'
functions-framework==3.9.2
google-cloud-translate==3.18.0
Werkzeug==3.1.9; python_version >= '3.10'

  4. לוחצים על Deploy וממתינים לפריסת הפונקציה.

  5. לוחצים על הכרטיסייה Trigger (טריגר).

  6. מעתיקים את הערך של Trigger URL ושומרים אותו למועד מאוחר יותר. צריך להשתמש בכתובת ה-URL הזו כשיוצרים פונקציה מרוחקת ב-BigQuery.

יצירת מערך נתונים ב-BigQuery

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

  • בשדה Dataset ID, מזינים remote_function_test.
  • בשדה Location type, בוחרים באפשרות Multi-region.
  • בשדה Multi-region, בוחרים באפשרות US (multiple regions in United States).

יצירת חיבור וחשבון שירות ב-BigQuery

יוצרים חיבור ל-BigQuery כדי להטמיע פונקציה מרוחקת בכל שפה שנתמכת בפונקציות Cloud Run וב-Cloud Run. כשיוצרים חיבור, נוצר בשבילו חשבון שירות.

  1. יוצרים Google Cloud חיבור למשאב עם המאפיינים הבאים:

    • בשדה Connection type, בוחרים באפשרות BigLake and remote functions (Cloud Resource).
    • בשדה מזהה החיבור, מזינים את הערך remote-function-connection.
    • בשדה Location type, בוחרים באפשרות Multi-region.
    • בשדה Multi-region, בוחרים באפשרות US (multiple regions in United States).

  2. פותחים את הרשימה חיבורים ולוחצים על us.remote-function-connection.

  3. מעתיקים את מזהה חשבון השירות ושומרים אותו לשימוש בהמשך. בשלב הבא צריך לתת הרשאות למזהה הזה.

מתן הרשאות לחשבון השירות של BigQuery

כדי שהפונקציה המרוחקת של BigQuery תוכל להשתמש בפונקציית Cloud Run, צריך לתת לחשבון השירות שיצרתם בשלב הקודם הרשאה להשתמש ב-Cloud Run. כדי לתת הרשאות לחשבון השירות:

  1. נכנסים לדף Cloud Run.

    כניסה ל-Cloud Run

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

  3. מסמנים את התיבה לצד translation-handler.

  4. בחלונית Permissions, לוחצים על Add principal.

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

  6. ברשימה Assign roles, מחפשים את התפקיד Cloud Run Invoker ובוחרים אותו.

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

יצירת פונקציה מרוחקת ב-BigQuery

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

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

    כניסה ל-BigQuery

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

    CREATE OR REPLACE FUNCTION `remote_function_test.translate_text`(x STRING)
RETURNS
STRING
    REMOTE WITH CONNECTION `us.remote-function-connection`
OPTIONS (
    endpoint = 'TRIGGER_URL',
    max_batching_rows = 10);

    מחליפים את TRIGGER_URL בכתובת ה-URL של הטריגר ששמרתם קודם כשיצרתם פונקציית Cloud Run.

  3. לוחצים על Run. מוצגת הודעה דומה לזו:

    This statement created a new function named
your_project.remote_function_test.translate_text.

קריאה לפונקציה המרוחקת של BigQuery

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

  1. בעורך השאילתות של BigQuery, מזינים את השאילתה הבאה ולוחצים על Run.

    SELECT
  remote_function_test.translate_text('This new feature is fantastic!')
    AS translated_text;

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

    +-------------------------------------------+
| translated_text                           |
+-------------------------------------------+
| ¡Esta nueva característica es fantástica! |
+-------------------------------------------+

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

    SELECT
    text,
    remote_function_test.translate_text(text) AS translated_text
FROM
    (SELECT text FROM `bigquery-public-data.hacker_news.full` LIMIT 3);

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

    +---------------------------------------------------------------------------+
| text                            | translated_text                         |
+---------------------------------------------------------------------------+
| These benchmarks look good.     | Estos puntos de referencia se ven bien. |
| Who is using Java?              | ¿Quién está usando Java?                |
| You need more database storage. | Necesitas más almacenamiento.           |
+---------------------------------------------------------------------------+

מחיקת המשאבים

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

  1. במסוף Google Cloud , נכנסים לדף Manage resources.

    כניסה לדף Manage resources

  2. ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete.
  3. כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

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