Wdróż podstawową wersję Tłumacza Google aplikacja w języku Python 2 Cloud Run (Docker)

1. Przegląd

Ta seria ćwiczeń z programowania (samodzielnych samouczków praktycznych) ma pomóc deweloperom w poznaniu różnych opcji wdrażania aplikacji. Z tego przewodnika dowiesz się, jak korzystać z interfejsu Google Cloud Translation API w Pythonie i uruchamiać go lokalnie lub wdrażać na bezserwerowej platformie obliczeniowej w chmurze (App Engine, Cloud Functions lub Cloud Run). Przykładową aplikację z repozytorium tego samouczka można wdrożyć na co najmniej 8 różnych sposobów, wprowadzając tylko niewielkie zmiany w konfiguracji:

Lokalny serwer Flask (Python 2)
Lokalny serwer Flask (Python 3)
App Engine (Python 2)
App Engine (Python 3)
Cloud Functions (Python 3)
Cloud Run (Python 2 przez Dockera)
Cloud Run (Python 3 przez Dockera)
Cloud Run (Python 3 za pomocą pakietów kompilacji Cloud Buildpacks)

Ten przewodnik skupia się na wdrażaniu tej aplikacji na wytłuszczonych platformach wymienionych powyżej.

Dowiesz się, jak:

korzystać z interfejsów Google Cloud API, w szczególności z Cloud Translation API (zaawansowanego/wersji 3);
Uruchamianie podstawowej aplikacji internetowej lokalnie lub wdrażanie jej na bezserwerowej platformie obliczeniowej w chmurze

Czego potrzebujesz

projekt Google Cloud z aktywnym kontem rozliczeniowym Cloud;
Zainstalowany Flask do uruchamiania lokalnego lub włączona bezserwerowa platforma obliczeniowa w chmurze do wdrożeń w chmurze.
podstawowe umiejętności w zakresie Pythona,
Praktyczna znajomość podstawowych poleceń systemu operacyjnego

Ankieta

Jak zamierzasz korzystać z tego samouczka?

Przeczytaj i wykonaj ćwiczenia

Przeczytaj

Jak oceniasz swoje doświadczenie z Pythonem?

Początkujący

Średnio zaawansowany

Zaawansowany

Jak oceniasz korzystanie z usług Google Cloud?

Początkujący

Średnio zaawansowany

Zaawansowany

2. Konfiguracja i wymagania

Samodzielne konfigurowanie środowiska

Zaloguj się w konsoli Google Cloud i utwórz nowy projekt lub użyj istniejącego. Jeśli nie masz jeszcze konta Gmail ani Google Workspace, musisz je utworzyć.

Nazwa projektu to wyświetlana nazwa uczestników tego projektu. Jest to ciąg znaków, który nie jest używany przez interfejsy API Google. Możesz go w dowolnym momencie zaktualizować.
Identyfikator projektu musi być unikalny we wszystkich projektach Google Cloud i jest niezmienny (nie można go zmienić po ustawieniu). Konsola Cloud automatycznie generuje unikalny ciąg znaków. Zwykle nie musisz się nim przejmować. W większości modułów z kodem musisz odwoływać się do identyfikatora projektu (zwykle oznaczanego jako PROJECT_ID). Jeśli Ci się nie podoba, wygeneruj inny losowy identyfikator lub spróbuj użyć własnego i sprawdź, czy jest dostępny. Po utworzeniu projektu jest on „zamrażany”.
Istnieje też trzecia wartość, czyli numer projektu, którego używają niektóre interfejsy API. Więcej informacji o tych 3 wartościach znajdziesz w dokumentacji.

Następnie musisz włączyć płatności w konsoli Cloud, aby korzystać z zasobów i interfejsów API Google Cloud. Ukończenie tego laboratorium nie powinno wiązać się z dużymi kosztami, a nawet z żadnymi. Aby wyłączyć zasoby i uniknąć naliczenia opłat po zakończeniu tego samouczka, postępuj zgodnie z instrukcjami „czyszczenia” na końcu ćwiczenia. Nowi użytkownicy Google Cloud mogą skorzystać z bezpłatnego okresu próbnego, w którym mają do dyspozycji środki w wysokości 300 USD.

3. Włączanie interfejsu Translation API

Włączanie interfejsów Cloud API

Z tej sekcji dowiesz się, jak włączyć interfejsy API Google. W przypadku naszej przykładowej aplikacji włączysz Cloud Translation API, Cloud Run i Cloud Artifact Registry.

Wprowadzenie

Niezależnie od tego, którego interfejsu Google API chcesz używać w swojej aplikacji, musi on być włączony. Poniższy przykład pokazuje 2 sposoby włączania interfejsu Cloud Vision API. Gdy dowiesz się, jak włączyć jeden interfejs Cloud API, będziesz w stanie włączyć inne interfejsy API, ponieważ proces jest podobny.

Opcja 1. W Cloud Shell lub interfejsie wiersza poleceń

Włączanie interfejsów API w konsoli Cloud jest bardziej powszechne, ale niektórzy programiści wolą wykonywać wszystkie czynności w wierszu poleceń. Aby to zrobić, musisz wyszukać „nazwę usługi” interfejsu API. Wygląda na adres URL: SERVICE_NAME.googleapis.com. Znajdziesz je w tabeli obsługiwanych usług lub możesz wysłać do nich zapytanie programowe za pomocą interfejsu Google Discovery API.

Mając te informacje, możesz włączyć interfejs API za pomocą Cloud Shell (lub lokalnego środowiska programistycznego z zainstalowanym gcloud narzędziem wiersza poleceń):

gcloud services enable SERVICE_NAME.googleapis.com

Na przykład to polecenie włącza interfejs Cloud Vision API:

gcloud services enable vision.googleapis.com

To polecenie włącza App Engine:

gcloud services enable appengine.googleapis.com

W jednym żądaniu możesz też włączyć kilka interfejsów API. Na przykład ten wiersz poleceń włącza Cloud Run, Cloud Artifact Registry i Cloud Translation API:

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

Opcja 2. Z poziomu konsoli Cloud

Możesz też włączyć Vision API w Menedżerze interfejsów API. W konsoli Cloud otwórz Menedżera interfejsów API i wybierz Biblioteka.

Jeśli chcesz włączyć interfejs Cloud Vision API, zacznij wpisywać „vision” na pasku wyszukiwania. Pojawią się wszystkie wyniki pasujące do wpisanego tekstu:

Wybierz interfejs API, który chcesz włączyć, i kliknij Włącz:

Koszt

Wiele interfejsów API Google można używać bezpłatnie, ale korzystanie z usług i interfejsów API Google Cloud nie jest bezpłatne. Podczas włączania interfejsów API Google Cloud możesz zostać poproszony(-a) o podanie aktywnego konta rozliczeniowego. Warto jednak pamiętać, że niektóre usługi Google Cloud mają bezpłatny poziom (dzienny lub miesięczny), który musisz przekroczyć, aby ponieść opłaty. W przeciwnym razie Twoja karta kredytowa (lub określony instrument płatniczy) nie zostanie obciążona.

Przed włączeniem interfejsu API użytkownicy powinni zapoznać się z informacjami o cenach, zwracając szczególną uwagę na to, czy jest on dostępny w ramach bezpłatnego poziomu, a jeśli tak, to w jakim zakresie. Jeśli włączasz interfejs Cloud Vision API, sprawdź informacje o cenach. Cloud Vision ma bezpłatny limit, więc jeśli w danym miesiącu nie przekroczysz go łącznie, nie poniesiesz żadnych opłat.

Ceny i bezpłatne wersje różnią się w zależności od interfejsu API Google. Przykłady:

Google Cloud/GCP – każda usługa jest rozliczana inaczej, zwykle na podstawie cyklu vCPU, zużycia pamięci, wykorzystania pamięci lub płatności za użycie. Informacje o poziomie bezpłatnym znajdziesz powyżej.
Mapy Google – obejmują zestaw interfejsów API i oferują użytkownikom bezpłatne środki o wartości 200 USD miesięcznie.
Interfejsy Google Workspace (dawniej G Suite) – zapewniają bezpłatne korzystanie (do określonych limitów) w ramach miesięcznej opłaty za subskrypcję Workspace, więc nie ma bezpośrednich opłat za korzystanie z interfejsów Gmaila, Dysku Google, Kalendarza, Dokumentów, Arkuszy i Prezentacji.

Różne usługi Google są rozliczane w różny sposób, dlatego zapoznaj się z dokumentacją interfejsu API, aby uzyskać te informacje.

Podsumowanie

Teraz, gdy wiesz już, jak włączyć interfejsy API Google, otwórz Menedżera interfejsów API i włącz Cloud Translation API, Cloud Run i Cloud Artifact Registry (jeśli jeszcze tego nie zrobiono). Włącz tę pierwszą opcję, ponieważ jest ona używana przez naszą aplikację. Włączasz tę drugą, ponieważ to w niej są przechowywane obrazy kontenerów przed wdrożeniem w celu uruchomienia usługi Cloud Run. Dlatego musisz ją włączyć. Jeśli wolisz włączyć je wszystkie za pomocą narzędzia gcloud, w terminalu wpisz to polecenie:

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

Chociaż miesięczny limit nie jest wymieniony na stronie podsumowania ogólnego poziomu „Zawsze bezpłatnie”, na stronie z cennikiem interfejsu Translation API jest podana stała miesięczna liczba przetłumaczonych znaków, którą otrzymują wszyscy użytkownicy. Jeśli nie przekroczysz tego progu, nie zostaną naliczone żadne opłaty za korzystanie z interfejsu API. Wszelkie inne opłaty związane z Google Cloud zostaną omówione na końcu w sekcji „Czyszczenie”.

4. Pobieranie kodu przykładowej aplikacji

Sklonuj kod z repozytorium lokalnie lub w Cloud Shell (za pomocą polecenia git clone) albo pobierz plik ZIP, klikając zielony przycisk Code (Kod), jak pokazano na tym zrzucie ekranu:

Teraz, gdy masz już wszystko, utwórz pełną kopię folderu, aby wykonać ten samouczek, ponieważ prawdopodobnie będziesz usuwać lub zmieniać pliki. Jeśli chcesz przeprowadzić inne wdrożenie, możesz zacząć od skopiowania oryginału, aby nie musieć go ponownie klonować ani pobierać.

5. Prezentacja przykładowej aplikacji

Przykładowa aplikacja to prosta pochodna Tłumacza Google, która prosi użytkowników o wpisanie tekstu w języku angielskim i wyświetla jego odpowiednik w języku hiszpańskim. Teraz otwórz plik main.py, aby zobaczyć, jak to działa. Po pominięciu wierszy z komentarzami dotyczącymi licencjonowania wygląda to tak:

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)))

Importy wprowadzają funkcje Flask, moduł google.auth i bibliotekę klienta Cloud Translation API.
Zmienne globalne reprezentują aplikację Flask, identyfikator projektu w chmurze, klienta interfejsu Translation API, ścieżkę nadrzędną „location path” dla wywołań interfejsu Translation API oraz języki źródłowy i docelowy. W tym przypadku są to języki angielski (en) i hiszpański (es), ale możesz zmienić te wartości na inne kody języków obsługiwanych przez Cloud Translation API.
Duży blok if u dołu jest używany w samouczku dotyczącym lokalnego uruchamiania tej aplikacji – wykorzystuje on serwer deweloperski Flask do obsługi naszej aplikacji. Ta sekcja jest też dostępna w samouczkach dotyczących wdrażania w Cloud Run na wypadek, gdyby serwer WWW nie był dołączony do kontenera. Pojawi się prośba o włączenie pakowania serwera w kontenerze, ale jeśli to pominiesz, kod aplikacji wróci do korzystania z serwera deweloperskiego Flask. Nie jest to problem z App Engine ani Cloud Functions, ponieważ są to platformy oparte na źródłach, co oznacza, że Google Cloud udostępnia i uruchamia domyślny serwer WWW.

W środku funkcji main.py znajduje się najważniejsza część aplikacji, czyli funkcja 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)

Główna funkcja przetwarza dane wejściowe użytkownika i wywołuje interfejs Translation API, aby wykonać większość pracy. Przyjrzyjmy się temu bliżej:

Sprawdź, czy żądania pochodzą z Cloud Functions, używając zmiennej local_request. Cloud Functions wysyła własny obiekt żądania Flask, natomiast wszystkie inne (działające lokalnie lub wdrażane w App Engine lub Cloud Run) otrzymują obiekt żądania bezpośrednio z Flask.
Zresetuj podstawowe zmienne formularza. Dotyczy to głównie żądań GET, ponieważ żądania POST będą zawierać dane, które je zastąpią.
Jeśli jest to żądanie POST, pobierz tekst do przetłumaczenia i utwórz strukturę JSON reprezentującą wymagania dotyczące metadanych interfejsu API. Następnie wywołaj interfejs API, a jeśli użytkownik korzysta ze starszej biblioteki, użyj poprzedniej wersji interfejsu API.
Niezależnie od tego sformatuj rzeczywiste wyniki (POST) lub brak danych (GET) w kontekście szablonu i wyrenderuj.

Część wizualna aplikacji znajduje się w pliku szablonu index.html. Wyświetla wcześniej przetłumaczone wyniki (w przeciwnym razie jest puste), a następnie formularz z prośbą o przetłumaczenie:

<!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. Wdrażanie usługi

Teraz możesz wdrożyć usługę tłumaczenia w Cloud Run, uruchamiając to polecenie:

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

Dane wyjściowe powinny wyglądać tak jak poniżej i zawierać kilka sugestii dotyczących kolejnych kroków:

$ 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

Teraz, gdy aplikacja jest dostępna na całym świecie, możesz uzyskać do niej dostęp pod adresem URL zawierającym identyfikator projektu, jak pokazano w wyniku wdrożenia:

Przetłumacz coś, aby zobaczyć, jak to działa.

7. Podsumowanie

Gratulacje! Dowiedzieliśmy się, jak włączyć interfejs Cloud Translation API, uzyskać niezbędne dane logowania i wdrożyć prostą aplikację internetową w Cloud Run w Pythonie 2. Więcej informacji o tym wdrożeniu znajdziesz w tej tabeli w repozytorium.

Czyszczenie danych

Interfejs Cloud Translation API umożliwia bezpłatne przetłumaczenie określonej liczby znaków miesięcznie. App Engine ma też bezpłatny limit, podobnie jak Cloud Functions i Cloud Run. Jeśli przekroczysz którykolwiek z tych limitów, zostaną naliczone opłaty. Jeśli planujesz przejść do następnych ćwiczeń, nie musisz zamykać aplikacji.

Jeśli nie chcesz jeszcze przechodzić do następnego samouczka lub obawiasz się, że internet odkryje właśnie wdrożoną aplikację, wyłącz aplikację App Engine, usuń funkcję w Cloud Functions lub wyłącz usługę Cloud Run, aby uniknąć naliczania opłat. Gdy zechcesz przejść do kolejnych ćwiczeń, możesz ponownie włączyć tę funkcję. Jeśli nie zamierzasz kontynuować pracy nad tą aplikacją ani innymi Codelabs i chcesz wszystko całkowicie usunąć, możesz wyłączyć projekt.

Wdrażanie na bezserwerowej platformie obliczeniowej Google Cloud wiąże się też z niewielkimi kosztami kompilacji i przechowywania. Cloud Build ma własny bezpłatny limit, podobnie jak Cloud Storage. Aby zapewnić większą przejrzystość, Cloud Build kompiluje obraz aplikacji, który jest następnie przechowywany w Cloud Container Registry lub w Artifact Registry, czyli w usłudze, która ją zastąpiła. Przechowywanie tego obrazu wykorzystuje część tego limitu, podobnie jak ruch wychodzący w sieci podczas przesyłania obrazu do usługi. Możesz jednak mieszkać w regionie, w którym nie ma takiego bezpłatnego pakietu, więc kontroluj wykorzystanie miejsca na dane, aby zminimalizować potencjalne koszty.

8. Dodatkowe materiały

W kolejnych sekcjach znajdziesz dodatkowe materiały do czytania oraz zalecane ćwiczenia, które pomogą Ci poszerzyć wiedzę zdobytą podczas tego samouczka.

Dodatkowe materiały

Masz już pewne doświadczenie w korzystaniu z interfejsu Translation API, więc wykonajmy kilka dodatkowych ćwiczeń, aby jeszcze bardziej rozwinąć Twoje umiejętności. Aby kontynuować ścieżkę szkoleniową, zmodyfikuj naszą przykładową aplikację w ten sposób:

Wykonaj wszystkie pozostałe wersje tego laboratorium, aby uruchomić je lokalnie lub wdrożyć na bezserwerowych platformach obliczeniowych Google Cloud (patrz plik README repozytorium).
Ukończ ten samouczek, korzystając z innego języka programowania.
Zmień tę aplikację, aby obsługiwała inne języki źródłowe lub docelowe.
Uaktualnij tę aplikację, aby można było tłumaczyć tekst na więcej niż 1 język. Zmień plik szablonu, aby zawierał menu obsługiwanych języków docelowych.

Więcej informacji

Google App Engine

Google Cloud Functions

Google Cloud Run

Google Cloud Buildpacks, Container Registry, Artifact Registry

Google Cloud Translation i Google ML Kit

Inne usługi i strony Google Cloud

Python i Flask

Flask

Licencja

Ten samouczek jest licencjonowany na podstawie ogólnej licencji Creative Commons Uznanie autorstwa 2.0, a kod źródłowy w repozytorium jest licencjonowany na podstawie licencji Apache 2.