> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/getzep/graphiti/llms.txt
> Use this file to discover all available pages before exploring further.

# Embedding Providers

> Configure embedding models for semantic search with OpenAI, Azure OpenAI, Google Gemini, or Voyage AI

Embeddings power semantic search in Graphiti by converting text into vector representations. Configure your preferred embedding provider to enable similarity-based retrieval.

## Supported Providers

<CardGroup cols={2}>
  <Card title="OpenAI" icon="openai">
    text-embedding-3-small, text-embedding-3-large
  </Card>

  <Card title="Azure OpenAI" icon="microsoft">
    OpenAI embeddings on Azure infrastructure
  </Card>

  <Card title="Google Gemini" icon="google">
    text-embedding-004 and models-embedding-001
  </Card>

  <Card title="Voyage AI" icon="ship">
    voyage-3, voyage-3-lite for domain-specific embeddings
  </Card>
</CardGroup>

## Default Provider (OpenAI)

By default, Graphiti uses OpenAI's `text-embedding-3-small`:

```python theme={null}
from graphiti_core import Graphiti
import os

# Set your API key
os.environ["OPENAI_API_KEY"] = "sk-..."

# Uses OpenAI embeddings by default
graphiti = Graphiti(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password"
)
```

## OpenAI Embeddings

### Basic Configuration

```python theme={null}
from graphiti_core import Graphiti
from graphiti_core.embedder import OpenAIEmbedder, OpenAIEmbedderConfig

# Configure OpenAI embedder
embedder_config = OpenAIEmbedderConfig(
    api_key="sk-...",
    embedding_model="text-embedding-3-small",
    embedding_dim=1536
)

embedder = OpenAIEmbedder(config=embedder_config)

graphiti = Graphiti(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password",
    embedder=embedder
)
```

### Configuration Options

| Parameter         | Type  | Default                    | Description                 |
| ----------------- | ----- | -------------------------- | --------------------------- |
| `api_key`         | `str` | From env                   | OpenAI API key              |
| `embedding_model` | `str` | `"text-embedding-3-small"` | Embedding model name        |
| `embedding_dim`   | `int` | `1024`                     | Embedding vector dimensions |
| `base_url`        | `str` | `None`                     | Custom API endpoint         |

### Available Models

<Tabs>
  <Tab title="text-embedding-3-small">
    * Dimensions: 1536 (default) or lower
    * Best for: General use, cost-effective
    * Price: \$0.02 per 1M tokens
  </Tab>

  <Tab title="text-embedding-3-large">
    * Dimensions: 3072 (default) or lower
    * Best for: Maximum quality
    * Price: \$0.13 per 1M tokens
  </Tab>

  <Tab title="text-embedding-ada-002">
    * Dimensions: 1536
    * Best for: Legacy applications
    * Price: \$0.10 per 1M tokens
  </Tab>
</Tabs>

### Custom Dimensions

Reduce dimensions for lower storage costs:

```python theme={null}
embedder_config = OpenAIEmbedderConfig(
    embedding_model="text-embedding-3-small",
    embedding_dim=512  # Reduce from default 1536
)
```

<Warning>
  Lower dimensions may reduce search quality. Test before deploying to production.
</Warning>

## Azure OpenAI Embeddings

Use OpenAI embeddings deployed on Azure:

```python theme={null}
from graphiti_core import Graphiti
from graphiti_core.embedder.azure_openai import AzureOpenAIEmbedderClient
from openai import AsyncOpenAI

# Create Azure OpenAI client
azure_client = AsyncOpenAI(
    base_url="https://your-resource.openai.azure.com/openai/v1/",
    api_key="your-azure-api-key"
)

# Configure embedder
embedder = AzureOpenAIEmbedderClient(
    azure_client=azure_client,
    model="text-embedding-3-small"  # Your Azure deployment name
)

graphiti = Graphiti(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password",
    embedder=embedder
)
```

### Environment Variables

```bash theme={null}
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_API_KEY=your-key
AZURE_OPENAI_EMBEDDING_DEPLOYMENT=text-embedding-3-small
```

## Google Gemini Embeddings

Use Google's embedding models:

```python theme={null}
from graphiti_core import Graphiti
from graphiti_core.embedder.gemini import GeminiEmbedder, GeminiEmbedderConfig

# Configure Gemini embedder
embedder_config = GeminiEmbedderConfig(
    api_key="your-google-api-key",
    embedding_model="text-embedding-004",
    embedding_dim=768
)

embedder = GeminiEmbedder(config=embedder_config)

graphiti = Graphiti(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password",
    embedder=embedder
)
```

### Environment Variables

```bash theme={null}
GOOGLE_API_KEY=your-key
```

### Available Models

* `text-embedding-004` - Latest model, 768 dimensions
* `models/embedding-001` - Earlier model, 768 dimensions

## Voyage AI Embeddings

Use Voyage AI for specialized domain embeddings:

### Installation

```bash theme={null}
pip install graphiti-core[voyageai]
```

### Configuration

```python theme={null}
from graphiti_core import Graphiti
from graphiti_core.embedder.voyage import VoyageAIEmbedder, VoyageAIEmbedderConfig

# Configure Voyage AI embedder
embedder_config = VoyageAIEmbedderConfig(
    api_key="pa-...",
    embedding_model="voyage-3",
    embedding_dim=1024
)

embedder = VoyageAIEmbedder(config=embedder_config)

graphiti = Graphiti(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password",
    embedder=embedder
)
```

### Environment Variables

```bash theme={null}
VOYAGE_API_KEY=pa-...
```

### Available Models

<Tabs>
  <Tab title="voyage-3">
    * Dimensions: 1024
    * Best for: General-purpose, state-of-the-art quality
    * Context: 32K tokens
  </Tab>

  <Tab title="voyage-3-lite">
    * Dimensions: 512
    * Best for: Cost-effective, faster inference
    * Context: 32K tokens
  </Tab>

  <Tab title="voyage-code-3">
    * Dimensions: 1024
    * Best for: Code and technical documentation
    * Context: 32K tokens
  </Tab>

  <Tab title="voyage-finance-2">
    * Dimensions: 1024
    * Best for: Financial documents
    * Context: 32K tokens
  </Tab>

  <Tab title="voyage-law-2">
    * Dimensions: 1024
    * Best for: Legal documents
    * Context: 32K tokens
  </Tab>
</Tabs>

## Custom Embedding Clients

Implement a custom embedder by extending `EmbedderClient`:

```python theme={null}
from graphiti_core.embedder.client import EmbedderClient, EmbedderConfig
from collections.abc import Iterable

class CustomEmbedderConfig(EmbedderConfig):
    embedding_model: str = "custom-model"
    api_endpoint: str = "https://api.example.com"

class CustomEmbedder(EmbedderClient):
    def __init__(self, config: CustomEmbedderConfig):
        self.config = config
        # Initialize your client here
    
    async def create(
        self, 
        input_data: str | list[str] | Iterable[int] | Iterable[Iterable[int]]
    ) -> list[float]:
        # Generate embedding for single input
        # Return a list of floats
        pass
    
    async def create_batch(self, input_data_list: list[str]) -> list[list[float]]:
        # Generate embeddings for batch input
        # Return list of embedding vectors
        pass

# Use custom embedder
embedder = CustomEmbedder(config=CustomEmbedderConfig())
graphiti = Graphiti(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password",
    embedder=embedder
)
```

## Embedding Usage

Embeddings are generated automatically for:

* **Entity Names** - For entity similarity search
* **Relationship Facts** - For semantic fact retrieval
* **Community Summaries** - For cluster-based search
* **Episode Content** - For source document search

```python theme={null}
# Add episode - embeddings generated automatically
result = await graphiti.add_episode(
    name="Example",
    episode_body="Alice is a software engineer at Google.",
    source=EpisodeType.text,
    source_description="Bio",
    reference_time=datetime.now(timezone.utc)
)

# Nodes have name embeddings
for node in result.nodes:
    if node.name_embedding:
        print(f"Embedding dims: {len(node.name_embedding)}")

# Edges have fact embeddings
for edge in result.edges:
    if edge.fact_embedding:
        print(f"Embedding dims: {len(edge.fact_embedding)}")
```

## Batch Embedding Generation

Graphiti batches embedding requests for efficiency:

```python theme={null}
# Multiple embeddings generated in batches
await graphiti.add_episode_bulk(
    bulk_episodes=[
        RawEpisode(
            name="Episode 1",
            content="Content 1",
            source=EpisodeType.text,
            source_description="Source",
            reference_time=datetime.now(timezone.utc)
        ),
        RawEpisode(
            name="Episode 2",
            content="Content 2",
            source=EpisodeType.text,
            source_description="Source",
            reference_time=datetime.now(timezone.utc)
        )
    ]
)
# Embeddings generated in efficient batches
```

## Choosing an Embedding Model

<CardGroup cols={2}>
  <Card title="Quality vs Cost" icon="balance-scale">
    Balance search quality with API costs. Start with `text-embedding-3-small`.
  </Card>

  <Card title="Dimension Size" icon="ruler">
    Higher dimensions = better quality but more storage. 512-1024 works for most cases.
  </Card>

  <Card title="Domain Specificity" icon="bullseye">
    Use domain-specific models (Voyage) for specialized content.
  </Card>

  <Card title="Consistency" icon="check">
    Don't change embedding models after deployment - requires full re-embedding.
  </Card>
</CardGroup>

## Cost Optimization

<Steps>
  <Step title="Choose efficient models">
    Use `text-embedding-3-small` or `voyage-3-lite` for cost savings
  </Step>

  <Step title="Reduce dimensions">
    Lower `embedding_dim` to reduce storage and API costs
  </Step>

  <Step title="Batch operations">
    Use `add_episode_bulk()` to generate embeddings in larger batches
  </Step>

  <Step title="Cache strategy">
    Consider caching embeddings for frequently used content
  </Step>
</Steps>

## Performance Tips

```python theme={null}
# Use smaller dimensions for faster search
embedder_config = OpenAIEmbedderConfig(
    embedding_model="text-embedding-3-small",
    embedding_dim=512  # Faster than 1536
)

# Batch embeddings for efficiency
await graphiti.add_episode_bulk(episodes)  # Better than individual adds

# Monitor embedding generation
result = await graphiti.add_episode(...)
print(f"Nodes embedded: {len([n for n in result.nodes if n.name_embedding])}")
print(f"Edges embedded: {len([e for e in result.edges if e.fact_embedding])}")
```

## Changing Embedding Models

<Warning>
  Changing embedding models requires re-embedding all existing content. Embeddings from different models are not comparable.
</Warning>

If you need to switch models:

1. Export your graph structure and content
2. Create a new database
3. Configure the new embedding model
4. Re-ingest all episodes with the new embedder

```python theme={null}
# Export current data
episodes = await graphiti.retrieve_episodes(...)

# Create new database with new embedder
new_embedder = VoyageAIEmbedder(config=VoyageAIEmbedderConfig(
    embedding_model="voyage-3"
))

new_graphiti = Graphiti(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password",
    embedder=new_embedder
)

# Re-ingest with new embeddings
for episode in episodes:
    await new_graphiti.add_episode(...)
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Searching" icon="magnifying-glass" href="/guides/searching">
    Use embeddings for semantic search
  </Card>

  <Card title="LLM Providers" icon="brain" href="/guides/llm-providers">
    Configure your LLM provider
  </Card>

  <Card title="Graph Drivers" icon="database" href="/guides/graph-drivers">
    Choose your graph database
  </Card>
</CardGroup>