What is OpenAIEmbeddings?
OpenAIEmbeddings wraps the OpenAI embeddings API and supports the two text-embedding-3 models: text-embedding-3-small (1536 dimensions, cost-effective, strong general quality) and text-embedding-3-large (3072 dimensions, best quality, ~3x the cost). Both support Matryoshka representation learning via the dimensions parameter — you can truncate to any lower dimension (e.g. 256) with only a modest quality loss, which reduces vector store storage and speeds up similarity search.
The class automatically reads OPENAI_API_KEY from the environment and handles batching internally. embed_documents() sends up to 2048 inputs per API call and manages the chunking transparently. Never call embed_query() in a loop — embed_documents() is far more efficient because it parallelises the API requests and handles retries.
For Azure OpenAI deployments, use AzureOpenAIEmbeddings instead — it has the same interface but reads AZURE_OPENAI_API_KEY and AZURE_OPENAI_ENDPOINT. For caching embeddings to avoid re-computing identical strings, wrap in CacheBackedEmbeddings with a Redis or local filesystem store — this is especially valuable during iterative development when you are reindexing frequently.
When to Use
You need to embed text for semantic search or RAG. Use this for production systems that need high-quality embeddings.
Use Cases
- • Semantic search in RAG
- • Building vector stores
- • Similarity-based recommendations
- • Duplicate detection
- • Document clustering
- • Content matching
Key Features
- ✓ Two models available
- ✓ High quality embeddings
- ✓ Batch processing
- ✓ Fast API
- ✓ Token counting
- ✓ Cost-effective
When NOT to Use
For privacy-sensitive data or if avoiding API calls. Don't use for local-only systems.
Notes
Batch with embed_documents() — never call embed_query() in a loop
embed_query() is for single lookups at query time. For indexing a corpus, always use embed_documents(texts) — it batches up to 2048 strings per API call, handles retries on rate limits, and is orders of magnitude faster than looping over embed_query(). Calling embed_query() in a loop for 10 000 documents will take ~10x longer and hit rate limits.
text-embedding-3 models support Matryoshka truncation
Both text-embedding-3-small and text-embedding-3-large support the dimensions parameter. Setting dimensions=512 on text-embedding-3-large gives you a 512-dim vector that beats text-embedding-3-small in quality while using less storage. This is the recommended approach when storage cost matters — do not use ada-002 for this purpose.
Rate limits: 1 000 000 TPM on tier 1, lower on free
Embedding API calls share the same rate limit tier as completions. On the free tier, large batch indexing jobs will hit 429 errors. Use exponential back-off or LangChain's built-in retry (max_retries parameter). For production indexing jobs, raise your rate limit tier or use a queue.
CacheBackedEmbeddings prevents re-billing during re-indexing
Wrap OpenAIEmbeddings in CacheBackedEmbeddings when developing or running re-index jobs. It hashes each input string and only calls the API for unseen inputs. A LocalFileStore cache persists across process restarts. Use a namespaced store so you can invalidate when you change models.
Import
from langchain_openai import OpenAIEmbeddingsConfiguration
| Parameter | Type | Default | Purpose |
|---|---|---|---|
| model | str | text-embedding-3-small | Model name (small=512-dim, large=3072-dim) |
Usage Examples
Default text-embedding-3-small
from langchain_openai import OpenAIEmbeddings
embeddings = OpenAIEmbeddings() # defaults to text-embedding-3-small
vec = embeddings.embed_query('What is semantic search?')
print(len(vec)) # 1536 dimensionsLarge Model with Reduced Dimensions
# High-quality large model with Matryoshka truncation
embeddings = OpenAIEmbeddings(
model="text-embedding-3-large",
dimensions=256, # truncate from 3072
)
docs = ['LangChain is a framework', 'RAG pipelines scale']
vecs = embeddings.embed_documents(docs)
print(len(vecs[0])) # 256 — smaller index, similar recallCache-backed Embeddings
# Cache embeddings to avoid re-computing during development
from langchain.embeddings import CacheBackedEmbeddings
from langchain.storage import LocalFileStore
store = LocalFileStore("./embed_cache")
cached = CacheBackedEmbeddings.from_bytes_store(
OpenAIEmbeddings(), store, namespace="oai-3-small"
)
vecs = cached.embed_documents(['same doc each run']) # API called onceCommon Pitfalls
❌ Calling embed_query() in a loop
✅ Use embed_documents() for batch processing
Alternative Embedding Models
| Model | When to Use |
|---|---|
| HuggingFaceEmbeddings | For local, privacy-focused embeddings |
Related LangChain References
Browse the full LangChain API reference index to explore more classes, methods, and decorators, or start with the LangChain introduction tutorial for end-to-end context on building with OpenAIEmbeddings and the wider framework.
OpenAIEmbeddings FAQ
What is OpenAIEmbeddings in LangChain?
Create text embeddings using OpenAI's models. OpenAIEmbeddings wraps the OpenAI embeddings API and supports the two text-embedding-3 models: text-embedding-3-small (1536 dimensions, cost-effective, strong general quality) and text-embedding-3-large (3072 dimensions, best quality, ~3x the cost). Both support Matryoshka representation learning via the dimensions parameter — you can truncate to any lower dimension (e.g. 256) with only a modest quality loss, which reduces vector store storage and speeds up similarity search.…
Which package provides OpenAIEmbeddings?
DevShelfHub documents OpenAIEmbeddings from the langchain-openai package. Pin your installed LangChain version and match imports to the snippet on this page.
When should I use OpenAIEmbeddings?
You need to embed text for semantic search or RAG. Use this for production systems that need high-quality embeddings.
When should I avoid using OpenAIEmbeddings?
For privacy-sensitive data or if avoiding API calls. Don't use for local-only systems.
How do I import OpenAIEmbeddings in Python?
from langchain_openai import OpenAIEmbeddings
Where can I explore more LangChain API reference pages?
Open the LangChain API reference index on DevShelfHub to browse classes, methods, and decorators, each with runnable examples, parameters, common mistakes, and cross-links.