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

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

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

기본 요건

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

Firebase 프로젝트 설정

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

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

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

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

3. 메시지가 표시되면 이 솔루션을 사용하기 위해 Google Analytics를 설정하지 않아도 됩니다.

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
   

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

구현

다음 단계에 따라 Remote Config 및 Vertex AI를 사용하여 2세대 Cloud Functions를 만들고 테스트 및 배포하세요.

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

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

1. Google Cloud 콘솔을 열고 메시지가 표시되면 프로젝트를 선택합니다.
2. 콘솔 상단의 검색 필드에 Vertex AI를 입력하고 Vertex AI가 결과로 표시될 때까지 기다립니다.
3. Vertex AI을 선택합니다. Vertex AI 대시보드가 표시됩니다.

4. 모든 권장 API 사용 설정을 클릭합니다.

   API 사용 설정이 완료되는 데 몇 분 정도 걸릴 수 있습니다. 사용 설정이 완료될 때까지 페이지를 활성 상태로 열어둡니다.

5. 결제가 사용 설정되어 있지 않으면 Cloud Billing 계정을 추가하거나 연결하라는 메시지가 표시됩니다. 결제 계정을 사용 설정한 후 Vertex AI 대시보드로 돌아가 모든 권장 API가 사용 설정되어 있는지 확인합니다.

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

1. 컴퓨터에서 터미널을 열고 함수를 만들 디렉터리로 이동합니다.

2. Firebase에 로그인합니다.

   firebase login
   

3. 다음 명령어를 실행하여 Cloud Functions for Firebase를 초기화합니다.

   firebase init functions
   

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

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를 사용하는 경우 ESLint가 포함된 스탠자가 표시됩니다. 또한 노드 엔진 버전이 Node.js의 설치된 버전 및 최종적으로 Google Cloud에서 실행하는 버전과 일치하는지 확인합니다. 예를 들어 package.json의 engines 스탠자가 노드 버전 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. 다른 역할 추가를 클릭하고 Remote Config 뷰어를 선택합니다.
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를 초기화하고, Remote Config을 사용하여 기본 파라미터를 구성하고, 최신 Remote Config 파라미터를 가져오고, 사용자 입력을 처리하고, 사용자에게 응답을 다시 스트리밍하는 포괄적인 함수를 빌드합니다.

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

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 클라이언트를 참조하세요.

   원하는 경우 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-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 Console을 열고 탐색 메뉴에서 실행을 펼치고 Remote Config을 선택합니다.

2. Remote Config 페이지 상단의 클라이언트/서버 선택기에서 서버를 선택합니다.

   • Remote Config 또는 서버 템플릿을 처음 사용하는 경우 구성 만들기를 클릭합니다. 첫 번째 서버 측 파라미터 만들기 창이 표시됩니다.
   • Remote Config 서버 템플릿을 처음 사용하는 것이 아니라면 파라미터 추가를 클릭합니다.

3. 다음 Remote Config 파라미터를 정의합니다.

   매개변수 이름	설명	유형	기본값
   model_name	모델 이름 코드에서 사용할 최신 모델 이름 목록은 모델 버전 및 수명 주기 또는 사용 가능한 모델 이름을 참조하세요.	문자열	gemini-1.5-flash-002
   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. 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가 Remote Config 서버 템플릿에 구성되어 있으므로 Vertex AI Gemini API를 통해 Gemini에 액세스해야 하며 요금이 발생할 수 있습니다.

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

6. Firebase Console에서 Remote Config 서버 템플릿을 변경한 다음 함수에 다시 액세스하여 변경사항을 관찰합니다.

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

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

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

4. Google Cloud 콘솔 Cloud Functions 페이지를 열고 generateWithVertex 목록에서 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"

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

다음 단계

• Firebase에서는 App Check를 사용하여 Cloud Functions를 보호할 것을 권장합니다. App Check로 함수를 보호하는 방법에 관한 자세한 내용은 Cloud Functions에 App Check 적용 사용 설정을 참조하세요.
• Remote Config 및 App Check로 Vertex AI Gemini API 호출에서 서버 측 Remote Config 및 App Check로 호출 가능한 함수 샘플을 사용해 보세요.
• Firebase용 Cloud Functions 자세히 알아보기
• 서버 환경에서 Remote Config 사용 자세히 알아보기