Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Как использовать серверную конфигурацию 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:

Войдите в консоль Firebase.
Нажмите Создать проект и выберите один из следующих вариантов:
- Вариант 1. Создайте новый проект Firebase (и связанный с ним проект Google Cloud) автоматически, введя название проекта на первом шаге создания проекта.
- Вариант 2. Добавьте Firebase в существующий проект Google Cloud, выбрав его Google Cloud название в раскрывающемся меню на первом шаге создания проекта.
Когда появится запрос, не настраивайте Google Analytics, чтобы использовать это решение.
Следуйте инструкциям на экране, чтобы создать проект.

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

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

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

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

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

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

Важно! Мы рекомендуем использовать Node.js версии 20 или более поздней. Важную информацию о поддержке версий Node.js можно найти в разделе Настройка параметров среды выполнения.
Установите Firebase CLI любым удобным способом. Например, чтобы установить интерфейс командной строки с помощью npm, выполните следующую команду:
```
npm install -g firebase-tools@latest
```
Эта команда устанавливает глобально доступную команду firebase. Если эта команда не сработает, возможно, вам потребуется изменить разрешения npm.

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

Примечание. Вы также можете выполнять команды Firebase CLI в Cloud Shell. Cloud Shell – это предварительно аутентифицированная среда командной строки на основе браузера, доступная из консоли Firebase. В ней предустановлен интерфейс командной строки Firebase. Это удобный вариант для быстрого начала работы, если вы добавите файлы проекта в среду Cloud Shell.
Установите firebase-functions и firebase-admin и используйте --save, чтобы сохранить их в package.json:
```
npm install firebase-functions@latest firebase-admin@latest --save
```

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

Реализация

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

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

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

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

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

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

Откройте терминал на компьютере и перейдите в каталог, в котором вы планируете создать функцию.
Войдите в Firebase:
```
firebase login
```
Выполните следующую команду, чтобы инициализировать Cloud Functions for Firebase:
```
firebase init functions
```
Выберите Использовать существующий проект и укажите идентификатор проекта.
Когда вам будет предложено выбрать язык, укажите Javascript и нажмите Ввод.
Для остальных параметров выберите значения по умолчанию.

В текущем каталоге будет создан каталог functions. Внутри вы найдете файл index.js, который используется для создания функции, каталог node_modules с зависимостями для функции и файл package.json с зависимостями пакета.
Добавьте пакеты 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.js и версии, которую вы в конечном итоге запустите на Google Cloud. Например, если в разделе engines файла package.json указана версия Node 18, а вы используете Node.js 20, обновите файл, чтобы в нем использовалась версия 20:

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

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

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

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

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

В консоли Google Cloud откройте страницу Credentials (Учетные данные).
Нажмите на сервисный аккаунт Admin SDK, чтобы открыть страницу Подробности.
Нажмите Ключи.
Нажмите Add key (Добавить ключ) и выберите Create new key (Создать ключ).
Убедитесь, что в качестве типа ключа выбран вариант JSON, и нажмите Создать.
Скачайте ключ и сохраните его в надежном месте на компьютере.
В терминале экспортируйте ключ как переменную среды:
```
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, обрабатывает ввод данных пользователем и постепенно выводит ответ пользователю.

Откройте файл functions/index.js в текстовом редакторе или IDE.

Удалите существующий контент, а затем добавьте 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();index.js

Настройте значения по умолчанию, которые функция будет использовать, если не сможет подключиться к серверу 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
};index.js
```

Создайте функцию и настройте тег на стороне сервера 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;index.js

Настройте 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');
  }
});index.js

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

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

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

В консоли Firebase выберите DevOps & Engagement (DevOps и взаимодействие) > Remote Config (Удаленная настройка).
В верхней части страницы в раскрывающемся списке Клиент/Сервер выберите Сервер.
- Если вы впервые используете Remote Config или шаблоны серверов, нажмите Создать конфигурацию. Появится панель Создайте свой первый параметр на стороне сервера.
- Если вы уже использовали шаблоны серверов Remote Config, нажмите Добавить параметр.

Укажите следующие параметры 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`

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

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

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

Убедитесь, что вы задали GOOGLE_APPLICATION_CREDENTIALS в качестве переменной среды, как описано в шаге 3: настройте разрешения IAM для сервисного аккаунта Admin SDK и сохраните ключ. Затем из родительского каталога каталога functions разверните функцию в эмуляторе Firebase:
```
firebase emulators:start --project PROJECT_ID --only functions
```
Совет. Вы также можете запустить функции в эмуляторе, выполнив команду npm run serve из каталога functions.
Откройте страницу журналов эмулятора. Это означает, что функция загружена.
Чтобы получить доступ к функции, выполните следующую команду, где PROJECT_ID – идентификатор проекта, а LOCATION – регион, в котором развернута функция (например, us-central1):
```
curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex
```
Совет. Эта ссылка также появится в выходных данных консоли после запуска эмулятора. Вы также можете вырезать и вставить его в браузер.
Дождитесь ответа, а затем вернитесь на страницу журнала эмулятора Firebase или в консоль и проверьте, есть ли ошибки или предупреждения.
Попробуйте отправить ввод данных пользователем, учитывая, что, поскольку is_vertex_enabled настроен в шаблоне сервера Remote Config, он должен получить доступ к модели Gemini через Agent Platform Gemini API (formerly Vertex AI), и за это может взиматься плата:
```
curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20cats
```
Внесите изменения в Remote Configшаблон сервера в консоли Firebase, а затем снова откройте функцию, чтобы увидеть изменения.

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

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

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

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

firebase deploy --only functions

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

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

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

В консоли Google Cloud откройте Cloud Run.
Нажмите generateWithVertex и откройте вкладку Безопасность.
Включите параметр Требовать аутентификацию и нажмите Сохранить.

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

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

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

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

Более подробную информацию о том, как скрыть имена пользователей с помощью сервисного аккаунта, можно найти в разделе Как скрыть имена пользователей с помощью сервисного аккаунта документации по Google Cloud.
Откройте консоль Google CloudCloud Functions и нажмите на функцию generateWithVertex в списке Функции.
Выберите Триггер > Изменить и разверните Настройки времени выполнения, сборки, подключений и безопасности.
На вкладке Среда выполнения измените Сервисный аккаунт среды выполнения на Аккаунт Admin SDK.
Нажмите Далее, а затем – Развернуть.

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

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

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

Если на вашем компьютере ещё не установлен gcloud CLI, сделайте это, следуя инструкциям в разделе Установка gcloud CLI.
Получите учетные данные для доступа к аккаунту Google Cloud:
```
gcloud auth login
```
Укажите идентификатор проекта в 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, публиковать их и тестировать разные варианты.

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

Firebase рекомендует использовать App Check для защиты Cloud Functions. Подробнее о том, App Check Cloud Functions как защитить функцию с помощью App Check…
Попробуйте вызвать функцию с серверной частью Remote Config и App Check на странице Вызов функции Agent Platform Gemini API (formerly Vertex AI) с Remote Config и App Check.
Подробнее о Cloud Functions для Firebase…
Подробнее о том, как использовать Remote Config в серверных средах…