# GoogleCloudPlatform/generative-ai: Google 공식 AI 샘플 코드 완벽 가이드

# GoogleCloudPlatform/generative-ai: Google 공식 AI 샘플 코드 완벽 가이드

> Google Cloud가 공식으로 관리하는 생성형 AI 샘플 코드 저장소입니다. Vertex AI 플랫폼 위에서 Gemini를 중심으로 텍스트, 이미지, 음성, AI 에이전트 등 생성형 AI 전 영역의 실행 가능한 Jupyter Notebook과 프로덕션 샘플 앱을 제공합니다.

Google Cloud에서 생성형 AI를 시작하려는 개발자라면 공식 문서부터 찾게 됩니다. 하지만 개념만으로는 실제 구현까지의 간극이 큽니다. 바로 이 간극을 메워주는 것이 [GoogleCloudPlatform/generative-ai](https://github.com/GoogleCloudPlatform/generative-ai) 리포지토리입니다. 15,800개 이상의 GitHub 스타와 4,000개 이상의 포크를 기록하는 이 리포지토리는 Vertex AI 기반 생성형 AI 개발의 실질적인 출발점입니다.

## TL;DR

- **규모**: 15,800+ 스타, 2,024+ 커밋, 82.4% Jupyter Notebook으로 구성
- **핵심**: Gemini 모델 입문부터 AI 에이전트, RAG, 멀티모달 처리까지 완전 커버
- **특징**: 새 모델 출시와 동시에 업데이트되는 "살아있는" 공식 자료
- **시작**: Google Colab에서 로컬 환경 설정 없이 바로 실행 가능
- **라이선스**: Apache 2.0 — 상용 프로젝트에서 자유롭게 사용 및 수정 가능

---

## 리포지토리 개요: 규모와 구성

이 리포지토리의 영향력을 숫자로 확인해보겠습니다.

| 항목 | 수치 | 의미 |
|------|------|------|
| GitHub Stars | 15,800+ | 개발자 커뮤니티의 광범위한 신뢰 |
| Forks | 4,000+ | 많은 팀이 이를 기반으로 프로젝트 시작 |
| Commits | 2,024+ | Google Cloud 팀의 지속적 관리 |
| Watchers | 271 | 핵심 개발자 추적 |
| 주요 언어 | Jupyter Notebook (82.4%) | **실행 가능한 코드 중심** |
| 보조 언어 | Python 7.6%, TypeScript 2.8% | 웹 앱/유틸리티 |
| 라이선스 | Apache 2.0 | 상용 사용 가능 |

**가장 주목할 점**: 전체 코드의 82.4%가 Jupyter Notebook입니다. 이는 단순한 "코드 읽기 자료"가 아니라 Google Colab이나 Vertex AI Workbench에서 **바로 실행하며 학습할 수 있는 인터랙티브 환경**을 의미합니다.

---

## 디렉토리 구조: 생성형 AI 전 영역 매핑

이 리포지토리의 강점은 생성형 AI의 거의 모든 영역을 **하나의 저장소에서 체계적으로 다룬다**는 점입니다. 주요 디렉토리를 기능별로 분류했습니다.

### 핵심 모델 & 입문 (Gemini 중심)

| 폴더 | 내용 | 대상 개발자 |
|------|------|-----------|
| `gemini/` | Gemini 모델 입문, Function Calling, 프롬프트 엔지니어링, 샘플 앱 | Gemini를 처음 시작하는 모든 개발자 |
| `open-models/` | Gemma 등 오픈소스 모델 활용 | 오픈소스 모델을 선호하거나 프라이빗 배포가 필요한 개발자 |
| `partner-models/` | 서드파티 모델 통합 (Anthropic Claude 등) | 멀티모델 하이브리드 전략 구축자 |
| `sdk/` | Vertex AI Python SDK 사용법 | SDK 기반으로 프로덕션 애플리케이션 개발자 |

### 고급 기능 & 엔터프라이즈 AI

| 폴더 | 내용 | 사용 시나리오 |
|------|------|------------|
| `agents/` | 자율 AI 에이전트 구축 샘플 | 직원 생산성 향상, 고객 지원 자동화, 워크플로우 자동화 |
| `rag-grounding/` | RAG(검색 증강 생성) & Grounding | 최신 정보 반영, 환각(hallucination) 감소, 엔터프라이즈 데이터 활용 |
| `search/` | Vertex AI Search 엔진 구축 | 웹사이트, 문서, 전자상거래 검색 기능 |
| `embeddings/` | 텍스트/멀티모달 임베딩 | 시맨틱 검색, 추천 시스템, 유사도 계산 |

### 멀티모달 & 미디어 처리

| 폴더 | 내용 | 활용 분야 |
|------|------|----------|
| `vision/` | Imagen — 이미지 생성, 편집, 캡셔닝, VQA | 마케팅 자산 생성, 이미지 분석 |
| `audio/` | Chirp (USM) — 음성 인식/합성 | 음성 기반 AI, 자막 생성, 더빙 |
| `translation/` | 다국어 번역 | 글로벌 서비스 지원 |

### 도구 & 프로덕션 배포

| 폴더 | 용도 |
|------|------|
| `genkit/` | Firebase Genkit 샘플 (Node.js 기반 AI 앱) |
| `setup-env/` | 환경 설정 가이드 (Colab, Workbench, 로컬) |
| `workshops/` | 기술 워크샵 자료 (실제 Google Cloud 팀 세션) |
| `tools/llmevalkit` | LLM 성능 평가 도구 |

---

## Gemini 폴더: 최신 모델과의 시간차 제거

`gemini/` 폴더는 이 리포지토리에서 **가장 활발하게 유지되는 영역**입니다. 이는 Google의 우선순위를 반영합니다.

### 업데이트 패턴: 모델 릴리스 동시성

Gemini 3.1 Pro가 출시되었을 때, 이 리포지토리는 동시에 `intro_gemini_3_1_pro.ipynb` 노트북을 추가했습니다. 이는 다음을 의미합니다:

- **공식 문서 출시** → **실행 가능한 노트북 제공** (시간차 최소화)
- Google Cloud 팀이 직접 관리하므로, 모델 최신 기능을 즉시 반영

### Gemini 폴더가 다루는 주제

```
gemini/
├── intro_gemini_3_1_pro.ipynb          # 최신 모델 입문
├── function_calling_examples.ipynb     # API 연동 패턴
├── prompting_best_practices.ipynb      # 프롬프트 엔지니어링
├── use_cases/
│   ├── document_summarization.ipynb    # 문서 요약
│   ├── code_generation.ipynb           # 코드 생성
│   └── data_analysis.ipynb             # 데이터 분석
└── sample_apps/
    ├── chatbot.py                      # 프로덕션급 챗봇
    └── web_app/                        # Flask 기반 웹 앱
```

**공식 문서 vs 이 리포지토리의 차이**:
- 공식 문서: API 레퍼런스, 개념 설명 중심
- 이 리포지토리: "실제로 어떻게 구현하는가" 중심

---

## AI 에이전트 & RAG: 엔터프라이즈 AI 구축

`agents/` 폴더와 `rag-grounding/` 폴더는 엔터프라이즈 AI 솔루션을 구축하려는 팀에게 **특히 중요**합니다.

### 에이전트 생태계: 연결된 리소스

생성형 AI 에이전트는 단순한 프롬프트 체인이 아니라, 다중 도구(tool)와 의사결정 로직을 갖춘 자율형 시스템입니다. Google은 에이전트 개발을 위한 **연결된 생태계**를 구축했습니다:

| 리소스 | 특징 |
|--------|------|
| **Agent Development Kit (ADK) Samples** | 에이전트 개발의 표준 패턴 |
| **Agent Starter Pack** | 프로덕션급 템플릿 (바로 배포 가능한 수준) |
| **MCP Servers for GenMedia** | 에이전트가 미디어(이미지, 음성)를 다루기 위한 도구 |
| **generative-ai 리포지토리 `agents/` 폴더** | 실습 샘플 코드 |

### RAG와 Grounding: 신뢰할 수 있는 AI

LLM의 핵심 문제 중 하나는 **환각(Hallucination)** — 근거 없는 답변을 마치 사실인 듯 생성하는 것입니다.

**RAG (Retrieval-Augmented Generation)**는 이를 해결합니다:
1. 사용자 질문 → 임베딩 변환
2. 벡터 데이터베이스에서 관련 문서 검색
3. 검색 결과 + 질문을 LLM에 제공
4. LLM이 검색 결과 기반으로만 답변

`rag-grounding/` 폴더에서는 Vertex AI의 Grounding 기능을 활용하여 실시간 정보(Google Search 결과)를 바탕으로 신뢰할 수 있는 답변을 생성하는 방법을 배울 수 있습니다.

**실습 예시**:
```python
# Grounding을 통해 실시간 정보 기반 답변
response = model.generate_content(
    "2026년 주식 시장 전망은?",
    tools=[google_search_tool],  # 실시간 검색 결과 반영
)
```

---

## 관련 리포지토리: Google 생성형 AI 생태계

GoogleCloudPlatform/generative-ai는 독립된 저장소가 아니라, 더 넓은 Google 생성형 AI 생태계의 **중심 허브**입니다.

| 리포지토리 | 용도 | 특징 |
|-----------|------|------|
| **Gemini Cookbook** | Gemini API 레시피 모음 | API 중심, 빠른 프로토타이핑 |
| **Vertex AI Creative Studio** | 생성형 미디어 스튜디오 | 이미지/비디오 생성 UI |
| **GenAI for Marketing** | 마케팅 워크플로우 | 캠페인 최적화, 콘텐츠 생성 |
| **GenAI for Developers** | 개발자 생산성 | 코드 생성, 리뷰, 리팩토링 |
| **Agent Starter Pack** | 프로덕션급 에이전트 | 즉시 배포 가능한 템플릿 |

각 리포지토리는 특정 목적에 최적화되어 있으면서도, generative-ai 메인 리포지토리의 기반 위에서 동작합니다.

---

## 시작하는 방법: 환경 설정부터 첫 실행까지

### Step 1: Google Cloud 프로젝트 준비 (5분)

```bash
# 1. Google Cloud Console 접속
# https://console.cloud.google.com/

# 2. 새 프로젝트 생성
# "my-genai-project" → 생성

# 3. Vertex AI API 활성화
# 검색창에 "Vertex AI" → API 활성화

# 4. 인증 설정
gcloud auth application-default login
gcloud config set project my-genai-project
```

### Step 2: 환경 선택 (무료/유료 비교)

| 환경 | 비용 | 특징 | 추천 |
|------|------|------|------|
| **Google Colab** | 무료 (GPU 제한) | 설정 불필요, 브라우저 기반 | 🌟 초보자 |
| **Vertex AI Workbench** | $0.27/시간 (t2.medium 기준) | 완전한 Jupyter 환경, 구글 클라우드 통합 | 프로덕션 코드 |
| **로컬 머신** | 무료 | 최고 자유도, GPU 설정 필요 | 고급 개발자 |

### Step 3: 첫 노트북 실행

```bash
# Google Colab이라면:
1. https://github.com/GoogleCloudPlatform/generative-ai 접속
2. gemini/intro_gemini_3_1_pro.ipynb 찾기
3. "Open in Colab" 버튼 클릭
4. 첫 셀 실행 (Google 계정 인증)

# Workbench라면:
git clone https://github.com/GoogleCloudPlatform/generative-ai.git
cd generative-ai
jupyter notebook
```

---

## 누가 활용하면 좋을까?

### 개발자별 활용 시나리오

**1. Google Cloud 생성형 AI를 시작하는 개발자**
- 공식 문서의 개념을 실제 코드로 확인하고 싶을 때
- Gemini API의 각 기능을 직접 실행해보고 싶을 때
- 예: "Function Calling은 정말 외부 API와 연동되나?" → 노트북에서 바로 확인

**2. Vertex AI + Gemini 기반 엔터프라이즈 AI 솔루션 구축자**
- 에이전트 아키텍처의 구현 패턴을 참고하고 싶을 때
- RAG 시스템의 실제 구축 방법을 배우고 싶을 때
- 검색/추천 시스템을 Vertex AI Search로 구현할 때

**3. AI 최신 기능을 직접 실습하려는 학습자**
- 이미지 생성(Imagen)을 직접 돌려보고 싶을 때
- 음성 처리(Chirp)를 테스트하고 싶을 때
- 멀티모달 임베딩으로 추천 시스템을 만들어보고 싶을 때

---

## FAQ

### Google Colab에서 바로 실행할 수 있나요?

네, 대부분의 노트북은 Google Colab에서 바로 실행 가능합니다. 필요한 것:
- Google Cloud 프로젝트 (Google 계정으로 자동 연결)
- Vertex AI API 활성화 (첫 실행 시 자동 안내)

Colab의 장점: 로컬 설정 필요 없음, 무료 GPU 시간 제공

### 이 리포지토리와 Gemini Cookbook의 차이는 무엇인가요?

| 항목 | Gemini Cookbook | generative-ai 리포지토리 |
|------|-----------------|------------------------|
| **범위** | Gemini API 전용 | Vertex AI 전체 플랫폼 |
| **깊이** | 빠른 레시피 | 심화 기능 (에이전트, RAG) |
| **환경** | API 중심 | Vertex AI 통합 |
| **대상** | Gemini 빠르 체험 | 엔터프라이즈 AI 구축 |

**선택 가이드**:
- "Gemini API 빠르게 시작": Gemini Cookbook
- "엔터프라이즈급 AI 솔루션": generative-ai 리포지토리

### 상용 프로젝트에 코드를 사용해도 되나요?

네, Apache 2.0 라이선스로 제공되므로:
- ✅ 상용 프로젝트 적용 가능
- ✅ 자유롭게 수정 및 재배포 가능
- ⚠️ 라이선스 텍스트 포함 필수

### Gemini 최신 모델이 나오면 노트북도 업데이트되나요?

네, Google Cloud 팀이 직접 관리합니다.

역사적 증거:
- Gemini 3 Pro 출시 → `intro_gemini_3_pro.ipynb` 추가 (2024년)
- Gemini 3.1 Pro 출시 → `intro_gemini_3_1_pro.ipynb` 추가 (2025년)
- Gemini 3.5 Pro (예상) → 동시 업데이트 예상

### 노트북을 수정해서 내 프로젝트에 사용할 수 있나요?

네, Apache 2.0 라이선스이므로 가능합니다:

```bash
# Fork 후 수정
git clone https://github.com/{your-username}/generative-ai.git
cd generative-ai
# 노트북 수정 후 자신의 프로젝트에 복사
```

---

## 실전 활용: 3가지 시나리오

### 시나리오 1: 챗봇 빌더 (초보자)

목표: Gemini 기반 고객 지원 챗봇 만들기

```
학습 경로:
gemini/intro_gemini_3_1_pro.ipynb
  ↓
gemini/use_cases/chatbot.ipynb
  ↓
agents/simple_agent.ipynb
  ↓
sample_apps/chatbot.py (참고)
```

### 시나리오 2: RAG 시스템 (중급 개발자)

목표: 기업 문서 기반 Q&A 시스템 구축

```
학습 경로:
gemini/function_calling_examples.ipynb
  ↓
embeddings/text_embeddings.ipynb
  ↓
rag-grounding/basic_rag.ipynb
  ↓
rag-grounding/advanced_rag_with_grounding.ipynb
```

### 시나리오 3: 멀티모달 AI 앱 (고급 개발자)

목표: 이미지 생성 + 음성 합성 기반 미디어 앱

```
학습 경로:
vision/image_generation.ipynb
  ↓
audio/speech_synthesis.ipynb
  ↓
genkit/ (Node.js 프로덕션 앱)
```

---

## 마무리

GoogleCloudPlatform/generative-ai는 Google Cloud 생성형 AI의 **공식 실습 교재**입니다. 15,800개 이상의 스타가 의미하는 것은 단순한 인기를 넘어, **전 세계 개발자들이 이미 이를 신뢰하고 활용**하고 있다는 뜻입니다.

### 핵심 정리

✅ **포괄성**: Gemini, 에이전트, RAG, 멀티모달까지 생성형 AI 전 영역 커버
✅ **신뢰성**: Google Cloud 팀이 직접 관리, 최신 모델 동시 업데이트
✅ **실행성**: Jupyter Notebook 82.4% — 브라우저에서 바로 실행 가능
✅ **자유도**: Apache 2.0 라이선스 — 상용 프로젝트에 사용 가능
✅ **학습곡선**: 입문부터 엔터프라이즈급까지 점진적 난이도

### 다음 단계

생성형 AI 실습 자료를 찾고 있다면, 이 리포지토리를 지금 바로 북마크하세요:
- [GoogleCloudPlatform/generative-ai](https://github.com/GoogleCloudPlatform/generative-ai)

공식 문서로 개념을 이해하고, 이 리포지토리의 노트북으로 직접 실행해보는 것이 **가장 효과적인 학습 경로**입니다.

---

## 참고 자료

- [GoogleCloudPlatform/generative-ai GitHub Repository](https://github.com/GoogleCloudPlatform/generative-ai) - 메인 리포지토리
- [Google Cloud Vertex AI 공식 문서](https://cloud.google.com/vertex-ai/docs/generative-ai/learn/overview) - 개념 학습
- [Gemini API Documentation](https://ai.google.dev/docs) - API 레퍼런스
- [Agent Development Kit (ADK)](https://cloud.google.com/agents/docs/agent-development-kit) - 에이전트 개발 표준
- [Vertex AI Search Documentation](https://cloud.google.com/vertex-ai/docs/generative-ai/search/overview) - 검색 엔진 구축