n8n Custom Embedding Nodes

n8n Custom Embedding Nodes - a collection of custom nodes for n8n that generate text embeddings using your own API service.

✨ Features

• 🚀 Two Node Types:
  • Custom Embedding (Sub-node) - embedding provider for AI models and Vector Store nodes
  • Custom Embedding (Standalone) - standalone node for direct embedding generation in workflows
• 🔌 Custom API Integration - use your own embedding service
• 📊 Two Endpoints:
  • /embed - generate embeddings for texts
  • /similarity - calculate similarity between two texts
• 🎯 Support for Various Task Types (classification, clustering, search_query, search_document, default)
• ⚙️ Configurable Host and Port through Credentials
• 📝 Logging and Error Handling
• 🎨 Modern UI with conditional parameter display

🎯 Node Types

1. Custom Embedding (Sub-node)

• Purpose: Used as embedding provider for AI models and Vector Store nodes
• Type: embedding (special type for n8n AI integration)
• Inputs: None (sub-node)
• Outputs: ai_embedding (for AI integration)
• Method: supplyData() - provides embedding functionality to parent nodes

2. Custom Embedding (Standalone)

• Purpose: Used as standalone node in workflows for direct embedding generation
• Type: Regular n8n node
• Inputs: main (standard input)
• Outputs: main (standard output with embedding data)
• Method: execute() - processes input data and returns embeddings

🚀 Installation

For n8n 1.0+

1. Install the package:

   npm install n8n-nodes-custom-embedding

2. Restart n8n

3. Configure Credentials (see Credentials section below)

For Development

1. Clone the repository:

   git clone https://github.com/24auru/n8n-nodes-custom-embedding.git
   cd n8n-nodes-custom-embedding

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

🔑 Credentials

EmbeddingApi

Configure connection to your API service:

• Host (required) - address of your API server (default: http://10.24.10.153)
• Port (required) - port of API server (default: 8081)
• API Key (optional) - key for authentication

📋 Node Parameters

Custom Embedding (Sub-node)

This node has no configurable parameters as it's designed to work as an embedding provider for other nodes.

Custom Embedding (Standalone)

• Input Type - input type:

  • Single Text - single text
  • Multiple Texts - multiple texts (separated by newlines)

• Text - text for embedding generation (only for Single Text)

• Texts - texts for embedding generation (only for Multiple Texts)

• Endpoint - API endpoint:

  • embed - generate embeddings
  • similarity - calculate similarity

• Task Type - task type:

  • classification - for symmetric tasks (STS, NLI, Bitext Mining)
  • clustering - for thematic tasks (classification, headline search)
  • search_query - for search queries
  • search_document - for search documents
  • default - without prefix

💡 Usage Examples

Example 1: Using Custom Embedding (Standalone) Node

{
  "inputType": "single",
  "text": "Hello, world!",
  "endpoint": "embed",
  "task": "classification"
}

Example 2: Using Custom Embedding (Sub-node) with Vector Store

1. Add a Vector Store node (e.g., Supabase Vector Store)
2. In the Vector Store node, look for Embedding connection
3. Select Custom Embedding from the dropdown
4. Configure your credentials
5. The Vector Store will automatically use your custom embedding service

Example 3: Multiple Texts Processing

{
  "inputType": "multiple",
  "texts": "First document\nSecond document\nThird document",
  "endpoint": "embed",
  "task": "clustering"
}

Example 4: Similarity Calculation

{
  "inputType": "multiple",
  "texts": "First text\nSecond text",
  "endpoint": "similarity",
  "task": "classification"
}

🏗️ Project Structure

n8n-nodes-custom-embedding/
├── nodes/
│   ├── Embedding/                    # Embedding sub-node
│   │   ├── Embedding.node.ts        # Sub-node implementation
│   │   └── embedding.svg            # Node icon
│   └── StandaloneEmbedding/         # Standalone embedding node
│       ├── StandaloneEmbedding.node.ts  # Standalone node implementation
│       └── embedding.svg            # Node icon (shared)
├── credentials/
│   └── EmbeddingApi.credentials.ts  # API credentials
├── dist/                            # Compiled JavaScript files
├── examples/                        # Usage examples
├── package.json                     # Project configuration
├── tsconfig.json                    # TypeScript configuration
└── README.md                        # This file

🔧 Development

Building the Project

# Install dependencies
npm install

# Build the project
npm run build

# Build with icon copying
npm run build

Project Architecture

The project contains two separate nodes:

1. Embedding Node (nodes/Embedding/)

   • Implements INodeType interface
   • Has type: 'embedding' getter for AI integration
   • Uses supplyData() method for sub-node functionality
   • No configurable parameters (works as provider)

2. StandaloneEmbedding Node (nodes/StandaloneEmbedding/)

   • Implements INodeType interface
   • Standard n8n node with execute() method
   • Full parameter configuration
   • Processes input data and returns embeddings

Both nodes share the same underlying embedding logic and API integration.

API Endpoints

POST /embed

Generates embeddings for one or more texts.

Request Body:

{
  "texts": ["text 1", "text 2"],
  "task": "classification"
}

Response:

{
  "embeddings": [[0.1, 0.2, ...], [0.3, 0.4, ...]],
  "model": "sentence-transformers",
  "task": "classification"
}

POST /similarity

Calculates similarity between two texts.

Request Body:

{
  "texts": ["text 1", "text 2"],
  "task": "classification"
}

Response:

{
  "similarity": 0.85,
  "text1": "text 1",
  "text2": "text 2",
  "task": "classification"
}

Task Types

| Type | Description | Application | |------|-------------|-------------| | classification | Symmetric tasks | STS, NLI, Bitext Mining | | clustering | Thematic tasks | Classification, headline search | | search_query | Search queries | Query-based search | | search_document | Search documents | Document-based search | | default | Without prefix | General tasks |

🧪 Testing

API Testing

1. Check API availability:

   curl -X GET http://10.24.10.153:8081/health

2. Test embedding generation:

   curl -X POST http://10.24.10.153:8081/embed \
     -H "Content-Type: application/json" \
     -d '{"texts": ["test"], "task": "classification"}'

3. Test similarity calculation:

   curl -X POST http://10.24.10.153:8081/similarity \
     -H "Content-Type: application/json" \
     -d '{"texts": ["hello", "hi"], "task": "classification"}'

Testing in n8n

1. Create a new workflow
2. Add "Custom Embedding" node
3. Configure Credentials
4. Test with simple text

🔧 Troubleshooting

Common Issues

1. "Host and port are required"

   • Check Credentials settings
   • Ensure Host and Port are specified

2. "Connection refused"

   • Check API server availability
   • Ensure port is open

3. "Invalid response from API"

   • Check API response format
   • Ensure API returns correct structure

Logs

Enable logging in n8n for debugging:

n8n start --log-level debug

Useful Links

• n8n 1.0 Migration Guide
• Custom Nodes Documentation
• README_local.md - Local API documentation
• INSTALL.md - Detailed installation instructions

🤝 Contributing

We welcome contributions to the project! Please:

1. Fork the repository
2. Create a branch for new feature
3. Make changes
4. Create Pull Request

📄 License

MIT License - see LICENSE file for details.

‍ Author

24auru - GitHub

Version: 0.1.2
Last Updated: January 2024