Используйте удаленную настройку на стороне сервера с облачными функциями и 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. Включите рекомендуемые 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.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/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 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 или шаблоны сервера, нажмите Create Configuration . Появится панель Create your first server-side parameter .
    • Если вы не в первый раз используете шаблоны сервера 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 и Vertex AI Gemini API , вы захотите использовать ее для запуска своей функции. Для этого вы должны иметь возможность создавать токены для учетной записи из своей учетной записи пользователя.

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

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