Hướng Dẫn Sử Dụng Gemini Embedding 2 API Chi Tiết

API Gemini Embedding 2 của Google cho phép bạn tạo nhúng (embeddings) cho văn bản, hình ảnh, video, âm thanh và PDF. Hướng dẫn này sẽ chỉ cho bạn cách sử dụng, với các ví dụ code thực tế bạn có thể chạy ngay hôm nay.

Lưu ý: Hướng dẫn này bao gồm phiên bản xem trước công khai (gemini-embedding-2-preview). API có thể thay đổi trước khi được phát hành rộng rãi.

Bạn muốn hiểu Gemini Embedding 2 là gì trước tiên? Đọc bài tổng quan của chúng tôi: Gemini Embedding 2 là gì?

Yêu cầu

Bạn cần:

• Một khóa API Google AI
• Python 3.7 trở lên
• SDK Google Generative AI

Cài đặt

Cài đặt SDK:

pip install google-generativeai

Thiết lập cơ bản

Thiết lập khóa API của bạn:

import google.generativeai as genai

# Đặt khóa API của bạn
genai.configure(api_key='YOUR_API_KEY')

Đối với môi trường sản xuất, hãy sử dụng biến môi trường:

import os
import google.generativeai as genai

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

Kiểm tra với Apidog

Trước khi đi sâu vào code, bạn có thể kiểm tra API Gemini Embedding trực tiếp trong Apidog:

1. Tạo một yêu cầu mới trong Apidog
2. Đặt phương thức là POST
3. URL: https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2-preview:embedContent
4. Thêm header: x-goog-api-key: YOUR_API_KEY
5. Body (JSON):

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

Điều này cho phép bạn xác minh khóa API của mình hoạt động và xem cấu trúc phản hồi trước khi viết code. Bạn có thể lưu lại làm trường hợp kiểm thử và xác thực phản hồi nhúng trong pipeline CI/CD của mình.

Tạo nhúng văn bản

Trường hợp sử dụng đơn giản nhất - nhúng văn bản:

import google.generativeai as genai

genai.configure(api_key='YOUR_API_KEY')

# Tạo nhúng
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='What is the meaning of life?'
)

# Lấy vector nhúng
embedding = result['embedding']
print(f"Kích thước nhúng: {len(embedding)}")
print(f"5 giá trị đầu tiên: {embedding[:5]}")

Đầu ra:

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

Lưu ý: Cấu trúc phản hồi là result['embedding'] trả về một danh sách các số thực. Mỗi số thực đại diện cho một chiều của vector nhúng.

Sử dụng hướng dẫn tác vụ

Hướng dẫn tác vụ tối ưu hóa nhúng cho các trường hợp sử dụng cụ thể:

# Dành cho truy vấn tìm kiếm
query_result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='best API testing tools',
    task_type='RETRIEVAL_QUERY'
)

# Dành cho tài liệu bạn đang lập chỉ mục
doc_result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Apidog is an API testing platform...',
    task_type='RETRIEVAL_DOCUMENT'
)

Các loại tác vụ khả dụng:

• RETRIEVAL_QUERY - Dùng cho các truy vấn tìm kiếm
• RETRIEVAL_DOCUMENT - Dùng cho các tài liệu bạn đang lập chỉ mục
• SEMANTIC_SIMILARITY - Dùng để so sánh độ tương đồng nội dung
• CLASSIFICATION - Dùng cho các tác vụ phân loại
• CLUSTERING - Dùng để nhóm các nội dung tương tự

Kiểm soát kích thước đầu ra

Giảm chi phí lưu trữ bằng cách sử dụng kích thước nhỏ hơn:

# Tối ưu hóa cho sản xuất: 768 chiều
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Your text here',
    output_dimensionality=768
)

# Cân bằng: 1536 chiều
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Your text here',
    output_dimensionality=1536
)

# Chất lượng tối đa: 3072 chiều (mặc định)
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content='Your text here',
    output_dimensionality=3072
)

Đối với hầu hết các ứng dụng, 768 chiều mang lại chất lượng gần như cao nhất với chi phí lưu trữ ít hơn 75%.

Nhúng hình ảnh

Nhúng hình ảnh để tìm kiếm trực quan:

import PIL.Image

# Tải hình ảnh
image = PIL.Image.open('product-photo.jpg')

# Tạo nhúng
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=image
)

embedding = result['embedding']

Bạn có thể nhúng tối đa 6 hình ảnh mỗi yêu cầu:

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
)

Nhúng video

Nhúng nội dung video để tìm kiếm video:

# Tải tệp video trước
video_file = genai.upload_file(path='demo-video.mp4')

# Chờ xử lý
import time
while video_file.state.name == 'PROCESSING':
    time.sleep(2)
    video_file = genai.get_file(video_file.name)

# Tạo nhúng
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=video_file
)

embedding = result['embedding']

Giới hạn video:

• Tối đa 128 giây mỗi yêu cầu
• Định dạng: MP4, MOV
• Codec: H264, H265, AV1, VP9

Nhúng âm thanh

Nhúng âm thanh mà không cần chuyển đổi giọng nói thành văn bản:

# Tải tệp âm thanh
audio_file = genai.upload_file(path='podcast-episode.mp3')

# Chờ xử lý
while audio_file.state.name == 'PROCESSING':
    time.sleep(2)
    audio_file = genai.get_file(audio_file.name)

# Tạo nhúng
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=audio_file
)

embedding = result['embedding']

Giới hạn âm thanh:

• Tối đa 80 giây mỗi yêu cầu
• Định dạng: MP3, WAV

Nhúng tài liệu PDF

Nhúng các trang PDF để tìm kiếm tài liệu:

# Tải PDF
pdf_file = genai.upload_file(path='user-manual.pdf')

# Chờ xử lý
while pdf_file.state.name == 'PROCESSING':
    time.sleep(2)
    pdf_file = genai.get_file(pdf_file.name)

# Tạo nhúng
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=pdf_file
)

embedding = result['embedding']

Giới hạn PDF:

• Tối đa 6 trang mỗi yêu cầu
• Xử lý cả nội dung văn bản và hình ảnh

Nhúng đa phương thức (Văn bản + Hình ảnh)

Kết hợp nhiều loại nội dung trong một lần nhúng:

import PIL.Image

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

# Nhúng cả hai cùng nhau
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=[text, image]
)

embedding = result['embedding']

Điều này nắm bắt mối quan hệ giữa văn bản và hình ảnh trong một nhúng duy nhất.

Xử lý hàng loạt

Xử lý nhiều mục một cách hiệu quả:

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"Đã tạo {len(embeddings)} nhúng")

Đối với các lô lớn, hãy sử dụng API hàng loạt để tiết kiệm 50% chi phí.

Xây dựng hệ thống tìm kiếm ngữ nghĩa

Đây là một ví dụ hoàn chỉnh sử dụng Gemini Embedding 2 cho tìm kiếm ngữ nghĩa.

Bước 1: Cài đặt các phụ thuộc

pip install google-generativeai numpy scikit-learn

Bước 2: Nhúng tài liệu của bạn

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

genai.configure(api_key='YOUR_API_KEY')

# Tài liệu mẫu
documents = [
    "Apidog là một nền tảng kiểm thử API dành cho nhà phát triển",
    "REST API sử dụng các phương thức HTTP như GET, POST, PUT, DELETE",
    "GraphQL cung cấp ngôn ngữ truy vấn cho API",
    "Tài liệu API giúp nhà phát triển hiểu các endpoint",
    "Postman là một công cụ kiểm thử API phổ biến"
]

# Tạo nhúng cho tất cả tài liệu
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'])

# Chuyển đổi thành mảng numpy
doc_embeddings = np.array(doc_embeddings)

Bước 3: Tạo chức năng tìm kiếm

def search(query, top_k=3):
    # Nhúng truy vấn
    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']])

    # Tính toán độ tương đồng
    similarities = cosine_similarity(query_embedding, doc_embeddings)[0]

    # Lấy kết quả hàng đầu
    top_indices = np.argsort(similarities)[::-1][:top_k]

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

    return results

Bước 4: Tìm kiếm

# Kiểm tra tìm kiếm
results = search("Tôi có thể dùng công cụ nào để kiểm thử API?")

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

Đầu ra:

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

Xây dựng hệ thống RAG

Sử dụng Gemini Embedding 2 cho Retrieval-Augmented Generation (Tạo sinh tăng cường truy xuất).

Bước 1: Thiết lập cơ sở kiến thức

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

genai.configure(api_key='YOUR_API_KEY')

# Cơ sở kiến thức
knowledge_base = [
    "Apidog hỗ trợ REST, GraphQL và WebSocket API",
    "Bạn có thể tạo các trường hợp kiểm thử và chạy chúng tự động",
    "Apidog tạo tài liệu API từ các yêu cầu của bạn",
    "Mock server giúp bạn kiểm thử trước khi backend sẵn sàng",
    "Các tính năng cộng tác nhóm bao gồm không gian làm việc chung"
]

# Nhúng cơ sở kiến thức
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)

Bước 2: Tạo chức năng truy vấn RAG

def rag_query(question):
    # 1. Nhúng câu hỏi
    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. Tìm ngữ cảnh liên quan
    similarities = cosine_similarity(query_embedding, kb_embeddings)[0]
    top_idx = np.argmax(similarities)
    context = knowledge_base[top_idx]

    # 3. Tạo câu trả lời với ngữ cảnh
    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

Bước 3: Truy vấn hệ thống RAG của bạn

# Kiểm tra RAG
answer = rag_query("Apidog có thể tạo tài liệu không?")
print(answer)

Điều này truy xuất ngữ cảnh phù hợp nhất từ cơ sở kiến thức của bạn và sử dụng nó để tạo ra các câu trả lời chính xác.

Lưu trữ nhúng trong cơ sở dữ liệu vector

Sử dụng ChromaDB để lưu trữ và truy vấn nhúng:

import chromadb
import google.generativeai as genai

genai.configure(api_key='YOUR_API_KEY')

# Khởi tạo ChromaDB
client = chromadb.Client()
collection = client.create_collection(name="my_documents")

# Tài liệu để lập chỉ mục
documents = [
    "Kiểm thử API đảm bảo các endpoint của bạn hoạt động chính xác",
    "REST API tuân theo các nguyên tắc kiến trúc không trạng thái",
    "GraphQL cho phép client yêu cầu dữ liệu cụ thể"
]

# Tạo và lưu trữ nhúng
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}"]
    )

# Truy vấn bộ sưu tập
query = "Làm cách nào để kiểm thử API của tôi?"
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("Kết quả hàng đầu:")
for doc in results['documents'][0]:
    print(f"- {doc}")

Xử lý lỗi

Xử lý lỗi API một cách linh hoạt:

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"Đầu vào không hợp lệ: {e}")
        # Ví dụ: Nội dung quá dài hoặc định dạng không được hỗ trợ
        return None

    except exceptions.ResourceExhausted as e:
        print(f"Đã vượt quá hạn ngạch: {e}")
        # Ví dụ: Đã đạt giới hạn tỷ lệ hoặc hết hạn ngạch
        return None

    except exceptions.DeadlineExceeded as e:
        print(f"Yêu cầu hết thời gian chờ: {e}")
        # Ví dụ: Sự cố mạng hoặc phản hồi chậm
        return None

    except Exception as e:
        print(f"Lỗi không mong muốn: {e}")
        return None

# Sử dụng nó
embedding = safe_embed("Nội dung của bạn ở đây")
if embedding:
    print("Nhúng đã được tạo thành công")
else:
    print("Không thể tạo nhúng")

Thông báo lỗi thường gặp:

• InvalidArgument: Content exceeds maximum length - Giảm kích thước đầu vào
• ResourceExhausted: Quota exceeded - Chờ hoặc nâng cấp gói
• Unauthenticated: API key not valid - Kiểm tra khóa API của bạn
• PermissionDenied: Model not available - Xác minh tên mô hình

Giới hạn tỷ lệ và các thực hành tốt nhất

Giới hạn tỷ lệ:

• Bậc miễn phí: 60 yêu cầu mỗi phút
• Bậc trả phí: Giới hạn cao hơn tùy theo gói của bạn

Thực hành tốt nhất:

Sử dụng kích thước phù hợp: 768 cho sản xuất, 3072 chỉ khi bạn cần chất lượng tối đa

Yêu cầu hàng loạt: Xử lý nhiều mục cùng lúc nếu có thể

Bộ nhớ đệm nhúng: Không nhúng lại cùng một nội dung

Sử dụng hướng dẫn tác vụ: Chúng cải thiện độ chính xác cho các trường hợp sử dụng cụ thể

Xử lý lỗi: Triển khai logic thử lại với thuật toán lũy thừa (exponential backoff)

Theo dõi chi phí: Theo dõi mức sử dụng token của bạn

Tối ưu hóa chi phí

Giảm chi phí với các chiến lược sau:

1. Sử dụng kích thước nhỏ hơn:

# 768 chiều = giảm 75% lưu trữ
result = genai.embed_content(
    model='models/gemini-embedding-2-preview',
    content=text,
    output_dimensionality=768
)

2. Sử dụng API hàng loạt cho các tác vụ không khẩn cấp:

# Tiết kiệm 50% chi phí cho xử lý hàng loạt
# (Việc triển khai API hàng loạt tùy thuộc vào thiết lập của bạn)

3. Bộ nhớ đệm nhúng:

import hashlib
import json

embedding_cache = {}

def get_embedding_cached(content):
    # Tạo khóa bộ nhớ đệm
    cache_key = hashlib.md5(content.encode()).hexdigest()

    # Kiểm tra bộ nhớ đệm
    if cache_key in embedding_cache:
        return embedding_cache[cache_key]

    # Tạo nhúng
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=content,
        output_dimensionality=768
    )

    # Lưu trữ vào bộ nhớ đệm
    embedding_cache[cache_key] = result['embedding']

    return result['embedding']

Các vấn đề thường gặp và giải pháp

Vấn đề: "Khóa API không hợp lệ"

# Giải pháp: Kiểm tra khóa API của bạn
import os
api_key = os.getenv('GEMINI_API_KEY')
if not api_key:
    print("Khóa API chưa được đặt!")

Vấn đề: "Nội dung quá dài"

# Giải pháp: Chia văn bản dài thành các đoạn nhỏ
def chunk_text(text, max_tokens=8000):
    # Chia theo từ đơn giản
    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

# Nhúng từng đoạn
for chunk in chunk_text(long_text):
    embedding = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=chunk
    )

Vấn đề: "Hết thời gian xử lý tệp"

# Giải pháp: Tăng thời gian chờ cho các tệp lớn
import time

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

max_wait = 300  # 5 phút
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("Hết thời gian xử lý tệp")
else:
    # Tạo nhúng
    result = genai.embed_content(
        model='models/gemini-embedding-2-preview',
        content=video_file
    )

Các bước tiếp theo

Bây giờ bạn đã biết cách sử dụng API Gemini Embedding 2. Dưới đây là những gì nên thử tiếp theo:

1. Xây dựng hệ thống tìm kiếm ngữ nghĩa cho tài liệu của bạn
2. Tạo ứng dụng RAG với ngữ cảnh đa phương thức
3. Triển khai tìm kiếm trực quan cho danh mục sản phẩm
4. Thiết lập tìm kiếm âm thanh cho nội dung podcast hoặc video
5. Thử nghiệm với các kích thước khác nhau để tối ưu hóa chi phí

API này rất đơn giản, nhưng khả năng của nó là rất lớn. Hãy bắt đầu với nhúng văn bản, sau đó thêm hình ảnh, video hoặc âm thanh tùy theo yêu cầu trường hợp sử dụng của bạn.

Bạn đang kiểm tra việc triển khai của mình? Sử dụng Apidog để kiểm tra các endpoint API Gemini, xác thực phản hồi và tự động hóa các bài kiểm thử pipeline nhúng của bạn.