Google Embedding Node
The Google Embedding node converts text content into numerical vector representations using Google Generative AI models, with task-specific optimizations for search, similarity, classification, and clustering. It supports multiple transport protocols (REST, gRPC, async gRPC) for different performance requirements. Task-aware optimization produces higher quality embeddings compared to generic, unoptimized vectors.
How It Works
When the node executes, it receives text input from a workflow variable, sends the text to Google's API with the specified task type, and returns embedding vectors as arrays of floating-point numbers. Each text input produces one embedding vector, with dimensionality determined by the selected model (e.g., models/embedding-001 produces 768-dimensional vectors). The node validates text content, constructs API requests with authentication and task type parameters, calls the Google endpoint, and stores the resulting vectors in the output variable.
The node supports task-specific optimization through the Task Type parameter, which tells Google's models how the embeddings will be used. For example, retrieval_query optimizes embeddings for search queries, while retrieval_document optimizes for documents being searched, ensuring better matching between queries and documents. Semantic similarity optimization produces embeddings that work well for comparing text similarity, while classification and clustering optimizations tune vectors for those specific machine learning tasks.
Authentication is handled through API keys, with support for custom API endpoints and multiple transport protocols. The node supports REST (standard HTTP), gRPC (high-performance binary protocol), and gRPC async (asynchronous gRPC) for different performance and compatibility requirements. Output embeddings maintain correlation with input items through unique identifiers. Failed embedding generation for individual items does not stop processing of other items.
Configuration Parameters
Input Field
Input Field (Text, Required): Workflow variable containing text to embed.
The node expects a list of embedding request objects where each object contains a type field (set to "text"), an optional id field (string for tracking), and a text field (string content to embed). Single objects are automatically converted to single-item lists.
Example input structure:
[
{"type": "text", "id": "query1", "text": "What is machine learning?"},
{"type": "text", "id": "doc1", "text": "Machine learning is a subset of artificial intelligence..."}
]
Output Field
Output Field (Text, Required): Workflow variable where embedding results are stored.
The output is a list of EmbeddingResponse objects where each object contains a uuid field (string identifier matching input ID or generated UUID) and an embeddings field (array of floating-point numbers). The list maintains the same order as the input. Empty embeddings are returned for failed generation attempts.
Example output structure:
[
{"uuid": "query1", "embeddings": [0.123, -0.456, 0.789, ...]},
{"uuid": "doc1", "embeddings": [0.234, -0.567, 0.890, ...]}
]
Common naming patterns: text_embeddings, document_vectors, query_embeddings, semantic_vectors.
Model
Model (Text, Required): Google Generative AI model identifier for embedding generation.
Common models include models/embedding-001 (768 dimensions) and models/text-embedding-004. The model identifier determines embedding dimensionality and semantic capabilities. Variable interpolation using ${variable_name} syntax is supported.
Google API key
Google API Key (Text, Required): API key for authentication with Google Generative AI services.
Obtain keys from Google Cloud Console. Variable interpolation with ${variable_name} syntax enables secure credential management. API keys typically start with AIza prefix.
Task Type
Task Type (Dropdown, Default: task_type_unspecified): Optimization type for embeddings.
| Task type | Optimization | Best For |
|---|---|---|
| task_type_unspecified | General-purpose embeddings | Unknown task or mixed use cases |
| retrieval_query | Optimized for search queries | User search queries, questions to match against documents |
| retrieval_document | Optimized for searchable documents | Documents, articles, knowledge base content to be searched |
| semantic_similarity | Optimized for similarity comparison | Comparing texts, duplicate detection, clustering by meaning |
| classification | Optimized for classification tasks | Text categorization, labeling, supervised learning |
| clustering | Optimized for clustering tasks | Grouping similar texts, unsupervised learning, topic modeling |
For search systems, retrieval_query for queries and retrieval_document for documents maximizes matching accuracy.
Base URL
Base URL (Text, Optional): Custom API endpoint for Google Generative AI services.
Leave empty to use the default Google endpoint (https://generativelanguage.googleapis.com). Supports routing requests through proxy servers or regional endpoints. Variable interpolation is supported.
Transport
Transport (Dropdown, Default: rest): API communication protocol.
- rest - Standard HTTP/REST protocol, widely compatible and easy to debug
- grpc - High-performance binary protocol with lower latency and better throughput
- grpc_asyncio - Asynchronous gRPC for concurrent request handling and improved scalability
REST provides simplicity and compatibility; gRPC provides performance for critical applications; gRPC async supports high-concurrency workflows.
Common Parameters
This node supports common parameters shared across workflow nodes, including Stream Output Response, Streaming Messages, and Logging Mode. For detailed information, see Common Parameters.
Best Practices
- Store API keys in workflow variables rather than hardcoding, enabling secure credential management
- For search systems, retrieval_query task type for user queries and retrieval_document for indexed documents significantly improves search relevance
- Descriptive output variable names like
query_embeddingsordocument_vectorsdistinguish different embedding purposes - gRPC or gRPC async transport improves performance when generating thousands of embeddings
- Implement error handling using conditional nodes to check for empty embeddings arrays
- Monitor API quota usage when processing large volumes, as embedding generation consumes Google Cloud API quota
Limitations
- Text-only support: The node only supports text embeddings. Image embedding requests fail even though the node accepts multimodal input format.
- No retry logic: Failed API requests are not automatically retried. Network errors, authentication failures, or API errors result in empty embeddings.
- No timeout configuration: The node does not expose timeout parameters. Long-running embedding requests may hang if the API is slow.
- No continue on fail: The node is excluded from the Continue on Fail common parameter. Errors during execution stop the workflow unless handled by conditional logic.
- API rate limits: Subject to Google Cloud API rate limits and quotas. High-volume embedding generation may be throttled.
- Model availability: Not all Google models support all task types. Check Google's documentation for model-specific task type support.