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

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

В этом руководстве вы добавите Remote Config к функции, подобной чат-боту, которая использует модель Gemini для ответов на вопросы пользователей. Remote Config будет управлять входными данными API Gemini (включая подсказку, которую вы будете добавлять к входящим запросам пользователей), и вы сможете обновлять эти данные по запросу из консоли 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 CLI.

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

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

  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

Теперь вы готовы приступить к внедрению этого решения.

Выполнение

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

  1. Включите рекомендуемые API Vertex AI в консоли 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 включены.

Шаг 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 совпадает с установленной версией 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 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"

Шаг 4: Создание функции

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

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

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

    const { onRequest } = require("firebase-functions/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 client» .

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

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

  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. Сохраните и закройте файл.

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

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

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

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

    • Если вы впервые используете 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 Настройки безопасности для 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

  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. Попробуйте отправить пользовательский ввод, учитывая, что поскольку is_vertex_enabled настроен в шаблоне сервера Remote Config , он должен получить доступ к модели Gemini через API Vertex AI Gemini , и это может повлечь за собой плату: 

    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 CLI: 

firebase deploy --only functions

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  6. На вкладке Runtime измените учетную запись службы Runtime на учетную запись Admin SDK .

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

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

Для безопасного запуска и тестирования вашей функции из командной строки вам необходимо пройти аутентификацию в службе 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 , публиковать эти изменения и тестировать различные варианты.

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