Embedding

1. Overview

The Embedding component (embedding) transforms a text into a numeric vector (embedding), used for semantic search, similarity comparison, and feeding vector databases (like Qdrant). Supports the OpenAI, Google Gemini, and Hugging Face providers.

Use it when the flow needs to generate vector representations of text — for example, before writing a document to a vector database, or to compare the similarity between two texts. Works only as an output action.

2. Prerequisites

• A valid API key for the chosen provider (OpenAI, Gemini, or Hugging Face).
• If a custom/compatible provider is used, that service's base URL.

3. Authentication and Connection

Field	Required	Type	Description	Example
apiKey	Yes	Text	Authentication key for the chosen provider.	An expression that fetches the key from a secure variable
provider	No	Text: openai, gemini, or huggingface	Embedding provider to use. Default value: "openai".	"gemini"
baseUrl	No	Text	Custom base URL for the provider (for compatible or self-hosted endpoints). If not informed, uses the chosen provider's default URL.	"https://my-proxy.example.com/v1"

4. Configuration / Supported Operations

The component has a single operation: generate the embedding of a text.

Field	Required	Type	Description	Example
text	Yes	Text	Text to be transformed into a vector.	"Product description..."
model	No	Text	Embedding model identifier. Each provider has its own default value (e.g., OpenAI uses text-embedding-ada-002).	"text-embedding-3-small"
maxChunkSize	No	Number	Maximum text size (in characters) before automatically splitting into chunks. Default value: 8000.	4000
chunkSize	No	Number	Size of each chunk, when the text is split. Default value: 1000.	800
chunkOverlap	No	Number	Overlap between consecutive chunks. Default value: 200.	100

If the text is smaller than or equal to maxChunkSize, a single embedding is generated. If it's larger, the text is split into chunks and an embedding is generated for each one.

5. Practical Examples

Simple example: generate the embedding of a short product description, using OpenAI.

Input:

{
  "product": { "description": "Running sports shoes, cushioned sole" }
}

Component configuration:

{
  "componentName": "embedding",
  "configurations": {
    "provider": "openai",
    "apiKey": "{$.secrets.openaiApiKey}",
    "text": "{$.body.product.description}"
  }
}

Response:

{
  "provider": "openai:text-embedding-ada-002",
  "textLength": 60,
  "chunked": false,
  "originalText": "Running sports shoes, cushioned sole",
  "embedding": [0.0123, -0.0456, 0.0789],
  "dimensions": 1536
}

Advanced example: generate embeddings for a long document, automatically split into chunks.

Input:

{
  "document": "<long multi-page text>"
}

Component configuration:

{
  "componentName": "embedding",
  "configurations": {
    "provider": "gemini",
    "apiKey": "{$.secrets.geminiApiKey}",
    "text": "{$.body.document}",
    "maxChunkSize": "4000",
    "chunkSize": "800",
    "chunkOverlap": "100"
  }
}

Response (document split into chunks):

{
  "provider": "gemini:gemini-embedding-001",
  "totalChunks": 3,
  "chunkSize": 800,
  "chunkOverlap": 100,
  "originalTextLength": 9500,
  "chunked": true,
  "chunks": [
    { "index": 0, "text": "...", "length": 800, "embedding": [0.01, 0.02], "dimensions": 768 },
    { "index": 1, "text": "...", "length": 800, "embedding": [0.03, 0.04], "dimensions": 768 }
  ]
}

6. Common Errors and Troubleshooting

Error / Symptom	Likely Cause	How to Fix
"API Key is required but has not been configured."	The apiKey field wasn't filled in.	Fill in apiKey with a valid provider key.
"Text is required but has not been configured."	The text field wasn't filled in.	Fill in text with the content to be turned into an embedding.
"Unsupported embedding provider: ..."	The provider value isn't recognized.	Use openai, gemini, or huggingface.
"OpenAI API error: ..." / "Gemini API error: ..." / "HuggingFace API error: ..."	The provider returned an error (invalid key, quota exceeded, nonexistent model).	Review the API key and the configured model name.
"Embedding operation failed: ..."	General failure calling the provider.	Check connectivity and review the provider configuration.