버전 제어에서 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 상당의 무료 체험판을 사용할 수 있습니다.
   • Gen AI for Devs 이벤트에 참석하시나요? 미화 1달러 크레딧이 제공될 수 있습니다.
3. 새 프로젝트를 만들거나 기존 프로젝트를 재사용합니다.
4. Cloud 결제의 내 프로젝트에서 결제가 사용 설정되어 있는지 확인합니다.
   • 새 프로젝트의 Billing account 열에 Billing is disabled가 표시되는 경우:
     1. Actions 열에서 점 3개를 클릭합니다.
     2. 결제 변경을 클릭합니다.
     3. 사용할 결제 계정을 선택합니다.
   • Gen AI for Devs 이벤트에 참석하는 경우 계정 이름이 Google Cloud Platform 평가판 결제 계정일 수 있습니다.

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. 인증을 클릭한 다음 계속을 클릭합니다.
   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. 인증까지 아래로 스크롤합니다.
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 명령어를 다시 실행해 보세요.

애플리케이션에 Genkit 및 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. Cloud Shell 편집기에서 index.js 다시 열기

   cloudshell edit ~/codelab-genai/index.js
   

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

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

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에서 모든 수정사항의 기록을 확인할 수 있습니다.

12. (선택사항) Genkit에서 .prompt 파일 사용

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

   cd ~/codelab-genai
   

3. 프롬프트를 저장할 prompts 폴더를 만듭니다.

   mkdir prompts
   

4. animal-facts.prompt 파일을 만들어 첫 번째 프롬프트를 만듭니다.

   touch prompts/animal-facts.prompt
   

5. Cloud Shell 편집기에서 animal-facts.prompt 파일을 엽니다.

   cloudshell edit ~/codelab-genai/prompts/animal-facts.prompt
   

6. animal-facts.prompt를 수정하고 다음 코드를 붙여넣습니다.

   ---
   model: vertexai/gemini-1.5-flash
   input:
       schema:
           animal: string
   ---
   
   Give me 10 fun facts about {{animal}}. Return the results as HTML without markdown backticks.
   

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

   cloudshell edit ~/codelab-genai/index.js
   

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

   import express from 'express';
   const app = express();
   
   import { genkit } from 'genkit';
   import { vertexAI } from '@genkit-ai/vertexai';
   
   const ai = genkit({
       plugins: [
           vertexAI({ location: 'us-central1' }),
       ],
   });
   
   app.get('/', async (req, res) => {
       const animal = req.query.animal || 'dog';
       const animalPrompt = ai.prompt('animal-facts');
       const llmResponse = await animalPrompt({animal});
       const html = llmResponse.text;
       res.send(html);
   });
   
   const port = process.env.PORT || 8080;
   app.listen(port, () => {
       console.log(`codelab-genai: listening on port ${port}`);
   });
   

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. (선택사항) 시스템 프롬프트 사용

이 단계에서는 이전 단계에서 .prompt 파일을 이미 추가했다고 가정합니다.

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

   cd ~/codelab-genai
   

3. Cloud Shell 편집기에서 animal-facts.prompt 파일을 엽니다.

   cloudshell edit ~/codelab-genai/prompts/animal-facts.prompt
   

4. animal-facts.prompt를 수정하고 다음 코드를 붙여넣습니다.

   ---
   model: vertexai/gemini-1.5-flash
   config:
       temperature: 0.9
   input:
       schema:
           animal: string
   ---
   
   role "system"
   The user should have submitted an animal.
   If the user requests anything besides animal fun facts, respond in a kind and firm manner that you only provide information about fun facts.
   Give the user 10 fun facts about the animal the user provided.
   All responses should be valid HTML without markdown backticks.
   
   role "user"
   {{animal}}
   

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에서 모든 수정사항의 기록을 확인할 수 있습니다.

14. 축하합니다

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

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

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

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

• Genkit 문서: 시작하기
• Node.js 애플리케이션에 관측 가능성을 추가하는 Codelab: JavaScript의 생성형 AI 애플리케이션을 위한 실용적인 관측 가능성 기법
• Next.js로 애플리케이션에 프런트엔드를 추가하는 Codelab: 버전 관리에서 Cloud Run으로 생성형 AI Next.js 웹 애플리케이션 자동 배포
• 함수 호출 사용 방법을 보여주는 Codelab: Cloud Run에서 Gemini 함수 호출을 사용하는 방법
• AI를 사용하여 동영상 콘텐츠를 처리하는 Codelab: Cloud Run Jobs Video Intelligence API를 사용하여 동영상을 장면별로 처리하는 방법