Registry / llm-agents / llama-index-embeddings-azure-openai

llama-index-embeddings-azure-openai

library0.6.0pypypi✓ verified 22d ago

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.

llm-agents ai-ml azure vector-search

pip install llama-index-embeddings-azure-openai

package ↗

INSTALL

IMPORT

SIG · LLAMA-INDEX-EMBEDD

llama-index-embeddings-azure-openai

llm-agentspythonv0.6.0

Install

22.4s avg

Import

9195ms

Disk

292MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.6.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 7.644s · 280.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 22.4s · import 7.068s · 276MB

292MB installed

● package 292MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AzureOpenAIEmbedding

✓ from llama_index.embeddings.azure_openai import AzureOpenAIEmbedding

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

Debug

Known issues

gotchaAzure 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.

affects: >=0.1.0

gotchaDue 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.

affects: >=0.1.0

breakingVersion 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.

affects: <0.5.0

gotchaWhen 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.

affects: <0.5.0

Errors

Common errors & fixes

AuthenticationError: Error code: 401

This error occurs when the Azure OpenAI service rejects the API request due to incorrect or missing authentication credentials, an expired token, or an incorrectly configured endpoint.

fix

Ensure that `api_key`, `azure_endpoint`, `api_version`, and `deployment_name` are correctly set when initializing `AzureOpenAIEmbedding`. Verify that the API key is valid and the endpoint URL is correct and includes the resource name.

ValueError: Did not find api_key, please add an environment variable `AZURE_OPENAI_API_KEY` which contains it, or pass `api_key` as a named parameter.

The `AzureOpenAIEmbedding` class could not find the API key in the environment variable `AZURE_OPENAI_API_KEY` or through the `api_key` parameter during initialization. This can happen if the environment variable is not set, or if the library is looking for `OPENAI_API_KEY` instead of `AZURE_OPENAI_API_KEY` in some versions or contexts, or if the environment variable is read as an empty string.

fix

Explicitly pass the `api_key` parameter to the `AzureOpenAIEmbedding` constructor, or ensure the `AZURE_OPENAI_API_KEY` environment variable is correctly set before importing the library and that its value is not empty.

ValueError: You must set OPENAI_API_VERSION for Azure OpenAI.

Azure OpenAI requires an explicit `api_version` to be specified, which was not provided during the initialization of `AzureOpenAIEmbedding`.

fix

Pass the `api_version` parameter with a valid Azure OpenAI API version string (e.g., '2023-07-01-preview', '2024-02-15-preview') when creating the `AzureOpenAIEmbedding` instance, or set the `OPENAI_API_VERSION` environment variable.

ModuleNotFoundError: No module named 'llama_index.embeddings'

This error often occurs due to incorrect import paths, especially as the LlamaIndex library structure evolves. Users might be trying to import `AzureOpenAIEmbedding` from an old or incorrect `llama_index` submodule.

fix

Ensure `llama-index-embeddings-azure-openai` is installed, and import `AzureOpenAIEmbedding` from the correct and specific path: `from llama_index.embeddings.azure_openai import AzureOpenAIEmbedding`.

InvalidRequestError: The API deployment for this resource does not exist.

This specific `InvalidRequestError` indicates that the `deployment_name` provided to the `AzureOpenAIEmbedding` class does not correspond to an actual deployed model in your Azure OpenAI resource, or there's a mismatch between the model name and the deployment name.

fix

Verify that the `deployment_name` passed to `AzureOpenAIEmbedding` exactly matches the deployment name you configured in your Azure OpenAI Studio for the embedding model, and ensure the model is successfully deployed.

Upgrade

Version history

0.6.0latest on PyPI · released Aug 29, 2026

Audit

Dependencies

llama-index-corerequiredCore framework dependency for all LlamaIndex integrations.

openairequiredRequired for interacting with Azure OpenAI service APIs.

llama-index-embeddings-openairequiredServes as the base class for AzureOpenAIEmbedding, providing shared functionality.

Agent activity

36 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/llama-index-embeddings-azure-openai/ ↗