Как использовать серверную конфигурацию Remote Config с Cloud Functions и платформой агентов

В этом руководстве рассказывается, как начать использовать Cloud Functions второго поколения с Remote Config на стороне сервера, чтобы выполнять вызовы Agent Platform Gemini API (formerly Vertex AI) на стороне сервера.

В этом руководстве вы добавите Remote Config в функцию чат-бота, которая использует модель Gemini для ответов на вопросы пользователей. Remote Config будет управлять входными данными Gemini API (включая подсказку, которую вы добавите к входящим запросам пользователей). Вы сможете обновлять эти входные данные по запросу в консоли Firebase. Вы также будете использовать Firebase Local Emulator Suite для тестирования и отладки функции, а затем, убедившись, что она работает, развернете и протестируете ее в Google Cloud.

Требования

Предполагается, что вы умеете разрабатывать приложения на JavaScript.

Как настроить проект Firebase

Если у вас нет проекта Firebase:

  1. Войдите в консоль Firebase.

  2. Нажмите Создать проект и выберите один из следующих вариантов:

    • Вариант 1. Создайте новый проект Firebase (и автоматически связанный с ним проект Google Cloud), указав название нового проекта на первом шаге создания проекта.
    • Вариант 2. Добавьте Firebase в существующий проект Google Cloud, выбрав его Google Cloud название в раскрывающемся меню на первом шаге создания проекта.

  3. Когда появится запрос, вам не нужно настраивать Google Analytics, чтобы использовать это решение.

  4. Следуйте инструкциям на экране, чтобы создать проект.

Если у вас уже есть проект Firebase:

Перейдите к разделу Настройте среду разработки.

Как настроить среду разработки

Для написания функций вам понадобится среда Node.js, а для их развертывания в среде выполнения Cloud Functions – интерфейс командной строки Firebase.

  1. Установите Node.js и npm.

    Для установки Node.js и npm рекомендуем использовать Node Version Manager.

  2. Установите CLI Firebase удобным для вас способом. Например, чтобы установить CLI с помощью npm, выполните следующую команду:

    npm install -g firebase-tools@latest

    Эта команда устанавливает глобально доступную команду firebase. Если команда не сработает, возможно, вам потребуется изменить разрешения npm.

    Чтобы обновить firebase-tools до последней версии, выполните ту же команду.

  3. Установите firebase-functions и firebase-admin и используйте --save, чтобы сохранить их в package.json:

    npm install firebase-functions@latest firebase-admin@latest --save

Теперь вы готовы к реализации этого решения.

Реализация

Чтобы создать, протестировать и развернуть функцию Cloud Functions второго поколения с помощью Remote Config и Agent Platform, выполните следующие действия:

  1. Включите Agent Platform рекомендуемых API в консоли Google Cloud.
  2. Инициализируйте проект и установите зависимости Node.
  3. Настройте разрешения IAM для сервисного аккаунта Admin SDK и сохраните ключ.
  4. Создайте функцию.
  5. Создайте шаблон Remote Config для сервера.
  6. Разверните функцию и протестируйте ее в Firebase Local Emulator Suite.
  7. Разверните функцию в Google Cloud.

Шаг 1. Включите рекомендуемые API Agent Platform в консоли Google Cloud

  1. Откройте консоль Google Cloud и выберите проект.
  2. В поле Поиск в верхней части консоли введите Agent Platform и дождитесь, пока в результатах появится Agent Platform.
  3. Нажмите на значок Agent Platform. Откроется панель управления Agent Platform.

  4. Нажмите Enable All Recommended APIs (Включить все рекомендуемые API).

    Включение API может занять некоторое время. Не закрывайте страницу, пока процесс не завершится.

  5. Если платежные функции не включены, вам будет предложено добавить или связать аккаунт Cloud Billing. После включения платежного аккаунта вернитесь на панель управления Agent Platform и убедитесь, что все рекомендуемые API включены.

Шаг 2. Инициализируйте проект и установите зависимости Node

  1. Откройте терминал на компьютере и перейдите в каталог, в котором вы планируете создать функцию.

  2. Войдите в Firebase.

    firebase login

  3. Чтобы инициализировать Cloud Functions for Firebase, выполните следующую команду:

    firebase init functions

  4. Выберите Использовать существующий проект и укажите идентификатор проекта.

  5. Когда вам будет предложено выбрать язык, укажите Javascript и нажмите Ввод.

  6. Для всех остальных параметров выберите значения по умолчанию.

    В текущем каталоге будет создан каталог functions. Внутри вы найдете файл index.js, который будете использовать для создания функции, каталог node_modules, содержащий зависимости для функции, и файл package.json, содержащий зависимости пакета.

  7. Добавьте пакеты Admin SDK и Agent Platform, выполнив следующие команды. Используйте --save, чтобы сохранить их в файле package.json:

    cd functions
npm install firebase-admin@latest @google-cloud/vertexai --save

Теперь файл functions/package.json должен выглядеть следующим образом (с указанием последних версий):

  {
    "name": "functions",
    "description": "Cloud Functions for Firebase",
    "scripts": {
      "serve": "firebase emulators:start --only functions",
      "shell": "firebase functions:shell",
      "start": "npm run shell",
      "deploy": "firebase deploy --only functions",
      "logs": "firebase functions:log"
    },
    "engines": {
      "node": "20"
    },
    "main": "index.js",
    "dependencies": {
      "@google-cloud/vertexai": "^1.1.0",
      "firebase-admin": "^12.1.0",
      "firebase-functions": "^5.0.0"
    },
    "devDependencies": {
      "firebase-functions-test": "^3.1.0"
    },
    "private": true
  }

Если вы используете ESLint, вы увидите строфу, которая его включает. Кроме того, убедитесь, что версия node engine соответствует установленной версии Node.js и версии, которая в конечном итоге будет запущена в Google Cloud. Например, если в разделе engines файла package.json указана версия Node 18, а вы используете Node.js 20, обновите файл, чтобы использовать версию 20:

  "engines": {
    "node": "20"
  },

Шаг 3. Настройте разрешения IAM для сервисного аккаунта Admin SDK и сохраните ключ

В этом решении для запуска функции вы будете использовать сервисный аккаунт Firebase Admin SDK.

  1. В консоли Google Cloud откройте страницу IAM & Admin (IAM и администрирование) и найдите сервисный аккаунт Admin SDK (с названием firebase-adminsdk).
  2. Выберите аккаунт и нажмите Изменить субъект. Откроется страница "Права на редактирование".
  3. Нажмите Добавить роль и выберите Remote Config Viewer (Читатель ).
  4. Нажмите Добавить другую роль и выберите Разработчик ИИ-платформы.
  5. Нажмите Добавить роль и выберите Пользователь Agent Platform.
  6. Нажмите Добавить роль и выберите Cloud Run Invoker.
  7. Нажмите Сохранить.

Затем экспортируйте учетные данные для сервисного аккаунта Admin SDK и сохраните их в переменной среды GOOGLE_APPLICATION_CREDENTIALS.

  1. В консоли Google Cloud откройте страницу Credentials (Учетные данные).
  2. Нажмите на сервисный аккаунт Admin SDK, чтобы открыть страницу Details (Сведения).
  3. Нажмите Ключи.
  4. Нажмите Add key (Добавить ключ) и выберите Create new key (Создать ключ).
  5. Убедитесь, что в качестве типа ключа выбран вариант JSON, и нажмите Создать.
  6. Скачайте ключ в безопасное место на компьютере.

  7. В терминале экспортируйте ключ как переменную среды:

    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

Шаг 4. Создайте функцию

На этом шаге вы создадите функцию, которая обрабатывает пользовательский ввод и генерирует ответы на основе искусственного интеллекта. Вы объедините несколько фрагментов кода, чтобы создать комплексную функцию, которая инициализирует Admin SDK и Agent Platform Gemini API (formerly Vertex AI), настраивает параметры по умолчанию с помощью Remote Config, получает последние параметры Remote Config, обрабатывает пользовательский ввод и передает ответ пользователю.

  1. Откройте файл functions/index.js в текстовом редакторе или интегрированной среде разработки.

  2. Удалите существующий контент, добавьте SDK Admin SDK, Remote Config и Agent Platform и инициализируйте приложение, вставив в файл следующий код:

    const { onRequest } = require("firebase-functions/https");
const { requiresRole, requiresAPI } = require("firebase-functions");
const logger = require("firebase-functions/logger");

const { initializeApp } = require("firebase-admin/app");
const { VertexAI } = require('@google-cloud/vertexai');
const { getRemoteConfig } = require("firebase-admin/remote-config");

requiresRole("roles/aiplatform.user");
requiresRole("roles/cloudconfig.viewer");
requiresAPI("aiplatform.googleapis.com", "Needed to query Vertex AI Gemini models");
requiresAPI("firebaseremoteconfig.googleapis.com", "Needed to fetch server-side Remote Config templates");

// Set and check environment variables.
const project = process.env.GCLOUD_PROJECT;

// Initialize Firebase.
const app = initializeApp();

  3. Настройте значения по умолчанию, которые будут использоваться, если не удастся подключиться к серверу Remote Config. Это решение настраивает textModel, generationConfig, safetySettings, textPrompt и location как параметры Remote Config, которые соответствуют параметрам Remote Config, которые вы настроите далее в этом руководстве. Подробную информацию об этих параметрах можно найти в статье Клиент Vertex AI Node.js.

    При необходимости вы также можете настроить параметр, который будет определять, есть ли у вас доступ к Agent Platform Gemini API (formerly Vertex AI) (в этом примере – параметр vertex_enabled). Такая настройка может быть полезна при тестировании функции. В приведенных ниже фрагментах кода этому параметру присвоено значение false, что позволяет не использовать Agent Platform при тестировании развертывания базовой функции. Если задать значение true, будет вызываться Agent Platform Gemini API (formerly Vertex AI).

    // Define default (fallback) parameter values for Remote Config.
const defaultConfig = {

  // Default values for Vertex AI.
  model_name: "gemini-1.5-flash-002",
  generation_config: [{
    "stopSequences": [], "temperature": 0.7,
    "maxOutputTokens": 64, "topP": 0.1, "topK": 20
  }],
  prompt: "I'm a developer who wants to learn about Firebase and you are a \
    helpful assistant who knows everything there is to know about Firebase!",
  safety_settings: [{
    "category":
      "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT",
    "threshold": "HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE"
  }],
  location: 'us-central1',

  // Disable Vertex AI Gemini API access for testing.
  vertex_enabled: false
};

  4. Создайте функцию и настройте серверную часть Remote Config:

    // Export the function.
exports.generateWithVertex = onRequest(async (request, response) => {

  try {

    // Set up Remote Config.
    const rc = getRemoteConfig(app);

    // Get the Remote Config template and assign default values.
    const template = await rc.getServerTemplate({
      defaultConfig: defaultConfig
    });

    // Add the template evaluation to a constant.
    const config = template.evaluate();

    // Obtain values from Remote Config.
    const textModel = config.getString("model_name") ||
        defaultConfig.model_name;
    const textPrompt = config.getString("prompt") || defaultConfig.prompt;
    const generationConfig = config.getString("generation_config") ||
        defaultConfig.generation_config;
    const safetySettings = config.getString("safety_settings") ||
        defaultConfig.safety_settings;
    const location = config.getString("location") ||
        defaultConfig.location;
    const vertexEnabled = config.getBoolean("is_vertex_enabled") ||
        defaultConfig.vertex_enabled;

  5. Настройте Agent Platform и добавьте логику чата и ответов:

      // Allow user input.
  const userInput = request.query.prompt || '';

  // Instantiate Vertex AI.
    const vertex_ai = new VertexAI({ project: project, location: location });
    const generativeModel = vertex_ai.getGenerativeModel({
      model: textModel,
      safety_settings: safetySettings,
      generation_config: generationConfig,
    });

    // Combine prompt from Remote Config with optional user input.
    const chatInput = textPrompt + " " + userInput;

    if (!chatInput) {
      return res.status(400).send('Missing text prompt');
    }
    // If vertexEnabled isn't true, do not send queries to Vertex AI.
    if (vertexEnabled !== true) {
      response.status(200).send({
        message: "Vertex AI call skipped. Vertex is not enabled."
      });
      return;
    }

    logger.log("\nRunning with model ", textModel, ", prompt: ", textPrompt,
      ", generationConfig: ", generationConfig, ", safetySettings: ",
      safetySettings, " in ", location, "\n");

    const result = await generativeModel.generateContentStream(chatInput); 
    response.writeHead(200, { 'Content-Type': 'text/plain' });

    for await (const item of result.stream) {
      const chunk = item.candidates[0].content.parts[0].text;
      logger.log("Received chunk:", chunk);
      response.write(chunk);
    }

    response.end();

  } catch (error) {
    logger.error(error);
    response.status(500).send('Internal server error');
  }
});

  6. Сохраните и закройте файл.

Шаг 5. Создайте шаблон Remote Config для сервера

Затем создайте серверный шаблон Remote Config и настройте параметры и значения, которые будут использоваться в функции. Чтобы создать шаблон Remote Config для определенного сервера, выполните следующие действия:

  1. В консоли Firebase выберите DevOps & Engagement (DevOps и вовлечение) > Remote Config (Удаленная конфигурация).

  2. В меню Клиент/сервер в верхней части страницы выберите Сервер.

    • Если вы впервые используете Remote Config или серверные шаблоны, нажмите Создать конфигурацию. Появится панель Создайте свой первый параметр на стороне сервера.
    • Если вы уже использовали серверные шаблоны Remote Config, нажмите Добавить параметр.

  3. Задайте следующие параметры Remote Config:

    Название параметра Описание Тип Значение по умолчанию
    model_name Название модели
    Актуальные списки названий моделей, которые можно использовать в коде, приведены в статьях Версии и жизненные циклы моделей и Доступные названия моделей.     		Строка gemini-2.0-flash
    prompt Запрос, который будет добавлен перед запросом пользователя. Строка I'm a developer who wants to learn about Firebase and you are a helpful assistant who knows everything there is to know about Firebase!
    generation_config Параметры, которые нужно передать модели JSON [{"stopSequences": ["I hope this helps"],"temperature": 0.7,"maxOutputTokens": 512, "topP": 0.1,"topK": 20}]
    safety_settings Настройки безопасности для пользователя Agent Platform JSON [{"category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_LOW_AND_ABOVE"}]
    location Местоположение для запуска сервиса и модели Agent Platform Строка global
    is_vertex_enabled Необязательный параметр, который определяет, отправляются ли запросы в Agent Platform. Логическое значение true

  4. Добавив параметры, проверьте их и убедитесь, что типы данных указаны правильно, а затем нажмите Опубликовать изменения.

Шаг 6. Разверните функцию и протестируйте ее в Firebase Local Emulator Suite

Теперь вы можете развернуть и протестировать функцию локально с помощью Firebase Local Emulator Suite.

  1. Убедитесь, что вы задали GOOGLE_APPLICATION_CREDENTIALS в качестве переменной среды, как описано в разделе Шаг 3. Настройте разрешения IAM для сервисного аккаунта Admin SDK и сохраните ключ. Затем из родительского каталога каталога functions разверните функцию в эмуляторе Firebase:

    firebase emulators:start --project PROJECT_ID --only functions

  2. Откройте страницу журналов эмулятора. Это означает, что функция загружена.

  3. Чтобы получить доступ к функции, выполните следующую команду, где PROJECT_ID – идентификатор проекта, а LOCATION – регион, в котором развернута функция (например, us-central1):

    curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex

  4. Дождитесь ответа, а затем вернитесь на страницу журналов эмулятора Firebase или в консоль и проверьте, нет ли ошибок или предупреждений.

  5. Попробуйте отправить пользовательский запрос. Обратите внимание, что поскольку в шаблоне сервера Remote Config настроена модель is_vertex_enabled, она должна получить доступ к модели Gemini через Agent Platform Gemini API (formerly Vertex AI). За это может взиматься плата.

    curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20cats

  6. Внесите изменения в шаблон сервера Remote Config в консоли Firebase, а затем снова откройте функцию, чтобы посмотреть изменения.

Шаг 7. Разверните функцию в Google Cloud

После тестирования и проверки функции вы можете развернуть ее в Google Cloud и протестировать в реальных условиях.

Разверните функцию

Разверните функцию с помощью интерфейса командной строки Firebase:

firebase deploy --only functions

Блокировать неаутентифицированный доступ к функции

Если функции развертываются с помощью Firebase, неаутентифицированные вызовы разрешены по умолчанию, если это не запрещено правилами организации. Во время тестирования и до настройки защиты с помощью App Check рекомендуем заблокировать доступ без аутентификации.

Чтобы заблокировать неаутентифицированный доступ к функции:

  1. В консоли Google Cloud откройте Cloud Run.

  2. Нажмите на значок generateWithVertex и выберите вкладку Безопасность.

  3. Включите параметр Требовать аутентификацию и нажмите Сохранить.

Настройте аккаунт пользователя, чтобы использовать учетные данные сервисного аккаунта Admin SDK.

Поскольку у сервисного аккаунта Admin SDK есть все необходимые роли и разрешения для запуска функции и взаимодействия с Remote Config и Agent Platform Gemini API (formerly Vertex AI), вы можете использовать его для запуска функции. Для этого у вас должна быть возможность создавать токены для аккаунта из вашего аккаунта пользователя.

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

  1. В консоли Google Cloud включите IAM Service Account Credentials API.
  2. Назначьте своему аккаунту пользователя роль Создатель токенов сервисного аккаунта. Для этого в консоли Google Cloud выберите IAM и администрирование > IAM, выберите свой аккаунт пользователя и нажмите Изменить субъект > Добавить другую роль.

  3. Выберите Создатель токенов сервисного аккаунта и нажмите Сохранить.

    Подробную информацию о смене аккаунта можно найти в документации Google Cloud.

  4. Откройте страницу консоли Google Cloud Cloud Functions и нажмите на функцию generateWithVertex в списке Функции.

  5. Выберите Trigger (Триггер) > Edit (Изменить) и разверните Runtime, build, connections and security settings (Среда выполнения, сборка, подключения и настройки безопасности).

  6. На вкладке Runtime (Среда выполнения) измените Runtime service account (Сервисный аккаунт среды выполнения) на Admin SDK account (Аккаунт Admin SDK).

  7. Нажмите Next (Далее), а затем – Deploy (Развернуть).

Как настроить gcloud CLI

Чтобы безопасно запустить и протестировать функцию из командной строки, вам нужно выполнить аутентификацию в сервисе Cloud Functions и получить действительный токен аутентификации.

Чтобы включить создание токенов, установите и настройте gcloud CLI:

  1. Если на вашем компьютере не установлен gcloud CLI, установите его, как описано в статье Установка gcloud CLI.

  2. Получите учетные данные для доступа к аккаунту Google Cloud:

    gcloud auth login

  3. Укажите идентификатор проекта в gcloud:

    gcloud config set project PROJECT_ID

Протестируйте функцию

Теперь вы можете протестировать функцию в Google Cloud. Чтобы протестировать функцию, выполните следующую команду:

curl -X POST https://LOCATION-PROJECT_ID.cloudfunctions.net/generateWithVertex \
  -H "Authorization: bearer $(gcloud auth print-identity-token)" \
  -H "Content-Type: application/json"

Повторите попытку, используя данные, предоставленные пользователем:

curl -X POST https://LOCATION-PROJECT_ID.cloudfunctions.net/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20dogs \
 -H "Authorization: bearer $(gcloud auth print-identity-token)" \
 -H "Content-Type: application/json"

Теперь вы можете вносить изменения в серверный шаблон Remote Config, публиковать их и тестировать разные варианты.

Дальнейшие действия