Encoders

Encoders are essential components in Semantic Router that transform text (or other data) into numerical representations that capture semantic meaning. These numerical representations, called embeddings, allow the system to measure semantic similarity between texts, which is the core functionality of the routing process.

Understanding Encoders

In Semantic Router, an encoder serves two primary purposes:

Convert utterances from routes into embeddings during initialization
Convert incoming user queries into embeddings during routing

By comparing these embeddings, Semantic Router can determine which route(s) best match the user’s intent, even when the exact wording differs.

Dense vs. Sparse Encoders

Semantic Router supports two main types of encoders:

Dense Encoders

Dense encoders generate embeddings where every dimension has a value, resulting in a “dense” vector. These encoders typically:

Produce fixed-size vectors (e.g., 1536 dimensions for OpenAI’s text-embedding-3-small)
Capture complex semantic relationships in the text
Perform well on tasks requiring understanding of context and meaning

Example usage:

from semantic_router.encoders import OpenAIEncoder
import os

# Set up API key
os.environ["OPENAI_API_KEY"] = "your-api-key"

# Initialize the encoder
encoder = OpenAIEncoder()

# Generate dense embeddings for documents
embeddings = encoder(["How's the weather today?", "Tell me about politics"])

Sparse Encoders

Sparse encoders generate embeddings where most dimensions are zero, with only a few dimensions having non-zero values. These encoders typically:

Focus on specific words or tokens in the text
Excel at keyword matching and term frequency
Can be more interpretable than dense encoders (non-zero dimensions often correspond to specific words)

Example usage:

from semantic_router.encoders import AurelioSparseEncoder
from semantic_router import Route
import os

# Set up API key
os.environ["AURELIO_API_KEY"] = "your-api-key"

# Create some routes for routing
routes = [
    Route(name="weather", utterances=["How's the weather?", "Is it raining?"]),
    Route(name="politics", utterances=["Tell me about politics", "Who's the president?"])
]

# Initialize the sparse encoder
encoder = AurelioSparseEncoder()

# Generate sparse embeddings for documents
embeddings = encoder(["How's the weather today?", "Tell me about politics"])

Hybrid Approaches

Semantic Router also allows combining both dense and sparse encoders in a hybrid approach through the HybridRouter. This can leverage the strengths of both encoding methods:

from semantic_router.routers import HybridRouter
from semantic_router.encoders import OpenAIEncoder, AurelioSparseEncoder
import os

# Set up API keys
os.environ["OPENAI_API_KEY"] = "your-openai-api-key"
os.environ["AURELIO_API_KEY"] = "your-aurelio-api-key"

# Create dense and sparse encoders
dense_encoder = OpenAIEncoder()
sparse_encoder = AurelioSparseEncoder()

# Initialize the hybrid router
router = HybridRouter(
    encoder=dense_encoder,
    sparse_encoder=sparse_encoder,
    routes=routes,
    alpha=0.5  # Balance between dense (0) and sparse (1) embeddings
)

Supported Encoders

Dense Encoders

Encoder	Description	Installation
OpenAIEncoder	Uses OpenAI’s text embedding models	`pip install -qU semantic-router`
AzureOpenAIEncoder	Uses Azure OpenAI’s text embedding models	`pip install -qU semantic-router`
CohereEncoder	Uses Cohere’s text embedding models	`pip install -qU semantic-router`
HuggingFaceEncoder	Uses local Hugging Face models	`pip install -qU "semantic-router[local]"`
HFEndpointEncoder	Uses Hugging Face Inference API	`pip install -qU semantic-router`
FastEmbedEncoder	Uses FastEmbed for local embeddings	`pip install -qU "semantic-router[local]"`
MistralEncoder	Uses Mistral’s text embedding models	`pip install -qU semantic-router`
GoogleEncoder	Uses Google’s text embedding models	`pip install -qU semantic-router`
BedrockEncoder	Uses AWS Bedrock embedding models	`pip install -qU semantic-router`
VitEncoder	Vision Transformer for image embeddings	`pip install -qU semantic-router`
CLIPEncoder	Uses CLIP for image embeddings	`pip install -qU semantic-router`

Sparse Encoders

Encoder	Description	Installation
BM25Encoder	Implements BM25 algorithm for sparse embeddings	`pip install -qU semantic-router`
TfidfEncoder	Implements TF-IDF for sparse embeddings	`pip install -qU semantic-router`
AurelioSparseEncoder	Uses Aurelio’s API for BM25 sparse embeddings	`pip install -qU semantic-router`
LocalSparseEncoder	Uses local sentence-transformers SPLADE/CSR models for neural sparse embeddings	`pip install -qU "semantic-router[local]"`

Example usage:

from semantic_router.encoders import LocalSparseEncoder

encoder = LocalSparseEncoder(name="naver/splade-v3")
embeddings = encoder(["How's the weather today?", "Tell me about politics"])

This encoder uses sentence-transformers >=v5’s SparseEncoder API to generate high-dimensional sparse vectors (e.g., SPLADE, CSR).
No API key required; all computation is local (CPU, CUDA, or MPS).
You can use any compatible sparse model from the Hugging Face Hub (e.g., naver/splade-v3, mixedbread-ai/mxbai-embed-large-v1, etc.).

Using AutoEncoder

Semantic Router provides an AutoEncoder class that automatically selects the appropriate encoder based on the specified type:

from semantic_router.encoders import AutoEncoder
from semantic_router.schema import EncoderType

# Create an encoder based on type
encoder = AutoEncoder(type=EncoderType.OPENAI.value, name="text-embedding-3-small").model

# Use the encoder
embeddings = encoder(["How can I help you today?"])

Considerations for Choosing an Encoder

When selecting an encoder for your application, consider:

Accuracy: Dense encoders typically provide better semantic understanding but may miss exact keyword matches
Speed: Local encoders are faster but may be less accurate than cloud-based ones
Cost: Cloud-based encoders (OpenAI, Cohere, Aurelio AI) incur API costs
Privacy: Local encoders keep data within your environment
Use case: Hybrid approaches may work best for balanced retrieval

For more detailed information on specific encoders, refer to their respective documentation pages.

Get Started

Client Reference

User Guide

Understanding Encoders

Dense vs. Sparse Encoders

Dense Encoders

Sparse Encoders

Hybrid Approaches

Supported Encoders

Dense Encoders

Sparse Encoders

Using AutoEncoder

Considerations for Choosing an Encoder

​Understanding Encoders

​Dense vs. Sparse Encoders

​Dense Encoders

​Sparse Encoders

​Hybrid Approaches

​Supported Encoders

​Dense Encoders

​Sparse Encoders

​Using AutoEncoder

​Considerations for Choosing an Encoder

Understanding Encoders

Dense vs. Sparse Encoders

Dense Encoders

Sparse Encoders

Hybrid Approaches

Supported Encoders

Dense Encoders

Sparse Encoders

Using AutoEncoder

Considerations for Choosing an Encoder