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:

1. Convert utterances from routes into embeddings during initialization
2. 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

​

Sparse Encoders

​

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:

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

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