LlamaIndex Embeddings Azure OpenAI

0.5.2 · active · verified Mon Apr 13

The `llama-index-embeddings-azure-openai` library provides an integration for LlamaIndex to leverage Azure OpenAI's embedding models. It allows users to generate sophisticated numerical representations of text for use within LlamaIndex applications, particularly for Retrieval-Augmented Generation (RAG) workflows. This library is an actively developed component of the broader LlamaIndex ecosystem, with updates typically aligning with the main LlamaIndex project's release cycle.

Warnings

gotcha Azure OpenAI requires explicit configuration of `api_base` (or `azure_endpoint`), `api_key`, `api_version`, and a `deployment_name` (often referred to as 'engine' in older docs). These are distinct from standard OpenAI API calls.
Fix: Ensure `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_API_VERSION`, and `AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME` environment variables are set, or pass these parameters directly to the `AzureOpenAIEmbedding` constructor.
gotcha Due to regional variations in Azure OpenAI model availability, you might need to deploy embedding models and chat completion models in different Azure regions, requiring separate endpoint configurations.
Fix: Consult Azure OpenAI documentation for model availability by region. Configure `AzureOpenAIEmbedding` and `AzureOpenAI` (for LLMs) with distinct `azure_endpoint` values if their respective deployments are in different regions.
breaking Version compatibility issues can arise between specific versions of `llama-index-embeddings-azure-openai` and `llama-index-core`, leading to dependency resolution errors. For example, some `llama-index-llms-azure-openai` versions depended on `llama-index-core<0.13`, conflicting with newer `llama-index` requirements.
Fix: Always check the `pyproject.toml` or `setup.py` of `llama-index-embeddings-azure-openai` for its exact `llama-index-core` dependency range. When encountering conflicts, try upgrading or downgrading `llama-index-core` or the `azure-openai` integration package to a compatible version. Using `pip install --upgrade llama-index llama-index-embeddings-azure-openai` may help resolve to compatible versions, but manual intervention might be needed for specific scenarios.
gotcha When using Azure AD for authentication, older versions (e.g., 0.1.9) had a bug where `api_key` was still erroneously required. While likely fixed in newer versions (0.5.2+ includes `azure_ad_token_provider` parameter), ensure proper configuration if using Azure AD.
Fix: For versions 0.5.0+, utilize the `azure_ad_token_provider` and `use_azure_ad=True` parameters in `AzureOpenAIEmbedding`. Verify that `AZURE_OPENAI_API_KEY` is not set if relying solely on Azure AD for authentication, unless explicitly required by your specific Azure setup.

Install

pip install llama-index-embeddings-azure-openai Install package

Imports

AzureOpenAIEmbedding

from llama_index.embeddings.azure_openai import AzureOpenAIEmbedding

Quickstart

This quickstart demonstrates how to initialize `AzureOpenAIEmbedding` and set it as the global embedding model for LlamaIndex. It fetches necessary Azure OpenAI credentials from environment variables, which is the recommended secure practice. Replace placeholder values with your actual Azure OpenAI details.

import os
from llama_index.embeddings.azure_openai import AzureOpenAIEmbedding
from llama_index.core import Settings

# Ensure environment variables are set for Azure OpenAI
# AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_VERSION, AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME

api_key = os.environ.get('AZURE_OPENAI_API_KEY', 'your-api-key')
azure_endpoint = os.environ.get('AZURE_OPENAI_ENDPOINT', 'https://your-resource-name.openai.azure.com/')
api_version = os.environ.get('AZURE_OPENAI_API_VERSION', '2023-07-01-preview')
deployment_name = os.environ.get('AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME', 'your-embedding-deployment-name')
model_name = os.environ.get('AZURE_OPENAI_EMBEDDING_MODEL_NAME', 'text-embedding-ada-002') # The actual model name you deployed

if not all([api_key, azure_endpoint, api_version, deployment_name]):
    raise ValueError("Please set all required Azure OpenAI environment variables or provide them directly.")

embed_model = AzureOpenAIEmbedding(
    model=model_name,
    deployment_name=deployment_name,
    api_key=api_key,
    azure_endpoint=azure_endpoint,
    api_version=api_version,
)

# Set the embedding model globally for LlamaIndex
Settings.embed_model = embed_model

# Example usage: get an embedding
text_to_embed = "This is a test sentence for Azure OpenAI embeddings."
embeddings = embed_model.get_text_embedding(text_to_embed)

print(f"Embedding generated with length: {len(embeddings)}")
# print(embeddings) # Uncomment to see the full embedding vector

view raw JSON →