Beta: Firebase Genkit is in Beta, which means that it is not subject to any SLA or deprecation policy and could change in backwards-incompatible ways. Throughout the Beta period, Firebase Genkit and its documentation will be updated and improved.

Questa pagina è stata tradotta dall'API Cloud Translation.

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:

Crea un nuovo progetto Google Cloud utilizzando la console Cloud o scegline uno esistente.
Collega il progetto a un account di fatturazione, che è obbligatorio per Cloud Run.
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:

Gemini (IA di Google)

Assicurati che l'AI di Google sia disponibile nella tua regione.
Genera una chiave API per l'API Gemini utilizzando Google AI Studio.
Rendi disponibile la chiave API nell'ambiente Cloud Run:
1. Nella console Cloud, abilita l'API Secret Manager.
2. Nella pagina Secret Manager, crea un nuovo secret contenente la tua chiave API.
3. Dopo aver creato il secret, nella stessa pagina concedi all'account di servizio Compute predefinito l'accesso al secret con il ruolo Funzione di accesso ai secret di Secret Manager. Puoi cercare il nome dell'account di servizio di calcolo predefinito nella pagina IAM.
In un passaggio successivo, quando esegui il deployment del servizio, dovrai fare riferimento al nome di questo secret.

Gemini (Vertex AI)

Nella console Cloud, abilita l'API Vertex AI per il tuo progetto.
Nella pagina IAM, assicurati che all'account di servizio Compute predefinito sia stato concesso il ruolo Utente Vertex AI.

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.

3. Esegui il deployment dei flussi in Cloud Run

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

Gemini (IA di Google)

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

Gemini (Vertex AI)

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"}'