פריסת "Google Translate" app ב-Python 2 Cloud Run (Docker)

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

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

  1. שרת Flask מקומי (Python 2)
  2. שרת Flask מקומי (Python 3)
  3. App Engine (Python 2)
  4. App Engine (Python 3)
  5. Cloud Functions (Python 3)
  6. Cloud Run (Python 2 דרך Docker)
  7. Cloud Run (Python 3 דרך Docker)
  8. Cloud Run (Python 3 דרך Cloud Buildpacks)

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

כאן מוסבר איך

מה צריך להכין

  • פרויקט ב-Google Cloud עם חשבון פעיל לחיוב ב-Cloud
  • בקבוקון שמותקן להפעלה מקומית, או פלטפורמת מחשוב ללא שרת (Cloud) שהופעלה לפריסות מבוססות-ענן
  • מיומנויות בסיסיות ב-Python
  • ידע בעבודה עם פקודות בסיסיות במערכת הפעלה

סקר

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

לקרוא אותו ולבצע את התרגילים קריאה בלבד

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

מתחילים בינונית בקיאים

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

מתחילים בינונית בקיאים

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

הגדרת סביבה בקצב עצמאי

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

96a9c957bc475304.png

b9a10ebdf5b5a448.png

a1e3c01a38fa61c2.png

  • Project name הוא השם המוצג של המשתתפים בפרויקט. זו מחרוזת תווים שלא נעשה בה שימוש ב-Google APIs, ואפשר לעדכן אותה בכל שלב.
  • Project ID חייב להיות ייחודי בכל הפרויקטים ב-Google Cloud ואי אפשר לשנות אותו (אי אפשר לשנות אותו אחרי שמגדירים אותו). מסוף Cloud יוצר מחרוזת ייחודית באופן אוטומטי; בדרך כלל לא מעניין אותך מה זה. ברוב ה-Codelabs תצטרכו להפנות אל מזהה הפרויקט (ובדרך כלל הוא מזוהה כ-PROJECT_ID), כך שאם הוא לא מוצא חן בעיניכם, תוכלו ליצור פרויקט אקראי אחר או לנסות בעצמכם ולבדוק אם הוא זמין. ואז המכשיר 'קפוא' לאחר יצירת הפרויקט.
  • יש ערך שלישי, Project Number, שחלק מממשקי ה-API משתמשים בו. מידע נוסף על כל שלושת הערכים האלה זמין במסמכי התיעוד.
  1. בשלב הבא צריך להפעיל את החיוב במסוף Cloud כדי להשתמש במשאבים או בממשקי API של Cloud. מעבר ב-Codelab הזה לא אמור לעלות הרבה, אם בכלל. כדי להשבית את המשאבים ולא לצבור חיובים מעבר למדריך הזה, פועלים לפי ההנחיות למחיקת המשאבים. בסוף ה-Codelab. משתמשים חדשים ב-Google Cloud זכאים להצטרף לתוכנית תקופת ניסיון בחינם בשווי 1,200 ש"ח.

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 או מממשק שורת הפקודה (CLI)

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

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

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

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

fb0f1d315f122d4a.png

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

2275786a24f8f204.png

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

2556f923b628e31.png

עלות

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

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

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

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

סיכום

עכשיו, אחרי שהבנתם איך להפעיל את Google APIs באופן כללי, עברו אל 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

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

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

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

5cd6110c4414cf65.png

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

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)))
  1. הייבוא כולל את הפונקציונליות של Flask, את המודול google.auth ואת ספריית הלקוח של Cloud Translation API.
  2. המשתנים הגלובליים מייצגים את אפליקציית Flask, את מזהה הפרויקט ב-Cloud, את לקוח Translation API, את 'נתיב המיקום' ההורה עבור קריאות ל-Translate API, ועם שפות המקור והיעד. במקרה הזה השפה היא אנגלית (en) וספרדית (es), אבל אפשר לשנות את הערכים האלה לקודים של שפות אחרות שנתמכות על ידי Cloud Translation API.
  3. הבלוק הגדול 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 כדי לבצע את העבודה הקשה. נסביר קצת:

  1. כדי לבדוק אם בקשות מגיעות מ-Cloud Functions, משתמשים במשתנה local_request. שירות Cloud Functions שולח ב-אובייקט Falask Request משלו, וכל שאר האובייקטים (שפועלים באופן מקומי או נפרסים ב-App Engine או ב-Cloud Run) יקבלו את אובייקט הבקשה ישירות מ-Flask.
  2. מאפסים את המשתנים הבסיסיים של הטופס. מדובר בעיקר בבקשות GET כי בבקשות POST יהיו נתונים שיחליפו אותן.
  3. אם מדובר ב-POST, צריך לשלוף את הטקסט לתרגום וליצור מבנה JSON שמייצג את דרישת המטא-נתונים של ה-API. לאחר מכן קוראים ל-API, וחוזרים לגרסה קודמת של ה-API אם המשתמש משתמש בספרייה ישנה יותר.
  4. בכל מקרה, צריך לעצב את התוצאות בפועל (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. פריסת השירות

עכשיו אתם מוכנים לפרוס את שירות התרגום ב-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 שמכילה את מזהה הפרויקט, כפי שמוצג בפלט הפריסה:

169f6edf5f7d2068.png

כדאי לתרגם משהו כדי לראות שהוא עובד!

31554e71cb80f1b4.png

7. סיכום

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

הסרת המשאבים

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

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

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

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

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

מחקר נוסף

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

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

מידע נוסף

Google App Engine

פונקציות Google Cloud

Google Cloud Run

Google Cloud Buildpacks, Container Registry, Artifact Registry

תרגום של Google Cloud וערכת למידת מכונה של Google

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

Python ו-Flask

רישיון

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