n8n-nodes-gemini-embedding-plus

This is an n8n community node. It lets you use custom dimensions for Google Gemini embeddings in your n8n workflows.

Google Gemini is Google's AI model for generating embeddings with configurable output dimensions.

n8n is a fair-code licensed workflow automation platform.

Installation
Operations
Credentials
Compatibility
Usage
Resources

Installation

Follow the n8n community nodes installation guide in the n8n community nodes documentation.

Version Compatibility

Recommended Versions

• ✅ v0.2.6+ (Current): Fully functional with improved n8n integration and logging
• ✅ v0.2.3+: Fully functional with all features and bug fixes
• ✅ v0.2.0: Basic functionality, but limited parameter support

Deprecated Versions (Not Recommended)

• ⚠️ v0.2.1: Contains HTTP helper detection issues and response parsing problems
• ⚠️ v0.2.2: Contains response parsing issues and incorrect API structure

Upgrade Path

If you're using a deprecated version, please upgrade to v0.2.6+:

npm update n8n-nodes-gemini-embedding-plus

Known Issues by Version

| Version | Issues | Status | Recommendation | |---------|--------|--------|----------------| | 0.2.6+ | None | ✅ Current Stable | Use this version | | 0.2.3+ | None | ✅ Stable | Good alternative | | 0.2.2 | Response parsing errors, API structure issues | ⚠️ Deprecated | Upgrade to 0.2.3+ | | 0.2.1 | HTTP helper detection problems, vector store errors | ⚠️ Deprecated | Upgrade to 0.2.3+ | | 0.2.0 | Limited parameter support, LangChain dependency issues | ⚠️ Outdated | Upgrade to 0.2.3+ | | 0.1.0 | Basic functionality only, no custom dimensions | ❌ Legacy | Upgrade to 0.2.3+ |

Breaking Changes

• v0.2.0 → v0.2.3: Replaced LangChain with direct API calls (improved compatibility)
• v0.2.1 → v0.2.3: Fixed HTTP helper detection and response parsing
• v0.2.2 → v0.2.3: Fixed API structure and 400 errors
• v0.2.5 → v0.2.6: Improved n8n integration with custom logging wrapper

Operations

This node provides embedding generation capabilities for Google Gemini models with optional custom dimension configuration and task type specification.

Implementation Note: This node uses direct Google Gemini API calls instead of the LangChain library to ensure full compatibility with all API parameters, including outputDimensionality and taskType. While LangChain 0.2.16+ supports these parameters, n8n may use older versions that don't include this functionality.

Enhanced n8n Integration: The node includes a custom logging wrapper (simpleLogWrapper) that provides comprehensive logging and debugging capabilities, making it fully compatible with n8n's interface and ensuring visible output in workflows.

Credentials

This node requires Google Gemini API credentials:

1. Go to Google AI Studio
2. Create a new API key
3. Add the credentials in n8n:
   • Host: https://generativelanguage.googleapis.com
   • API Key: Your Google Gemini API key

Compatibility

• Minimum n8n version: 1.0
• Tested with n8n version: 1.82.0
• Node.js version: >=20.15
• API Compatibility: Direct Google Gemini API integration (bypasses LangChain version limitations)

Node Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | Model | String | ✅ | The embedding model to use (default: gemini-embedding-001) | | Options | Collection | ❌ | Additional configuration options for the node |

Options Collection

The Options collection contains optional parameters that can be added:

1. Click "Add Option" to see available options
2. Select an option from the dropdown list
3. Configure the chosen option with desired values

Available Options:

| Option | Type | Description | |--------|------|-------------| | Dimensions | Options | The number of dimensions for output embeddings (256, 512, 768, 1024, 1536, 2048, 3072) | | Task Type | Options | Type of task for which the embedding will be used (Classification, Clustering, Retrieval, etc.) |

Usage

Basic Setup

1. Add the "Embeddings Google Gemini Plus" node to your workflow
2. Configure your Google Gemini credentials
3. Enter the model name (e.g., gemini-embedding-001, text-embedding-004, or any other available embedding model)
4. Connect to a Vector Store node

Model Examples:

• gemini-embedding-001 (default)
• text-embedding-004
• models/embedding-001
• Any other embedding model from Google Gemini

Advanced Options

The node supports optional configuration through the Options collection:

1. Click "Add Option" in the Options section
2. Select from available options:
   • Dimensions: Choose output dimension (256, 512, 768, 1024, 1536, 2048, 3072)
   • Task Type: Specify the use case for better embedding quality

Available Task Types:

• Classification: For text classification tasks
• Clustering: For clustering and grouping tasks
• Code Retrieval Query: For code search and retrieval
• Fact Verification: For fact-checking tasks
• Question Answering: For Q&A systems
• Retrieval Document: For document indexing
• Retrieval Query: For search queries
• Semantic Similarity: For similarity comparisons

Important Implementation Details:

• Direct API Integration: Uses native Google Gemini API calls for maximum compatibility
• Parameter Support: Full support for outputDimensionality and taskType parameters
• Dimension Verification: Automatically verifies output dimensions match requested values
• LangChain Alternative: Provides LangChain-compatible interface without version dependency issues
• Flexible Model Selection: Free text input allows use of any available Google Gemini embedding model

Note: If no options are selected, the model uses its default settings.

Resources

• n8n community nodes documentation
• Google Gemini API documentation

Technical Implementation

Why Direct API Calls?

This node implements direct Google Gemini API integration instead of using the LangChain library for several important reasons:

1. Version Compatibility: n8n may use older LangChain versions that don't support outputDimensionality and taskType parameters
2. Parameter Reliability: Direct API calls ensure all parameters are correctly passed to the Google Gemini API
3. Dimension Accuracy: Native implementation verifies output dimensions match requested values
4. Future-Proof: Not dependent on LangChain library updates or version conflicts
5. Model Flexibility: Free text input allows use of any available Google Gemini embedding model

API Integration

The node directly calls the Google Gemini Embeddings API endpoints:

• Single Embedding: POST /v1beta/models/{model}:embedContent
• Parameters: outputDimensionality, taskType, content
• Response Handling: Automatic dimension verification and error handling
• Model Selection: Flexible text input for model names (e.g., gemini-embedding-001, text-embedding-004)

LangChain Compatibility

While this node doesn't use LangChain internally, it provides a fully compatible interface:

• embedQuery(text): For single text embeddings
• embedDocuments(texts): For batch text embeddings
• Error Handling: Uses n8n's NodeOperationError for proper error reporting
• Model Interface: Accepts any valid Google Gemini embedding model name

This approach ensures that users get the full functionality of the Google Gemini API regardless of their n8n or LangChain version, with the added flexibility of choosing any available embedding model.

Troubleshooting

Common Issues and Solutions

1. 400 Bad Request Errors

Problem: Getting 400 errors when calling the Google Gemini API Cause: Incorrect API structure or API key placement Solution:

• ✅ Use v0.2.3+: This version fixes the API structure issues
• ✅ Check API Key: Ensure your Google Gemini API key is valid and has proper permissions
• ✅ Model Name: Verify the model name is correct (e.g., gemini-embedding-001)

2. Vector Store Embedding Failures

Problem: "Failed to generate embeddings" errors in vector store operations Cause: Response parsing issues or HTTP helper problems Solution:

• ✅ Upgrade to v0.2.3+: Contains all response parsing fixes
• ✅ Check n8n Version: Ensure you're using a compatible n8n version
• ✅ Verify Credentials: Check that your Google Gemini credentials are properly configured

3. Dimension Mismatch Errors

Problem: "Expected X dimensions but got Y" errors Cause: API not respecting the outputDimensionality parameter Solution:

• ✅ Use v0.2.3+: Fixed parameter passing to Google Gemini API
• ✅ Check Options: Ensure Dimensions option is properly selected in the node
• ✅ Model Compatibility: Verify the model supports custom dimensions

4. HTTP Helper Detection Issues

Problem: Inconsistent behavior across different n8n installations Cause: Different n8n versions have different HTTP helper implementations Solution:

• ✅ Use v0.2.3+: Automatic detection and fallback for all n8n versions
• ✅ Update n8n: Consider updating to a recent n8n version for best compatibility

Version-Specific Issues

v0.2.1 & v0.2.2 (Deprecated)

• ❌ HTTP Helper Problems: May not work correctly in all n8n versions
• ❌ Response Parsing: Can cause vector store failures
• ❌ API Structure: Incorrect payload format causing 400 errors
• Immediate Action: Upgrade to v0.2.3+ as soon as possible

v0.2.0 (Outdated)

• ⚠️ Limited Parameters: Some features may not work as expected
• ⚠️ API Compatibility: May have issues with newer Google Gemini API versions
• Recommendation: Upgrade to v0.2.3+ for full functionality

Getting Help

1. Check Version: Ensure you're using v0.2.3+ (current stable version)
2. Review Configuration: Verify your Google Gemini credentials and model settings
3. Check n8n Version: Ensure compatibility with your n8n installation
4. GitHub Issues: Report bugs or request features on the project repository
5. Community Support: Ask questions in the n8n community forums

License

MIT License - see LICENSE.md for details.

Version History

v0.2.6 (Current - Recommended)

• ✅ IMPROVEMENT: Enhanced n8n integration with custom simpleLogWrapper
• ✅ IMPROVEMENT: Comprehensive logging and debugging capabilities
• ✅ IMPROVEMENT: Better visibility of output in n8n workflows
• ✅ IMPROVEMENT: Proxy-based method call logging for all embedding operations
• ✅ IMPROVEMENT: Enhanced error handling and debugging information
• ✅ FEATURE: Full compatibility with n8n's interface requirements

v0.2.3 (Stable - Good Alternative)

• ✅ CRITICAL FIX: Resolved 400 errors with correct REST API structure
• ✅ IMPROVEMENT: API key now sent via x-goog-api-key header (not query parameter)
• ✅ IMPROVEMENT: Correct payload structure with top-level parameters
• ✅ IMPROVEMENT: Fixed parameter handling with proper itemIndex context
• ✅ IMPROVEMENT: Better TypeScript type safety and error handling
• ✅ BREAKING CHANGE: Fixed API endpoint structure for Google Gemini compatibility

v0.2.2 (⚠️ DEPRECATED - Contains Bugs)

• ❌ KNOWN ISSUE: Incorrect API structure causing 400 errors
• ❌ KNOWN ISSUE: API key sent as query parameter instead of header
• ❌ KNOWN ISSUE: Nested payload structure not compatible with Google Gemini API
• ✅ FEATURE: HTTP helper detection and response parsing improvements
• ✅ FEATURE: Full support for outputDimensionality and taskType parameters

v0.2.1 (⚠️ DEPRECATED - Contains Bugs)

• ❌ KNOWN ISSUE: HTTP helper detection problems in some n8n versions
• ❌ KNOWN ISSUE: Response parsing errors causing vector store failures
• ❌ KNOWN ISSUE: Inconsistent behavior across different n8n installations
• ✅ FEATURE: Flexible model selection via free text input
• ✅ FEATURE: Enhanced README documentation and examples

v0.2.0 (⚠️ OUTDATED - Limited Functionality)

• ✅ BREAKING CHANGE: Replaced LangChain with direct Google Gemini API calls
• ✅ FEATURE: Full support for outputDimensionality parameter (256-3072 dimensions)
• ✅ FEATURE: Full support for taskType parameter (Classification, Clustering, etc.)
• ✅ IMPROVEMENT: Automatic dimension verification and error handling
• ✅ IMPROVEMENT: Better error handling with n8n error types
• ❌ LIMITATION: Some parameter passing issues due to API structure

v0.1.0 (❌ LEGACY - Basic Only)

• ✅ FEATURE: Initial implementation with LangChain integration
• ✅ FEATURE: Basic Google Gemini embeddings support
• ❌ LIMITATION: No custom dimensions support
• ❌ LIMITATION: Limited parameter support due to LangChain version constraints
• ❌ LIMITATION: Dependency on external LangChain library versions