빠른 시작: Vertex AI Studio 프롬프트를 웹 애플리케이션으로 배포

프리뷰

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참고하세요.

Vertex AI Studio에서는 프롬프트를 설계하고 반복하며 다양한 구성과 모델에서 나온 결과를 비교할 수 있습니다. 프롬프트 엔지니어링을 완료한 뒤에는 이를 웹 애플리케이션으로 배포해 공동작업자 또는 대상 사용자에게 공유하여 실제로 테스트할 수 있습니다. 이 웹 애플리케이션은 Cloud Run에서 호스팅되며 Google Cloud 콘솔 외부에서도 사용할 수 있습니다.

이 빠른 시작에서는 다음을 수행합니다.

• 프롬프트 변수와 함께 프롬프트 만들기
• 프롬프트를 웹 애플리케이션으로 배포
• 배포 진행 상황 모니터링 및 배포된 애플리케이션 테스트
• 프롬프트 업데이트 및 다시 배포
• 멀티모달을 지원하는 프롬프트 제출 기능 테스트

시작하기 전에

Vertex AI Studio를 처음 사용한다면, 다른 빠른 시작 가이드를 참조하거나 Google Cloud Skills Boost 과정을 통해 Vertex AI Studio의 기본 개념을 익힐 수 있습니다. 이 가이드를 진행하려면 아래 항목을 준비해야 합니다.

1. 결제 및 Vertex AI API가 사용 설정된 Google Cloud 프로젝트
2. Vertex AI Studio 프롬프트를 웹 애플리케이션으로 배포하는 데 필요한 역할. 이 가이드에 새 프로젝트를 만든 경우 필요한 권한이 이미 있는 것입니다.

선택적으로 Compute Engine 기본 서비스 계정에 배포 서비스 계정에 필요한 역할이 있는지 확인할 수도 있습니다. 역할을 부여할 수 있는 권한이 있다면, 애플리케이션 배포 시점에 직접 역할을 부여할 수도 있습니다.

필요한 역할

Vertex AI Studio 프롬프트를 웹 애플리케이션으로 배포하는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 프로젝트 수준에서 부여해 달라고 요청하세요.

• Vertex AI 사용자(roles/aiplatform.user)
• 필요한 API 사용 설정: 서비스 사용량 관리자(roles/serviceusage.serviceUsageAdmin)
• Compute Engine 기본 서비스 계정에 필요한 역할 부여: 프로젝트 IAM 관리자(roles/resourcemanager.projectIamAdmin)
• Cloud Run 애플리케이션 배포:
  • Cloud Run 관리자(roles/run.admin)
  • Cloud Run 소스 개발자(roles/run.sourceDeveloper)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

배포 서비스 계정에 필요한 역할

Compute Engine 기본 서비스 계정이 사용자 대신 빌드를 실행하는 데 필요한 권한을 갖추도록 하려면 관리자에게 Compute Engine 기본 서비스 계정에 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

중요: 이러한 역할을 사용자 계정이 아닌 Compute Engine 기본 서비스 계정에 부여해야 합니다. 올바른 주 구성원에 역할을 부여하지 않으면 권한 오류가 발생할 수 있습니다.

• Vertex AI 서비스 에이전트(roles/aiplatform.serviceAgent)
• Cloud Build 서비스 계정(roles/cloudbuild.builds.builder)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

관리자는 커스텀 역할이나 다른 사전 정의된 역할을 통해 Compute Engine 기본 서비스 계정에 필요한 권한을 부여할 수도 있습니다.

역할을 부여할 수 있는 권한이 있다면, 애플리케이션 배포 시점에 직접 역할을 부여할 수도 있습니다.

프롬프트 변수와 함께 프롬프트 만들기

Vertex AI Studio의 프롬프트 만들기 페이지로 이동한 다음 프롬프트 입력 상자에서 변수 추가를 클릭합니다.

프롬프트 변수 관리 대화상자에서 변수 이름을 입력하고 값을 설정합니다. 그런 다음 적용을 클릭합니다.

프롬프트 입력 상자에서 변수를 사용해 프롬프트를 작성한 후 다른 파라미터도 조정합니다. 예를 들어 Google 검색을 사용한 그라운딩을 사용 설정하고 시스템 지침에 '항상 웹에서 현재 날씨 가져오기'와 같은 문구를 설정할 수 있습니다.

프롬프트를 웹 애플리케이션으로 배포

프롬프트를 웹 애플리케이션으로 배포하려면 오른쪽 상단의 코드로 빌드 버튼을 클릭합니다. 그런 다음 앱으로 배포를 클릭합니다.

프롬프트 저장

프롬프트는 배포 전에 저장해야 하므로 프롬프트 저장 대화상자가 표시됩니다. 프롬프트가 저장되면 배포 대화상자가 자동으로 열립니다.

참고: 프로젝트에서 특정 리전에 프롬프트를 처음 저장할 때는 완료까지 2~3분 정도 걸릴 수 있습니다. 1분이 지나면 경고 상자가 표시됩니다. 이는 최초 한 번만 느리게 처리되는 정상 동작입니다. 동일한 프로젝트와 리전을 사용할 경우 이후의 프롬프트 저장 작업은 몇 초만에 완료됩니다.

첫 번째 배포를 위해 API 사용 설정 및 권한 부여

1. 프롬프트가 저장되면 배포 프로세스가 계속 진행됩니다. 첫 번째 배포라면, 필요한 API를 사용 설정하기 위한 대화상자가 표시됩니다. 필요한 API 사용 설정을 클릭합니다.
2. API가 사용 설정되면 웹 앱 만들기 대화상자가 표시됩니다. 인증 필요(IAP(Identity Aware Proxy) 사용) 또는 공개 액세스 허용을 선택할 수 있습니다.
   • 인증 필요를 선택한 경우 액세스 권한 부여 가이드에 따라 액세스 권한을 부여합니다(본인 포함).
   • 공개 액세스 허용을 선택하면 누구나 이 앱에 액세스할 수 있습니다. 따라서 프롬프트에 민감한 정보나 개인 식별 정보(PII)를 포함하지 마세요. 이 앱이 공개적으로 배포된다는 점을 이해합니다 체크박스를 선택해 이를 승인합니다.
3. 앱 만들기를 클릭하여 배포를 시작합니다.
4. 첫 번째 배포라면, 서비스 계정에 필요한 역할을 부여하라는 다른 대화상자가 다시 표시됩니다. 모두 부여를 클릭하여 계속 진행합니다.

   참고: API를 사용 설정하거나 액세스를 부여할 권한이 없는 경우 프로젝트 관리자에게 필요한 권한을 부여해 달라고 요청하세요. 자세한 내용은 배포 서비스 계정에 필요한 역할을 참조하세요.

배포 시작

Vertex AI Studio는 웹 애플리케이션의 소스 코드를 포함한 ZIP 파일을 만든 후 해당 ZIP 파일을 Cloud Storage 버킷에 업로드합니다. 배포가 시작되면 애플리케이션 이름, 마지막 배포 시간, 배포 상태 등 배포와 관련된 정보가 포함된 웹 앱 관리 대화상자가 표시됩니다.

배포 상태 모니터링

배포는 완료까지 2~3분이 소요되며, 배포 상태는 웹 앱 관리 대화상자의 상태 열에 표시됩니다. 웹 앱 관리 대화상자를 닫은 경우 코드로 빌드 버튼 아래의 메뉴에서 다시 열 수 있습니다.

배포가 완료되면 상태 열이 준비로 변경되고 애플리케이션 이름 옆에 열기 버튼이 표시됩니다.

액세스 제어 및 보안 비밀 키

웹 애플리케이션은 기본적으로 비인증 액세스 허용 액세스 제어가 사용 설정된 상태로 배포됩니다. 연필 아이콘 버튼을 클릭하여 이 설정을 사용 중지할 수 있습니다. 자세한 내용은 공개 액세스 사용 중지 섹션을 참조하세요.

기본적인 보호를 위해 프롬프트를 제출할 때는 웹 애플리케이션에서 URL에 보안 비밀 키를 추가해야 합니다. 보안 비밀 키는 보안 비밀 키 열에서 확인할 수 있습니다. Vertex AI Studio에서 웹 애플리케이션을 열면, 키가 URL에 자동으로 추가됩니다.

웹 애플리케이션을 열고 프롬프트 제출

배포된 애플리케이션에 액세스하려면 웹 앱 관리 대화상자에서 열기를 클릭합니다. 애플리케이션은 URL에 보안 비밀 키가 ?key=SECRET_KEY 형식으로 추가된 상태로 열립니다.

변수에 값을 입력한 뒤 제출을 클릭합니다. 오른쪽에서 결과를 확인할 수 있습니다.

코드로 빌드 버튼 메뉴로 웹 애플리케이션 열기

웹 애플리케이션이 준비되었다면 코드로 빌드 버튼 메뉴에서도 열 수 있습니다.

Cloud Run은 서버리스 서비스이므로 애플리케이션이 일정 시간 사용되지 않으면 컨테이너가 종료됩니다. 따라서 웹 애플리케이션은 로딩에 몇 초가 걸릴 수 있고, 오랫동안 웹 애플리케이션을 방치한 경우 제출이 동작하지 않을 수 있습니다. 페이지를 새로고침하면 이 문제가 해결됩니다.

종 모양 알림 아이콘으로 상태 모니터링

종 모양 아이콘을 클릭하면 알림 메뉴에서 상태를 모니터링할 수도 있습니다. 배포가 성공적으로 완료되면 종 모양 아이콘의 로딩 애니메이션이 멈추고 녹색 원이 표시됩니다.

알림을 클릭하면 Cloud Run 페이지로 리디렉션됩니다. Cloud Run 페이지의 URL에는 보안 비밀 키가 추가되어 있지 않습니다. ?key=SECRET_KEY 형식으로 직접 보안 비밀 키를 URL에 추가해야 합니다.

프롬프트 업데이트 및 다시 배포

Vertex AI Studio에서 프롬프트를 추가로 수정하고 이를 대화형 프롬프트로 전환할 수 있습니다. 그런 다음 코드로 빌드 버튼을 클릭하고 앱 관리를 클릭하여 웹 앱 관리 대화상자를 엽니다. 업데이트된 프롬프트로 웹 애플리케이션을 다시 배포하려면 앱 업데이트를 클릭합니다.

확인 대화상자가 표시됩니다. 여기에는 다시 배포할 경우 Vertex AI Studio 외부(예: Cloud Run 소스 코드 편집기)에서 웹 애플리케이션에 적용한 변경사항이 모두 사라진다는 내용이 표시됩니다. 확인을 클릭하여 계속 진행합니다.

웹 앱 관리 대화상자가 다시 표시됩니다. 이 프로세스는 초기 배포 때와 거의 동일합니다. 진행 상황은 첫 번째 배포와 동일한 방식으로 모니터링할 수 있습니다.

업데이트가 완료되면 웹 애플리케이션을 다시 열 수 있습니다. 프롬프트 변수가 포함된 대화 UI가 표시됩니다. 값을 입력하고, 비어 있지 않은 내용을 입력하면 대화를 계속할 수 있습니다.

멀티모달 콘텐츠 삽입

대화 UI에는 이미지, 동영상, 오디오, 문서 등 다양한 입력을 삽입할 수 있습니다. 지원되는 입력 형식은 프롬프트에 선택한 모델에 따라 달라집니다. 모델별 멀티모달 지원 문서를 참조하세요.

파일을 삽입하려면 대화 입력 상자의 클립 아이콘 버튼을 클릭합니다.

제공한 입력을 사용하여 모델과 상호작용할 수 있습니다.

심화 주제

배포 프로세스에 익숙해지면 다음 작업을 고려할 수 있습니다.

Cloud Run에서 소스 코드 수정

웹 애플리케이션을 맞춤설정하려면 Cloud Run에서 소스 코드를 변경하면 됩니다. 행 끝에 있는 더보기 아이콘 버튼을 클릭하여 웹 앱 관리 대화상자에서 Cloud Run 소스 코드 페이지를 엽니다.

또는 웹 애플리케이션에서 소스 코드 편집기 링크를 클릭하여 보안 페이지로 이동할 수도 있습니다.

Cloud Run 소스 코드 페이지에서 소스 수정을 클릭하면 수정 모드가 시작됩니다. 수정을 완료하면 저장 및 다시 배포를 클릭합니다.

참고: Cloud Run은 버전 관리를 직접 지원하지 않습니다. Vertex AI Studio에서 다시 배포하면 변경사항이 모두 덮어쓰여집니다. 버전을 보관하려면 다시 배포하기 전에 왼쪽 하단의 ZIP 다운로드를 클릭하여 현재 버전을 저장할 수 있습니다.

재배포가 완료되면 Vertex AI Studio에서 애플리케이션을 열어야 합니다. Vertex AI에서 배포됨 배지에 있는 링크를 통해 Vertex AI Studio 페이지로 이동할 수 있습니다.

액세스 권한 부여

사용자 또는 그룹에 앱 액세스 권한을 부여하려면 다음 단계를 따르세요.

1. 웹 앱 관리 대화상자를 엽니다.
2. 액세스 제어 열에서 연필 아이콘을 클릭합니다. 그러면 Cloud Run 보안 페이지가 새 탭에서 열립니다.
3. Cloud Run 보안 페이지에서 IAP(Identity-Aware Proxy) 체크박스를 찾습니다. 선택되어 있는지 확인한 후 정책 수정을 클릭합니다.
4. 액세스 권한을 수정할 수 있는 하위 태스크가 표시됩니다. 주 구성원 필드에 사용자 또는 그룹 이메일을 입력합니다. 조직 계정을 사용하는 경우, 동일한 조직에 속한 사용자만 추가할 수 있습니다.
   
5. 액세스 수준 필드는 비워 둡니다.
6. 저장을 클릭합니다.
7. 하위 태스크가 닫힌 후 Cloud Run 페이지에서 저장을 다시 클릭합니다.
   
   변경사항이 적용되려면 두 번째 저장 클릭 단계가 필요합니다. 정책 수정사항이 적용되기까지 몇 분 정도 지연될 수도 있습니다.

공개 액세스 사용 중지

웹 애플리케이션에 공개적으로 액세스할 필요가 없을 때는 Cloud Run에서 사용 중지하면 됩니다. 웹 앱 관리 대화상자를 열고 액세스 제어 열의 연필 아이콘을 클릭합니다. Cloud Run 보안 페이지가 새 탭에서 열립니다.

웹 애플리케이션에서 보안 설정 링크를 클릭하여 보안 페이지로 이동할 수도 있습니다.

해당 웹 애플리케이션의 Cloud Run 서비스 보안 페이지에서 Cloud IAM을 사용하여 수신 요청 인증을 선택하고 인증 필요를 선택합니다. 저장을 클릭합니다.

이렇게 하면 웹 애플리케이션은 URL로 더 이상 액세스할 수 없게 됩니다. 이후 액세스를 시도하면 오류: 금지됨 페이지가 표시됩니다.

공개 액세스 다시 사용 설정

공개 액세스를 다시 사용 설정하려면 Cloud IAM을 사용하여 수신 요청 인증 체크박스를 선택 해제하고 저장합니다. 인증되지 않은 호출 허용을 선택해도, 프로젝트가 조직에 속해 있으면 이 옵션은 작동하지 않습니다. 자세한 내용은 Cloud Run의 인증을 참조하세요.

개발을 위한 로컬 액세스 설정

공개 미리보기에서는 액세스 제어가 아직 지원되지 않습니다. 따라서 공개 액세스를 사용 중지하면 로컬 프록시를 설정해야만 웹 애플리케이션에 액세스할 수 있습니다. 이 작업은 gcloud 명령어를 통해 수행할 수 있습니다. 먼저 Google Cloud 콘솔 오른쪽 상단의 터미널 아이콘 버튼을 통해 Cloud Shell을 엽니다. Cloud Shell을 승인하라는 메시지가 표시됩니다. 계속하려면 승인을 클릭합니다.

완료되면 웹 앱 관리 대화상자를 열고 행 끝에 있는 더보기 아이콘 버튼을 클릭하여 추가 작업을 확인합니다. Cloud Shell을 통해 로컬 액세스 설정을 클릭합니다.

Cloud Shell에 명령어가 추가됩니다. Enter 키를 눌러 실행한 두 출력이 완료될 때까지 기다립니다. 출력 중 Click on the link to preview로 시작하는 줄에 표시된 링크를 클릭합니다. 그러면 애플리케이션을 확인할 수 있습니다. 이 링크는 gcloud 명령어가 실행 중일 때만 작동합니다.

일반적인 문제

인증 오류: 보안 비밀 키 없음

다음 오류가 표시되면 URL에 보안 비밀 키가 추가되지 않은 것입니다. Vertex AI Studio에서 웹 애플리케이션을 여는 방법을 다시 따라하거나, 앱 관리 대화상자에서 보안 비밀 키를 복사한 후 ?key=SECRET_KEY 형식으로 URL에 추가합니다.

인증 오류: 잘못된 보안 비밀 키

다음 오류는 URL에 추가된 키가 유효하지 않다는 의미입니다. 보안 비밀 키는 각 프롬프트마다 고유합니다. 다른 프롬프트의 보안 비밀 키라면 작동하지 않습니다. 웹 애플리케이션을 올바르게 여는 방법을 다시 따르세요.

400 잘못된 인수: 입력이 비어 있음

이 오류는 프롬프트 변수에는 값이 있지만 채팅 입력이 비어 있을 때 발생하며, 400 오류 메시지가 표시됩니다. 비어 있지 않은 아무 내용이나 입력한 뒤 다시 제출하면 이 문제를 해결할 수 있습니다.

400 잘못된 인수: mimeType이 지원되지 않음

모델에서 지원하지 않는 파일 유형을 선택하면 400 오류가 반환됩니다. 이는 정상적인 동작이며 모델이 지원하는 다른 파일 유형을 사용해야 합니다. 모델별 멀티모달 지원 문서를 참조하세요.

다음 단계

• 문서 또는 Google Cloud Skills Boost의 Vertex AI Studio 소개 과정에서 Vertex AI Studio의 추가 기능을 확인하세요.

• Cloud Run 가격 책정을 확인하세요.

• Cloud Run의 인증을 확인하세요.