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

llama-index-embeddings-openai

JSON →
library0.6.0pypypi✓ verified 24d ago

This library provides an integration for LlamaIndex, a data framework for LLM applications, to utilize OpenAI's embedding models. It enables users to convert text into numerical vector representations (embeddings) using various OpenAI models. Currently at version 0.6.0, it follows the rapid development and release cadence of the broader LlamaIndex ecosystem.

pip install llama-index-embeddings-openai
INSTALL
IMPORT
SIG · LLAMA-INDEX-EMBEDD
L
llama-index-embeddings-openai
llm-agentspythonv0.6.0
Install
20.5s avg
Import
8876ms
Disk
271MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.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.103.95 runs
installs and imports cleanly · install 0.0s · import 7.408s · 260.6MB
glibc
py 3.103.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`.
fix
Change 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`.
fix
After 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`.
fix
Set `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`.
fix
Upgrade `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.
fix
Review 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.
fix
Ensure 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.
fix
Set 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.
fix
Check 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.
fix
Use 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.
Agent activity
44 hits · last 30 days
node
38
OpenAI (training)
1
Resources
llama-index-embeddings-openai — pip install llama-index-embeddings-openai · libregistry