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

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

סדרת ה-codelabs הזו (מדריכים מעשיים וברמה עצמאית) נועדה לעזור למפתחים להבין את האפשרויות השונות שעומדות לרשותם בפריסה של האפליקציות שלהם. ב-codelab הזה תלמדו איך להשתמש ב-Google Cloud Translation API עם Python ולהריץ אותו באופן מקומי או לפרוס אותו בפלטפורמת מחשוב ללא שרת ב-Cloud (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)

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

כאן מוסבר איך

מה צריך להכין

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

סקר

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

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

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

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

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

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

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

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

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

96a9c957bc475304.png

b9a10ebdf5b5a448.png

a1e3c01a38fa61c2.png

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

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

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

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

יש הבדלים בחיוב של מוצרים שונים של 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

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

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

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

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, את 'נתיב המיקום' של ההורה לקריאות ל-Translation 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 שולח אובייקט בקשה של Flask משלו, ואילו כל שאר הפלטפורמות (שפועלות באופן מקומי או שנפרסות ב-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. הגדרת 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 או מבטלים את ההערה בשורה העליונה ומוחקים את השורה הישנה 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 שמכילה את מזהה הפרויקט, כפי שמוצג בפלט הפריסה:

169f6edf5f7d2068.png

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

31554e71cb80f1b4.png

8. סיכום

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

הסרת המשאבים

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

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

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

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

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

מחקר נוסף

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

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

מידע נוסף

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

רישיון

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