Embedders

Embedders convert text into vectors (lists of numbers) that capture meaning. These vectors enable semantic search, so "How do I reset my passcode?" finds documents mentioning "change PIN" even without keyword matches.

The examples use a running PgVector database, a db_url connection string, and OPENAI_API_KEY. Follow the PgVector setup first; supply your own documents/ directory for ingestion.

from agno.knowledge.knowledge import Knowledge
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.vectordb.pgvector import PgVector

knowledge = Knowledge(
    vector_db=PgVector(
        table_name="docs",
        db_url=db_url,
        embedder=OpenAIEmbedder(),  # Default
    ),
)

How It Works

1. Insert: When you add content, each chunk is converted to a vector
2. Store: Vectors are saved in your vector database
3. Search: Queries are embedded and matched against stored vectors by similarity

Agno uses OpenAIEmbedder by default, but you can swap in any supported embedder.

Configuration

from agno.knowledge.embedder.openai import OpenAIEmbedder

embedder = OpenAIEmbedder(
    id="text-embedding-3-small",
    dimensions=1536,
)

Using with Knowledge

from agno.knowledge.knowledge import Knowledge
from agno.vectordb.pgvector import PgVector

knowledge = Knowledge(
    vector_db=PgVector(
        table_name="docs",
        db_url=db_url,
        embedder=OpenAIEmbedder(id="text-embedding-3-small"),
    ),
)

# Content is embedded automatically on insert
knowledge.insert(path="documents/")

Batch Embeddings

Batch-capable embedders can send multiple texts per request. Whether ingestion uses that interface depends on the vector database and ingestion method. Setting enable_batch=True alone does not make synchronous insertion batch its requests.

For example, PgVector uses this interface during asynchronous insertion:

embedder = OpenAIEmbedder(
    id="text-embedding-3-small",
    dimensions=1536,
    enable_batch=True,
    batch_size=100,
)

knowledge = Knowledge(
    vector_db=PgVector(table_name="batched_docs", db_url=db_url, embedder=embedder),
)

async def main():
    await knowledge.ainsert(path="documents/")

# In a Python script:
import asyncio
asyncio.run(main())

Agno provides a batch interface for OpenAI, Azure OpenAI, Gemini, Cohere, Voyage AI, Mistral, Fireworks, Together, Jina, Nebius, LangDB, and vLLM. Provider and mode behavior differs: local vLLM currently loops over individual embedding calls. Confirm that your ingestion path consumes the batch interface, then measure its effect on request count and latency.

Best Practices

Supported Embedders

Choosing an Embedder

Compare candidates on your own content and queries:

• Retrieval quality: Evaluate relevant-document recall across the languages and domains you need.
• Deployment: Local models require suitable hardware and model downloads; hosted models require credentials and an available endpoint.
• Latency and cost: Measure your workload and check current provider pricing. Local execution still has compute and operational costs.
• Dimensions: Match the database's vector size and re-embed into a new compatible collection when changing models.

Next Steps