كيفية استخدام Gemini Embedding 2 API؟

تتيح لك واجهة برمجة تطبيقات تضمين Gemini 2 من Google إنشاء تضمينات للنصوص والصور والفيديو والصوت وملفات PDF. يوضح لك هذا الدليل كيفية استخدامها، مع أمثلة تعليمات برمجية حقيقية يمكنك تشغيلها اليوم.

ملاحظة: يغطي هذا الدليل الإصدار التجريبي العام (gemini-embedding-2-preview). قد تتغير واجهة برمجة التطبيقات قبل التوفر العام.

هل تريد فهم ما هو تضمين Gemini 2 أولاً؟ اقرأ نظرتنا العامة: ما هو تضمين Gemini 2؟

المتطلبات الأساسية

أنت بحاجة إلى:

مفتاح Google AI API
بايثون 3.7 أو أحدث
حزمة تطوير البرامج (SDK) الخاصة بالذكاء الاصطناعي التوليدي من Google

التثبيت

قم بتثبيت حزمة تطوير البرامج (SDK):

pip install google-generativeai

الإعداد الأساسي

قم بإعداد مفتاح API الخاص بك:

import google.generativeai as genai

# Set your API key
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

قبل البدء في كتابة التعليمات البرمجية، يمكنك اختبار واجهة برمجة تطبيقات تضمين Gemini مباشرة في Apidog:

أنشئ طلبًا جديدًا في Apidog
عيّن الطريقة إلى POST
الرابط: https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2-preview:embedContent
أضف العنوان: x-goog-api-key: YOUR_API_KEY
الجسم (JSON):

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

يتيح لك هذا التحقق من أن مفتاح API الخاص بك يعمل ورؤية بنية الاستجابة قبل كتابة التعليمات البرمجية. يمكنك حفظ هذا كحالة اختبار والتحقق من صحة استجابات التضمين في خط أنابيب CI/CD الخاص بك.

إنشاء تضمينات نصية

أبسط حالة استخدام - تضمين النص:

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]}")

الإخراج:

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

ملاحظة: بنية الاستجابة هي result['embedding'] التي تُرجع قائمة من الأرقام العشرية. يمثل كل رقم عشري بُعدًا واحدًا لمتجه التضمين.

استخدام تعليمات المهام

تعمل تعليمات المهام على تحسين التضمينات لحالات استخدام محددة:

# 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'
)

أنواع المهام المتاحة:

RETRIEVAL_QUERY - يُستخدم لاستعلامات البحث
RETRIEVAL_DOCUMENT - يُستخدم للمستندات التي تقوم بفهرستها
SEMANTIC_SIMILARITY - يُستخدم لمقارنة تشابه المحتوى
CLASSIFICATION - يُستخدم لمهام التصنيف
CLUSTERING - يُستخدم لتجميع المحتوى المتشابه

التحكم في أبعاد الإخراج

قلل تكاليف التخزين باستخدام أبعاد أصغر:

# 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
)

بالنسبة لمعظم التطبيقات، توفر 768 بُعدًا جودة قريبة من الذروة مع تخزين أقل بنسبة 75%.

تضمين الصور

تضمين الصور للبحث المرئي:

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']

يمكنك تضمين ما يصل إلى 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
)

تضمين الفيديو

تضمين محتوى الفيديو للبحث عن الفيديو:

# 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']

قيود الفيديو:

128 ثانية كحد أقصى لكل طلب
التنسيقات: MP4, MOV
برامج الترميز: H264, H265, AV1, VP9

تضمين الصوت

تضمين الصوت بدون تحويل إلى نص:

# 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']

قيود الصوت:

80 ثانية كحد أقصى لكل طلب
التنسيقات: MP3, WAV

تضمين مستندات PDF

تضمين صفحات PDF للبحث في المستندات:

# 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']

قيود PDF:

6 صفحات كحد أقصى لكل طلب
يعالج النصوص والمحتوى المرئي على حد سواء

التضمينات متعددة الوسائط (نص + صورة)

ادمج أنواع محتوى متعددة في تضمين واحد:

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']

يلتقط هذا العلاقات بين النص والصورة في تضمين واحد.

المعالجة الدفعية

معالجة عناصر متعددة بكفاءة:

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")

للحزم الكبيرة، استخدم واجهة برمجة تطبيقات الدفعة لتوفير 50% من التكلفة.

بناء نظام بحث دلالي

إليك مثال كامل يوضح استخدام تضمين Gemini 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')

# 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)

الخطوة 3: إنشاء دالة بحث

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

الخطوة 4: البحث

# 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")

الإخراج:

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

بناء نظام RAG (توليد معزز بالاسترجاع)

استخدم تضمين Gemini 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
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)

الخطوة 2: إنشاء دالة استعلام 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

الخطوة 3: استعلام نظام RAG الخاص بك

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

يسترجع هذا السياق الأكثر صلة من قاعدة المعرفة الخاصة بك ويستخدمه لإنشاء إجابات دقيقة.

تخزين التضمينات في قاعدة بيانات متجهات

استخدم ChromaDB لتخزين التضمينات والاستعلام عنها:

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}")

معالجة الأخطاء

تعامل مع أخطاء 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"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")

رسائل الأخطاء الشائعة:

InvalidArgument: Content exceeds maximum length - قلل حجم الإدخال
ResourceExhausted: Quota exceeded - انتظر أو قم بترقية الخطة
Unauthenticated: API key not valid - تحقق من مفتاح API الخاص بك
PermissionDenied: Model not available - تحقق من اسم النموذج

حدود المعدل وأفضل الممارسات

حدود المعدل:

الطبقة المجانية: 60 طلبًا في الدقيقة
الطبقة المدفوعة: حدود أعلى بناءً على خطتك

أفضل الممارسات:

استخدم الأبعاد المناسبة: 768 للإنتاج، 3072 فقط عندما تحتاج إلى أقصى جودة

الطلبات الدفعية: عالج عناصر متعددة معًا عندما يكون ذلك ممكنًا

تضمينات ذاكرة التخزين المؤقت: لا تقم بإعادة تضمين نفس المحتوى

استخدم تعليمات المهام: إنها تحسن الدقة لحالات استخدام محددة

معالجة الأخطاء: نفذ منطق إعادة المحاولة مع التراجع الأسي

مراقبة التكاليف: تتبع استخدامك للرموز

تحسين التكلفة

قلل التكاليف بهذه الاستراتيجيات:

1. استخدم أبعادًا أصغر:

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

2. استخدم واجهة برمجة تطبيقات الدفعة للمهام غير العاجلة:

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

3. تضمينات ذاكرة التخزين المؤقت:

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']

المشكلات الشائعة والحلول

المشكلة: "مفتاح API غير صالح"

# الحل: تحقق من مفتاح API الخاص بك
import os
api_key = os.getenv('GEMINI_API_KEY')
if not api_key:
    print("API key not set!")

المشكلة: "المحتوى طويل جدًا"

# الحل: قسّم النص الطويل إلى أجزاء
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
    )

المشكلة: "مهلة معالجة الملف"

# الحل: زد وقت الانتظار للملفات الكبيرة
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
    )

الخطوات التالية

أنت تعرف الآن كيفية استخدام واجهة برمجة تطبيقات تضمين Gemini 2. إليك ما يمكنك تجربته لاحقًا:

ابنِ نظام بحث دلالي لوثائقك
أنشئ تطبيق RAG بسياق متعدد الوسائط
نفذ البحث المرئي لكتالوجات المنتجات
أعد البحث الصوتي لمحتوى البودكاست أو الفيديو
جرب أبعادًا مختلفة لتحسين التكاليف

واجهة برمجة التطبيقات بسيطة، لكن الإمكانيات هائلة. ابدأ بتضمينات النصوص، ثم أضف الصور أو الفيديو أو الصوت حسب متطلبات حالة استخدامك.

هل تختبر تطبيقك؟ استخدم Apidog لاختبار نقاط نهاية Gemini API، والتحقق من صحة الاستجابات، وأتمتة اختبارات مسار عمل التضمين الخاص بك.