Registry /
llm-agents / llama-index-embeddings-openai
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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 7.408s · 260.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 20.5s · import 6.794s · 256MB
271MB installed
● package 271MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OpenAIEmbedding
✓ from llama_index.embeddings.openai import OpenAIEmbedding
✗ from llama_index.core.embeddings.openai import OpenAIEmbedding
As of LlamaIndex v0.9.x, provider integrations like OpenAIEmbeddings were moved to their own dedicated packages and are no longer re-exported from `llama_index.core`.
Settings
✓ from llama_index.core import Settings
Used for setting the global default embedding model.
This quickstart demonstrates how to install the `llama-index-embeddings-openai` package, set your OpenAI API key, and initialize `OpenAIEmbedding` either globally via `Settings` or as a local instance to generate text embeddings. It shows how to get embeddings for both single and multiple text inputs.
import os
from llama_index.core import Settings
from llama_index.embeddings.openai import OpenAIEmbedding
# Set your OpenAI API key as an environment variable
# It's recommended to load this from a .env file in production
os.environ["OPENAI_API_KEY"] = os.environ.get("OPENAI_API_KEY", "YOUR_OPENAI_API_KEY")
# Ensure the API key is set
if not os.environ["OPENAI_API_KEY"] or os.environ["OPENAI_API_KEY"] == "YOUR_OPENAI_API_KEY":
raise ValueError("OPENAI_API_KEY environment variable not set. Please set it to your OpenAI API key.")
# Initialize the OpenAI Embedding model and set it as the global default
# By default, uses 'text-embedding-ada-002'
Settings.embed_model = OpenAIEmbedding(model="text-embedding-ada-002")
# Alternatively, create a local instance without setting it globally
embed_model_local = OpenAIEmbedding(model="text-embedding-3-small")
# Get a single text embedding using the local instance
text = "This is a test sentence for embedding with a local model."
embedding = embed_model_local.get_text_embedding(text)
print(f"Embedding length: {len(embedding)}")
# print(f"First 5 elements of embedding: {embedding[:5]}...")
# Get embeddings for multiple texts using the global default
texts_list = ["Hello world!", "LlamaIndex is great.", "OpenAI embeddings are powerful."]
embeddings_for_list = Settings.embed_model.get_text_embeddings(texts_list)
print(f"Number of embeddings for list: {len(embeddings_for_list)}")
for i, emb in enumerate(embeddings_for_list):
print(f"Embedding {i} length: {len(emb)}")
Debug
Known issues
breakingBreaking Change (LlamaIndex v0.9.x): Embedding providers are no longer re-exported from `llama_index.core`. You must import `OpenAIEmbedding` directly from `llama_index.embeddings.openai`.fixChange import statements from `from llama_index.core.embeddings.openai import OpenAIEmbedding` to `from llama_index.embeddings.openai import OpenAIEmbedding`.
affects: llama-index-core>=0.9.0
breakingBreaking Change (LlamaIndex v0.11.x): Default LLM and embedding models are no longer set automatically via `Settings`. You must explicitly set `Settings.embed_model`.fixAfter importing `Settings` and `OpenAIEmbedding`, explicitly assign `Settings.embed_model = OpenAIEmbedding()`.
affects: llama-index-core>=0.11.0
gotchaOpenAI API Key is mandatory and must be configured. Lack of a valid key will result in `APIConnectionError` or `AuthenticationError`.fixSet `OPENAI_API_KEY` as an environment variable (e.g., `export OPENAI_API_KEY='sk-...'`) or pass it explicitly during `OpenAIEmbedding` initialization if the underlying `openai` client is not configured globally. Environment variables take precedence.
affects: All versions
gotchaOlder `llama-index` core versions (e.g., 0.10.6) might encounter issues with `callback_manager` assignments leading to `ValueError` or crashes when using `OpenAIEmbedding`.fixUpgrade `llama-index-core` to a newer version or, if stuck on 0.10.6, try creating a new `OpenAIEmbedding` instance or investigate if a workaround involving `callback_manager` initialization is available for your specific `llama-index-core` patch version.
affects: llama-index-core==0.10.6
gotchaRate limits and connection errors can occur due to frequent API calls or network issues, especially when processing many documents.fixReview OpenAI's rate limits. The `OpenAIEmbedding` class has internal retry logic, but adjusting the `batch_size` parameter during initialization or implementing custom backoff strategies may be necessary for large-scale operations. Ensure stable internet connection.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'llama_index.embeddings.openai'
This error occurs because the `OpenAIEmbedding` class is part of a separate integration package (`llama-index-embeddings-openai`) and needs to be imported directly from its specific module, not a generic `llama_index.embeddings` path.
fixEnsure the `llama-index-embeddings-openai` package is installed (`pip install llama-index-embeddings-openai`) and import `OpenAIEmbedding` using `from llama_index.embeddings.openai import OpenAIEmbedding`.
AuthenticationError: Invalid Authentication
This error indicates that the OpenAI API key is missing, invalid, or incorrectly configured, preventing successful authentication with the OpenAI service.
fixSet your OpenAI API key as an environment variable (`OPENAI_API_KEY`) or pass it directly when initializing `OpenAIEmbedding`: `os.environ["OPENAI_API_KEY"] = "sk-..."` or `embed_model = OpenAIEmbedding(api_key="sk-...")`.
APIConnectionError: Connection error.
This error typically arises from issues connecting to the OpenAI API, which can include transient network problems, incorrect API endpoint configurations, or rate limits being hit.
fixCheck your internet connection, verify the OpenAI API endpoint if customized (especially for Azure OpenAI), and ensure you're not exceeding OpenAI's rate limits. Transient errors often resolve with retries. For Azure, ensure `azure_endpoint`, `api_version`, and `deployment_name` are correct.
AttributeError: 'OpenAIEmbedding' object has no attribute 'embed_documents'
This error usually occurs when attempting to call `embed_documents` on an `OpenAIEmbedding` instance from `llama_index`, as this method might be present in other embedding libraries (like `langchain.embeddings.openai.OpenAIEmbeddings`) but not directly exposed by `llama_index.embeddings.openai.OpenAIEmbedding`. The `llama-index` integration uses methods like `get_text_embedding` for single texts.
fixUse the appropriate embedding methods provided by `llama_index.embeddings.openai.OpenAIEmbedding`, such as `embed_model.get_text_embedding(text)` for single text embeddings or integrate with `llama_index`'s higher-level components that handle batching internally. If migrating from LangChain, adjust method calls accordingly.
Upgrade
Version history
0.6.0latest on PyPI · released Mar 12, 2026
Audit
Dependencies
llama-index-corerequiredCore LlamaIndex framework for setting up embedding models and indices.
openairequiredThe underlying Python client for interacting with OpenAI's API.