Principle:CrewAIInc CrewAI Embedding Configuration

Metadata

Field	Value
Principle Name	Embedding Configuration
Workflow	Knowledge_RAG_Pipeline
Category	Vector Representation
Repository	crewAIInc/crewAI
Implemented By	Implementation:CrewAIInc_CrewAI_Embedder_Config

Overview

A configuration pattern for selecting and parameterizing text embedding providers that convert document chunks and queries into dense vector representations for semantic search. Embedding Configuration provides a unified interface across 18+ embedding providers, abstracting provider-specific details behind a common configuration structure.

Description

Embedding Configuration handles the selection of the embedding model that will be used to convert text into vectors. The framework supports 18+ embedding providers (OpenAI, Cohere, Ollama, HuggingFace, etc.) through a unified configuration interface. Each provider has specific configuration options (API keys, model names, dimensions). The embedding configuration is shared across knowledge sources, storage, and crew-level settings.

The configuration follows a provider + config pattern: the user specifies a provider name (as a string literal) and a provider-specific configuration dictionary. This approach allows the framework to:

• Validate the configuration at the type level using TypedDicts
• Route to the correct embedding backend at runtime
• Share a single configuration across the entire pipeline (sources, storage, Knowledge, Crew, Agent)

The embedding configuration can be specified at multiple levels:

1. Crew level -- Shared by all agents and knowledge sources in the crew
2. Agent level -- Overrides the crew-level embedder for a specific agent
3. Knowledge level -- Specified directly when constructing a Knowledge object
4. Storage level -- Specified directly on a KnowledgeStorage instance

Theoretical Basis

This principle is grounded in the Vector Space Model where text is mapped to dense vectors in a high-dimensional space. In this model:

• Each text chunk is converted to a fixed-dimensional vector (e.g., 1536 dimensions for OpenAI's text-embedding-ada-002)
• Semantic similarity between texts corresponds to geometric proximity in vector space
• Similarity is measured via cosine distance or dot product
• Queries are embedded using the same model, enabling comparison between query vectors and document vectors

The choice of embedding model significantly impacts retrieval quality. Different providers offer different tradeoffs:

Provider	Tradeoff
OpenAI	High quality, cloud-hosted, per-token pricing
Ollama	Local execution, no API costs, requires local GPU
HuggingFace	Wide model selection, variable quality
Cohere	Strong multilingual support
Sentence-Transformer	Fast local inference, good quality

Configuration Levels

The embedding configuration propagates through the pipeline in the following precedence order (highest to lowest):

1. Storage-level embedder (directly on KnowledgeStorage)
2. Knowledge-level embedder (on the Knowledge object)
3. Agent-level embedder (on a specific Agent)
4. Crew-level embedder (on the Crew object)
5. Default embedder (OpenAI text-embedding-3-small if no configuration is provided)

Usage Context

Embedding Configuration is the second step in the Knowledge RAG Pipeline, following source selection:

1. Select and configure knowledge sources (see Principle:CrewAIInc_CrewAI_Knowledge_Source_Selection)
2. Configure the embedding provider (this principle)
3. Ingest sources into vector storage (see Principle:CrewAIInc_CrewAI_Knowledge_Ingestion)
4. Attach knowledge to a Crew or Agent (see Principle:CrewAIInc_CrewAI_Knowledge_Attachment)
5. Retrieve relevant chunks during task execution (see Principle:CrewAIInc_CrewAI_Semantic_Retrieval)

Design Decisions

• Union type for flexibility -- The EmbedderConfig type accepts either a provider spec dictionary, a provider instance, or a provider class, accommodating different usage patterns.
• 18+ providers -- Broad provider support ensures users are not locked into a single vendor.
• Dictionary-based configuration -- Using dictionaries rather than provider-specific classes keeps the API simple and JSON-serializable.

Example Scenario

A team running an air-gapped deployment needs local embeddings. They configure Ollama as their embedding provider:

embedder_config = {
    "provider": "ollama",
    "config": {
        "model": "nomic-embed-text",
        "url": "http://localhost:11434",
    },
}

# This config is passed to Crew, Agent, or Knowledge

Related Pages

• Implementation:CrewAIInc_CrewAI_Embedder_Config -- Concrete type definitions and provider specs
• Principle:CrewAIInc_CrewAI_Knowledge_Source_Selection -- Previous step: source selection
• Principle:CrewAIInc_CrewAI_Knowledge_Ingestion -- Next step: vector store ingestion