0
# Embeddings
1

2
High-quality text embeddings using Google's Generative AI models for semantic search, similarity analysis, clustering, and machine learning applications. Provides efficient batch processing and configurable task types for optimal performance.
3

4
## Capabilities
5

6
### GoogleGenerativeAIEmbeddings
7

8
Primary embeddings interface that extends LangChain's `Embeddings` class to provide access to Google's embedding models.
9

10
```python { .api }
11
class GoogleGenerativeAIEmbeddings:
12
    def __init__(
13
        self,
14
        *,
15
        model: str,
16
        task_type: Optional[str] = None,
17
        google_api_key: Optional[SecretStr] = None,
18
        credentials: Any = None,
19
        client_options: Optional[Dict] = None,
20
        transport: Optional[str] = None,
21
        request_options: Optional[Dict] = None
22
    )
23
```
24

25
**Parameters:**
26
- `model` (str): Embedding model name (e.g., "models/gemini-embedding-001")
27
- `task_type` (Optional[str]): Task type for embeddings optimization
28
- `google_api_key` (Optional[SecretStr]): Google API key (defaults to GOOGLE_API_KEY env var)
29
- `credentials` (Any): Google authentication credentials object
30
- `client_options` (Optional[Dict]): API client configuration options
31
- `transport` (Optional[str]): Transport method ["rest", "grpc", "grpc_asyncio"]
32
- `request_options` (Optional[Dict]): Request configuration options
33

34
**Task Types:**
35
- `"task_type_unspecified"`: Default, general-purpose embeddings
36
- `"retrieval_query"`: Optimized for search queries
37
- `"retrieval_document"`: Optimized for document content
38
- `"semantic_similarity"`: Optimized for similarity comparisons
39
- `"classification"`: Optimized for classification tasks
40
- `"clustering"`: Optimized for clustering applications
41

42
### Core Methods
43

44
#### Single Query Embedding
45

46
```python { .api }
47
def embed_query(
48
    self,
49
    text: str,
50
    *,
51
    task_type: Optional[str] = None,
52
    title: Optional[str] = None,
53
    output_dimensionality: Optional[int] = None
54
) -> List[float]
55
```
56

57
Generate embedding for a single query text.
58

59
**Parameters:**
60
- `text` (str): Input text to embed
61
- `task_type` (Optional[str]): Override default task type for this request
62
- `title` (Optional[str]): Optional title for context
63
- `output_dimensionality` (Optional[int]): Desired embedding dimensions
64

65
**Returns:** List of float values representing the embedding vector
66

67
#### Batch Document Embedding
68

69
```python { .api }
70
def embed_documents(
71
    self,
72
    texts: List[str],
73
    *,
74
    batch_size: int = 100,
75
    task_type: Optional[str] = None,
76
    titles: Optional[List[str]] = None,
77
    output_dimensionality: Optional[int] = None
78
) -> List[List[float]]
79
```
80

81
Generate embeddings for multiple documents with automatic batching.
82

83
**Parameters:**
84
- `texts` (List[str]): List of input texts to embed
85
- `batch_size` (int): Batch size for processing (default: 100, max: based on token limits)
86
- `task_type` (Optional[str]): Override default task type for this request
87
- `titles` (Optional[List[str]]): Optional titles for each document
88
- `output_dimensionality` (Optional[int]): Desired embedding dimensions
89

90
**Returns:** List of embedding vectors, one for each input text
91

92
#### Async Methods
93

94
```python { .api }
95
async def aembed_query(
96
    self,
97
    text: str,
98
    *,
99
    task_type: Optional[str] = None,
100
    title: Optional[str] = None,
101
    output_dimensionality: Optional[int] = None
102
) -> List[float]
103
```
104

105
Async version of embed_query().
106

107
```python { .api }
108
async def aembed_documents(
109
    self,
110
    texts: List[str],
111
    *,
112
    batch_size: int = 100,
113
    task_type: Optional[str] = None,
114
    titles: Optional[List[str]] = None,
115
    output_dimensionality: Optional[int] = None
116
) -> List[List[float]]
117
```
118

119
Async version of embed_documents().
120

121
## Usage Examples
122

123
### Basic Query Embedding
124

125
```python
126
from langchain_google_genai import GoogleGenerativeAIEmbeddings
127

128
# Initialize embeddings model
129
embeddings = GoogleGenerativeAIEmbeddings(
130
    model="models/gemini-embedding-001"
131
)
132

133
# Generate embedding for a query
134
query = "What is machine learning?"
135
query_embedding = embeddings.embed_query(query)
136

137
print(f"Query embedding dimension: {len(query_embedding)}")
138
print(f"First 5 values: {query_embedding[:5]}")
139
```
140

141
### Document Embeddings
142

143
```python
144
# Embed multiple documents
145
documents = [
146
    "Machine learning is a subset of artificial intelligence.",
147
    "Deep learning uses neural networks with multiple layers.",
148
    "Natural language processing focuses on text and speech.",
149
    "Computer vision enables machines to interpret visual information."
150
]
151

152
doc_embeddings = embeddings.embed_documents(documents)
153

154
print(f"Number of embeddings: {len(doc_embeddings)}")
155
print(f"Each embedding dimension: {len(doc_embeddings[0])}")
156
```
157

158
### Task-Specific Embeddings
159

160
```python
161
# Query embeddings optimized for retrieval
162
query_embeddings = GoogleGenerativeAIEmbeddings(
163
    model="models/gemini-embedding-001",
164
    task_type="retrieval_query"
165
)
166

167
# Document embeddings optimized for retrieval
168
doc_embeddings = GoogleGenerativeAIEmbeddings(
169
    model="models/gemini-embedding-001",
170
    task_type="retrieval_document"
171
)
172

173
# Generate embeddings with task-specific optimization
174
query_vector = query_embeddings.embed_query("Find information about AI")
175
doc_vectors = doc_embeddings.embed_documents([
176
    "AI article content here...",
177
    "Another AI document..."
178
])
179
```
180

181
### Similarity Search
182

183
```python
184
import numpy as np
185
from sklearn.metrics.pairwise import cosine_similarity
186

187
# Initialize embeddings
188
embeddings = GoogleGenerativeAIEmbeddings(
189
    model="models/gemini-embedding-001",
190
    task_type="semantic_similarity"
191
)
192

193
# Documents to search
194
documents = [
195
    "Python is a programming language",
196
    "Machine learning algorithms learn from data",
197
    "Cats are domestic animals",
198
    "Data science involves analyzing large datasets"
199
]
200

201
# Query
202
query = "What is data analysis?"
203

204
# Generate embeddings
205
doc_embeddings = embeddings.embed_documents(documents)
206
query_embedding = embeddings.embed_query(query)
207

208
# Calculate similarities
209
similarities = cosine_similarity(
210
    [query_embedding], 
211
    doc_embeddings
212
)[0]
213

214
# Find most similar document
215
best_match_idx = np.argmax(similarities)
216
print(f"Most similar document: {documents[best_match_idx]}")
217
print(f"Similarity score: {similarities[best_match_idx]:.3f}")
218
```
219

220
### Batch Processing with Custom Sizes
221

222
```python
223
# Large document collection
224
large_doc_collection = [f"Document {i} content..." for i in range(1000)]
225

226
# Process in smaller batches to manage memory and API limits
227
embeddings = GoogleGenerativeAIEmbeddings(
228
    model="models/gemini-embedding-001"
229
)
230

231
# Embed with custom batch size
232
all_embeddings = embeddings.embed_documents(
233
    large_doc_collection,
234
    batch_size=50  # Smaller batches for large collections
235
)
236

237
print(f"Generated {len(all_embeddings)} embeddings")
238
```
239

240
### Clustering Application
241

242
```python
243
from sklearn.cluster import KMeans
244
import numpy as np
245

246
# Prepare embeddings for clustering
247
embeddings = GoogleGenerativeAIEmbeddings(
248
    model="models/gemini-embedding-001",
249
    task_type="clustering"
250
)
251

252
texts = [
253
    "Machine learning and AI research",
254
    "Deep learning neural networks",
255
    "Cooking recipes and food preparation",
256
    "Baking techniques and desserts",
257
    "Space exploration and astronomy",
258
    "Planetary science and cosmology"
259
]
260

261
# Generate embeddings optimized for clustering
262
vectors = embeddings.embed_documents(texts)
263

264
# Perform clustering
265
kmeans = KMeans(n_clusters=3, random_state=42)
266
clusters = kmeans.fit_predict(vectors)
267

268
# Display results
269
for i, (text, cluster) in enumerate(zip(texts, clusters)):
270
    print(f"Cluster {cluster}: {text}")
271
```
272

273
### Async Processing
274

275
```python
276
import asyncio
277

278
async def process_embeddings_async():
279
    embeddings = GoogleGenerativeAIEmbeddings(
280
        model="models/gemini-embedding-001"
281
    )
282
    
283
    # Process query and documents concurrently
284
    query_task = embeddings.aembed_query("What is AI?")
285
    docs_task = embeddings.aembed_documents([
286
        "AI is artificial intelligence",
287
        "Machine learning is part of AI",
288
        "Deep learning uses neural networks"
289
    ])
290
    
291
    # Wait for both to complete
292
    query_vector, doc_vectors = await asyncio.gather(query_task, docs_task)
293
    
294
    print(f"Query embedding: {len(query_vector)} dimensions")
295
    print(f"Document embeddings: {len(doc_vectors)} vectors")
296

297
# Run async example
298
asyncio.run(process_embeddings_async())
299
```
300

301
### Custom Configuration
302

303
```python
304
# Configure with custom client options
305
embeddings = GoogleGenerativeAIEmbeddings(
306
    model="models/gemini-embedding-001",
307
    client_options={
308
        "api_endpoint": "https://generativelanguage.googleapis.com"
309
    },
310
    transport="rest",
311
    request_options={
312
        "timeout": 30
313
    }
314
)
315

316
# Use with custom configuration
317
vectors = embeddings.embed_documents(["Custom configured embedding"])
318
```
319

320
### Integration with Vector Stores
321

322
```python
323
from langchain_community.vectorstores import FAISS
324
from langchain_core.documents import Document
325

326
# Initialize embeddings
327
embeddings = GoogleGenerativeAIEmbeddings(
328
    model="models/gemini-embedding-001",
329
    task_type="retrieval_document"
330
)
331

332
# Create documents
333
docs = [
334
    Document(page_content="AI is transforming technology", metadata={"source": "doc1"}),
335
    Document(page_content="Machine learning enables predictions", metadata={"source": "doc2"}),
336
    Document(page_content="Deep learning uses neural networks", metadata={"source": "doc3"})
337
]
338

339
# Create vector store
340
vector_store = FAISS.from_documents(docs, embeddings)
341

342
# Perform similarity search
343
results = vector_store.similarity_search("What is artificial intelligence?", k=2)
344

345
for result in results:
346
    print(f"Content: {result.page_content}")
347
    print(f"Source: {result.metadata['source']}")
348
```
349

350
### Dimensionality Control
351

352
```python
353
# Control output dimensions (if supported by model)
354
embeddings = GoogleGenerativeAIEmbeddings(
355
    model="models/gemini-embedding-001"
356
)
357

358
# Generate embeddings with specific dimensions
359
vector = embeddings.embed_query(
360
    "Sample text",
361
    output_dimensionality=512  # Request 512-dimensional embeddings
362
)
363

364
print(f"Requested dimensions: 512, Got: {len(vector)}")
365
```
366

367
## Constants and Limits
368

369
```python { .api }
370
_MAX_TOKENS_PER_BATCH = 20000  # Maximum tokens per batch request
371
_DEFAULT_BATCH_SIZE = 100      # Default batch size for document processing
372
```
373

374
The embedding service automatically manages token limits and batch sizes to ensure efficient processing while staying within API constraints.
375

376
## Error Handling
377

378
```python
379
from langchain_google_genai import GoogleGenerativeAIEmbeddings
380

381
try:
382
    embeddings = GoogleGenerativeAIEmbeddings(
383
        model="models/gemini-embedding-001"
384
    )
385
    
386
    vectors = embeddings.embed_documents(["text1", "text2"])
387
    
388
except Exception as e:
389
    if "quota" in str(e).lower() or "rate" in str(e).lower():
390
        print(f"API limit error: {e}")
391
    elif "auth" in str(e).lower():
392
        print(f"Authentication error: {e}")
393
    else:
394
        print(f"Embedding error: {e}")
395
```
396

397
## Best Practices
398

399
1. **Choose appropriate task types** for your use case to get optimized embeddings
400
2. **Use batch processing** for multiple documents to improve efficiency
401
3. **Consider async methods** for high-throughput applications
402
4. **Monitor token usage** when processing large document collections
403
5. **Cache embeddings** when possible to avoid redundant API calls
404
6. **Use appropriate batch sizes** based on your document lengths and API limits