Men-deploy alur menggunakan Cloud Run

Anda dapat men-deploy flow Genkit sebagai endpoint HTTPS menggunakan Cloud Run. Cloud Run memiliki beberapa opsi deployment, termasuk deployment berbasis container; halaman ini akan menjelaskan cara men-deploy alur Anda langsung dari kode.

Sebelum memulai

  • Instal Google Cloud CLI.
  • Anda harus memahami konsep alur Genkit, dan cara menulisnya. Halaman ini mengasumsikan bahwa Anda sudah memiliki alur yang ingin di-deploy.
  • Akan sangat membantu, tetapi tidak diwajibkan, jika Anda sudah pernah menggunakan Google Cloud dan Cloud Run sebelumnya.

1. Menyiapkan project Google Cloud

Jika Anda belum menyiapkan project Google Cloud, ikuti langkah-langkah berikut:

  1. Buat project Google Cloud baru menggunakan Konsol Cloud atau pilih yang sudah ada.

  2. Tautkan project ke akun penagihan, yang diperlukan untuk Cloud Run.

  3. Konfigurasikan Google Cloud CLI untuk menggunakan project Anda:

    gcloud init

2. Menyiapkan project Node untuk deployment

Agar alur dapat di-deploy, Anda harus melakukan beberapa perubahan kecil pada kode project:

Menambahkan skrip mulai dan build ke package.json

Saat men-deploy project Node.js ke Cloud Run, alat deployment mengharapkan project Anda memiliki skrip start dan, secara opsional, skrip build. Untuk project TypeScript biasa, skrip berikut biasanya memadai:

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

Menambahkan kode untuk mengonfigurasi dan memulai server flow

Dalam file yang dijalankan oleh skrip start, tambahkan panggilan ke startFlowServer. Metode ini akan memulai server Express yang disiapkan untuk menayangkan flow Anda sebagai endpoint web.

Saat melakukan panggilan, tentukan flow yang ingin ditayangkan:

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

Ada juga beberapa parameter opsional yang dapat Anda tentukan:

  • port: port jaringan yang akan diproses. Jika tidak ditentukan, server akan memproses port yang ditentukan dalam variabel lingkungan PORT, dan jika PORT tidak ditetapkan, defaultnya adalah 3400.
  • cors: Kebijakan CORS server flow. Jika akan mengakses endpoint ini dari aplikasi web, Anda mungkin perlu menentukannya.
  • pathPrefix: awalan jalur opsional yang akan ditambahkan sebelum endpoint alur Anda.
  • jsonParserOptions: opsi yang akan diteruskan ke parser isi JSON Express

Opsional: Menentukan kebijakan otorisasi

Semua alur yang di-deploy harus memerlukan beberapa bentuk otorisasi; jika tidak, alur AI generatif Anda yang berpotensi mahal dapat dipanggil oleh siapa saja.

Saat men-deploy alur dengan Cloud Run, Anda memiliki dua opsi untuk otorisasi:

  • Otorisasi berbasis Cloud IAM: Gunakan fasilitas pengelolaan akses native Google Cloud untuk mengontrol akses ke endpoint Anda. Lihat Autentikasi di dokumen Cloud Run untuk mengetahui informasi tentang cara memberikan kredensial ini.

  • Kebijakan otorisasi yang ditentukan dalam kode: Gunakan fitur kebijakan otorisasi alur Genkit untuk memverifikasi info otorisasi menggunakan kode kustom. Hal ini sering kali, tetapi tidak selalu, berupa otorisasi berbasis token.

Jika Anda ingin menentukan kebijakan otorisasi dalam kode, gunakan parameter authPolicy dalam definisi alur:

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

Parameter auth kebijakan otorisasi berasal dari properti auth objek permintaan. Anda biasanya menetapkan properti ini menggunakan middleware Express. Lihat Otorisasi dan integritas.

Menyediakan kredensial API untuk alur yang di-deploy

Setelah di-deploy, alur Anda memerlukan beberapa cara untuk melakukan autentikasi dengan layanan jarak jauh yang menjadi andalannya. Sebagian besar alur setidaknya akan memerlukan kredensial untuk mengakses layanan API model yang mereka gunakan.

Untuk contoh ini, lakukan salah satu hal berikut, bergantung pada penyedia model yang Anda pilih:

Gemini (AI Google)

  1. Pastikan AI Google tersedia di region Anda.

  2. Buat kunci API untuk Gemini API menggunakan Google AI Studio.

  3. Sediakan kunci API di lingkungan Cloud Run:

    1. Di Konsol Cloud, aktifkan Secret Manager API.
    2. Di halaman Secret Manager, buat secret baru yang berisi kunci API Anda.
    3. Setelah Anda membuat secret, di halaman yang sama, berikan akses akun layanan komputasi default ke secret tersebut dengan peran Secret Manager Secret Accessor. (Anda dapat mencari nama akun layanan komputasi default di halaman IAM.)

    Pada langkah selanjutnya, saat men-deploy layanan, Anda harus mereferensikan nama secret ini.

Gemini (Vertex AI)

  1. Di Konsol Cloud, Aktifkan API Vertex AI untuk project Anda.

  2. Di halaman IAM, pastikan bahwa Akun layanan komputasi default diberikan peran Vertex AI User.

Satu-satunya secret yang perlu Anda siapkan untuk tutorial ini adalah untuk penyedia model, tetapi secara umum, Anda harus melakukan hal serupa untuk setiap layanan yang digunakan oleh flow Anda.

3. Men-deploy alur ke Cloud Run

Setelah menyiapkan project untuk di-deploy, Anda dapat men-deploynya menggunakan alat gcloud.

Gemini (AI Google)

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

Gemini (Vertex AI)

gcloud run deploy

Alat deployment akan meminta informasi yang diperlukan.

Saat ditanya apakah Anda ingin mengizinkan pemanggilan yang tidak diautentikasi:

  • Jawab Y jika Anda tidak menggunakan IAM dan sebagai gantinya telah menentukan kebijakan otorisasi dalam kode.
  • Jawab N untuk mengonfigurasi layanan Anda agar memerlukan kredensial IAM.

Opsional: Mencoba alur yang di-deploy

Setelah deployment selesai, alat akan mencetak URL layanan. Anda dapat mengujinya dengan curl:

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