Cloud Functions 및 Vertex AI와 함께 서버 측 원격 구성 사용

이 가이드에서는 Vertex AI Gemini API에 대한 서버 측 호출을 수행하기 위해 서버 측 원격 구성과 함께 2세대 Cloud Functions를 사용하여 시작하는 방법을 설명합니다.

이 튜토리얼에서는 Gemini 모델을 사용하여 사용자 질문에 답변하는 챗봇과 유사한 함수에 원격 구성을 추가합니다. 원격 구성은 Gemini API 입력(수신하는 사용자 쿼리 앞에 추가할 프롬프트 포함)을 관리하고 이러한 입력을 필요에 따라 Firebase Console에서 업데이트할 수 있습니다. 또한 Firebase 로컬 에뮬레이터 도구 모음을 사용하여 함수를 테스트 및 디버그하고, 작동하는지 확인한 후 Google Cloud에 배포하고 테스트할 수 있습니다

기본 요건

이 가이드에서는 독자가 JavaScript를 사용하여 애플리케이션을 개발하는 데 익숙하다고 가정합니다.

Firebase 프로젝트 설정

아직 Firebase 프로젝트가 없는 경우:

Firebase Console에 로그인합니다.
프로젝트 만들기를 클릭하고 다음 옵션 중 하나를 사용합니다.
- 옵션 1: '프로젝트 만들기' 워크플로의 첫 번째 단계에서 새 프로젝트 이름을 입력하여 새 Firebase 프로젝트(및 기본 Google Cloud 프로젝트 자동 생성)를 만듭니다.
- 옵션 2: '프로젝트 만들기' 워크플로의 첫 번째 단계에서 드롭다운 메뉴에서 Google Cloud 프로젝트 이름을 선택하여 기존 Google Cloud 프로젝트에 'Firebase를 추가'합니다.
메시지가 표시되면 이 솔루션을 사용하기 위해 Google 애널리틱스를 설정하지 않아도 됩니다.
계속해서 화면에 표시된 안내에 따라 프로젝트를 만듭니다.

이미 Firebase 프로젝트가 있는 경우:

개발 환경 구성을 진행합니다.

개발 환경 구성

함수를 작성하려면 Node.js 환경이 필요하고, 함수를 Cloud Functions 런타임에 배포하려면 Firebase CLI가 필요합니다.

Node.js 및 npm을 설치합니다.

Node.js와 npm을 설치하려면 노드 버전 관리자를 사용하는 것이 좋습니다.

중요: Node.js v20 이상을 사용하는 것이 좋습니다. 진행 중인 Node.js 버전 지원과 관련된 중요한 정보는 런타임 옵션 설정을 참조하세요.
선호하는 방법을 사용하여 Firebase CLI를 설치합니다. 예를 들어 npm을 사용하여 CLI를 설치하려면 다음 명령어를 실행합니다.
```
npm install -g firebase-tools@latest
```
이 명령어는 디렉터리에 관계없이 사용할 수 있는 firebase 명령어를 설치합니다. 이 명령어가 작동하지 않으면 npm 권한을 변경해야 할 수도 있습니다.

firebase-tools의 최신 버전으로 업데이트하려면 같은 명령어를 다시 실행합니다.
firebase-functions 및 firebase-admin을 설치하고 --save를 사용하여 package.json에 저장합니다.
```
npm install firebase-functions@latest firebase-admin@latest --save
```

이제 이 솔루션의 구현을 진행할 준비가 되었습니다.

구현

다음 단계에 따라 원격 구성 및 Vertex AI를 사용하여 2세대 Cloud Functions를 생성, 테스트, 배포하세요.

Google Cloud 콘솔에서 Vertex AI 권장 API를 사용 설정합니다.
프로젝트를 초기화하고 노드 종속 항목을 설치합니다.
Admin SDK 서비스 계정의 IAM 권한을 구성하고 키를 저장합니다.
함수를 만듭니다.
서버별 원격 구성 템플릿을 만듭니다.
함수를 배포하고 Firebase 로컬 에뮬레이터 도구 모음에서 테스트합니다.
Google Cloud에 함수를 배포합니다.

1단계: Google Cloud 콘솔에서 Vertex AI 권장 API 사용 설정

Google Cloud 콘솔을 열고 메시지가 표시되면 프로젝트를 선택합니다.
콘솔 상단의 검색 필드에서 Vertex AI를 입력하고 Vertex AI가 결과로 표시될 때까지 기다립니다.
Vertex AI를 선택합니다. Vertex AI 대시보드가 나타납니다.
모든 권장 API 사용 설정을 클릭합니다.

API 사용 설정이 완료되는 데 몇 분 정도 걸릴 수 있습니다. 사용 설정이 완료될 때까지 페이지를 활성 상태로 열어둡니다.
결제가 사용 설정되어 있지 않으면 Cloud Billing 계정을 추가하거나 연결하라는 메시지가 표시됩니다. 결제 계정을 사용 설정한 후 Vertex AI 대시보드로 돌아가 모든 권장 API가 사용 설정되어 있는지 확인합니다.

2단계: 프로젝트 초기화 및 노드 종속 항목 설치

컴퓨터에서 터미널을 열고 함수를 만들 디렉터리로 이동합니다.
Firebase에 로그인합니다.
```
firebase login
```
다음 명령어를 실행하여 Firebase용 Cloud Functions를 초기화합니다.
```
firebase init functions
```
기존 프로젝트 사용을 선택하고 프로젝트 ID를 지정합니다.
사용할 언어를 선택하라는 메시지가 표시되면 JavaScript를 선택하고 Enter 키를 누릅니다.
다른 모든 옵션은 기본값을 선택합니다.

현재 디렉터리에 functions 디렉터리가 생성됩니다. 디렉터리에 함수를 빌드하는 데 사용할 index.js 파일, 함수의 종속 항목이 포함된 node_modules 디렉터리, 패키지 종속 항목이 포함된 package.json 파일이 있습니다.
다음 명령어를 실행하여 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를 사용하는 경우 ESLint가 포함된 스탠자가 표시됩니다. 또한 노드 엔진 버전이 Node.js의 설치된 버전 및 최종적으로 Google Cloud에서 실행하는 버전과 일치하는지 확인합니다. 예를 들어 package.json의 engines 스탠자가 노드 버전 18로 구성되고 Node.js 20을 사용하는 경우 20을 사용하도록 파일을 업데이트합니다.

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

3단계: Admin SDK 서비스 계정의 IAM 권한 구성 및 키 저장

이 솔루션에서는 Firebase Admin SDK 서비스 계정을 사용하여 함수를 실행합니다.

Google Cloud 콘솔에서 IAM 및 관리 페이지를 열고 firebase-adminsdk라는 Admin SDK 서비스 계정을 찾습니다.
계정을 선택하고 주 구성원 수정을 클릭합니다. 액세스 권한 수정 페이지가 표시됩니다.
다른 역할 추가를 클릭하고 원격 구성 뷰어를 선택합니다.
다른 역할 추가를 클릭하고 AI Platform 개발자를 선택합니다.
다른 역할 추가를 클릭하고 Vertex AI 사용자를 선택합니다.
다른 역할 추가를 클릭하고 Cloud Run 호출자를 선택합니다.
저장을 클릭합니다.

그런 다음 Admin SDK 서비스 계정의 사용자 인증 정보를 내보내고 GOOGLE_APPLICATION_CREDENTIALS 환경 변수에 저장합니다.

Google Cloud 콘솔에서 사용자 인증 정보 페이지를 엽니다.
Admin SDK 서비스 계정을 클릭하여 세부정보 페이지를 엽니다.
키를 클릭합니다.
키 추가 > 새 키 만들기를 클릭합니다.
JSON으로 JSON이 선택되어 있는지 확인한 다음 JSON를 클릭합니다.
컴퓨터의 안전한 위치에 키를 다운로드합니다.

터미널에서 키를 환경 변수로 내보냅니다.

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

4단계: 함수 만들기

이 단계에서는 사용자 입력을 처리하고 AI 기반 응답을 생성하는 함수를 구성합니다. 여러 코드 스니펫을 결합하여 Admin SDK 및 Vertex AI Gemini API를 초기화하고, 원격 구성을 사용하여 기본 파라미터를 구성하며, 최신 원격 구성 파라미터를 가져오고, 사용자 입력을 처리하고, 사용자에게 응답을 다시 스트리밍하는 포괄적인 함수를 빌드합니다.

코드베이스에서 텍스트 편집기 또는 IDE에서 functions/index.js를 엽니다.

기존 콘텐츠를 삭제한 다음 Admin SDK, 원격 구성, 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

함수가 원격 구성 서버에 연결될 수 없는 경우 사용할 기본값을 구성합니다. 이 솔루션은 textModel, generationConfig, safetySettings, textPrompt, location을 이 가이드 뒷부분에서 구성할 원격 구성 파라미터에 해당하는 원격 구성 파라미터로 구성합니다. 이러한 파라미터에 대한 자세한 내용은 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
```

함수를 만들고 서버 측 원격 구성을 설정합니다.

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

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

저장하고 파일을 닫습니다.

5단계: 서버별 원격 구성 템플릿 만들기

다음으로 서버 측 원격 구성 템플릿을 만들고 함수에서 사용할 파라미터 및 값을 구성합니다. 서버별 원격 구성 템플릿을 만들려면 다음 단계를 따르세요.

Firebase Console을 열고 탐색 메뉴에서 실행을 펼치고 원격 구성을 선택합니다.
원격 구성 페이지 상단의 클라이언트/서버 선택기에서 서버를 선택합니다.
- 원격 구성이나 서버 템플릿을 처음 사용한다면 구성 만들기를 클릭합니다. 첫 번째 서버 측 파라미터 만들기 창이 표시됩니다.
- 원격 구성 서버 템플릿을 처음 사용하는 것이 아니라면 파라미터 추가를 클릭합니다.

다음 원격 구성 파라미터를 정의합니다.

매개변수 이름	설명	유형	기본값
`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`

파라미터 추가가 완료되면 파라미터와 데이터 유형이 올바른지 다시 확인한 후 변경사항 게시를 클릭합니다.

6단계: 함수 배포 및 Firebase 로컬 에뮬레이터 도구 모음에서 테스트

이제 Firebase 로컬 에뮬레이터 도구 모음을 사용하여 로컬에서 함수를 배포하고 테스트할 준비가 되었습니다.

3단계: Admin SDK 서비스 계정의 IAM 권한 구성 및 키 저장에 설명된 대로 GOOGLE_APPLICATION_CREDENTIALS를 환경 변수로 설정했는지 확인합니다. 그런 다음 functions 디렉터리의 상위 디렉터리에서 함수를 Firebase 에뮬레이터에 배포합니다.
```
firebase emulators:start --project PROJECT_ID --only functions
```
도움말: functions 디렉터리에서 npm run serve를 실행하여 에뮬레이터에서 함수를 실행할 수도 있습니다.
에뮬레이터 로그 페이지를 엽니다. 그러면 함수가 로드되었음을 알 수 있습니다.
다음 명령어를 실행하여 함수에 액세스합니다. 여기서, PROJECT_ID는 프로젝트 ID이며 LOCATION은 함수를 배포한 리전입니다(예: us-central1).
```
curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex
```
팁: 이 링크는 에뮬레이터를 시작한 후 콘솔 출력에도 표시됩니다. 잘라낸 다음 브라우저에 붙여넣을 수도 있습니다.
응답을 기다린 다음 Firebase 에뮬레이터 로그 페이지 또는 콘솔로 돌아가 오류나 경고가 있는지 확인합니다.
사용자 입력을 전송해 보세요. is_vertex_enabled가 원격 구성 서버 템플릿에 구성되어 있으므로 Vertex AI Gemini API를 통해 Gemini에 액세스해야 하며 요금이 발생할 수 있습니다.
```
curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20cats
```
Firebase Console에서 원격 구성 서버 템플릿을 변경한 다음 함수에 다시 액세스하여 변경사항을 관찰합니다.

7단계: Google Cloud에 함수 배포

함수를 테스트하고 확인한 후에는 Google Cloud에 배포하고 라이브 함수를 테스트할 준비가 되었습니다.

함수 배포하기

Firebase CLI를 사용하여 함수를 배포합니다.

firebase deploy --only functions

함수에 대한 인증되지 않은 액세스 차단

Firebase를 사용해 함수를 배포하면 조직의 정책에서 제한하지 않는 경우 인증되지 않은 호출이 기본적으로 허용됩니다. 테스트하는 동안과 앱 체크로 보호하기 전에 인증되지 않은 액세스를 차단하는 것이 좋습니다.

함수에 대한 인증되지 않은 액세스를 차단하려면 다음을 수행합니다.

Google Cloud 콘솔에서 Cloud Run을 엽니다.
generateWithVertex를 클릭한 다음 보안 탭을 클릭합니다.
인증 필요를 사용 설정하고 저장을 클릭합니다.

Admin SDK 서비스 계정 사용자 인증 정보를 사용하도록 사용자 계정 구성

Admin SDK 서비스 계정에는 함수를 실행하고 원격 구성 및 Vertex AI Gemini API와 상호작용하기 위해 필요한 모든 역할과 권한이 있으므로 함수를 실행하는 데 사용할 수 있습니다. 그러려면 사용자 계정에서 해당 계정에 대한 토큰을 만들 수 있어야 합니다.

다음 단계에서는 Admin SDK 서비스 계정 권한으로 실행하도록 사용자 계정 및 함수를 구성하는 방법을 설명합니다.

Google Cloud 콘솔에서 IAM Service Account Credentials API를 사용 설정합니다.
사용자 계정에 서비스 계정 토큰 생성자 역할을 부여합니다. Google Cloud 콘솔에서 IAM 및 관리 > IAM을 열고 사용자 계정을 선택한 다음 주 구성원 수정 > 다른 역할 추가를 클릭합니다.
서비스 계정 토큰 생성자를 선택한 다음 저장을 클릭합니다.

서비스 계정 가장에 대한 자세한 내용은 Google Cloud 문서의 서비스 계정 가장을 참조하세요.
Google Cloud 콘솔 Cloud Functions 페이지를 열고 generateWithVertex 목록에서 generateWithVertex 함수를 클릭합니다.
트리거 > 수정을 선택하고 런타임, 빌드, 연결 및 보안 설정을 펼칩니다.
런타임 탭에서 런타임 서비스 계정을 Admin SDK 계정으로 변경합니다.
다음을 클릭한 후 배포를 클릭합니다.

gcloud CLI 설정

명령줄에서 함수를 안전하게 실행하고 테스트하려면 Cloud Functions 서비스에 인증하고 유효한 인증 토큰을 얻어야 합니다.

토큰 생성을 사용 설정하려면 gcloud CLI를 설치하고 구성합니다.

컴퓨터에 아직 설치하지 않았다면 gcloud CLI 설치에 설명된 대로 gcloud CLI를 설치합니다.
Google Cloud 계정의 액세스 사용자 인증 정보를 가져옵니다.
```
gcloud auth login
```
gcloud에서 프로젝트 ID를 설정합니다.
```
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"

이제 원격 구성 서버 템플릿을 변경하고 변경사항을 게시하고 다양한 옵션을 테스트할 수 있습니다.

다음 단계

Firebase에서는 앱 체크를 사용하여 Cloud Functions를 보호할 것을 권장합니다. 앱 체크로 함수 보호에 대한 자세한 내용은 Cloud Functions에 대한 앱 체크 적용 사용 설정을 참조하세요.
원격 구성 및 앱 체크로 Vertex AI Gemini API 호출에서 서버 측 원격 구성 및 앱 체크로 함께 호출 가능한 함수 샘플을 사용해 보세요.
Firebase용 Cloud Functions 자세히 알아보기
서버 환경에서 원격 구성 사용 자세히 알아보기