פריסת "Google Translate" אפליקציה ב-Python 3 Cloud Run (Docker)

1. סקירה כללית

סדרת ה-codelabs הזו (הדרכות מעשיות בקצב אישי) נועדה לעזור למפתחים להבין את האפשרויות השונות שיש להם כשמפיצים את האפליקציות שלהם. ב-codelab הזה תלמדו איך להשתמש ב-Google Cloud Translation API עם Python, ולהפעיל אותו באופן מקומי או לפרוס אותו בפלטפורמת מחשוב ללא שרת (serverless) ב-Cloud (App Engine,‏ Cloud Functions או Cloud Run). אפשר לפרוס את אפליקציית הדוגמה שמופיעה במאגר של המדריך הזה (לפחות) בשמונה דרכים שונות, עם שינויים קלים בלבד בהגדרות:

שרת Flask מקומי (Python 2)
שרת Flask מקומי (Python 3)
‫App Engine (Python 2)
App Engine ‏ (Python 3)
‫Cloud Functions (Python 3)
‫Cloud Run (Python 2 דרך Docker)
‫Cloud Run (Python 3 via Docker)
‫Cloud Run (Python 3 באמצעות Cloud Buildpacks)

ה-Codelab הזה מתמקד בפריסת האפליקציה בפלטפורמות המובלטות שלמעלה.

מה תלמדו

שימוש בממשקי Google Cloud API, במיוחד ב-Cloud Translation API (מתקדם/גרסה 3)
הפעלת אפליקציית אינטרנט בסיסית באופן מקומי או פריסה בפלטפורמת מחשוב ללא שרת בענן

מה תצטרכו

פרויקט בענן עם חשבון לחיוב ב-Cloud
‫Flask מותקן להרצה מקומית, או פלטפורמת מחשוב ללא שרת בענן שמופעלת לפריסות מבוססות-ענן
מיומנויות בסיסיות ב-Python
ידע מעשי בפקודות בסיסיות של מערכת ההפעלה

סקר

איך תשתמשו במדריך הזה?

לקרוא ולענות על התרגילים

לקרוא בלבד

איך היית מדרג את חוויית השימוש שלך ב-Python?

מתחילים

ביניים

מומחים

איזה דירוג מתאים לדעתך לחוויית השימוש שלך בשירותי Google Cloud?

מתחילים

ביניים

מומחים

‫2. הגדרה ודרישות

הגדרת סביבה בקצב אישי

נכנסים ל-מסוף Google Cloud ויוצרים פרויקט חדש או משתמשים בפרויקט קיים. אם עדיין אין לכם חשבון Gmail או Google Workspace, אתם צריכים ליצור חשבון.

שם הפרויקט הוא השם המוצג של הפרויקט הזה למשתתפים. זו מחרוזת של תווים שלא נמצאת בשימוש ב-Google APIs, ואפשר לעדכן אותה בכל שלב.
מזהה הפרויקט חייב להיות ייחודי בכל הפרויקטים ב-Google Cloud, והוא קבוע (אי אפשר לשנות אותו אחרי שמגדירים אותו). מסוף Cloud יוצר באופן אוטומטי מחרוזת ייחודית. בדרך כלל לא צריך להתייחס אליה. ברוב סדנאות ה-Codelab, צריך להפנות למזהה הפרויקט (ובדרך כלל הוא מזוהה כ-PROJECT_ID), אז אם לא מוצא חן בעיניכם, אפשר ליצור מזהה אקראי אחר, או לנסות מזהה משלכם ולבדוק אם הוא זמין. אחרי שהפרויקט נוצר, הוא 'קפוא'.
יש ערך שלישי, מספר פרויקט, שחלק מממשקי ה-API משתמשים בו. במאמרי העזרה מפורט מידע נוסף על שלושת הערכים האלה.

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

‫3. הפעלת Translation API

הפעלת Cloud APIs

בקטע הזה מוסבר איך להפעיל Google APIs באופן כללי. באפליקציה לדוגמה שלנו, תפעילו את Cloud Translation API,‏ Cloud Run ו-Cloud Artifact Registry.

מבוא

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

אפשרות 1: מ-Cloud Shell או מממשק שורת הפקודה

הפעלת ממשקי API מ-Cloud Console היא פעולה נפוצה יותר, אבל יש מפתחים שמעדיפים לעשות הכול משורת הפקודה. כדי לעשות זאת, צריך לחפש את 'שם השירות' של ה-API. נראה שזו כתובת URL: SERVICE_NAME.googleapis.com. אפשר למצוא אותם בטבלת המוצרים הנתמכים, או לבצע שאילתה לגביהם באופן פרוגרמטי באמצעות Google Discovery API.

בעזרת המידע הזה, אפשר להפעיל API באמצעות Cloud Shell (או סביבת הפיתוח המקומית עם gcloud כלי שורת הפקודה מותקן), באופן הבא:

gcloud services enable SERVICE_NAME.googleapis.com

לדוגמה, הפקודה הזו מפעילה את Cloud Vision API:

gcloud services enable vision.googleapis.com

הפקודה הזו מפעילה את App Engine:

gcloud services enable appengine.googleapis.com

אפשר גם להפעיל כמה ממשקי API באמצעות בקשה אחת. לדוגמה, שורת הפקודה הבאה מפעילה את Cloud Run, את Cloud Artifact Registry ואת Cloud Translation API:

gcloud services enable artifactregistry.googleapis.com run.googleapis.com translate.googleapis.com

אפשרות 2: דרך Cloud Console

אפשר גם להפעיל את Vision API ב-API Manager. במסוף Cloud, עוברים אל API Manager ובוחרים באפשרות Library.

אם רוצים להפעיל את Cloud Vision API, מתחילים להזין 'vision' בסרגל החיפוש, וכל מה שתואם למה שהזנתם עד עכשיו יופיע:

בוחרים את ה-API שרוצים להפעיל ולוחצים על הפעלה:

עלות

אפשר להשתמש בהרבה ממשקי Google API ללא תשלום, אבל השימוש במוצרים ובממשקי API של Google Cloud לא בחינם. כשמפעילים Cloud APIs, יכול להיות שתתבקשו לספק חשבון לחיוב פעיל. עם זאת, חשוב לציין שלחלק ממוצרי Google Cloud יש רמת שימוש 'תמיד בחינם' (יומית או חודשית), שצריך לחרוג ממנה כדי שיופיעו חיובים בחשבון. אחרת, לא יחויב כרטיס האשראי (או אמצעי התשלום שצוין).

לפני שמפעילים API, חשוב לעיין במידע על התמחור שלו, ולבדוק אם יש לו רמת שימוש בחינם, ואם כן, מה היא. אם מפעילים את Cloud Vision API, צריך לעיין בדף המידע על התמחור שלו. ל-Cloud Vision יש מכסת שימוש בחינם, וכל עוד לא חורגים מהמגבלות שלה (בכל חודש), לא אמורים לחול חיובים.

התמחור והתוכניות החינמיות משתנים בין ממשקי Google API. דוגמאות:

‫Google Cloud/GCP – כל מוצר מחויב באופן שונה, ובדרך כלל התשלום הוא לפי מחזור vCPU, לפי צריכת אחסון, לפי שימוש בזיכרון או לפי שימוש. מידע על רמת שימוש בחינם מופיע למעלה.
‫מפות Google – כולל חבילה של ממשקי API ומציע למשתמשים זיכוי חודשי בסך 200$‎.
ממשקי API של Google Workspace (לשעבר G Suite) – השימוש בהם הוא בחינם (עד למגבלות מסוימות) במסגרת דמי המינוי החודשיים ל-Workspace, כך שאין חיוב ישיר על שימוש בממשקי API של Gmail,‏ Google Drive,‏ Calendar,‏ Docs,‏ Sheets ו-Slides.

יש הבדלים בחיוב בין מוצרי Google השונים, ולכן חשוב לעיין בתיעוד של ה-API כדי לקבל את המידע הזה.

סיכום

אחרי שלמדתם איך להפעיל ממשקי Google API באופן כללי, עוברים אל API Manager ומפעילים את Cloud Translation API,‏ Cloud Run ו-Cloud Artifact Registry (אם עדיין לא עשיתם זאת). אתם צריכים להפעיל את האפשרות הראשונה כי האפליקציה שלנו משתמשת בה. אתם צריכים להפעיל את האפשרות השנייה כי שם מאוחסנים קובצי האימג' של הקונטיינרים לפני הפריסה שלהם כדי להפעיל את שירות Cloud Run. לכן אתם צריכים להפעיל אותה. אם אתם מעדיפים להפעיל את כולם באמצעות הכלי gcloud, מריצים את הפקודה הבאה מהטרמינל:

gcloud services enable artifactregistry.googleapis.com run.googleapis.com translate.googleapis.com

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

4. קבלת הקוד של האפליקציה לדוגמה

משכפלים את הקוד במאגר באופן מקומי או ב-Cloud Shell (באמצעות הפקודה git clone), או מורידים את קובץ ה-ZIP מהלחצן הירוק Code (קוד) כמו שמוצג בצילום המסך הבא:

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

5. סיור באפליקציה לדוגמה

אפליקציית הדוגמה היא נגזרת פשוטה של Google Translate, שמבקשת מהמשתמשים להזין טקסט באנגלית ומקבלת את התרגום המקביל של הטקסט הזה בספרדית. עכשיו נפתח את הקובץ main.py כדי לראות איך הוא עובד. אם משמיטים את השורות עם ההערות לגבי הרישיון, הקוד נראה כך בחלק העליון והתחתון:

from flask import Flask, render_template, request
import google.auth
from google.cloud import translate

app = Flask(__name__)
_, PROJECT_ID = google.auth.default()
TRANSLATE = translate.TranslationServiceClient()
PARENT = 'projects/{}'.format(PROJECT_ID)
SOURCE, TARGET = ('en', 'English'), ('es', 'Spanish')

# . . . [translate() function definition] . . .

if __name__ == '__main__':
    import os
    app.run(debug=True, threaded=True, host='0.0.0.0',
            port=int(os.environ.get('PORT', 8080)))

הייבוא כולל את הפונקציונליות של Flask, את המודול google.auth ואת ספריית הלקוח של Cloud Translation API.
המשתנים הגלובליים מייצגים את אפליקציית Flask, את מזהה פרויקט בענן, את הלקוח של Translation API, את 'נתיב המיקום' של קריאות ל-Translation API ואת שפות המקור והיעד. בדוגמה הזו, שפת המקור היא אנגלית (en) ושפת היעד היא ספרדית (es), אבל אפשר לשנות את הערכים האלה לקודי שפה אחרים שנתמכים על ידי Cloud Translation API.
הבלוק הגדול if בתחתית משמש במדריך בנושא הפעלת האפליקציה הזו באופן מקומי – הוא משתמש בשרת הפיתוח של Flask כדי להציג את האפליקציה שלנו. הקטע הזה מופיע גם במדריכים בנושא פריסה ב-Cloud Run למקרה ששרת האינטרנט לא נארז בקונטיינר. אתם מתבקשים להפעיל את האפשרות לאגד את השרת בקונטיינר, אבל אם תפספסו את זה, קוד האפליקציה יחזור להשתמש בשרת הפיתוח של Flask. (זו לא בעיה ב-App Engine או ב-Cloud Functions כי אלה פלטפורמות מבוססות-מקור, כלומר Google Cloud מספקת ומפעילה שרת אינטרנט שמוגדר כברירת מחדל).

לבסוף, באמצע main.py נמצא הלב של האפליקציה, הפונקציה translate():

@app.route('/', methods=['GET', 'POST'])
def translate(gcf_request=None):
    """
    main handler - show form and possibly previous translation
    """

    # Flask Request object passed in for Cloud Functions
    # (use gcf_request for GCF but flask.request otherwise)
    local_request = gcf_request if gcf_request else request

    # reset all variables (GET)
    text = translated = None

    # if there is data to process (POST)
    if local_request.method == 'POST':
        text = local_request.form['text']
        data = {
            'contents': [text],
            'parent': PARENT,
            'target_language_code': TARGET[0],
        }
        # handle older call for backwards-compatibility
        try:
            rsp = TRANSLATE.translate_text(request=data)
        except TypeError:
            rsp = TRANSLATE.translate_text(**data)
        translated = rsp.translations[0].translated_text

    # create context & render template
    context = {
        'orig':  {'text': text, 'lc': SOURCE},
        'trans': {'text': translated, 'lc': TARGET},
    }
    return render_template('index.html', **context)

הפונקציה הראשית מבצעת את העבודה של קבלת קלט של משתמשים, וקוראת ל-Translation API כדי לבצע את העבודה הקשה. נסביר:

בודקים אם הבקשות מגיעות מ-Cloud Functions באמצעות המשתנה local_request. ‫Cloud Functions שולח אובייקט בקשה של Flask משלו, בעוד שכל השאר (שפועלים באופן מקומי או נפרסים ב-App Engine או ב-Cloud Run) יקבלו את אובייקט הבקשה ישירות מ-Flask.
מאפסים את המשתנים הבסיסיים של הטופס. ההגדרה הזו רלוונטית בעיקר לבקשות GET, כי בקשות POST יכללו נתונים שיחליפו את הערכים האלה.
אם זו בקשת POST, צריך לאחזר את הטקסט לתרגום וליצור מבנה JSON שמייצג את דרישת המטא-נתונים של ה-API. לאחר מכן קוראים ל-API, וחוזרים לגרסה קודמת של ה-API אם המשתמש משתמש בספרייה ישנה יותר.
בכל מקרה, צריך לעצב את התוצאות בפועל (POST) או את הנתונים (GET) בהקשר של התבנית ולבצע עיבוד.

החלק החזותי של האפליקציה נמצא בקובץ התבנית index.html. מוצגות תוצאות שכבר תורגמו (אם יש כאלה, אחרת מוצג שדה ריק), ואחריו הטופס שבו אפשר להזין טקסט לתרגום:

<!doctype html>
<html><head><title>My Google Translate 1990s</title><body>
<h2>My Google Translate (1990s edition)</h2>

{% if trans['text'] %}
    <h4>Previous translation</h4>
    <li><b>Original</b>:   {{ orig['text'] }}  (<i>{{ orig['lc'][0] }}</i>)</li>
    <li><b>Translated</b>: {{ trans['text'] }} (<i>{{ trans['lc'][0] }}</i>)</li>
{% endif %}

<h4>Enter <i>{{ orig['lc'][1] }}</i> text to translate to <i>{{ trans['lc'][1] }}</i>:</h4>
<form method="POST"><input name="text"><input type="submit"></form>
</body></html>

6. הגדרת Docker ליצירת קובץ אימג' של Python 3

עכשיו פותחים את הקובץ Dockerfile, שמוצג בלי פרטי הרישיון כך:

#FROM python:3-slim
FROM python:2-slim
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
ENTRYPOINT ["python", "main.py"]

כפי שאפשר לראות, כברירת מחדל, ההגדרה היא Python 2, אז נשנה את זה על ידי עריכת השורה FROM מ-python:2-slim ל-python:3-slim או על ידי ביטול סימון כהערה (uncomment) בשורה העליונה ומחיקת השורה הישנה FROM. בסיום התהליך, התג Dockerfile אמור להיראות כך:

FROM python:3-slim
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
ENTRYPOINT ["python", "main.py"]

7. פריסת השירות

עכשיו אפשר לפרוס את שירות התרגום ב-Cloud Run על ידי הפעלת הפקודה הבאה:

gcloud run deploy translate --source . --allow-unauthenticated --platform managed

הפלט אמור להיראות כך, ולכלול כמה הנחיות לשלבים הבאים:

$ gcloud run deploy translate --source . --allow-unauthenticated --platform managed
Please specify a region:
 [1] asia-east1
 [2] asia-east2
. . . (other regions) . . .
 [28] us-west4
 [29] cancel
Please enter your numeric choice:  REGION_CHOICE

To make this the default region, run `gcloud config set run/region REGION`.

Deploying from source requires an Artifact Registry repository to
store build artifacts. A repository named [cloud-run-source-deploy] in
 region [REGION] will be created.

Do you want to continue (Y/n)?

This command is equivalent to running "gcloud builds submit --pack image=[IMAGE] ." and "gcloud run deploy translate --image [IMAGE]"

Building . . . and deploying container to Cloud Run service [translate] in project [PROJECT_ID] region [REGION]
✓ Building and deploying... Done.
  ✓ Creating Container Repository...
  ✓ Uploading sources...
  ✓ Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds/60e1b
  9bb-b991-4b4e-8d8a-HASH?project=PROJECT_NUMBER].
  ✓ Creating Revision...
  ✓ Routing traffic...
  ✓ Setting IAM Policy...
Done.
Service [translate] revision [translate-00001-xyz] has been deployed and is serving 100 percent of traffic.
Service URL: https://SVC_NAME-HASH-REG_ABBR.a.run.app

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

כדי לראות איך זה עובד, אפשר לתרגם משהו.

8. סיכום

מעולה! למדתם איך להפעיל את Cloud Translation API, לקבל את פרטי הכניסה הדרושים ולפרוס אפליקציית אינטרנט פשוטה ל-Python 3 Cloud Run.

הסרת המשאבים

‫Cloud Translation API מאפשר לכם לבצע מספר קבוע של תרגומים של תווים בחודש בחינם. ל-App Engine יש גם מכסת שימוש בחינם, וכך גם ל-Cloud Functions ול-Cloud Run. אם תחרגו מאחד מהם, תחויבו. אם אתם מתכננים להמשיך ל-codelab הבא, אתם לא צריכים לסגור את האפליקציה.

עם זאת, אם אתם לא מוכנים לעבור אל המדריך הבא או חוששים שהאינטרנט יגלה את האפליקציה שפרסתם זה עתה, תוכלו להשבית את אפליקציית App Engine, למחוק את Cloud Function או להשבית את שירות Cloud Run כדי להימנע מחיובים. כשרוצים לעבור אל ה-codelab הבא, אפשר להפעיל אותו מחדש. לעומת זאת, אם אתם לא מתכוונים להמשיך עם האפליקציה הזו או עם Codelabs אחרים ואתם רוצים למחוק הכול לגמרי, אתם יכולים לסגור את הפרויקט.

בנוסף, פריסה בפלטפורמת מחשוב ללא שרת (serverless) ב-Google Cloud כרוכה בעלויות קלות של בנייה ואחסון. ל-Cloud Build יש מכסת שימוש משלו בחינם, כמו גם ל-Cloud Storage. כדי לשפר את השקיפות, Cloud Build יוצר את קובץ האימג' של האפליקציה, שמאוחסן ב-Cloud Container Registry או ב-Artifact Registry, שמהווה את המחליף שלו. האחסון של התמונה הזו תופס חלק מהמכסה, וכך גם תעבורת נתונים יוצאת (egress) מהרשת כשמעבירים את התמונה לשירות. עם זאת, יכול להיות שאתם גרים באזור שבו אין תוכנית בחינם כזו, ולכן חשוב לעקוב אחרי השימוש בנפח האחסון הנדרש כדי לצמצם את העלויות הפוטנציאליות.

9. מקורות מידע נוספים

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

מחקר נוסף

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

כדי להריץ באופן מקומי או לפרוס בפלטפורמות מחשוב ללא שרת של Google Cloud, צריך להשלים את כל המהדורות האחרות של ה-codelab הזה (ראו repo README).
להשלים את המדריך הזה באמצעות שפת תכנות אחרת.
שינוי האפליקציה כך שתתמוך בשפות מקור או יעד שונות.
שדרג את האפליקציה הזו כדי שתוכל לתרגם טקסט ליותר משפה אחת. שנה את קובץ התבנית כך שיהיה בו תפריט נפתח של שפות יעד נתמכות.

מידע נוסף

Google App Engine

‫Google Cloud Functions

Google Cloud Run

‫Google Cloud Buildpacks, ‏ Container Registry, ‏ Artifact Registry

‫Google Cloud Translation ו-Google ML Kit

מוצרים או דפים אחרים של Google Cloud

‫Python ו-Flask

Flask

רישיון

המדריך הזה מורשה לשימוש במסגרת רישיון Creative Commons שמותנה בייחוס 2.0 Generic, בעוד שקוד המקור במאגר מורשה לשימוש במסגרת Apache 2.