Esegui il deployment dei flussi utilizzando Cloud Run

Puoi eseguire il deployment dei flussi Genkit come endpoint HTTPS utilizzando Cloud Run. Cloud Run offre diverse opzioni di deployment, tra cui il deployment basato su container. In questa pagina viene spiegato come eseguire il deployment dei flussi direttamente dal codice.

Prima di iniziare

• Installa Google Cloud CLI.
• Dovresti conoscere il concetto di flussi di Genkit e come scriverli. Questa pagina presuppone che tu abbia già i flussi che vuoi eseguire.
• Sarebbe utile, ma non obbligatorio, se avessi già utilizzato Google Cloud e Cloud Run.

1. Configura un progetto Google Cloud

Se non hai ancora configurato un progetto Google Cloud, segui questi passaggi:

1. Crea un nuovo progetto Google Cloud utilizzando la console Cloud o scegline uno esistente.

2. Collega il progetto a un account di fatturazione, che è obbligatorio per Cloud Run.

3. Configura Google Cloud CLI in modo da utilizzare il tuo progetto:

   gcloud init

2. Preparare il progetto Node per il deployment

Affinché i flussi siano dispiegabili, dovrai apportare alcune piccole modifiche al codice del progetto:

Aggiungere script di avvio e compilazione a package.json

Quando esegui il deployment di un progetto Node.js in Cloud Run, gli strumenti di deployment si aspettano che il progetto abbia uno script start e, facoltativamente, uno script build. Per un progetto TypeScript tipico, in genere sono sufficienti i seguenti script:

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

Aggiungi il codice per configurare e avviare il server di flusso

Nel file eseguito dallo script start, aggiungi una chiamata a startFlowServer. Questo metodo avvia un server Express configurato per pubblicare i flussi come endpoint web.

Quando effettui la chiamata, specifica i flussi che vuoi pubblicare:

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

Esistono anche alcuni parametri facoltativi che puoi specificare:

• port: la porta di rete su cui ascoltare. Se non specificato, il server rimane in ascolto sulla porta definita nella variabile di ambiente PORT e, se PORT non è impostata, il valore predefinito è 3400.
• cors: il criterio CORS del server di flusso. Se accederai a questi endpoint da un'applicazione web, probabilmente dovresti specificarlo.
• pathPrefix: un prefisso del percorso facoltativo da aggiungere prima degli endpoint del flusso.
• jsonParserOptions: opzioni da passare al parser del corpo JSON di Express

(Facoltativo) Definisci un criterio di autorizzazione

Tutti i flussi di IA generativa di cui è stato eseguito il deployment devono richiedere una qualche forma di autorizzazione, altrimenti i flussi di IA generativa potenzialmente costosi potrebbero essere invocati da chiunque.

Quando esegui il deployment dei flussi con Cloud Run, hai due opzioni per l'autorizzazione:

• Autorizzazione basata su Cloud IAM: utilizza le funzionalità di gestione dell'accesso native di Google Cloud per controllare l'accesso ai tuoi endpoint. Per informazioni su come fornire queste credenziali, consulta la sezione Autenticazione nella documentazione di Cloud Run.

• Criterio di autorizzazione definito nel codice: utilizza la funzionalità dei criteri di autorizzazione dei flussi Genkit per verificare le informazioni di autorizzazione utilizzando codice personalizzato. Spesso, ma non necessariamente, si tratta di un'autorizzazione basata su token.

Se vuoi definire un criterio di autorizzazione nel codice, utilizza il parametro authPolicy nella definizione del flusso:

const myFlow = ai.defineFlow(
  {
    name: "myFlow",
    authPolicy: (auth, input) => {
      if (!auth) {
        throw new Error("Authorization required.");
      }
      // Custom checks go here...
    },
  },
  async () => {
    // ...
  }
);

Il parametro auth del criterio di autorizzazione proviene dalla proprietà auth dell'oggetto richiesta. In genere, questa proprietà viene impostata utilizzando il middleware Express. Consulta Autorizzazione e integrità.

Rendi disponibili le credenziali API per i flussi di cui è stato eseguito il deployment

Una volta implementati, i flussi devono avere un modo per autenticarsi con i servizi remoti su cui si basano. La maggior parte dei flussi richiederà almeno le credenziali per accedere al servizio API model che utilizzano.

Per questo esempio, esegui una delle seguenti operazioni, a seconda del fornitore di modelli scelto:

L'unico segreto che devi configurare per questo tutorial è per il provider del modello, ma in generale devi eseguire un'operazione simile per ogni servizio utilizzato dal flusso.

4. Esegui il deployment dei flussi in Cloud Run

Dopo aver preparato il progetto per il deployment, puoi eseguirlo utilizzando lo strumento gcloud.

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

gcloud run deploy

Lo strumento di implementazione ti chiederà le informazioni necessarie.

Quando ti viene chiesto se vuoi consentire chiamate non autenticate:

• Rispondi Y se non utilizzi IAM e hai definito un criterio di autorizzazione nel codice.
• Rispondi N per configurare il servizio in modo che richieda le credenziali IAM.

(Facoltativo) Prova il flusso di cui è stato eseguito il deployment

Al termine del deployment, lo strumento stampa l'URL del servizio. Puoi testarlo con curl:

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