버전 제어에서 Cloud Run으로 생성형 AI Node.js Genkit 웹 애플리케이션 자동 배포

1. 개요

웹 애플리케이션을 처음 배포하는 것은 쉽지 않을 수 있습니다. 첫 번째 배포 후에도 프로세스가 너무 많은 경우 새 버전의 애플리케이션을 배포하지 않을 수 있습니다. 지속적 배포를 사용하면 애플리케이션 변경사항을 간편하게 자동으로 배포할 수 있습니다.

이 실습에서는 웹 애플리케이션을 작성하고 애플리케이션의 소스 코드가 변경될 때 애플리케이션을 자동으로 배포하도록 Cloud Run을 구성합니다. 그런 다음 애플리케이션을 수정하고 다시 배포합니다.

학습할 내용

• Cloud Shell 편집기로 웹 애플리케이션 작성
• GitHub에 애플리케이션 코드 저장
• Cloud Run에 애플리케이션 자동 배포

• Genkit을 사용하여 애플리케이션에 생성형 AI 추가
• dotprompt 라이브러리를 사용하여 LLM 프롬프트 관리

2. 기본 요건

1. 아직 Google 계정이 없다면 Google 계정을 만들어야 합니다.
   • 직장 또는 학교 계정이 아닌 개인 계정을 사용합니다. 직장 및 학교 계정에는 이 실습에 필요한 API를 사용 설정할 수 없도록 하는 제한사항이 있을 수 있습니다.
2. 아직 GitHub 계정이 없다면 GitHub 계정을 만들어야 합니다.
   • 기존 GitHub 계정이 있는 경우 이를 사용합니다. GitHub에서 새 계정을 스팸으로 차단할 가능성이 높습니다.
   • 계정이 스팸으로 표시될 가능성을 줄이려면 GitHub 계정에 2단계 인증을 구성하세요.

3. 프로젝트 설정

1. Google Cloud 콘솔에 로그인합니다.
2. Cloud 콘솔에서 결제를 사용 설정합니다.
   • 이 실습을 완료하는 데 드는 Cloud 리소스 비용은 미화 1달러 미만입니다.
   • 이 실습의 끝에 있는 단계에 따라 리소스를 삭제하면 추가 비용이 발생하지 않습니다.
   • 신규 사용자는 미화 300달러 상당의 무료 체험판을 이용할 수 있습니다.
   • 개발자를 위한 생성형 AI 이벤트에 참석하시나요? 1달러 상당의 크레딧이 제공될 수 있습니다.
3. 새 프로젝트를 만들거나 기존 프로젝트를 재사용합니다.

4. Cloud Shell 편집기 열기

1. Cloud Shell 편집기로 이동합니다.
2. 터미널이 화면 하단에 표시되지 않으면 다음과 같이 엽니다.
   • 햄버거 메뉴 를 클릭합니다.
   • 터미널을 클릭합니다.
   • 새 터미널을 클릭합니다.
3. 터미널에서 다음 명령어를 사용하여 프로젝트를 설정합니다.
   • 형식:

     gcloud config set project [PROJECT_ID]
     

   • 예:

     gcloud config set project lab-project-id-example
     

   • 프로젝트 ID를 기억할 수 없는 경우 다음 안내를 따르세요.
     • 다음을 사용하여 모든 프로젝트 ID를 나열할 수 있습니다.

       gcloud projects list | awk '/PROJECT_ID/{print $2}'
       

     
4. 승인하라는 메시지가 표시되면 승인을 클릭하여 계속 진행합니다.
5. 다음 메시지가 표시됩니다.

   Updated property [core/project].
   

   WARNING가 표시되고 Do you want to continue (Y/N)?라는 메시지가 표시되면 프로젝트 ID를 잘못 입력했을 가능성이 큽니다. N를 누른 다음 Enter를 누르고 gcloud config set project 명령어를 다시 실행해 봅니다.

5. API 사용 설정

터미널에서 API를 사용 설정합니다.

gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  aiplatform.googleapis.com

이 명령어를 완료하는 데 몇 분 정도 걸릴 수 있지만 결국 다음과 비슷한 성공 메시지가 표시됩니다.

Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.

6. Git 구성

1. 전역 git 사용자 이메일을 설정합니다.

   git config --global user.email "[e-mail]"
   

2. 전역 Git 사용자 이름을 설정합니다.

   git config --global user.name "Your Name"
   

3. 전역 Git 기본 브랜치를 main로 설정합니다.

   git config --global init.defaultBranch main
   

7. 코드 작성

Node.js로 애플리케이션을 작성하려면 다음 안내를 따르세요.

1. 홈 디렉터리로 이동합니다.

   cd ~
   

2. codelab-genai 디렉터리를 만듭니다.

   mkdir codelab-genai
   

3. codelab-genai 디렉터리로 이동합니다.

   cd codelab-genai
   

4. index.js 파일을 만듭니다.

   touch index.js
   

5. package.json 파일을 만듭니다.

   npm init es6 -y
   

6. express를 종속 항목으로 추가합니다.

   npm install express
   

7. node_modules 커밋을 방지하기 위해 .gitignore 파일 추가

   echo node_modules/ >> .gitignore
   

8. Cloud Shell 편집기에서 index.js 파일을 엽니다.

   cloudshell edit index.js
   

   이제 화면 상단에 빈 파일이 표시됩니다. 여기에서 이 index.js 파일을 수정할 수 있습니다.
9. 다음 코드를 복사하여 열려 있는 index.js 파일에 붙여넣습니다.

   import express from 'express';
   
   const app = express();
   app.get('/', async (req, res) => {
       res.send('Hello world!');
   });
   
   const port = process.env.PORT || 8080;
   app.listen(port, () => {
       console.log(`codelab-genai: listening on port ${port}`);
   });
   

   몇 초 후 Cloud Shell 편집기에서 코드를 자동으로 저장합니다. 이 코드는 'Hello world!' 인사로 HTTP 요청에 응답합니다.

애플리케이션의 초기 코드가 완료되었으며 버전 제어에 저장할 준비가 되었습니다.

8. 저장소 만들기

1. 화면 하단의 Cloud Shell 터미널로 돌아갑니다.
2. 여전히 올바른 디렉터리에 있는지 확인합니다.

   cd ~/codelab-genai
   

3. git 저장소 초기화

   git init -b main
   

4. GitHub CLI에 로그인합니다.

   gh auth login
   

   Enter 키를 눌러 기본 옵션을 수락하고 다음을 포함하여 GitHub CLI 도구의 안내를 따릅니다.
   1. 어떤 계정에 로그인하시겠어요? GitHub.com
   2. 이 호스트에서 Git 작업에 사용하는 프로토콜은 무엇인가요? HTTPS
   3. GitHub 사용자 인증 정보로 Git을 인증하나요? Y (이 아이콘이 표시되지 않으면 건너뜁니다.)
   4. GitHub CLI를 어떻게 인증하시겠어요? Login with a web browser
   5. 일회성 코드 복사
   6. https://github.com/login/device를 엽니다.
   7. 일회성 코드 붙여넣기
   8. GitHub 승인을 클릭합니다.
   9. 로그인 완료
5. 로그인했는지 확인합니다.

   gh api user -q ".login"
   

   로그인한 경우 GitHub 사용자 이름이 출력됩니다.
6. GITHUB_USERNAME 변수 만들기

   GITHUB_USERNAME=$(gh api user -q ".login")
   

7. 환경 변수를 만들었는지 확인합니다.

   echo ${GITHUB_USERNAME}
   

   변수를 만들면 GitHub 사용자 이름이 출력됩니다.
8. codelab-genai라는 이름의 빈 GitHub 저장소를 만듭니다.

   gh repo create codelab-genai --private
   

   다음과 같은 오류가 표시되면

   GraphQL: Name already exists on this account (createRepository)
   

   codelab-genai라는 저장소가 이미 있는 것입니다. 이 튜토리얼을 계속 진행하는 방법에는 두 가지가 있습니다.
   • 기존 GitHub 저장소 삭제
   • 다른 이름으로 저장소를 만들고 다음 명령어에서 이름을 변경해야 합니다.
9. codelab-genai 저장소를 원격 origin로 추가합니다.

   git remote add origin https://github.com/${GITHUB_USERNAME}/codelab-genai
   

9. 코드 공유

1. 올바른 디렉터리에 있는지 확인합니다.

   cd ~/codelab-genai
   

2. 현재 디렉터리의 모든 파일을 이 커밋에 추가합니다.

   git add .
   

3. 첫 번째 커밋을 만듭니다.

   git commit -m "add http server"
   

4. origin 저장소의 main 브랜치로 커밋을 푸시합니다.

   git push -u origin main
   

이 명령어를 실행하고 결과 URL을 방문하여 GitHub에서 애플리케이션 코드를 볼 수 있습니다.

echo -e "\n\nTo see your code, visit this URL:\n \
    https://github.com/${GITHUB_USERNAME}/codelab-genai/blob/main/index.js \n\n"

10. 자동 배포 설정

1. Cloud Shell 편집기 탭을 열어 둡니다. 이 탭은 나중에 다시 살펴보겠습니다.
2. 새 탭에서 Cloud Run 페이지로 이동합니다.
3. 콘솔 에서 올바른 Google Cloud 프로젝트를 선택합니다.
4. 저장소 연결을 클릭합니다.
5. Cloud Build로 설정을 클릭합니다.
   1. 저장소 제공업체로 GitHub를 선택합니다.
      • 브라우저에서 GitHub 계정에 로그인하지 않은 경우 사용자 인증 정보로 로그인합니다.
   2. Authenticate를 클릭한 다음 Continue를 클릭합니다.
   3. 로그인하면 Cloud Run 페이지에 저장소에 GitHub 앱이 설치되지 않았습니다.라는 메시지가 표시됩니다.
   4. Google Cloud Build 설치 버튼을 클릭합니다.
      • 설치 설정 페이지에서 저장소만 선택을 선택하고 CLI를 통해 만든 codelab-genai 저장소를 선택합니다.
      • 설치를 클릭합니다.
      • 참고: GitHub 저장소가 많은 경우 로드하는 데 몇 분 정도 걸릴 수 있습니다.
   5. 저장소로 your-user-name/codelab-genai를 선택합니다.
      • 저장소가 표시되지 않으면 연결된 저장소 관리 링크를 클릭합니다.
   6. 브랜치를 ^main$로 둡니다.
   7. Google Cloud 빌드팩을 통한 Go, Node.js, Python, Java, .NET Core, Ruby 또는 PHP를 클릭합니다.
      • 다른 필드 (Build context directory, Entrypoint, Function target)는 그대로 둡니다.
   8. 저장을 클릭합니다.
6. Authentication(인증)까지 아래로 스크롤합니다.
7. 인증되지 않은 호출 허용을 클릭합니다.
8. 만들기를 클릭합니다.

빌드가 완료되면 (몇 분 정도 걸림) 이 명령어를 실행하고 결과 URL을 방문하여 실행 중인 애플리케이션을 확인합니다.

echo -e "\n\nOnce the build finishes, visit your live application:\n \
    "$( \
        gcloud run services list | \
        grep codelab-genai | \
        awk '/URL/{print $2}' | \
        head -1 \
    )" \n\n"

11. 코드 변경

Cloud Shell 편집기로 돌아가기

Cloud Shell 편집기가 아직 열려 있으면 이 단계를 건너뛸 수 있습니다.

1. Cloud Shell 편집기로 이동합니다.
2. 터미널이 화면 하단에 표시되지 않으면 다음과 같이 엽니다.
   • 햄버거 메뉴 를 클릭합니다.
   • 터미널을 클릭합니다.
   • 새 터미널을 클릭합니다.
3. 터미널에서 다음 명령어를 사용하여 프로젝트를 설정합니다.
   • 형식:

     gcloud config set project [PROJECT_ID]
     

   • 예:

     gcloud config set project lab-project-id-example
     

   • 프로젝트 ID를 기억할 수 없는 경우 다음 안내를 따르세요.
     • 다음을 사용하여 모든 프로젝트 ID를 나열할 수 있습니다.

       gcloud projects list | awk '/PROJECT_ID/{print $2}'
       

     
4. 승인하라는 메시지가 표시되면 승인을 클릭하여 계속 진행합니다.
5. 다음 메시지가 표시됩니다.

   Updated property [core/project].
   

   WARNING가 표시되고 Do you want to continue (Y/N)?라는 메시지가 표시되면 프로젝트 ID를 잘못 입력했을 가능성이 큽니다. N를 누른 다음 Enter를 누르고 gcloud config set project 명령어를 다시 실행해 봅니다.

애플리케이션에 Vertex AI 추가

1. 화면 하단의 Cloud Shell 터미널로 돌아갑니다.
2. 여전히 올바른 디렉터리에 있는지 확인합니다.

   cd ~/codelab-genai
   

3. Node.js Genkit SDK를 설치합니다.

   npm install @genkit-ai/ai
   

4. Vertex AI용 Node.js Genkit SDK를 설치합니다.

   npm install @genkit-ai/vertexai
   

5. Node.js Google 인증 SDK를 설치합니다.

   npm install google-auth-library
   

6. Cloud Shell 편집기에서 index.js를 다시 엽니다.

   cloudshell edit ~/codelab-genai/index.js
   

7. index.js 파일의 코드를 다음으로 바꿉니다.

   import express from 'express';
   const app = express();
   
   import { generate } from '@genkit-ai/ai';
   import { gemini15Flash, vertexAI } from '@genkit-ai/vertexai';
   
   import { GoogleAuth } from 'google-auth-library';
   const auth = new GoogleAuth();
   
   app.get('/', async (req, res) => {
       const project = await auth.getProjectId();
   
       const animal = req.query.animal || 'dog';
       const prompt = `Give me 10 fun facts about ${animal}. Return this as html without backticks.`
       const result = await generate({
           plugins: [
               vertexAI({ projectId: project, location: 'us-central1' }),
           ],
           model: gemini15Flash,
           prompt,
       });
       const html = result.text;
       res.send(html);
   });
   
   const port = process.env.PORT || 8080;
   app.listen(port, () => {
       console.log(`codelab-genai: listening on port ${port}`);
   });
   

12. 다시 배포

1. Cloud Shell에서 여전히 올바른 디렉터리에 있는지 확인합니다.

   cd ~/codelab-genai
   

2. 다음 명령어를 실행하여 새 버전의 애플리케이션을 로컬 Git 저장소에 커밋합니다.

   git add .
   git commit -m "add latest changes"
   

3. 변경사항을 GitHub로 푸시합니다.

   git push
   

4. 빌드가 완료되면 이 명령어를 실행하고 배포된 애플리케이션을 방문합니다.

   echo -e "\n\nOnce the build finishes, visit your live application:\n \
       "$( \
           gcloud run services list | \
           grep codelab-genai | \
           awk '/URL/{print $2}' | \
           head -1 \
       )" \n\n"
   

빌드가 완료되고 변경사항이 표시되기까지 몇 분 정도 걸릴 수 있습니다.

여기에서 모든 버전의 기록을 확인할 수 있습니다. https://console.cloud.google.com/run/detail/us-central1/codelab-genai/revisions

13. (선택사항) Vertex AI 사용 감사

다른 Google Cloud 서비스와 마찬가지로 Vertex AI 작업을 감사할 수 있습니다. 감사 로그는 '누가, 언제, 어디서, 무엇을 했나?'와 같은 질문의 답을 확인하는 데 도움이 됩니다. Vertex AI의 관리 감사 로그는 기본적으로 사용 설정되어 있습니다. 콘텐츠 생성 요청을 감사하려면 데이터 액세스 감사 로그를 사용 설정해야 합니다.

데이터 감사 로그로 인해 추가 비용이 발생할 수 있습니다.

1. Google Cloud 콘솔에서 감사 로그 페이지로 이동합니다.
   감사 로그로 이동
   검색창을 사용하여 이 페이지를 찾은 경우 부제목이 IAM 및 관리자인 결과를 선택합니다.
2. Cloud Run 애플리케이션을 만드는 Google Cloud 프로젝트가 기존 프로젝트인지 확인합니다.
3. 데이터 액세스 감사 로그 구성 표에서 서비스 열에서 Vertex AI API를 선택합니다.
4. 로그 유형 탭에서 데이터 액세스 감사 로그 유형 Admin read 및 Data read를 선택합니다.
5. 저장을 클릭합니다.

사용 설정하면 애플리케이션을 호출할 때마다 감사 로그를 볼 수 있습니다. 호출 세부정보가 포함된 감사 로그를 보려면 다음 단계를 따르세요.

1. 배포된 애플리케이션으로 돌아가서 페이지를 새로고침하여 로그를 트리거합니다.
2. Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.
   로그 탐색기로 이동
   
3. 쿼리 창에 다음을 입력합니다.

   LOG_ID("cloudaudit.googleapis.com%2Fdata_access")
   protoPayload.serviceName="aiplatform.googleapis.com"
   

4. 쿼리 실행을 클릭합니다.

감사 로그는 Vertex AI API 사용을 캡처하지만 프롬프트나 응답 세부정보와 같은 워크로드 관련 데이터는 관찰할 수 없습니다.

14. (선택사항) AI 워크로드의 관측 가능성 높이기

감사 로그에는 워크로드 관련 정보가 포함되지 않습니다. 워크로드의 관측 가능성을 높이려면 이 정보를 명시적으로 로깅해야 합니다. 이를 위해 좋아하는 로깅 프레임워크를 사용할 수 있습니다. 다음 단계에서는 네이티브 Node.js 로깅 메커니즘을 사용하여 이를 수행하는 방법을 보여줍니다.

1. Cloud Shell 편집기에서 index.js를 다시 엽니다.

   cloudshell edit ~/codelab-genai/index.js
   

2. await generativeModel.generateContent(prompt) 호출 (19번 줄) 뒤에 다음 줄을 추가합니다.

       console.log(JSON.stringify({
           severity: 'DEBUG',
           message: 'Content is generated',
           prompt: prompt,
           response: resp.response,
       }));
   

   이 코드는 구조화된 로깅 형식을 사용하여 생성된 콘텐츠에 관한 정보를 stdout에 씁니다. Cloud Run의 Logging 에이전트는 stdout에 출력된 출력을 캡처하고 이 형식을 Cloud Logging에 기록합니다.
3. Cloud Shell을 다시 열고 다음 명령어를 입력하여 올바른 디렉터리에 있는지 확인합니다.

   cd ~/codelab-genai
   

4. 변경사항을 커밋합니다.

   git commit -am "observe generated content"
   

5. GitHub에 변경사항을 푸시하여 수정된 버전의 재배포를 트리거합니다.

   git push
   

새 버전이 배포되면 Vertex AI 호출에 관한 디버그 정보를 확인할 수 있습니다.

애플리케이션 로그를 보려면 다음 단계를 따르세요.

1. Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.
   로그 탐색기로 이동
   
2. 쿼리 창에 다음을 입력합니다.

   LOG_ID("run.googleapis.com%2Fstdout")
   severity=DEBUG
   

3. 쿼리 실행을 클릭합니다.

쿼리 결과에는 프롬프트와 안전 관행 모니터링에 사용할 수 있는 '안전 등급'을 포함한 Vertex AI 응답이 포함된 로그가 표시됩니다.

프롬프트는 관찰 대상이 아닌 민감한 정보가 포함될 수 있으므로 로깅할 때는 주의해야 합니다. 이 정보를 마스킹하거나 다른 방법으로 가릴 수 있습니다. 자세한 내용은 DLP 문서를 참고하세요.

15. (선택사항) 정리

Cloud Run에서는 서비스를 사용하지 않을 때 비용이 청구되지 않지만 Artifact Registry에 컨테이너 이미지를 저장하는 데 요금이 부과될 수 있습니다. 비용이 청구되지 않도록 Cloud 프로젝트를 삭제할 수 있습니다. Cloud 프로젝트를 삭제하면 해당 프로젝트 내에서 사용되는 모든 리소스에 대한 청구가 중단됩니다.

원하는 경우 프로젝트를 삭제합니다.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

CloudShell 디스크에서 불필요한 리소스를 삭제할 수도 있습니다. 다음과 같은 작업을 할 수 있습니다.

1. Codelab 프로젝트 디렉터리를 삭제합니다.

   rm -rf ~/codelab-genai
   

2. 경고 이 작업은 실행취소할 수 없습니다. Cloud Shell에서 모든 항목을 삭제하여 공간을 확보하려면 전체 홈 디렉터리를 삭제하면 됩니다. 보관하려는 모든 항목이 다른 곳에 저장되어 있는지 확인합니다.

   sudo rm -rf $HOME
   

16. 축하합니다

이 실습에서는 웹 애플리케이션을 작성하고 애플리케이션의 소스 코드가 변경될 때 애플리케이션을 자동으로 배포하도록 Cloud Run을 구성했습니다. 그런 다음 애플리케이션을 수정하고 다시 배포했습니다.

이 실습이 마음에 들었다면 다른 코딩 언어 또는 프레임워크로 다시 시도해 보세요.

• Python
• Node.js
• Go
• 자바
• Angular
• Next.js

현재 사용 중인 제품을 개선하기 위한 사용자 경험 (UX) 연구에 참여하고 싶다면 여기에서 등록하세요.

다음은 학습을 계속할 수 있는 몇 가지 옵션입니다.

• 문서: Firebase GenKit를 유연한 모델 추상화로 사용하여 모든 모델 API를 쉽게 통합하고 커뮤니티에서 유지관리하는 모델을 사용할 수 있습니다.
• Codelab: Cloud Run에 Gemini 지원 채팅 앱을 배포하는 방법
• Cloud Run에서 Gemini 함수 호출을 사용하는 방법
• Cloud Run Jobs Video Intelligence API를 사용하여 동영상을 장면별로 처리하는 방법
• 주문형 워크샵: Google Kubernetes Engine 온보딩