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.js

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:

Parameter	Description	Example
`texts`	Text(s) to embed (required)	`"Your text here"`
`--model`, `-m`	Embedding model	`gemini-embedding-001`
`--task`, `-t`	Task type	`SEMANTIC_SIMILARITY`
`--dim`, `-d`	Output dimensionality	`768`, `1536`, `3072`
`--similarity`, `-s`	Calculate pairwise similarity	Flag
`--json`, `-j`	Output as JSON	Flag

Output: Embedding vectors or similarity scores

Workflows

Workflow 1: Single Text Embedding

node scripts/embed.js "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
node scripts/embed.js "best practices for coding" --task RETRIEVAL_QUERY > query.json

# 2. Generate embeddings for documents (batch)
node scripts/embed.js "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

node scripts/embed.js "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

node scripts/embed.js "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
node scripts/embed.js "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)
node scripts/embed.js "Document 1 content" "Document 2 content" --task RETRIEVAL_DOCUMENT --dim 1536

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

# 3. Use retrieved documents in prompt to LLM (gemini-text)
node skills/gemini-text/scripts/generate.js "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

node scripts/embed.js "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

Task Type	Best For	When to Use
`SEMANTIC_SIMILARITY`	Comparing text similarity	General comparison tasks
`RETRIEVAL_DOCUMENT`	Embedding documents	Storing documents for retrieval
`RETRIEVAL_QUERY`	Embedding search queries	Finding similar documents
`CLASSIFICATION`	Text classification	Categorizing text
`CLUSTERING`	Grouping similar texts	Document clustering

Dimensionality Options

Dimensions	Use Case	Trade-off
768	High-volume, real-time	Lower accuracy, faster
1536	Balanced performance	Good accuracy/speed balance
3072	Highest accuracy	Slower, more storage

Similarity Scores

Score	Interpretation
0.8 - 1.0	Very similar (likely duplicates)
0.6 - 0.8	Highly related (same topic)
0.4 - 0.6	Moderately related
0.2 - 0.4	Weakly related
0.0 - 0.2	Unrelated

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"

npm install @google/genai@latest dotenv@latest

"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
node scripts/embed.js "Your text here"

# Semantic search
node scripts/embed.js "Query" --task RETRIEVAL_QUERY

# Document embedding
node scripts/embed.js "Document text" --task RETRIEVAL_DOCUMENT

# Similarity comparison
node scripts/embed.js "Text 1" "Text 2" "Text 3" --similarity

# Dimensionality reduction
node scripts/embed.js "Text" --dim 768

# JSON output
node scripts/embed.js "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

gemini-embeddings