Skip to content

Embeddings Configuration

amsdal_ml uses OpenAI's embedding models to convert text into vector representations for semantic search. This page covers how to configure the embedding system.

OpenAI Embedder

The default embedder uses OpenAI's text-embedding-3-small model. Set your API key:

export OPENAI_API_KEY='sk-...'

Embedding Parameters

Env Variable Default Description
EMBED_MODEL_NAME text-embedding-3-small OpenAI embedding model to use
EMBED_DIMENSIONS 1536 Vector dimensions (must match the model)
EMBED_MAX_DEPTH 2 How deep to walk model relationships when generating text
EMBED_MAX_CHUNKS 10 Maximum number of chunks per object
EMBED_MAX_TOKENS_PER_CHUNK 800 Maximum tokens per text chunk

Available Models

Model Dimensions Description
text-embedding-3-small 1536 Fast, cost-effective (default)
text-embedding-3-large 3072 Higher quality, more expensive
text-embedding-ada-002 1536 Legacy model

To use a different model:

export EMBED_MODEL_NAME='text-embedding-3-large'
export EMBED_DIMENSIONS=3072

How Embeddings Work

When you index an AMSDAL model object, the system:

  1. Walks the object recursively (up to EMBED_MAX_DEPTH levels) collecting field values and related objects
  2. Generates text — structured facts about the object (field names + values)
  3. Splits text into chunks of up to EMBED_MAX_TOKENS_PER_CHUNK tokens, respecting sentence boundaries
  4. Embeds each chunk via the OpenAI Embeddings API
  5. Stores embeddings as EmbeddingModel records in the database, linked to the source object

EmbeddingModel

Each chunk is stored as an EmbeddingModel record with:

Field Description
data_object_class Source model class name
data_object_id Source object ID
chunk_index Chunk number (0-based)
raw_text The text that was embedded
embedding Vector embedding (VectorField)
tags List of string tags for filtering
ml_metadata Optional metadata (type Any, default None)

Custom Embedder

You can provide a custom embedder by subclassing Embedder:

from amsdal_ml.ml_ingesting.embedders.embedder import Embedder

class MyEmbedder(Embedder):
    def embed(self, text: str) -> list[float]:
        # Return embedding for the text
        ...

    async def aembed(self, text: str) -> list[float]:
        # Async version
        ...

Chunking Strategy

The default chunking splits text by sentences, accumulating up to EMBED_MAX_TOKENS_PER_CHUNK tokens per chunk. This ensures:

  • Chunks respect natural sentence boundaries
  • Each chunk is small enough for the embedding model's context window
  • Related facts stay together within a chunk

Configure chunking behavior:

# More chunks per object (for large/complex models)
export EMBED_MAX_CHUNKS=20

# Larger chunks (more context per embedding)
export EMBED_MAX_TOKENS_PER_CHUNK=1200

# Deeper relationship walking
export EMBED_MAX_DEPTH=3