ADK AI 에이전트 및 Gemini 모델로 진술의 사실 여부 확인

코딩 수준: 고급
소요 시간: 30분
프로젝트 유형: 맞춤 함수

개요

Vertex AI 에이전트와 Gemini 모델로 구동되는 바인드된 Apps Script 프로젝트로 사용되는 Google Sheets용 사실 확인 맞춤 함수

이 샘플에서는 다음과 같은 두 가지 강력한 유형의 AI 리소스를 Google Sheets 스프레드시트에 직접 사용하는 방법을 보여줍니다.

1. Vertex AI Agent Engine에 배포된 ADK 에이전트를 사용하여 정교한 멀티 도구, 다단계 추론 기능을 제공하는 AI 에이전트
2. Vertex AI의 Gemini 모델을 사용하여 고급 이해, 생성, 요약 기능을 제공하는 AI 모델

목표

• 솔루션의 기능을 이해합니다.
• 솔루션이 구현되는 방식을 이해합니다.
• Vertex AI 에이전트를 배포합니다.
• 스크립트를 설정합니다.
• 스크립트를 실행합니다.

이 솔루션 정보

스프레드시트 맞춤 함수는 FACT_CHECK이며 엔드 투 엔드 솔루션으로 작동합니다. 이 모델은 문장을 분석하고 최신 웹 정보를 사용하여 대답을 뒷받침하며 필요한 형식으로 결과를 반환합니다.

• 사용법:
  • =FACT_CHECK("Your statement here")를 사용하여 간결하고 요약된 출력을 생성합니다.
  • 특정 출력 형식의 =FACT_CHECK("Your statement here", "Your output formatting instructions here")
• 추론: LLM 감사자 ADK AI 에이전트(Python 샘플)
• 출력 형식: Gemini 모델

이 솔루션은 UrlFetchApp을 사용하여 Vertex AI REST API를 요청합니다.

아키텍처

다음 다이어그램은 맞춤 함수에서 사용하는 Google Workspace 및 Google Cloud 리소스의 아키텍처를 보여줍니다.

기본 요건

이 샘플을 사용하려면 다음 기본 요건이 필요합니다.

• Google 계정 (Google Workspace 계정의 경우 관리자 승인이 필요할 수 있음)

• 인터넷에 액세스할 수 있는 웹브라우저

• LLM 감사자 ADK 에이전트의 기본 요건

  • Python 3.11 이상: 설치하려면 공식 Python 웹사이트의 안내를 따르세요.
  • Python Poetry: 설치하려면 공식 Poetry 웹사이트의 안내를 따르세요.
  • Google Cloud CLI: 설치하려면 공식 Google Cloud 웹사이트의 안내를 따르세요.

환경 준비

이 섹션에서는 Google Cloud 프로젝트를 만들고 구성하는 방법을 보여줍니다.

Google Cloud 프로젝트 만들기

Google Cloud 콘솔

1. Google Cloud 콘솔에서 메뉴 > IAM 및 관리자 > 프로젝트 만들기로 이동합니다.

   프로젝트 만들기로 이동

2. 프로젝트 이름 필드에 프로젝트의 설명이 포함된 이름을 입력합니다.

   선택사항: 프로젝트 ID를 수정하려면 수정을 클릭합니다. 프로젝트가 생성된 후에는 프로젝트 ID를 변경할 수 없으므로 프로젝트의 전체 기간 동안 필요에 맞는 ID를 선택하세요.

3. 위치 필드에서 찾아보기를 클릭하여 프로젝트의 잠재적 위치를 표시합니다. 그런 다음 선택을 클릭합니다.
   주의: Google Workspace 조직을 찾을 수 없나요?
   Google Workspace 계정에 로그인되어 있지 않습니다. Google Workspace 개발자 문서에 설명된 일부 기능은 조직과 연결된 프로젝트에서만 사용할 수 있습니다.
4. 만들기를 클릭합니다. Google Cloud 콘솔이 대시보드 페이지로 이동하고 몇 분 이내에 프로젝트가 생성됩니다.

gcloud CLI

다음 개발 환경 중 하나에서 Google Cloud CLI (gcloud)에 액세스합니다.

• Cloud Shell: gcloud CLI가 이미 설정된 온라인 터미널을 사용하려면 Cloud Shell을 활성화하세요.
  Cloud Shell 활성화
• 로컬 셸: 로컬 개발 환경을 사용하려면 gcloud CLI를 설치하고 초기화합니다.
  Cloud 프로젝트를 만들려면 gcloud projects create 명령어를 사용합니다.

  gcloud projects create PROJECT_ID

  만들려는 프로젝트의 ID를 설정하여 PROJECT_ID를 바꿉니다.

Cloud 프로젝트에 결제 사용 설정

결제 계정을 연결할 수 없는 경우 이 변경을 수행하는 데 필요한 권한이 없는 것입니다. 자세한 내용은 결제를 사용 설정하는 데 필요한 권한을 참고하세요.

Google Cloud 콘솔

1. Google Cloud 콘솔에서 결제로 이동합니다. 메뉴 > 결제 > 내 프로젝트를 클릭합니다.

   내 프로젝트의 결제로 이동

2. 조직 선택에서 Google Cloud 프로젝트와 연결된 조직을 선택합니다.
3. 프로젝트 행에서 작업 메뉴()를 열고 결제 변경을 클릭한 후 Cloud Billing 계정을 선택합니다.
4. 계정 설정을 클릭합니다.

gcloud CLI

1. 사용 가능한 결제 계정을 나열하려면 다음을 실행합니다.

   gcloud billing accounts list

2. 결제 계정을 Google Cloud 프로젝트에 연결합니다.

   gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

   다음을 바꿉니다.

   • PROJECT_ID는 결제를 사용 설정하려는 Cloud 프로젝트의 프로젝트 ID입니다.
   • BILLING_ACCOUNT_ID는 Google Cloud 프로젝트와 연결할 결제 계정 ID입니다.

Vertex AI API 사용 설정

Google Cloud 콘솔

1. Google Cloud 콘솔에서 Vertex AI API를 사용 설정합니다.

   API 사용 설정

2. 올바른 Cloud 프로젝트에서 Vertex AI API를 사용 설정하고 있는지 확인한 후 다음을 클릭합니다.

3. 올바른 API를 사용 설정했는지 확인한 후 사용 설정을 클릭합니다.

gcloud CLI

1. 필요한 경우 현재 클라우드 프로젝트를 gcloud config set project 명령어로 만든 프로젝트로 설정합니다.

   gcloud config set project PROJECT_ID

   PROJECT_ID를 생성한 Cloud 프로젝트의 프로젝트 ID로 바꿉니다.

2. gcloud services enable 명령어를 사용하여 Vertex AI API를 사용 설정합니다.

   gcloud services enable aiplatform.googleapis.com

Google Cloud 콘솔에서 서비스 계정 만들기

다음 단계에 따라 역할이 Vertex AI User인 새 서비스 계정을 만듭니다.

Google Cloud 콘솔

1. Google Cloud 콘솔에서 메뉴 > IAM 및 관리자 > 서비스 계정으로 이동합니다.

   서비스 계정으로 이동

2. 서비스 계정 만들기를 클릭합니다.
3. 서비스 계정 세부정보를 입력한 다음 만들고 계속하기를 클릭합니다.
   참고: 기본적으로 Google은 고유한 서비스 계정 ID를 만듭니다. ID를 변경하려면 서비스 계정 ID 필드에서 ID를 수정하세요.
4. 선택사항: 서비스 계정에 역할을 할당하여 Google Cloud 프로젝트의 리소스에 대한 액세스 권한을 부여합니다. 자세한 내용은 리소스에 대한 액세스 권한 부여, 변경, 취소를 참고하세요.
5. 계속을 클릭합니다.
6. 선택사항: 이 서비스 계정으로 작업을 관리하고 수행할 수 있는 사용자 또는 그룹을 입력합니다. 자세한 내용은 서비스 계정 명의 도용 관리를 참고하세요.
7. 완료를 클릭합니다. 서비스 계정의 이메일 주소를 기록해 둡니다.

gcloud CLI

1. 서비스 계정을 만듭니다.

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. 선택사항: 서비스 계정에 역할을 할당하여 Google Cloud 프로젝트의 리소스에 대한 액세스 권한을 부여합니다. 자세한 내용은 리소스에 대한 액세스 권한 부여, 변경, 취소를 참고하세요.

서비스 계정이 서비스 계정 페이지에 표시됩니다. 다음으로 서비스 계정의 비공개 키를 만듭니다.

비공개 키 만들기

경고: 이 예에서는 편의상 내보낸 서비스 계정 키를 사용합니다. 비공개 키는 소스 제어와 같은 보안되지 않은 위치에 저장하면 안 되므로 프로덕션에서는 비공개 키를 내보내지 않는 것이 좋습니다.

보안 서비스 계정 구현 및 권장사항에 대해 자세히 알아보려면 서비스 계정 사용 시기 선택을 참고하세요.

서비스 계정의 비공개 키를 만들고 다운로드하려면 다음 단계를 따르세요.

1. Google Cloud 콘솔에서 메뉴 > IAM 및 관리자 > 서비스 계정으로 이동합니다.

   서비스 계정으로 이동

2. 서비스 계정을 선택합니다.
3. 키 > 키 추가 > 새 키 만들기를 클릭합니다.
4. JSON을 선택한 다음 만들기를 클릭합니다.

   새 공개 키/비공개 키 쌍이 생성되어 새 파일로 기기에 다운로드됩니다. 다운로드한 JSON 파일을 작업 디렉터리에 credentials.json로 저장합니다. 이 파일은 이 키의 유일한 사본입니다. 키를 안전하게 저장하는 방법을 자세히 알아보려면 서비스 계정 키 관리를 참고하세요.

5. 닫기를 클릭합니다.

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

LLM 감사자 ADK AI 에이전트 배포

1. 아직 수행하지 않았다면 Google Cloud 계정으로 인증하고 Google Cloud 프로젝트를 사용하도록 Google Cloud CLI를 구성합니다.

   gcloud auth application-default login
   gcloud config set project PROJECT_ID
   gcloud auth application-default set-quota-project PROJECT_ID

   PROJECT_ID를 만든 Cloud 프로젝트의 ID로 바꿉니다.

2. 이 GitHub 저장소를 다운로드합니다.

   다운로드

3. 선호하는 로컬 개발 환경에서 다운로드한 보관 파일의 압축을 풀고 adk-samples/python/agents/llm-auditor 디렉터리를 엽니다.

   unzip adk-samples-main.zip
   cd adk-samples-main/python/agents/llm-auditor

4. ADK 에이전트 전용 새 Cloud Storage 버킷을 만듭니다.

   gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION

   다음을 바꿉니다.

   1. CLOUD_STORAGE_BUCKET_NAME을 사용할 고유한 버킷 이름으로 바꿉니다.
   2. PROJECT_ID를 만든 Cloud 프로젝트의 ID로 바꿉니다.
   3. PROJECT_LOCATION를 개발자가 만든 Cloud 프로젝트의 위치로 바꿉니다.

5. 다음 환경 변수를 설정합니다.

   export GOOGLE_GENAI_USE_VERTEXAI=true
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME

   다음을 바꿉니다.

   1. CLOUD_STORAGE_BUCKET_NAME을 만든 버킷의 이름으로 바꿉니다.
   2. PROJECT_ID를 만든 Cloud 프로젝트의 ID로 바꿉니다.
   3. PROJECT_LOCATION를 개발자가 만든 Cloud 프로젝트의 위치로 바꿉니다.

6. 가상 환경에서 ADK 에이전트를 설치하고 배포합니다.

   python3 -m venv myenv
   source myenv/bin/activate
   poetry install --with deployment
   python3 deployment/deploy.py --create

7. 에이전트 ID를 가져옵니다. 나중에 맞춤 함수를 구성할 때 필요합니다.

   python3 deployment/deploy.py --list

샘플 코드 검토

원하는 경우 새 스프레드시트를 만들기 전에 GitHub에 호스팅된 샘플 코드를 검토하고 숙지하세요.

GitHub에서 보기

새 스프레드시트에서 만들기 및 구성

1. 다음 버튼을 클릭하고 컨테이너에 바인드된 Apps Script 프로젝트를 포함한 샘플 Google Sheets 스프레드시트의 전체 사본을 만듭니다.

   Google Sheets 스프레드시트 복사

2. 새로 만든 스프레드시트에서 확장 프로그램 > Apps Script로 이동합니다.

3. Apps Script 프로젝트에서 프로젝트 설정으로 이동하여 스크립트 속성 수정을 클릭한 다음 스크립트 속성 추가를 클릭하여 다음 스크립트 속성을 추가합니다.

   1. LOCATION을 이전 단계에서 만든 Google Cloud 프로젝트의 위치(예: us-central1)로 바꿉니다.
   2. 사용하려는 Gemini 모델(예: gemini-2.5-flash-lite)을 사용하여 GEMINI_MODEL_ID를 호출합니다.
   3. REASONING_ENGINE_ID을 이전 단계에서 배포된 LLM 감사자 ADK 에이전트의 ID(예: 1234567890)로 바꿉니다.
   4. SERVICE_ACCOUNT_KEY을 이전 단계에서 다운로드한 서비스 계정의 JSON 키(예: { ... })로 바꿉니다.

4. 스크립트 속성 저장을 클릭합니다.

맞춤 함수 테스트

1. 새로 만든 스프레드시트로 이동합니다.
2. A열의 문장을 변경합니다.
3. B열의 수식이 실행된 후 사실 확인 결과가 표시됩니다.

삭제

이 튜토리얼에서 사용한 리소스 비용이 Google Cloud 계정에 청구되지 않도록 하려면 Cloud 프로젝트를 삭제하는 것이 좋습니다.

주의: 프로젝트를 삭제하면 다음과 같은 효과가 발생합니다.

• 프로젝트의 모든 항목이 삭제됩니다. 이 튜토리얼의 기존 프로젝트를 사용한 경우 프로젝트를 삭제하면 프로젝트에서 수행한 다른 작업도 삭제됩니다.
• 커스텀 프로젝트 ID가 손실됩니다. 이 프로젝트를 만들 때 앞으로 사용할 커스텀 프로젝트 ID를 만들었을 수 있습니다. appspot.com의 URL과 같이 프로젝트 ID를 사용하는 URL을 보존하려면 전체 프로젝트 대신 프로젝트 내에서 선택한 리소스만 삭제합니다.

여러 튜토리얼과 빠른 시작을 살펴보려는 경우 프로젝트를 재사용하면 프로젝트 할당량 한도 초과를 방지할 수 있습니다.

1. Google Cloud 콘솔에서 리소스 관리 페이지로 이동합니다. 메뉴 > IAM 및 관리자 > 리소스 관리를 클릭합니다.

   Resource Manager로 이동

2. 프로젝트 목록에서 삭제할 프로젝트를 선택하고 삭제 를 클릭합니다.
3. 대화상자에서 프로젝트 ID를 입력한 다음 종료를 클릭하여 프로젝트를 삭제합니다.

다음 단계

• Google Sheets의 맞춤 함수
• Google Sheets 확장