Wdrażanie procesów za pomocą Cloud Run

Możesz wdrażać przepływy Genkit jako punkty końcowe HTTPS za pomocą Cloud Run. Cloud Run oferuje kilka opcji wdrażania, w tym wdrażanie na podstawie kontenera. Na tej stronie wyjaśniamy, jak wdrażać przepływy bezpośrednio z kodu.

Zanim zaczniesz

  • Zainstaluj interfejs wiersza poleceń Google Cloud.
  • Musisz znać pojęcie przepływów w Genkit i wiedzieć, jak je pisać. Na tej stronie zakładamy, że masz już przepływy, które chcesz wdrożyć.
  • Przydatne, choć nieobowiązkowe, może być wcześniejsze korzystanie z Google Cloud i Cloud Run.

1. Konfigurowanie projektu Google Cloud

Jeśli nie masz jeszcze skonfigurowanego projektu Google Cloud, wykonaj te czynności:

  1. Utwórz nowy projekt Google Cloud za pomocą konsoli Cloud lub wybierz istniejący.

  2. Połącz projekt z kontem rozliczeniowym, co jest wymagane w przypadku Cloud Run.

  3. Skonfiguruj Google Cloud CLI do korzystania z Twojego projektu:

    gcloud init

2. Przygotowanie projektu Node do wdrożenia

Aby móc wdrażać przepływy, musisz wprowadzić w kodzie projektu kilka drobnych zmian:

Dodawanie skryptów startowych i kompilacji do pliku package.json

Podczas wdrażania projektu Node.js do Cloud Run narzędzia do wdrażania oczekują, że projekt będzie zawierać skrypt start i opcjonalnie skrypt build. W przypadku typowego projektu TypeScript zwykle wystarczają te skrypty:

"scripts": {
  "start": "node lib/index.js",
  "build": "tsc"
},

Dodaj kod do konfigurowania i uruchamiania serwera przepływu

W pliku, który jest uruchamiany przez skrypt start, dodaj wywołanie funkcji startFlowServer. Ta metoda uruchamia serwer Express, który służy do obsługi przepływów jako punktów końcowych sieci.

Podczas wywołania określ przepływy, które mają być obsługiwane:

Dostępne są też:

import { startFlowServer } from '@genkit-ai/express';

startFlowServer({
  flows: [menuSuggestionFlow],
});

Możesz też określić kilka opcjonalnych parametrów:

  • port: port sieciowy, na którym ma nasłuchiwać. Jeśli nie określono inaczej, serwer nasłuchuje na porcie określonym w zmiennej środowiskowej PORT. Jeśli zmienna PORT nie jest ustawiona, domyślnie jest to port 3400.
  • cors: zasady CORS serwera przepływu. Jeśli będziesz uzyskiwać dostęp do tych punktów końcowych z aplikacji internetowej, prawdopodobnie musisz to określić.
  • pathPrefix: opcjonalny prefiks ścieżki do dodania przed punktami końcowymi przepływu.
  • jsonParserOptions: opcje przekazywane do parsera treści w formacie JSON Expressa.

Opcjonalnie: zdefiniuj zasady autoryzacji

Wszystkie wdrożone przepływy powinny wymagać autoryzacji. W przeciwnym razie drogie przepływy generatywne AI będą mogły być wywoływane przez dowolną osobę.

Podczas wdrażania przepływów w Cloud Run masz do wyboru 2 opcje autoryzacji:

  • Autoryzacja na podstawie uprawnień Cloud IAM: użyj natywnych funkcji zarządzania dostępem w Google Cloud, aby ograniczyć dostęp do punktów końcowych. Informacje o podaniu tych danych znajdziesz w sekcji Uwierzytelnianie w dokumentacji Cloud Run.

  • Zasady autoryzacji zdefiniowane w kodzie: użyj funkcji zasad autoryzacji w pluginie Genkit Express, aby zweryfikować informacje autoryzacyjne za pomocą kodu niestandardowego. Często, ale nie zawsze, jest to autoryzacja na podstawie tokena.

Jeśli chcesz zdefiniować zasady autoryzacji w kodzie, użyj parametru authPolicy w definicji przepływu:

// middleware for handling auth tokens in headers.
const authMiddleware = async (req, resp, next) => {
  // parse auth headers and convert to auth object.
  (req as RequestWithAuth).auth = {
    user: await verifyAuthToken(req.header('authorization')),
  };
  next();
};

app.post(
  '/simpleFlow',
  authMiddleware,
  expressHandler(simpleFlow, {
    authPolicy: ({ auth }) => {
      if (!auth.user) {
        throw new Error('not authorized');
      }
    },
  })
);

Parametr auth zasad autoryzacji pochodzi z właściwości auth obiektu żądania. Zwykle ustawiasz tę właściwość za pomocą pośrednika Express. Zobacz Autoryzacja i integralność.

Więcej informacji znajdziesz w dokumentacji wtyczki Express.

Udostępnianie danych logowania interfejsu API wdrożonym przepływom

Po wdrożeniu procesy muszą mieć możliwość uwierzytelniania się w usługach zdalnych, z których korzystają. Większość przepływów wymaga co najmniej danych logowania do interfejsu API modelu, z którego korzystają.

W tym przykładzie wykonaj jedną z tych czynności w zależności od wybranego dostawcy modelu:

Gemini (Google AI)

  1. Upewnij się, że Google AI jest dostępny w Twoim regionie.

  2. Wygeneruj klucz interfejsu API dla Gemini API za pomocą Google AI Studio.

  3. Udostępnij klucz API w środowisku Cloud Run:

    1. W konsoli Cloud włącz interfejs Secret Manager API.
    2. Na stronie Menedżer tajnych kluczy utwórz nowy tajny klucz zawierający klucz interfejsu API.
    3. Po utworzeniu obiektu tajnego na tej samej stronie przyznaj domyślnemu kontu usługi obliczeń dostęp do obiektu tajnego przy użyciu roli Uzyskujący dostęp do obiektów tajnych w Menedżerze obiektów tajnych. (nazwa domyślnego konta usługi obliczeniowej jest dostępna na stronie Uprawnienia).

    W późniejszym kroku, podczas wdrażania usługi, musisz odwołać się do nazwy tego obiektu tajnego.

Gemini (Vertex AI)

  1. W konsoli Cloud włącz interfejs Vertex AI API w projekcie.

  2. Na stronie Uprawnienia sprawdź, czy domyślnemu kontu usługi obliczeniowej przypisano rolę Użytkownik Vertex AI.

W tym samouczku musisz skonfigurować tylko jeden sekret – dla dostawcy modelu. Ogólnie jednak musisz wykonać podobne czynności w przypadku każdej usługi używanej przez przepływ danych.

3. Wdrażanie procesów w Cloud Run

Gdy przygotujesz projekt do wdrożenia, możesz go wdrożyć za pomocą narzędzia gcloud.

Gemini (Google AI)

gcloud run deploy --update-secrets=GOOGLE_GENAI_API_KEY=<your-secret-name>:latest

Gemini (Vertex AI)

gcloud run deploy

Narzędzie do wdrażania poprosi Cię o wszystkie wymagane informacje.

Gdy pojawi się pytanie, czy chcesz zezwolić na nieuwierzytelnione wywołania:

  • Odpowiedz Y, jeśli nie używasz usługi IAM, a zamiast tego zdefiniujesz w kodzie zasady autoryzacji.
  • Odpowiedz N, aby skonfigurować usługę tak, aby wymagała danych uwierzytelniających IAM.

Opcjonalnie: wypróbuj wdrożony proces

Po zakończeniu wdrażania narzędzie wydrukuje adres URL usługi. Możesz przetestować curl:

curl -X POST https://<service-url>/menuSuggestionFlow \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -H "Content-Type: application/json" -d '{"data": "banana"}'