Indexes

Indexes are critical components in Semantic Router that store and retrieve embeddings efficiently. They act as the search backend that enables Semantic Router to find the most relevant routes for incoming queries.

Understanding Indexes

In Semantic Router, an index serves several key purposes:

Store embeddings of route utterances
Search for similar vectors when routing queries
Persist route configurations across sessions
Scale to handle large numbers of routes and utterances

The choice of index can significantly impact the performance, scalability, and persistence capabilities of your semantic routing system.

Local vs. Remote Indexes

Semantic Router supports both local (in-memory) and remote (cloud-based) indexes:

Local Indexes

Local indexes store embeddings in memory, making them fast but ephemeral. They’re perfect for development, testing, or applications with a small number of routes. Example usage:

from semantic_router.index import LocalIndex
from semantic_router.routers import SemanticRouter
from semantic_router.encoders import OpenAIEncoder
import os

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

# Create routes
from semantic_router import Route
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 local index
index = LocalIndex()

# Create a router with the local index
router = SemanticRouter(
    encoder=OpenAIEncoder(),
    routes=routes,
    index=index
)

# Use the router
result = router("What's the weather like today?")
print(result.name)  # "weather"

Remote Indexes

Remote indexes store embeddings in cloud-based vector databases, making them persistent and scalable. They’re ideal for production applications or systems with many routes. Example usage with Pinecone:

from semantic_router.index import PineconeIndex
from semantic_router.routers import SemanticRouter
from semantic_router.encoders import OpenAIEncoder
import os

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

# Create routes
from semantic_router import Route
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 Pinecone index
index = PineconeIndex(
    index_name="semantic-router",
    dimensions=1536  # Must match your encoder's dimension
)

# Create a router with the Pinecone index
router = SemanticRouter(
    encoder=OpenAIEncoder(),
    routes=routes,
    index=index,
    auto_sync="remote"  # Automatically sync routes to remote index
)

# Use the router
result = router("What's the weather like today?")
print(result.name)  # "weather"

Hybrid Indexes

For advanced use cases, Semantic Router also provides a hybrid index that combines both dense and sparse embeddings:

from semantic_router.index import HybridLocalIndex
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"

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

# Create a hybrid index
index = HybridLocalIndex()

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

Supported Indexes

Index	Description	Installation
LocalIndex	In-memory index for development and testing	`pip install -qU semantic-router`
HybridLocalIndex	In-memory index supporting hybrid search	`pip install -qU "semantic-router[hybrid]"`
PineconeIndex	Pinecone vector database integration	`pip install -qU "semantic-router[pinecone]"`
QdrantIndex	Qdrant vector database integration	`pip install -qU "semantic-router[qdrant]"`
PostgresIndex	PostgreSQL with pgvector extension	`pip install -qU "semantic-router[postgres]"`

Auto-Sync Feature

Semantic Router provides an auto-sync feature that keeps your routes in sync between local and remote indexes:

# Initialize router with auto-sync to remote index
router = SemanticRouter(
    encoder=encoder,
    routes=routes,
    index=remote_index,
    auto_sync="remote"  # Options: "local", "remote", None
)

# Add a new route - it will be automatically synced to the remote index
new_route = Route(name="greetings", utterances=["Hello there", "Hi, how are you?"])
router.add(new_route)

Auto-sync modes:

"local": Sync from remote to local (pull)
"remote": Sync from local to remote (push)
None: No automatic syncing

Considerations for Choosing an Index

When selecting an index for your application, consider:

Persistence: Local indexes are lost when your application restarts; remote indexes persist
Scalability: Remote indexes can handle millions of vectors; local indexes are limited by memory
Latency: Local indexes have lower latency; remote indexes add network overhead
Setup complexity: Local indexes require no setup; remote indexes require account creation and configuration
Cost: Local indexes are free; remote indexes may incur usage costs
Hybrid search: Only certain indexes support combined dense and sparse search

Index Methods

All indexes in Semantic Router inherit from BaseIndex and implement these key methods:

add(): Add embeddings to the index
query(): Search for similar vectors
delete(): Remove routes from the index
describe(): Get information about the index
is_ready(): Check if the index is initialized and ready for use

For detailed information on specific indexes and their configuration options, refer to their respective documentation pages.

Get Started

Client Reference

User Guide

Understanding Indexes

Local vs. Remote Indexes

Local Indexes

Remote Indexes

Hybrid Indexes

Supported Indexes

Auto-Sync Feature

Considerations for Choosing an Index

Index Methods

​Understanding Indexes

​Local vs. Remote Indexes

​Local Indexes

​Remote Indexes

​Hybrid Indexes

​Supported Indexes

​Auto-Sync Feature

​Considerations for Choosing an Index

​Index Methods

Understanding Indexes

Local vs. Remote Indexes

Local Indexes

Remote Indexes

Hybrid Indexes

Supported Indexes

Auto-Sync Feature

Considerations for Choosing an Index

Index Methods