Gemini Embedding 2 API 사용법

Google의 Gemini Embedding 2 API를 사용하면 텍스트, 이미지, 비디오, 오디오 및 PDF에 대한 임베딩을 생성할 수 있습니다. 이 가이드에서는 오늘 바로 실행할 수 있는 실제 코드 예제를 통해 API 사용 방법을 설명합니다.

참고: 이 가이드는 공개 미리 보기 버전(gemini-embedding-2-preview)을 다룹니다. API는 정식 출시 전에 변경될 수 있습니다.

Gemini Embedding 2가 무엇인지 먼저 이해하고 싶으신가요? 저희 개요를 읽어보세요: Gemini Embedding 2란 무엇인가요?

선행 조건

필요한 것은 다음과 같습니다:

Google AI API 키
Python 3.7 이상
Google Generative AI SDK

설치

SDK를 설치하세요:

pip install google-generativeai

기본 설정

API 키를 설정하세요:

import google.generativeai as genai

# API 키 설정
genai.configure(api_key='YOUR_API_KEY')

프로덕션 환경에서는 환경 변수를 사용하세요:

import os
import google.generativeai as genai

api_key = os.getenv('GEMINI_API_KEY')
genai.configure(api_key=api_key)

Apidog로 테스트하기

코드를 작성하기 전에 Apidog에서 Gemini Embedding API를 직접 테스트할 수 있습니다:

Apidog에서 Gemini Embedding API를 테스트하는 방법을 보여주는 스크린샷

Apidog에서 새 요청 생성
메서드를 POST로 설정
URL: https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2-preview:embedContent
헤더 추가: x-goog-api-key: YOUR_API_KEY
본문 (JSON):

{
  "content": {
    "parts": [{
      "text": "API 테스팅이란 무엇인가요?"
    }]
  }
}

이를 통해 코드를 작성하기 전에 API 키가 작동하는지 확인하고 응답 구조를 볼 수 있습니다. 이를 테스트 케이스로 저장하고 CI/CD 파이프라인에서 임베딩 응답을 검증할 수 있습니다.

텍스트 임베딩 생성

가장 간단한 사용 사례 - 텍스트 임베딩:

import google.generativeai as genai

genai.configure(api_key='YOUR_API_KEY')

# 임베딩 생성
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='인생의 의미는 무엇인가요?'
)

# 임베딩 벡터 가져오기
embedding = result['embedding']
print(f"임베딩 차원: {len(embedding)}")
print(f"상위 5개 값: {embedding[:5]}")

출력:

Embedding dimensions: 3072
First 5 values: [0.0234, -0.0156, 0.0891, -0.0423, 0.0567]

참고: 응답 구조는 플로트 목록을 반환하는 result['embedding']입니다. 각 플로트는 임베딩 벡터의 한 차원을 나타냅니다.

작업 지침 사용

작업 지침은 특정 사용 사례에 대한 임베딩을 최적화합니다:

# 검색 쿼리용
query_result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='최고의 API 테스팅 도구',
    task_type='RETRIEVAL_QUERY'
)

# 색인화할 문서용
doc_result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Apidog는 API 테스팅 플랫폼입니다...',
    task_type='RETRIEVAL_DOCUMENT'
)

사용 가능한 작업 유형:

RETRIEVAL_QUERY - 검색 쿼리에 사용
RETRIEVAL_DOCUMENT - 색인화할 문서에 사용
SEMANTIC_SIMILARITY - 콘텐츠 유사성 비교에 사용
CLASSIFICATION - 분류 작업에 사용
CLUSTERING - 유사한 콘텐츠 그룹화에 사용

출력 차원 제어

더 작은 차원을 사용하여 저장 비용 절감:

# 프로덕션 최적화: 768 차원
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='여기에 텍스트를 입력하세요',
    output_dimensionality=768
)

# 균형: 1536 차원
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='여기에 텍스트를 입력하세요',
    output_dimensionality=1536
)

# 최대 품질: 3072 차원 (기본값)
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='여기에 텍스트를 입력하세요',
    output_dimensionality=3072
)

대부분의 애플리케이션에서 768차원은 저장 공간을 75% 절약하면서 거의 최고 품질을 제공합니다.

이미지 임베딩

시각적 검색을 위해 이미지 임베딩:

import PIL.Image

# 이미지 로드
image = PIL.Image.open('product-photo.jpg')

# 임베딩 생성
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=image
)

embedding = result['embedding']

요청당 최대 6개의 이미지를 임베딩할 수 있습니다:

images = [
    PIL.Image.open('image1.jpg'),
    PIL.Image.open('image2.jpg'),
    PIL.Image.open('image3.jpg')
]

result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=images
)

비디오 임베딩

비디오 검색을 위해 비디오 콘텐츠 임베딩:

# 먼저 비디오 파일 업로드
video_file = genai.upload_file(path='demo-video.mp4')

# 처리 완료 대기
import time
while video_file.state.name == 'PROCESSING':
    time.sleep(2)
    video_file = genai.get_file(video_file.name)

# 임베딩 생성
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=video_file
)

embedding = result['embedding']

비디오 제한:

요청당 최대 128초
형식: MP4, MOV
코덱: H264, H265, AV1, VP9

오디오 임베딩

전사 없이 오디오 임베딩:

# 오디오 파일 업로드
audio_file = genai.upload_file(path='podcast-episode.mp3')

# 처리 완료 대기
while audio_file.state.name == 'PROCESSING':
    time.sleep(2)
    audio_file = genai.get_file(audio_file.name)

# 임베딩 생성
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=audio_file
)

embedding = result['embedding']

오디오 제한:

요청당 최대 80초
형식: MP3, WAV

PDF 문서 임베딩

문서 검색을 위해 PDF 페이지 임베딩:

# PDF 업로드
pdf_file = genai.upload_file(path='user-manual.pdf')

# 처리 완료 대기
while pdf_file.state.name == 'PROCESSING':
    time.sleep(2)
    pdf_file = genai.get_file(pdf_file.name)

# 임베딩 생성
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=pdf_file
)

embedding = result['embedding']

PDF 제한:

요청당 최대 6페이지
텍스트 및 시각 콘텐츠 모두 처리

멀티모달 임베딩 (텍스트 + 이미지)

단일 임베딩에 여러 콘텐츠 유형 결합:

import PIL.Image

image = PIL.Image.open('product.jpg')
text = "노이즈 캔슬링 기능이 있는 고품질 무선 헤드폰"

# 둘을 함께 임베딩
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=[text, image]
)

embedding = result['embedding']

이는 단일 임베딩에서 텍스트와 이미지 간의 관계를 포착합니다.

배치 처리

여러 항목을 효율적으로 처리:

texts = [
    "API 테스팅에 대한 첫 번째 문서",
    "자동화에 대한 두 번째 문서",
    "성능에 대한 세 번째 문서"
]

embeddings = []
for text in texts:
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=text,
        task_type='RETRIEVAL_DOCUMENT',
        output_dimensionality=768
    )
    embeddings.append(result['embedding'])

print(f"생성된 임베딩 수: {len(embeddings)}")

대규모 배치에는 배치 API를 사용하여 50%의 비용 절감 효과를 얻으세요.

시맨틱 검색 시스템 구축

다음은 시맨틱 검색을 위해 Gemini Embedding 2를 사용하는 전체 예제입니다.

1단계: 종속성 설치

pip install google-generativeai numpy scikit-learn

2단계: 문서 임베딩

import google.generativeai as genai
import numpy as np
from sklearn.metrics.pairwise import cosine_similarity

genai.configure(api_key='YOUR_API_KEY')

# 샘플 문서
documents = [
    "Apidog는 개발자를 위한 API 테스팅 플랫폼입니다",
    "REST API는 GET, POST, PUT, DELETE와 같은 HTTP 메서드를 사용합니다",
    "GraphQL은 API를 위한 쿼리 언어를 제공합니다",
    "API 문서는 개발자가 엔드포인트를 이해하는 데 도움이 됩니다",
    "Postman은 인기 있는 API 테스팅 도구입니다"
]

# 모든 문서에 대한 임베딩 생성
doc_embeddings = []
for doc in documents:
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=doc,
        task_type='RETRIEVAL_DOCUMENT',
        output_dimensionality=768
    )
    doc_embeddings.append(result['embedding'])

# 넘파이 배열로 변환
doc_embeddings = np.array(doc_embeddings)

3단계: 검색 함수 생성

def search(query, top_k=3):
    # 쿼리 임베딩
    query_result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=query,
        task_type='RETRIEVAL_QUERY',
        output_dimensionality=768
    )
    query_embedding = np.array([query_result['embedding']])

    # 유사성 계산
    similarities = cosine_similarity(query_embedding, doc_embeddings)[0]

    # 상위 결과 가져오기
    top_indices = np.argsort(similarities)[::-1][:top_k]

    results = []
    for idx in top_indices:
        results.append({
            'document': documents[idx],
            'score': similarities[idx]
        })

    return results

4단계: 검색

# 검색 테스트
results = search("API 테스팅에 어떤 도구를 사용할 수 있나요?")

for i, result in enumerate(results, 1):
    print(f"{i}. 점수: {result['score']:.4f}")
    print(f"   {result['document']}\n")

출력:

1. Score: 0.8234
   Apidog는 개발자를 위한 API 테스팅 플랫폼입니다

2. Score: 0.7891
   Postman은 인기 있는 API 테스팅 도구입니다

3. Score: 0.6543
   API 문서는 개발자가 엔드포인트를 이해하는 데 도움이 됩니다

RAG 시스템 구축

검색 증강 생성(Retrieval-Augmented Generation)을 위해 Gemini Embedding 2를 사용하세요.

1단계: 지식 기반 설정

import google.generativeai as genai
import numpy as np
from sklearn.metrics.pairwise import cosine_similarity

genai.configure(api_key='YOUR_API_KEY')

# 지식 기반
knowledge_base = [
    "Apidog는 REST, GraphQL 및 WebSocket API를 지원합니다",
    "테스트 케이스를 생성하고 자동으로 실행할 수 있습니다",
    "Apidog는 요청에서 API 문서를 생성합니다",
    "목 서버는 백엔드가 준비되기 전에 테스트하는 데 도움이 됩니다",
    "팀 협업 기능에는 공유 작업 공간이 포함됩니다"
]

# 지식 기반 임베딩
kb_embeddings = []
for doc in knowledge_base:
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=doc,
        task_type='RETRIEVAL_DOCUMENT',
        output_dimensionality=768
    )
    kb_embeddings.append(result['embedding'])

kb_embeddings = np.array(kb_embeddings)

2단계: RAG 쿼리 함수 생성

def rag_query(question):
    # 1. 질문 임베딩
    query_result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=question,
        task_type='RETRIEVAL_QUERY',
        output_dimensionality=768
    )
    query_embedding = np.array([query_result['embedding']])

    # 2. 관련 컨텍스트 찾기
    similarities = cosine_similarity(query_embedding, kb_embeddings)[0]
    top_idx = np.argmax(similarities)
    context = knowledge_base[top_idx]

    # 3. 컨텍스트를 사용하여 답변 생성
    prompt = f"""Context: {context}

Question: {question}

제공된 컨텍스트를 기반으로 질문에 답하세요."""

    model = genai.GenerativeModel('gemini-2.0-flash-exp')
    response = model.generate_content(prompt)

    return response.text

3단계: RAG 시스템 쿼리

# RAG 테스트
answer = rag_query("Apidog는 문서를 생성할 수 있나요?")
print(answer)

이것은 지식 기반에서 가장 관련성 높은 컨텍스트를 검색하고 이를 사용하여 정확한 답변을 생성합니다.

벡터 데이터베이스에 임베딩 저장

ChromaDB를 사용하여 임베딩을 저장하고 쿼리하세요:

import chromadb
import google.generativeai as genai

genai.configure(api_key='YOUR_API_KEY')

# ChromaDB 초기화
client = chromadb.Client()
collection = client.create_collection(name="my_documents")

# 색인화할 문서
documents = [
    "API 테스팅은 엔드포인트가 올바르게 작동하는지 확인합니다",
    "REST API는 무상태 아키텍처 원칙을 따릅니다",
    "GraphQL은 클라이언트가 특정 데이터를 요청할 수 있도록 합니다"
]

# 임베딩 생성 및 저장
for i, doc in enumerate(documents):
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=doc,
        task_type='RETRIEVAL_DOCUMENT',
        output_dimensionality=768
    )

    collection.add(
        embeddings=[result['embedding']],
        documents=[doc],
        ids=[f"doc_{i}"]
    )

# 컬렉션 쿼리
query = "API를 어떻게 테스트하나요?"
query_result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=query,
    task_type='RETRIEVAL_QUERY',
    output_dimensionality=768
)

results = collection.query(
    query_embeddings=[query_result['embedding']],
    n_results=2
)

print("상위 결과:")
for doc in results['documents'][0]:
    print(f"- {doc}")

오류 처리

API 오류를 원활하게 처리하세요:

import google.generativeai as genai
from google.api_core import exceptions

genai.configure(api_key='YOUR_API_KEY')

def safe_embed(content):
    try:
        result = genai.embed_content(
            model='models/gemini-embedding-2-preview',
            content=content,
            output_dimensionality=768
        )
        return result['embedding']

    except exceptions.InvalidArgument as e:
        print(f"잘못된 입력: {e}")
        # 예시: 콘텐츠가 너무 길거나 지원되지 않는 형식
        return None

    except exceptions.ResourceExhausted as e:
        print(f"할당량 초과: {e}")
        # 예시: 속도 제한 도달 또는 할당량 소진
        return None

    except exceptions.DeadlineExceeded as e:
        print(f"요청 시간 초과: {e}")
        # 예시: 네트워크 문제 또는 느린 응답
        return None

    except Exception as e:
        print(f"예상치 못한 오류: {e}")
        return None

# 사용
embedding = safe_embed("여기에 텍스트를 입력하세요")
if embedding:
    print("임베딩이 성공적으로 생성되었습니다")
else:
    print("임베딩 생성 실패")

일반적인 오류 메시지:

InvalidArgument: Content exceeds maximum length - 입력 크기 줄이기
ResourceExhausted: Quota exceeded - 대기하거나 플랜 업그레이드
Unauthenticated: API key not valid - API 키 확인
PermissionDenied: Model not available - 모델 이름 확인

속도 제한 및 모범 사례

속도 제한:

무료 등급: 분당 60개 요청
유료 등급: 플랜에 따라 더 높은 제한

모범 사례:

적절한 차원 사용: 프로덕션에는 768, 최대 품질이 필요할 때만 3072 사용

배치 요청: 가능하면 여러 항목을 함께 처리

임베딩 캐싱: 동일한 콘텐츠를 다시 임베딩하지 않기

작업 지침 사용: 특정 사용 사례에 대한 정확도 향상

오류 처리: 지수 백오프를 사용하여 재시도 로직 구현

비용 모니터링: 토큰 사용량 추적

비용 최적화

다음 전략으로 비용을 절감하세요:

1. 더 작은 차원 사용:

# 768 차원 = 75% 적은 저장 공간
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=text,
    output_dimensionality=768
)

2. 긴급하지 않은 작업에 배치 API 사용:

# 배치 처리 시 50% 비용 절감
# (배치 API 구현은 설정에 따라 다름)

3. 임베딩 캐싱:

import hashlib
import json

embedding_cache = {}

def get_embedding_cached(content):
    # 캐시 키 생성
    cache_key = hashlib.md5(content.encode()).hexdigest()

    # 캐시 확인
    if cache_key in embedding_cache:
        return embedding_cache[cache_key]

    # 임베딩 생성
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=content,
        output_dimensionality=768
    )

    # 캐시에 저장
    embedding_cache[cache_key] = result['embedding']

    return result['embedding']

일반적인 문제 및 해결책

문제: "잘못된 API 키"

# 해결책: API 키 확인
import os
api_key = os.getenv('GEMINI_API_KEY')
if not api_key:
    print("API 키가 설정되지 않았습니다!")

문제: "콘텐츠가 너무 길어요"

# 해결책: 긴 텍스트를 청크로 분할
def chunk_text(text, max_tokens=8000):
    # 간단한 단어 기반 청크 분할
    words = text.split()
    chunks = []
    current_chunk = []

    for word in words:
        current_chunk.append(word)
        if len(current_chunk) >= max_tokens:
            chunks.append(' '.join(current_chunk))
            current_chunk = []

    if current_chunk:
        chunks.append(' '.join(current_chunk))

    return chunks

# 각 청크 임베딩
for chunk in chunk_text(long_text):
    embedding = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=chunk
    )

문제: "파일 처리 시간 초과"

# 해결책: 대용량 파일에 대한 대기 시간 증가
import time

video_file = genai.upload_file(path='large-video.mp4')

max_wait = 300  # 5분
waited = 0
while video_file.state.name == 'PROCESSING' and waited < max_wait:
    time.sleep(5)
    waited += 5
    video_file = genai.get_file(video_file.name)

if video_file.state.name == 'PROCESSING':
    print("파일 처리 시간 초과")
else:
    # 임베딩 생성
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=video_file
    )

다음 단계

이제 Gemini Embedding 2 API를 사용하는 방법을 알았습니다. 다음으로 시도해볼 사항은 다음과 같습니다:

문서를 위한 시맨틱 검색 시스템 구축
멀티모달 컨텍스트를 사용한 RAG 애플리케이션 생성
제품 카탈로그를 위한 시각적 검색 구현
팟캐스트 또는 비디오 콘텐츠를 위한 오디오 검색 설정
비용 최적화를 위해 다양한 차원 실험

API는 간단하지만 가능성은 무궁무진합니다. 텍스트 임베딩으로 시작한 다음 사용 사례에 따라 이미지, 비디오 또는 오디오를 추가하세요.

구현을 테스트 중이신가요? Apidog를 사용하여 Gemini API 엔드포인트를 테스트하고, 응답을 검증하고, 임베딩 파이프라인 테스트를 자동화하세요.