---
title: Embeddings Configuration
amsdal_docs:
  target: framework/plugins/amsdal-ml/embeddings-configuration.md
  nav_title: Configuration
  nav_section: Framework
  nav_path: ["Plugins & Extensions", "ML", "Embeddings & Search"]
  nav_order: 1
---

# 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:

```bash
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:

```bash
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`:

```python
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:

```bash
# 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
```
