이 프로젝트는 Google ADK(Agent Development Kit)를 사용하여 구축된 데이터 관리, 분석, 시각화 그리고 ML작업이 가능한 에이전트 샘플입니다. 해당 에이전트는 자연어를 통해 BigQuery 내 메타데이터, 데이터 생성과 분석을 진행할 수 있을 뿐만 아니라 모델 생성 및 훈련까지 경험할 수 있습니다. 또한 시각화를 통해 시각화된 결과를 볼 수 있습니다.
KR_BQ_AGENT/
├── sub_agents/
│ ├── bqml_agent/
│ │ ├── __init__.py
│ │ ├── agent.py
│ │ └── prompts.py
│ ├── data_analytics_agent/
│ │ ├── __init__.py
│ │ ├── agent.py
│ │ └── prompts.py
│ ├── data_management_agent/
│ │ ├── __init__.py
│ │ ├── agent.py
│ │ └── prompts.py
│ ├── visualization_agent/
│ │ ├── img/
│ │ ├── __init__.py
│ │ ├── agent.py
│ │ ├── prompts.py
│ │ └── tools.py
│ ├── __init__.py
│ └── .env.example
├── __init__.py
├── .env.example
├── agent.py
├── prompts.py
└── pyproject.toml이 에이전트는 다음과 같은 주요 기능을 수행할 수 있습니다.
- 자연어 쿼리: 질문을 이해하여 BigQuery에서 데이터를 조회하고 분석합니다.
- 메타데이터 및 데이터 관리: 스키마와 데이터를 이해하여 적절한 메타데이터 생성뿐만 아니라 데이터 관리가 가능합니다.
- 모델 생성 및 훈련: BigQueryML에서 지원하는 머신러닝 모델을 생성하고 데이터 훈련이 가능합니다.
- 시각화 생성: 분석된 데이터를 기반으로 아래와 같은 차트를 동적으로 생성합니다.
- Google Storage 또는 Local 저장 방식 두가지 옵션이 있으며 tools.py 내 return 설정으로 변경 가능합니다.
- 막대 차트 (Bar Chart)
- 선 차트 (Line Chart)
- 산점도 (Scatter Plot)
- 히스토그램 (Histogram)
이 에이전트를 실행하기 전에 다음 환경이 준비되어 있어야 합니다.
- Google Cloud Project: 결제가 활성화된 GCP 프로젝트.
- gcloud CLI: Google Cloud CLI가 설치 및 인증되어 있어야 합니다.
- 설치링크
gcloud auth logingcloud auth application-default logingcloud auth application-default set-quota-project <YOUR_PROJECT_ID>gcloud config list
- APIs Enabled: 프로젝트에서 다음 API가 활성화되어 있어야 합니다. 구글 클라우드 콘솔에서 다음 API 검색하여 활성화 확인합니다.
- Vertex AI API
- BigQuery API
- Python version: Python 3.12+ 이상이어야 합니다.
- Git: git이 설치되어 있어야 합니다.
- IAM: 연결된 계정이 최소한 BigQuery Editor, Vertex AI User, Storage Object User 권한 이상을 가져야 합니다.
- [Optional]System Fonts: 에이전트가 실행되는 환경에 나눔고딕 폰트가 설치되어 있어야 합니다.
- Ubuntu/Debian:
sudo apt-get update && sudo apt-get install -y fonts-nanum
- Ubuntu/Debian:
-
리포지토리 복제 (Clone Repository)
git clone https://github.com/changsub214/kr-data-agent.git cd kr-data-agent -
가상 환경 생성 및 활성화 (Create and Activate Virtual Environment)
python3 -m venv .venv source .venv/bin/activate -
의존성 설치 (Install Dependencies) kr_bq_agent 폴더로 이동 후
pyproject.toml파일을 사용하여 모든 필수 라이브러리를 설치합니다. 이후 상위 디렉터리로 이동합니다.cd kr_bq_agent pip install . cd ..
-
환경 변수 설정 (Configure Environment Variables) kr_bq_agent 내 루트와 sub_agents/에
.env.example파일을.env로 수정하고 양식에 맞춰 값을 채워넣습니다. MODEL 지정 가능 모델 리스트는 다음 링크를 참조하세요.GOOGLE_GENAI_USE_VERTEXAI=TRUE #GOOGLE_API_KEY="" #If you want to use API, you should set this value and FALSE on upper value and then you can use it. GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" GOOGLE_CLOUD_LOCATION="YOUR_REGION" MODEL = "YOUR MODEL"
단, sub_agents/ 내에 있는 환경 변수 설정 파일은 다음의 변수에 맞춰서 설정해야 합니다.
GOOGLE_GENAI_USE_VERTEXAI=TRUE #GOOGLE_API_KEY="" #If you want to use API, you can use it. GOOGLE_CLOUD_PROJECT="YOUR PROJECT NAME" GOOGLE_CLOUD_BUCKET="YOUR BUCKET" GOOGLE_CLOUD_LOCATION="YOUR REGION" MODEL = "YOUR MODEL"
Tip) 버킷은 다음과 같은 명령어로 생성이 가능합니다. 그리고, 버킷명은 고유해야 합니다.
gcloud storage buckets create gs://BUCKET_NAME --location=YOUR_REGION
아래 명령어를 사용하여 로컬 ADK 웹 환경을 시작합니다. 이때 위치는, kr-data-agent/ 에 위치해야 합니다.
adk web시작되면 http://127.0.0.1:8000 주소로 접속하여 웹 UI에서 에이전트와 상호작용할 수 있습니다. 생성된 차트 이미지는 GoogleCloud Storage Bucket(단, 로컬 저장인 경우kr_bq_agent/sub_agents/visualization_agent/img/ 디렉터리)에 저장됩니다. 만일, CLI 환경에서 진행할 경우 다음과 같이 진행합니다.
adk run kr_bq_agent에이전트에게 다음과 같은 질문을 할 수 있습니다.
Tip ) 본 프롬프트는 맞춰서 데이터가 사전 준비 필요할시 다음과 같은 프롬프트로 더미데이터 생성이 가능합니다.
- school이라는 데이터세트를 만들고 student 테이블을 만들어줘 컬럼으로는 studnet_id, studnet_name, admission_year, major, gender 로 하고 row는 3500개 정도 생성해서 값을 채워줘
은행 관련 고객 정보가 있는 테이블에서 성별별 가입자수를 나타내줘
지난 한 해 동안의 월별 매출 추이를 보여줘
광고비와 매출 사이의 상관관계를 분석하고 산점도로 시각화해줘
인구관련 데이터세트에서 인사이트를 얻기 위한 적절한 질문 3개 생성해줘
코호트 분석해줘
인구 변화 예측을 하고 싶은데 적절한 모델 생성하고 평가해줘
고객 테이블 메타데이터 생성해줘/지워줘/변경해줘
각 컬렴별 메타데이터 생성해줘/지워줘/변경해줘