Cara Menggunakan Gemini Embedding 2 API

API Gemini Embedding 2 dari Google memungkinkan Anda menghasilkan embedding untuk teks, gambar, video, audio, dan PDF. Panduan ini menunjukkan cara menggunakannya, dengan contoh kode nyata yang dapat Anda jalankan hari ini.

Catatan: Panduan ini mencakup versi pratinjau publik (gemini-embedding-2-preview). API dapat berubah sebelum ketersediaan umum.

Ingin memahami apa itu Gemini Embedding 2 terlebih dahulu? Baca ikhtisar kami: Apa Itu Gemini Embedding 2?

Prasyarat

Anda membutuhkan:

• Kunci API Google AI
• Python 3.7 atau lebih tinggi
• SDK Google Generative AI

Instalasi

Instal SDK:

pip install google-generativeai

Pengaturan Dasar

Siapkan kunci API Anda:

import google.generativeai as genai

# Set your API key
genai.configure(api_key='YOUR_API_KEY')

Untuk produksi, gunakan variabel lingkungan:

import os
import google.generativeai as genai

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

Pengujian dengan Apidog

Sebelum masuk ke kode, Anda dapat menguji API Gemini Embedding secara langsung di Apidog:

1. Buat permintaan baru di Apidog
2. Atur metode ke POST
3. URL: https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2-preview:embedContent
4. Tambahkan header: x-goog-api-key: YOUR_API_KEY
5. Body (JSON):

{
  "content": {
    "parts": [{
      "text": "What is API testing?"
    }]
  }
}

Ini memungkinkan Anda memverifikasi kunci API Anda berfungsi dan melihat struktur respons sebelum menulis kode. Anda dapat menyimpannya sebagai kasus uji dan memvalidasi respons embedding di pipeline CI/CD Anda.

Menghasilkan Embedding Teks

Kasus penggunaan paling sederhana - sematkan teks:

import google.generativeai as genai

genai.configure(api_key='YOUR_API_KEY')

# Generate embedding
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='What is the meaning of life?'
)

# Get the embedding vector
embedding = result['embedding']
print(f"Embedding dimensions: {len(embedding)}")
print(f"First 5 values: {embedding[:5]}")

Output:

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

Catatan: Struktur responsnya adalah result['embedding'] yang mengembalikan daftar float. Setiap float mewakili satu dimensi dari vektor embedding.

Menggunakan Instruksi Tugas

Instruksi tugas mengoptimalkan embedding untuk kasus penggunaan tertentu:

# For search queries
query_result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='best API testing tools',
    task_type='RETRIEVAL_QUERY'
)

# For documents you're indexing
doc_result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Apidog is an API testing platform...',
    task_type='RETRIEVAL_DOCUMENT'
)

Jenis tugas yang tersedia:

• RETRIEVAL_QUERY - Gunakan untuk kueri pencarian
• RETRIEVAL_DOCUMENT - Gunakan untuk dokumen yang Anda indeks
• SEMANTIC_SIMILARITY - Gunakan untuk membandingkan kesamaan konten
• CLASSIFICATION - Gunakan untuk tugas kategorisasi
• CLUSTERING - Gunakan untuk mengelompokkan konten serupa

Mengontrol Dimensi Output

Kurangi biaya penyimpanan dengan menggunakan dimensi yang lebih kecil:

# Production-optimized: 768 dimensions
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Your text here',
    output_dimensionality=768
)

# Balanced: 1536 dimensions
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Your text here',
    output_dimensionality=1536
)

# Maximum quality: 3072 dimensions (default)
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Your text here',
    output_dimensionality=3072
)

Untuk sebagian besar aplikasi, 768 dimensi memberikan kualitas mendekati puncak dengan penyimpanan 75% lebih sedikit.

Menyematkan Gambar

Sematkan gambar untuk pencarian visual:

import PIL.Image

# Load image
image = PIL.Image.open('product-photo.jpg')

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

embedding = result['embedding']

Anda dapat menyematkan hingga 6 gambar per permintaan:

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
)

Menyematkan Video

Sematkan konten video untuk pencarian video:

# Upload video file first
video_file = genai.upload_file(path='demo-video.mp4')

# Wait for processing
import time
while video_file.state.name == 'PROCESSING':
    time.sleep(2)
    video_file = genai.get_file(video_file.name)

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

embedding = result['embedding']

Batasan video:

• Maksimum 128 detik per permintaan
• Format: MP4, MOV
• Codec: H264, H265, AV1, VP9

Menyematkan Audio

Sematkan audio tanpa transkripsi:

# Upload audio file
audio_file = genai.upload_file(path='podcast-episode.mp3')

# Wait for processing
while audio_file.state.name == 'PROCESSING':
    time.sleep(2)
    audio_file = genai.get_file(audio_file.name)

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

embedding = result['embedding']

Batasan audio:

• Maksimum 80 detik per permintaan
• Format: MP3, WAV

Menyematkan Dokumen PDF

Sematkan halaman PDF untuk pencarian dokumen:

# Upload PDF
pdf_file = genai.upload_file(path='user-manual.pdf')

# Wait for processing
while pdf_file.state.name == 'PROCESSING':
    time.sleep(2)
    pdf_file = genai.get_file(pdf_file.name)

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

embedding = result['embedding']

Batasan PDF:

• Maksimum 6 halaman per permintaan
• Memproses konten teks dan visual

Embedding Multimodal (Teks + Gambar)

Gabungkan beberapa jenis konten dalam satu embedding:

import PIL.Image

image = PIL.Image.open('product.jpg')
text = "High-quality wireless headphones with noise cancellation"

# Embed both together
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=[text, image]
)

embedding = result['embedding']

Ini menangkap hubungan antara teks dan gambar dalam satu embedding.

Pemrosesan Batch

Proses beberapa item secara efisien:

texts = [
    "First document about API testing",
    "Second document about automation",
    "Third document about performance"
]

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"Generated {len(embeddings)} embeddings")

Untuk batch besar, gunakan API batch untuk penghematan biaya 50%.

Membangun Sistem Pencarian Semantik

Berikut adalah contoh lengkap menggunakan Gemini Embedding 2 untuk pencarian semantik.

Langkah 1: Instal Dependensi

pip install google-generativeai numpy scikit-learn

Langkah 2: Sematkan Dokumen Anda

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

genai.configure(api_key='YOUR_API_KEY')

# Sample documents
documents = [
    "Apidog is an API testing platform for developers",
    "REST APIs use HTTP methods like GET, POST, PUT, DELETE",
    "GraphQL provides a query language for APIs",
    "API documentation helps developers understand endpoints",
    "Postman is a popular API testing tool"
]

# Generate embeddings for all documents
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'])

# Convert to numpy array
doc_embeddings = np.array(doc_embeddings)

Langkah 3: Buat Fungsi Pencarian

def search(query, top_k=3):
    # Embed the query
    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']])

    # Calculate similarities
    similarities = cosine_similarity(query_embedding, doc_embeddings)[0]

    # Get top results
    top_indices = np.argsort(similarities)[::-1][:top_k]

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

    return results

Langkah 4: Pencarian

# Test the search
results = search("What tools can I use for API testing?")

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

Output:

1. Score: 0.8234
   Apidog is an API testing platform for developers

2. Score: 0.7891
   Postman is a popular API testing tool

3. Score: 0.6543
   API documentation helps developers understand endpoints

Membangun Sistem RAG

Gunakan Gemini Embedding 2 untuk Retrieval-Augmented Generation (RAG).

Langkah 1: Siapkan Basis Pengetahuan

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
knowledge_base = [
    "Apidog supports REST, GraphQL, and WebSocket APIs",
    "You can create test cases and run them automatically",
    "Apidog generates API documentation from your requests",
    "Mock servers help you test before backend is ready",
    "Team collaboration features include shared workspaces"
]

# Embed knowledge base
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)

Langkah 2: Buat Fungsi Kueri RAG

def rag_query(question):
    # 1. Embed the question
    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. Find relevant context
    similarities = cosine_similarity(query_embedding, kb_embeddings)[0]
    top_idx = np.argmax(similarities)
    context = knowledge_base[top_idx]

    # 3. Generate answer with context
    prompt = f"""Context: {context}

Question: {question}

Answer the question based on the context provided."""

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

    return response.text

Langkah 3: Kueri Sistem RAG Anda

# Test RAG
answer = rag_query("Can Apidog generate documentation?")
print(answer)

Ini mengambil konteks yang paling relevan dari basis pengetahuan Anda dan menggunakannya untuk menghasilkan jawaban yang akurat.

Menyimpan Embedding dalam Database Vektor

Gunakan ChromaDB untuk menyimpan dan mengkueri embedding:

import chromadb
import google.generativeai as genai

genai.configure(api_key='YOUR_API_KEY')

# Initialize ChromaDB
client = chromadb.Client()
collection = client.create_collection(name="my_documents")

# Documents to index
documents = [
    "API testing ensures your endpoints work correctly",
    "REST APIs follow stateless architecture principles",
    "GraphQL allows clients to request specific data"
]

# Generate and store embeddings
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 the collection
query = "How do I test my 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("Top results:")
for doc in results['documents'][0]:
    print(f"- {doc}")

Penanganan Kesalahan

Tangani kesalahan API dengan baik:

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"Invalid input: {e}")
        # Example: Content too long or unsupported format
        return None

    except exceptions.ResourceExhausted as e:
        print(f"Quota exceeded: {e}")
        # Example: Rate limit hit or quota exhausted
        return None

    except exceptions.DeadlineExceeded as e:
        print(f"Request timeout: {e}")
        # Example: Network issues or slow response
        return None

    except Exception as e:
        print(f"Unexpected error: {e}")
        return None

# Use it
embedding = safe_embed("Your text here")
if embedding:
    print("Embedding generated successfully")
else:
    print("Failed to generate embedding")

Pesan Kesalahan Umum:

• InvalidArgument: Content exceeds maximum length - Kurangi ukuran input
• ResourceExhausted: Quota exceeded - Tunggu atau tingkatkan paket
• Unauthenticated: API key not valid - Periksa kunci API Anda
• PermissionDenied: Model not available - Verifikasi nama model

Batasan Tingkat dan Praktik Terbaik

Batasan Tingkat (Rate Limits):

• Tingkat gratis: 60 permintaan per menit
• Tingkat berbayar: Batasan lebih tinggi berdasarkan paket Anda

Praktik Terbaik:

Gunakan dimensi yang sesuai: 768 untuk produksi, 3072 hanya jika Anda membutuhkan kualitas maksimum

Permintaan batch: Proses beberapa item bersamaan jika memungkinkan

Cache embedding: Jangan menyematkan ulang konten yang sama

Gunakan instruksi tugas: Ini meningkatkan akurasi untuk kasus penggunaan tertentu

Tangani kesalahan: Terapkan logika coba lagi dengan backoff eksponensial

Pantau biaya: Lacak penggunaan token Anda

Optimasi Biaya

Kurangi biaya dengan strategi ini:

1. Gunakan dimensi yang lebih kecil:

# 768 dimensions = 75% less storage
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=text,
    output_dimensionality=768
)

2. Gunakan API batch untuk tugas yang tidak mendesak:

# 50% cost savings for batch processing
# (Batch API implementation depends on your setup)

3. Cache embedding:

import hashlib
import json

embedding_cache = {}

def get_embedding_cached(content):
    # Create cache key
    cache_key = hashlib.md5(content.encode()).hexdigest()

    # Check cache
    if cache_key in embedding_cache:
        return embedding_cache[cache_key]

    # Generate embedding
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=content,
        output_dimensionality=768
    )

    # Store in cache
    embedding_cache[cache_key] = result['embedding']

    return result['embedding']

Masalah Umum dan Solusi

Masalah: "Kunci API tidak valid"

# Solution: Check your API key
import os
api_key = os.getenv('GEMINI_API_KEY')
if not api_key:
    print("API key not set!")

Masalah: "Konten terlalu panjang"

# Solution: Split long text into chunks
def chunk_text(text, max_tokens=8000):
    # Simple word-based chunking
    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

# Embed each chunk
for chunk in chunk_text(long_text):
    embedding = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=chunk
    )

Masalah: "Waktu pemrosesan file habis"

# Solution: Increase wait time for large files
import time

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

max_wait = 300  # 5 minutes
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("File processing timeout")
else:
    # Generate embedding
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=video_file
    )

Langkah Selanjutnya

Sekarang Anda tahu cara menggunakan API Gemini Embedding 2. Berikut adalah hal yang dapat Anda coba selanjutnya:

1. Buat sistem pencarian semantik untuk dokumentasi Anda
2. Buat aplikasi RAG dengan konteks multimodal
3. Implementasikan pencarian visual untuk katalog produk
4. Siapkan pencarian audio untuk konten podcast atau video
5. Bereksperimen dengan dimensi berbeda untuk mengoptimalkan biaya

API ini mudah digunakan, tetapi kemungkinannya sangat besar. Mulailah dengan embedding teks, lalu tambahkan gambar, video, atau audio sesuai kebutuhan kasus penggunaan Anda.

Menguji implementasi Anda? Gunakan Apidog untuk menguji endpoint API Gemini, memvalidasi respons, dan mengotomatiskan pengujian pipeline embedding Anda.