Используйте удаленную настройку на стороне сервера с облачными функциями и 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 второго поколения с помощью Remote Config и Vertex AI :

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

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

  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 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 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 и API Vertex AI Gemini , настраивает параметры по умолчанию с помощью 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 . В этом решении параметры Remote Config textModel , generationConfig , safetySettings , textPrompt и location настраиваются в соответствии с параметрами Remote Config , которые вы настроите далее в этом руководстве. Для получения дополнительной информации об этих параметрах см. клиент Vertex AI для Node.js.

    При желании вы также можете настроить параметр, определяющий, будете ли вы обращаться к 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. На вкладке «Среда выполнения» измените учетную запись службы среды выполнения на учетную запись 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 , публиковать эти изменения и тестировать различные варианты.

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