Используйте удаленную настройку на стороне сервера с облачными функциями и Vertex AI.

В этом руководстве описывается, как начать использовать Cloud Functions 2-го поколения с Remote Config на стороне сервера для выполнения серверных вызовов Vertex AI Gemini API .

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

Важно: Vertex AI и Cloud Functions требуется учетная запись для выставления счетов. Прежде чем продолжить, ознакомьтесь с ценами на Vertex AI и ценами Cloud Functions . Если вы новичок в Firebase и Google Cloud , проверьте, имеете ли вы право на кредит в размере 300 долларов США и бесплатную пробную учетную запись Cloud Billing .

Предварительные условия

В этом руководстве предполагается, что вы знакомы с использованием 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 .

   Важно! Мы рекомендуем использовать Node.js v20 или более позднюю версию. См. раздел Установка параметров времени выполнения для получения важной информации о постоянной поддержке версий Node.js.

2. Установите Firebase CLI, используя предпочитаемый вами метод. Например, чтобы установить 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
   

Совет. Во многих случаях новые функции и исправления ошибок доступны только в последней версии Firebase CLI и firebase-functions SDK. Рекомендуется часто обновлять интерфейс командной строки Firebase и SDK с помощью этих команд в папке functions вашей базы кода.

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

Выполнение

Выполните следующие шаги, чтобы создать, протестировать и развернуть Cloud Functions 2-го поколения с помощью Remote Config и Vertex AI :

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

Шаг 1. Включите API-интерфейсы, рекомендованные Vertex AI в консоли Google Cloud

1. Откройте консоль Google Cloud и при появлении запроса выберите свой проект.
2. В поле «Поиск» в верхней части консоли введите Vertex AI и дождитесь появления результата Vertex AI .
3. Выберите Vertex AI . Появится панель управления Vertex AI .

4. Нажмите «Включить все рекомендуемые API» .

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

5. Если выставление счетов не включено, вам будет предложено добавить или связать учетную запись Cloud Billing . После включения учетной записи для выставления счетов вернитесь на панель управления Vertex AI и убедитесь, что все рекомендуемые API включены.

Важно: Vertex AI и Cloud Functions требуется учетная запись для выставления счетов. Ознакомьтесь с ценами Vertex AI и ценами на облачные функции, чтобы получить информацию о ценах.

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

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

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

   firebase login
   

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

   firebase init functions
   

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

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

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

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

7. Добавьте пакеты Admin SDK и Vertex AI , выполнив следующие команды, используя --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 для запуска своей функции.

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

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

1. В консоли Google Cloud откройте страницу «Учетные данные» .
2. Щелкните учетную запись службы Admin SDK чтобы открыть страницу сведений .
3. Нажмите «Ключи» .
4. Нажмите «Добавить ключ» > «Создать новый ключ» .
5. Убедитесь, что в качестве типа ключа выбран JSON , затем нажмите «Создать» .
6. Загрузите ключ в безопасное место на свой компьютер.

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

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

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

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

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

Важно: код этой функции представлен в нескольких фрагментах. Перед запуском функции вам необходимо объединить их все в один файл index.js .

1. В своей базе кода откройте functions/index.js в текстовом редакторе или IDE.

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

   const { onRequest } = require("firebase-functions/v2/https");
   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");
   
   // Set and check environment variables.
   const project = process.env.GCLOUD_PROJECT;
   
   // Initialize Firebase.
   const app = initializeApp();
   index.js
   

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

   При желании вы также можете настроить параметр, управляющий доступом к Vertex AI Gemini API (в данном примере это параметр vertex_enabled ). Эта настройка может быть полезна при тестировании вашей функции. В следующих фрагментах кода для этого значения установлено значение false , что исключает использование Vertex AI при тестировании развертывания базовых функций. Установка значения true приведет к вызову Vertex AI Gemini API .

   // Define default (fallback) parameter values for Remote Config.
   const defaultConfig = {
   
     // Default values for Vertex AI.
     model_name: "gemini-1.5-flash-preview-0514",
     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
   

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;
   index.js
   

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

     // 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
   

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

Совет: Узнайте больше об использовании Vertex AI с Node.js для создания мультимодальных и потоковых ответов в кратком руководстве по Vertex AI для Node.js.

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

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

1. Откройте консоль Firebase и в меню навигации разверните «Выполнить» и выберите Remote Config .

2. Выберите «Сервер» в селекторе «Клиент/Сервер» в верхней части страницы Remote Config .

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

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

   Имя параметра	Описание	Тип	Значение по умолчанию
   model_name	Название модели Актуальные списки имен моделей для использования в вашем коде см. в разделах Версии и жизненные циклы моделей или Доступные имена моделей .	Нить	gemini-1.5-pro-preview-0514
   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	Настройки безопасности для Vertex AI .	JSON	[{"category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_LOW_AND_ABOVE"}]
   location	Местоположение для запуска сервиса и модели Vertex AI .	Нить	us-central1
   is_vertex_enabled	Необязательный параметр, управляющий отправкой запросов в Vertex AI .	логическое значение	true

   Важно: модели часто обновляются. Текущий список моделей, которые поддерживает Vertex AI , см. в разделе Версии и жизненный цикл моделей .

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
   

   Совет: Вы также можете запускать функции в эмуляторе, запустив npm run serve из каталога functions .

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

3. Получите доступ к своей функции, выполнив следующую команду, где PROJECT_ID — это идентификатор вашего проекта, а LOCATION — это регион, в котором вы развернули функцию (например, us-central1 ):

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

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

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

5. Попробуйте отправить некоторые пользовательские данные, отметив, что, поскольку is_vertex_enabled настроен в шаблоне вашего сервера Remote Config , доступ к Gemini должен осуществляться через Vertex AI Gemini API , и это может повлечь за собой дополнительную плату:

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

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

Совет. Дополнительную информацию о тестировании Cloud Functions с помощью Firebase см. в разделе Интерактивное тестирование функций .

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

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

Важно! Хотя тестирование функций в эмуляторе Firebase является бесплатным, любые вызовы Vertex AI при использовании эмулятора по-прежнему взимаются. Кроме того, после развертывания функций любой вызов этих функций может повлечь за собой затраты. Прежде чем продолжить, ознакомьтесь с ценами на Vertex AI и ценами на облачные функции .

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

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

firebase deploy --only functions

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

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

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

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

2. Нажмите generateWithVertex , затем перейдите на вкладку «Безопасность» .

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

Настройте свою учетную запись пользователя для использования учетных данных учетной записи службы Admin SDK

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

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

1. В консоли Google Cloud включите API учетных данных учетной записи службы IAM .
2. Назначьте своей учетной записи пользователя роль создателя токена сервисной учетной записи . В консоли Google Cloud откройте IAM & Admin > IAM , выберите свою учетную запись пользователя, а затем нажмите «Изменить участника» > «Добавить другую роль» .

3. Выберите «Создание токена учетной записи службы» , затем нажмите « Сохранить» .

   Более подробную информацию о выдаче себя за учетную запись службы см. в разделе «Олицетворение учетной записи службы» в документации Google Cloud .

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

5. Выберите «Триггер» > «Изменить» и разверните «Параметры выполнения, сборки, подключений и безопасности» .

6. На вкладке «Среда выполнения » измените учетную запись службы среды выполнения на учетную запись Admin SDK .

7. Нажмите «Далее» , затем нажмите «Развернуть» .

Настройте интерфейс командной строки gcloud

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

Чтобы включить генерацию токенов, установите и настройте интерфейс командной строки gcloud:

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 , публиковать эти изменения и тестировать различные параметры.

Следующие шаги

• Firebase рекомендует использовать App Check для защиты Cloud Functions . Дополнительную информацию о защите вашей функции с помощью App Check см. в разделе «Включение принудительной App Check для Cloud Functions .
• Попробуйте пример вызываемой функции с Remote Config и App Check на стороне сервера в статье Вызов Vertex AI Gemini API с Remote Config и App Check .
• Узнайте больше об Cloud Functions для Firebase .
• Узнайте больше об использовании Remote Config в серверных средах .