Implementation:Run llama Llama index Settings Embed Model Assignment

Overview

The Settings.embed_model property provides the mechanism for integrating finetuned (or any) embedding models into LlamaIndex. It is a getter/setter property on the global _Settings singleton that manages the default embedding model used across all LlamaIndex components. The setter accepts both BaseEmbedding instances and string identifiers, resolving them through resolve_embed_model().

Source Location

Property	Value
File	llama-index-core/llama_index/core/settings.py
Lines	60-74
Class	_Settings (instantiated as singleton Settings)
Property	embed_model (getter and setter)
Import	from llama_index.core import Settings

Property Definition

@property
def embed_model(self) -> BaseEmbedding:
    """Get the embedding model."""
    if self._embed_model is None:
        self._embed_model = resolve_embed_model("default")

    if self._callback_manager is not None:
        self._embed_model.callback_manager = self._callback_manager

    return self._embed_model

@embed_model.setter
def embed_model(self, embed_model: EmbedType) -> None:
    """Set the embedding model."""
    self._embed_model = resolve_embed_model(embed_model)

Type Definitions

Type	Definition	Description
EmbedType	Union[BaseEmbedding, str]	Accepted types for the embed_model setter
BaseEmbedding	Abstract base class	Standard embedding interface in LlamaIndex
Return type (getter)	BaseEmbedding	Always returns a resolved BaseEmbedding instance

Getter Behavior

The getter implements lazy initialization with callback manager injection:

1. Lazy default -- If self._embed_model is None, calls resolve_embed_model("default") to load the default embedding model
2. Callback injection -- If a global callback_manager is set on Settings, it is attached to the embedding model for event tracking
3. Return -- Returns the BaseEmbedding instance

Setter Behavior

The setter resolves the input to a BaseEmbedding instance:

1. Accepts EmbedType -- Can receive either a BaseEmbedding object or a string identifier
2. Resolution -- Calls resolve_embed_model(embed_model) which:
   • If the input is already a BaseEmbedding, returns it directly
   • If the input is a string with "local:" prefix, loads a local Sentence Transformer model
   • If the input is "default", loads the default embedding model
   • If the input is another string, interprets it as a HuggingFace model identifier
3. Storage -- Stores the resolved model in self._embed_model

The _Settings Singleton

The Settings object is a module-level singleton:

@dataclass
class _Settings:
    """Settings for the Llama Index, lazily initialized."""
    _embed_model: Optional[BaseEmbedding] = None
    # ... other settings ...

# Singleton
Settings = _Settings()

Key characteristics:

• Dataclass -- Uses Python @dataclass decorator for clean field definition
• Optional fields -- All fields default to None for lazy initialization
• Module-level instantiation -- Settings = _Settings() creates the single instance at import time

Usage Example: Finetuned Model Integration

from llama_index.core import Settings, VectorStoreIndex, SimpleDirectoryReader
from llama_index.finetuning import (
    SentenceTransformersFinetuneEngine,
    EmbeddingQAFinetuneDataset,
)

# Load and finetune
train_dataset = EmbeddingQAFinetuneDataset.from_json("train_dataset.json")
engine = SentenceTransformersFinetuneEngine(
    dataset=train_dataset,
    model_id="BAAI/bge-small-en",
    model_output_path="finetuned_model",
)
engine.finetune()

# Get the finetuned model (returns BaseEmbedding)
ft_embed = engine.get_finetuned_model()

# Assign to global Settings
Settings.embed_model = ft_embed

# All subsequent LlamaIndex operations use the finetuned embedding
documents = SimpleDirectoryReader("data/").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
response = query_engine.query("What is the main topic?")

Usage Example: String-Based Assignment

from llama_index.core import Settings

# Assign by string identifier (loads local finetuned model)
Settings.embed_model = "local:finetuned_model"

# Assign by HuggingFace identifier
Settings.embed_model = "BAAI/bge-small-en"

Related Settings Properties

The _Settings class follows the same pattern for other configurable components:

Property	Type	Description
llm	LLM	The default language model
embed_model	BaseEmbedding	The default embedding model (this property)
node_parser	NodeParser	The default node parser for document chunking
callback_manager	CallbackManager	Global callback manager for event tracking
transformations	List[TransformComponent]	Default ingestion pipeline transformations

Dependencies

• llama_index.core.embeddings.utils.resolve_embed_model -- Resolves string or BaseEmbedding input to a BaseEmbedding instance
• llama_index.core.embeddings.utils.EmbedType -- Type alias Union[BaseEmbedding, str]
• llama_index.core.base.embeddings.base.BaseEmbedding -- Abstract embedding interface
• llama_index.core.callbacks.base.CallbackManager -- Optional callback manager integration

Knowledge Sources

LlamaIndex Core Settings Source LlamaIndex Settings Configuration

Metadata

Machine Learning Embeddings RAG LlamaIndex Configuration

Principle:Run_llama_Llama_index_Embedding_Model_Integration