Развертывание потоков с помощью Cloud Run

Вы можете развернуть потоки Genkit в качестве конечных точек HTTPS с помощью Cloud Run. Cloud Run имеет несколько вариантов развертывания, включая развертывание на основе контейнера; на этой странице объясняется, как развертывать потоки непосредственно из кода.

Прежде чем начать

  • Установите Google Cloud CLI .
  • Вы должны быть знакомы с концепцией потоков Genkit и тем, как их писать. На этой странице предполагается, что у вас уже есть потоки, которые вы хотите развернуть.
  • Это было бы полезно, но не обязательно, если вы уже использовали Google Cloud и Cloud Run раньше.

1. Настройте проект Google Cloud.

Если у вас еще не настроен проект Google Cloud, выполните следующие действия:

  1. Создайте новый проект Google Cloud с помощью консоли Cloud или выберите существующий.

  2. Свяжите проект с платежным аккаунтом, который необходим для Cloud Run.

  3. Настройте Google Cloud CLI для использования вашего проекта:

    gcloud init

2. Подготовьте проект Node к развертыванию.

Чтобы ваши потоки можно было развернуть, вам необходимо внести некоторые небольшие изменения в код проекта:

Добавьте сценарии запуска и сборки в package.json.

При развертывании проекта Node.js в Cloud Run инструменты развертывания ожидают, что у вашего проекта будет сценарий start и, при необходимости, сценарий build . Для типичного проекта TypeScript обычно достаточно следующих сценариев:

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

Добавьте код для настройки и запуска сервера потока.

В файле, запускаемом вашим start сценарием, добавьте вызов startFlowServer . Этот метод запустит сервер Express, настроенный для обслуживания ваших потоков в качестве конечных точек веб-сайта.

При совершении вызова укажите потоки, которые вы хотите обслуживать:

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

Вы также можете указать некоторые дополнительные параметры:

  • port : сетевой порт для прослушивания. Если не указано, сервер прослушивает порт, определенный в переменной среды PORT, а если PORT не установлен, по умолчанию используется значение 3400.
  • cors : политика CORS сервера потока. Если вы будете получать доступ к этим конечным точкам из веб-приложения, вам, вероятно, потребуется указать это.
  • pathPrefix : необязательный префикс пути, который нужно добавить перед конечными точками потока.
  • jsonParserOptions : параметры для передачи в анализатор тела JSON Express.

Необязательно: Определите политику авторизации.

Все развернутые потоки должны требовать той или иной формы авторизации; в противном случае ваши потенциально дорогостоящие генеративные потоки ИИ будут доступны кому угодно.

При развертывании потоков с помощью Cloud Run у вас есть два варианта авторизации:

  • Авторизация на основе Cloud IAM . Используйте встроенные средства управления доступом Google Cloud для ограничения доступа к вашим конечным точкам. Информацию о предоставлении этих учетных данных см. в разделе «Аутентификация» в документации Cloud Run.

  • Политика авторизации, определенная в коде . Используйте функцию политики авторизации потоков Genkit для проверки информации авторизации с помощью специального кода. Часто, но не обязательно, это авторизация на основе токенов.

Если вы хотите определить политику авторизации в коде, используйте параметр authPolicy в определении потока:

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

Параметр auth политики авторизации берется из свойства auth объекта запроса. Обычно это свойство устанавливается с помощью промежуточного программного обеспечения Express. См. Авторизация и целостность .

Сделайте учетные данные API доступными для развернутых потоков.

После развертывания вашим потокам потребуется какой-то способ аутентификации с любыми удаленными службами, от которых они зависят. Большинству потоков как минимум потребуются учетные данные для доступа к используемому ими сервису API модели.

В этом примере выполните одно из следующих действий в зависимости от выбранного вами поставщика модели:

Близнецы (ИИ Google)

  1. Убедитесь, что Google AI доступен в вашем регионе .

  2. Создайте ключ API для Gemini API с помощью Google AI Studio.

  3. Сделайте ключ API доступным в среде Cloud Run:

    1. В облачной консоли включите API Secret Manager .
    2. На странице «Менеджер секретов» создайте новый секрет, содержащий ваш ключ API.
    3. После создания секрета на той же странице предоставьте своей учетной записи вычислительной службы по умолчанию доступ к секрету с помощью роли Секретного доступа диспетчера секретов . (Имя учетной записи вычислительной службы по умолчанию можно найти на странице IAM.)

    На более позднем этапе, когда вы развернете службу, вам нужно будет указать имя этого секрета.

Близнецы (Vertex AI)

  1. В облачной консоли включите API Vertex AI для своего проекта.

  2. На странице IAM убедитесь, что учетной записи службы вычислений по умолчанию назначена роль пользователя Vertex AI .

Единственный секрет, который вам нужно настроить для этого руководства, — это поставщик модели, но в целом вы должны сделать что-то подобное для каждой службы, которую использует ваш поток.

3. Развертывание потоков в Cloud Run

Подготовив проект к развертыванию, вы можете развернуть его с помощью инструмента gcloud .

Близнецы (ИИ Google) 

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

Близнецы (Vertex AI) 

gcloud run deploy

Инструмент развертывания запросит у вас всю необходимую информацию.

Когда вас спросят, хотите ли вы разрешить неаутентифицированные вызовы:

  • Ответьте Y , если вы не используете IAM и вместо этого определили политику авторизации в коде.
  • Ответьте N , чтобы настроить службу на требование учетных данных IAM.

Необязательно: попробуйте развернутый поток

После завершения развертывания инструмент распечатает URL-адрес службы. Вы можете проверить это с помощью curl :

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