Embeddings

Overview

Embeddings are numerical representations of text that capture semantic meaning. They enable your AI agent to find relevant information based on meaning, not just keyword matching.

How Embeddings Work

┌─────────────────────────────────────────────────────────┐
│                    Text Input                            │
│  "How do I reset my password?"                          │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                  Embedding Model                         │
│  (Transforms text into numerical vector)                │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│              Vector (1536 dimensions)                    │
│  [0.023, -0.041, 0.089, ..., 0.012]                     │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│              Similarity Search                           │
│  Find chunks with similar vectors                        │
└─────────────────────────────────────────────────────────┘

Supported Embedding Models

OpenAI Models

Configuration:

jsonCopy
{
  "embeddings": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "dimensions": 1536
  }
}

Anthropic/Voyage Models

Configuration:

jsonCopy
{
  "embeddings": {
    "provider": "voyage",
    "model": "voyage-large-2",
    "dimensions": 1536
  }
}

Cohere Models

Configuration:

jsonCopy
{
  "embeddings": {
    "provider": "cohere",
    "model": "embed-english-v3.0",
    "dimensions": 1024
  }
}

Local Models (Ollama)

Configuration:

jsonCopy
{
  "embeddings": {
    "provider": "ollama",
    "model": "nomic-embed-text",
    "base_url": "http://localhost:11434",
    "dimensions": 768
  }
}

Model Selection Guide

By Use Case

By Budget

Configuring Embeddings

Via UI

1. Go to Agents → Select agent → Knowledge Base
2. Click Settings → Embedding Model
3. Select provider and model
4. Click Save (existing documents will be re-embedded)

Via API

bashCopy
curl -X PATCH "https://api.arcanflows.com/api/v1/agents/{agent_id}/knowledge/settings" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "embeddings": {
      "provider": "openai",
      "model": "text-embedding-3-small",
      "dimensions": 1536,
      "batch_size": 100
    }
  }'

Vector Storage

Supported Vector Databases

Arcanflows supports multiple vector storage backends:

Default Configuration (pgvector)

jsonCopy
{
  "vector_store": {
    "type": "pgvector",
    "index_type": "ivfflat",
    "lists": 100,
    "probes": 10
  }
}

Index Types

Similarity Search

Distance Metrics

Default: Cosine similarity

Search Configuration

jsonCopy
{
  "search": {
    "metric": "cosine",
    "top_k": 5,
    "score_threshold": 0.7,
    "rerank": true,
    "rerank_model": "cross-encoder"
  }
}

Retrieval Strategies

Basic Similarity Search

pythonCopy
# Pseudocode
results = vector_store.similarity_search(
    query_embedding,
    k=5,
    threshold=0.7
)

Hybrid Search (Vector + Keyword)

Combines semantic and keyword search:

jsonCopy
{
  "search": {
    "type": "hybrid",
    "vector_weight": 0.7,
    "keyword_weight": 0.3,
    "keyword_method": "bm25"
  }
}

Benefits:

• Better for exact matches (names, codes)
• Handles both semantic and keyword queries
• More robust retrieval

Reranking

Apply a second-stage model to improve results:

jsonCopy
{
  "search": {
    "rerank": true,
    "rerank_model": "cohere-rerank-english-v2.0",
    "rerank_top_n": 10,
    "final_top_k": 3
  }
}

How it works:

1. Retrieve top 10 candidates via vector search
2. Rerank using cross-encoder model
3. Return top 3 reranked results

Maximal Marginal Relevance (MMR)

Diversifies results to reduce redundancy:

jsonCopy
{
  "search": {
    "type": "mmr",
    "lambda": 0.5,
    "fetch_k": 20,
    "final_k": 5
  }
}

Embedding Best Practices

1. Consistent Models

Use the same embedding model for documents and queries:

Documents: text-embedding-3-small → vectors
Queries: text-embedding-3-small → vectors  ✓

Documents: text-embedding-3-small → vectors
Queries: text-embedding-ada-002 → vectors  ✗

2. Preprocessing

Clean text before embedding:

pythonCopy
def preprocess(text):
    # Remove extra whitespace
    text = ' '.join(text.split())
    # Remove special characters (optional)
    text = text.replace('\n', ' ')
    # Truncate to model max length
    text = text[:8000]
    return text

3. Query Enhancement

Improve query embeddings:

jsonCopy
{
  "query_enhancement": {
    "expand_query": true,
    "add_context": true,
    "hypothetical_answer": false
  }
}

HyDE (Hypothetical Document Embedding):

1. Generate hypothetical answer to query
2. Embed the hypothetical answer
3. Search for similar real documents

4. Monitoring

Track embedding performance:

API Reference

Generate Embedding

bashCopy
curl -X POST "https://api.arcanflows.com/api/v1/embeddings" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "How do I reset my password?",
    "model": "text-embedding-3-small"
  }'

Response:

jsonCopy
{
  "embedding": [0.023, -0.041, 0.089, ...],
  "dimensions": 1536,
  "tokens_used": 8
}

Search Knowledge Base

bashCopy
curl -X POST "https://api.arcanflows.com/api/v1/agents/{agent_id}/knowledge/search" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "password reset process",
    "top_k": 5,
    "threshold": 0.7,
    "include_metadata": true
  }'

Troubleshooting

Low similarity scores

• Check embedding model consistency
• Improve chunk quality
• Try hybrid search

Irrelevant results

• Lower score threshold
• Enable reranking
• Add keyword search component

Slow search

• Add vector index (HNSW)
• Reduce top_k
• Optimize chunk sizes

High costs

• Switch to smaller embedding model
• Batch embedding requests
• Use local models for development