Gemini Embeddings

Generate high-quality text embeddings for semantic search, similarity analysis, clustering, and RAG (Retrieval Augmented Generation) applications through executable scripts.

When to Use This Skill

Use this skill when you need to:

• •Find semantically similar documents or texts
• •Build semantic search engines
• •Implement RAG (Retrieval Augmented Generation)
• •Cluster or group similar documents
• •Calculate text similarity scores
• •Power recommendation systems
• •Enable semantic document retrieval
• •Create vector databases for AI applications

Available Scripts

scripts/embed.py

Purpose: Generate embeddings and calculate similarity

When to use:

• •Creating vector representations of text
• •Comparing text similarity
• •Building semantic search systems
• •Implementing RAG pipelines
• •Clustering documents

Key parameters:

Output: Embedding vectors or similarity scores

Workflows

Workflow 1: Single Text Embedding

python scripts/embed.py "What is the meaning of life?"

• •Best for: Basic embedding generation
• •Output: Vector with 3072 dimensions (default)
• •Use when: Storing single document vectors

Workflow 2: Semantic Search

# 1. Generate embedding for query
python scripts/embed.py "best practices for coding" --task RETRIEVAL_QUERY > query.json

# 2. Generate embeddings for documents (batch)
python scripts/embed.py "Coding best practices include version control" "Clean code is essential" --task RETRIEVAL_DOCUMENT > docs.json

# 3. Compare and find most similar (calculate similarity separately)

• •Best for: Building search functionality
• •Task types: RETRIEVAL_QUERY, RETRIEVAL_DOCUMENT
• •Combines with: Similarity calculation for ranking

Workflow 3: Text Similarity Comparison

python scripts/embed.py "What is the meaning of life?" "What is the purpose of existence?" "How do I bake a cake?" --similarity

• •Best for: Comparing multiple texts, finding duplicates
• •Output: Pairwise similarity scores (0-1)
• •Use when: Need to rank text similarity

Workflow 4: Dimensionality Reduction for Efficiency

python scripts/embed.py "Text to embed" --dim 768

• •Best for: Faster storage and comparison
• •Options: 768, 1536, or 3072 (default)
• •Trade-off: Lower dimensions = less accuracy but faster

Workflow 5: Document Clustering

# 1. Generate embeddings for multiple documents
python scripts/embed.py "Machine learning is AI" "Deep learning is a subset" "Neural networks power AI" --json > embeddings.jsonl

# 2. Process embeddings with clustering algorithm (your code)
# Use scikit-learn, KMeans, etc.

• •Best for: Grouping similar documents, topic discovery
• •Task type: CLUSTERING
• •Combines with: Clustering libraries (scikit-learn)

Workflow 6: RAG Implementation

# 1. Create document embeddings (one-time setup)
python scripts/embed.py "Document 1 content" "Document 2 content" --task RETRIEVAL_DOCUMENT --dim 1536

# 2. For each query, find similar documents
python scripts/embed.py "User query here" --task RETRIEVAL_QUERY

# 3. Use retrieved documents in prompt to LLM (gemini-text)
python skills/gemini-text/scripts/generate.py "Context: [retrieved docs]. Answer: [user query]"

• •Best for: Building knowledge-based AI systems
• •Combines with: gemini-text for generation with context

Workflow 7: JSON Output for API Integration

python scripts/embed.py "Text to process" --json

• •Best for: API responses, database storage
• •Output: JSON array of embedding vectors
• •Use when: Programmatic processing required

Workflow 8: Batch Document Processing

# 1. Create JSONL with documents
echo '{"text": "Document 1"}' > docs.jsonl
echo '{"text": "Document 2"}' >> docs.jsonl

# 2. Process with script or custom code
python3 << 'EOF'
import json
from google import genai

client = genai.Client()

texts = []
with open("docs.jsonl") as f:
    for line in f:
        texts.append(json.loads(line)["text"])

response = client.models.embed_content(
    model="gemini-embedding-001",
    contents=texts,
    task_type="RETRIEVAL_DOCUMENT"
)

embeddings = [e.values for e in response.embeddings]
print(f"Generated {len(embeddings)} embeddings")
EOF

• •Best for: Large document collections
• •Combines with: Vector databases (Pinecone, Weaviate)

Parameters Reference

Task Types

Dimensionality Options

Similarity Scores

Output Interpretation

Embedding Vector

• •Format: List of float values (768, 1536, or 3072)
• •Range: Typically -1.0 to 1.0
• •Normalized for cosine similarity
• •Can be stored in vector databases

Similarity Output

Pairwise Similarity:
  'What is the meaning of life?...' <-> 'What is the purpose of existence?...': 0.8742
  'What is the meaning of life?...' <-> 'How do I bake a cake?...': 0.1234

• •Higher scores = more similar
• •Use threshold (e.g., 0.7) for matching

JSON Output

[[0.123, -0.456, 0.789, ...], [0.234, -0.567, 0.890, ...]]

• •Array of embedding vectors
• •One per input text
• •Ready for database storage

Common Issues

"google-genai not installed"

pip install google-genai numpy

"numpy not installed" (for similarity)

pip install numpy

"Invalid task type"

• •Use available tasks: SEMANTIC_SIMILARITY, RETRIEVAL_DOCUMENT, RETRIEVAL_QUERY, CLASSIFICATION, CLUSTERING
• •Check spelling (case-sensitive)
• •Use correct task for your use case

"Invalid dimension"

• •Options: 768, 1536, or 3072 only
• •Check model supports requested dimension
• •Default to 3072 if unsure

"No similarity calculated"

• •Need multiple texts for similarity comparison
• •Use --similarity flag
• •Check that at least 2 texts provided

"Embedding size mismatch"

• •All embeddings must have same dimensionality
• •Use consistent --dim parameter
• •Recompute if dimensions differ

Best Practices

Task Selection

• •SEMANTIC_SIMILARITY: General text comparison
• •RETRIEVAL_DOCUMENT: Storing documents for search
• •RETRIEVAL_QUERY: Querying for similar documents
• •CLASSIFICATION: Categorization tasks
• •CLUSTERING: Grouping similar content

Dimensionality Choice

• •768: Real-time applications, high volume
• •1536: Balanced choice for most use cases
• •3072: Maximum accuracy, offline processing

Performance Optimization

• •Use lower dimensions for speed
• •Batch multiple texts in one request
• •Cache embeddings for repeated queries
• •Precompute document embeddings for search

Storage Tips

• •Use vector databases (Pinecone, Weaviate, Chroma)
• •Normalize vectors for consistent comparison
• •Store metadata with embeddings
• •Index for fast retrieval

RAG Implementation

• •Precompute document embeddings
• •Use RETRIEVAL_DOCUMENT for docs
• •Use RETRIEVAL_QUERY for user questions
• •Combine top results with gemini-text

Similarity Thresholds

• •0.9+: Exact duplicates or near-duplicates
• •0.7-0.9: Same topic/subject
• •0.5-0.7: Related concepts
• •<0.5: Different topics

Related Skills

• •gemini-text: Generate text with retrieved context (RAG)
• •gemini-batch: Process embeddings in bulk
• •gemini-files: Upload documents for embedding
• •gemini-search: Implement semantic search (if available)

Quick Reference

# Basic embedding
python scripts/embed.py "Your text here"

# Semantic search
python scripts/embed.py "Query" --task RETRIEVAL_QUERY

# Document embedding
python scripts/embed.py "Document text" --task RETRIEVAL_DOCUMENT

# Similarity comparison
python scripts/embed.py "Text 1" "Text 2" "Text 3" --similarity

# Dimensionality reduction
python scripts/embed.py "Text" --dim 768

# JSON output
python scripts/embed.py "Text" --json

Reference

• •Get API key: https://aistudio.google.com/apikey
• •Documentation: https://ai.google.dev/gemini-api/docs/embeddings
• •Vector databases: Pinecone, Weaviate, Chroma, Qdrant
• •Cosine similarity: Standard for embedding comparison