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

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

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

기본 요건

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

Firebase 프로젝트 설정

아직 Firebase 프로젝트가 없다면 다음 안내를 따르세요.

1. Firebase Console에 로그인합니다.

2. 프로젝트 만들기를 클릭하고 다음 옵션 중 하나를 사용합니다.

   • 옵션 1: '프로젝트 만들기' 워크플로의 첫 번째 단계에서 새 프로젝트 이름을 입력하여 새 Firebase 프로젝트와 기본 Google Cloud 프로젝트를 자동으로 만듭니다.
   • 옵션 2: '프로젝트 만들기' 워크플로의 첫 번째 단계에 있는 드롭다운 메뉴에서 Google Cloud 프로젝트 이름을 선택하여 기존 Google Cloud 프로젝트에 'Firebase를 추가'합니다.

3. 메시지가 표시되면 이 솔루션을 사용하기 위해 Google 애널리틱스를 설정할 필요가 없습니다.

4. 계속해서 화면에 표시된 안내에 따라 프로젝트를 만듭니다.

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

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

개발 환경 구성

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

1. Node.js와 npm을 설치합니다.

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

2. 원하는 방법으로 Firebase CLI를 설치합니다. 예를 들어 npm을 사용하여 CLI를 설치하려면 다음 명령어를 실행합니다.

   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
   

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

구현

원격 구성 및 Vertex AI로 2세대 Cloud Functions를 생성, 테스트, 배포하려면 다음 단계를 따르세요.

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

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

1. Google Cloud 콘솔을 열고 메시지가 표시되면 프로젝트를 선택합니다.
2. 콘솔 상단의 Search(검색) 필드에 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. 다음 명령어를 실행하여 Firebase용 Cloud Functions를 초기화합니다.

   firebase init functions
   

4. 기존 프로젝트 사용을 선택하고 프로젝트 ID를 지정합니다.

5. 사용할 언어를 선택하라는 메시지가 표시되면 자바스크립트를 선택하고 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를 사용하는 경우 ESLint가 포함된 스탠자가 표시됩니다. 또한 노드 엔진 버전이 설치된 Node.js 버전 및 최종적으로 Google Cloud에서 실행하는 버전과 일치해야 합니다. 예를 들어 package.json의 engines 스탠자가 Node 버전 18로 구성되었고 Node.js 20을 사용 중인 경우 20을 사용하도록 파일을 업데이트합니다.

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

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

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

1. Google Cloud 콘솔에서 IAM 및 관리자 페이지를 열고 Admin SDK 서비스 계정 (firebase-adminsdk)을 찾습니다.
2. 계정을 선택하고 주 구성원 수정을 클릭합니다. 액세스 권한 수정 페이지가 나타납니다.
3. 다른 역할 추가를 클릭하고 원격 구성 뷰어를 선택합니다.
4. 다른 역할 추가를 클릭하고 AI Platform 개발자를 선택합니다.
5. 다른 역할 추가를 클릭하고 Vertex AI 사용자를 선택합니다.
6. 다른 역할 추가를 클릭하고 Cloud Run 호출자를 선택합니다.
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단계: 함수 만들기

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

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

2. 기존 콘텐츠를 삭제한 후 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
   

3. 함수가 원격 구성 서버에 연결할 수 없는 경우 사용할 기본값을 구성합니다. 이 솔루션은 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
   

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

   // 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단계: 서버별 원격 구성 템플릿 만들기

다음으로 서버 측 원격 구성 템플릿을 만들고 함수에 사용할 매개변수와 값을 구성합니다. 서버별 원격 구성 템플릿을 만드는 방법은 다음과 같습니다.

1. Firebase Console을 열고 탐색 메뉴에서 실행을 펼치고 원격 구성을 선택합니다.

2. 원격 구성 페이지 상단의 클라이언트/서버 선택기에서 서버를 선택합니다.

   • 원격 구성 또는 서버 템플릿을 처음 사용하는 경우 구성 만들기를 클릭합니다. 첫 번째 서버 측 매개변수 만들기 창이 나타납니다.
   • 원격 구성 서버 템플릿을 처음 사용하는 것이 아니라면 매개변수 추가를 클릭합니다.

3. 다음 원격 구성 매개변수를 정의합니다.

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

4. 매개변수 추가를 마쳤으면 매개변수를 다시 확인하고 데이터 유형이 올바른지 확인한 후 변경사항 게시를 클릭합니다.

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

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

1. 3단계: Admin SDK 서비스 계정에 대한 IAM 권한 구성 및 키 저장에 설명된 대로 GOOGLE_APPLICATION_CREDENTIALS를 환경 변수로 설정했는지 확인합니다. 그런 다음 functions 디렉터리의 상위 디렉터리에서 함수를 Firebase 에뮬레이터에 배포합니다.

   firebase emulators:start --project PROJECT_ID --only functions
   

2. 에뮬레이터의 로그 페이지를 엽니다. 그러면 함수가 로드되었음을 알 수 있습니다.

3. 다음 명령어를 실행하여 함수에 액세스합니다. 여기서 PROJECT_ID는 프로젝트 ID이고 LOCATION은 함수를 배포한 리전입니다 (예: us-central1).

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

4. 응답을 기다린 후 Firebase 에뮬레이터 로그 페이지 또는 콘솔로 돌아가서 오류나 경고가 있는지 확인합니다.

5. 사용자 입력을 전송해 봅니다. is_vertex_enabled는 원격 구성 서버 템플릿에 구성되어 있으므로 Vertex AI Gemini API를 통해 Gemini에 액세스해야 하며 이로 인해 요금이 부과될 수 있습니다.

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

6. Firebase Console에서 원격 구성 서버 템플릿을 변경한 후 함수에 다시 액세스하여 변경사항을 관찰합니다.

7단계: Google Cloud에 함수 배포

함수를 테스트하고 확인한 후에는 Google Cloud에 배포하고 실시간 함수를 테스트할 수 있습니다.

함수 배포하기

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

firebase deploy --only functions

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

Firebase를 사용하여 함수를 배포할 때 조직의 정책에서 제한하지 않는다면 인증되지 않은 호출이 기본적으로 허용됩니다. 테스트 중, 그리고 앱 체크로 보호하기 전에 인증되지 않은 액세스를 차단하는 것이 좋습니다.

함수에 대한 인증되지 않은 액세스를 차단하려면 다음 안내를 따르세요.

1. Google Cloud 콘솔에서 Cloud Run을 엽니다.

2. generateWithVertex를 클릭한 다음 보안 탭을 클릭합니다.

3. 인증 필요를 사용 설정한 다음 저장을 클릭합니다.

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

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

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

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

3. 서비스 계정 토큰 생성자를 선택한 후 저장을 클릭합니다.

   서비스 계정 가장에 대한 자세한 내용은 Google Cloud 문서의 서비스 계정 가장을 참조하세요.

4. Google Cloud 콘솔 Cloud Functions 페이지를 열고 함수 목록에서 generateWithVertex 함수를 클릭합니다.

5. 트리거 > 수정을 선택하고 런타임, 빌드, 연결, 보안 설정을 펼칩니다.

6. 런타임 탭에서 런타임 서비스 계정을 Admin SDK 계정으로 변경합니다.

7. 다음을 클릭한 후 배포를 클릭합니다.

gcloud CLI 설정

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

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

1. 컴퓨터에 아직 설치되지 않았다면 gcloud CLI 설치에 설명된 대로 gcloud CLI를 설치합니다.

2. Google Cloud 계정의 액세스 사용자 인증 정보를 가져옵니다.

   gcloud auth login
   

3. 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에 대해 자세히 알아보세요.
• 서버 환경에서 원격 구성 사용에 대해 자세히 알아보세요.