Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/openai/openai-cookbook/llms.txt

Use this file to discover all available pages before exploring further.

Text embeddings are dense numerical vectors that capture the semantic meaning of text. When you embed two pieces of text that mean similar things, their vectors end up close together in high-dimensional space — even if the words are completely different. This property makes embeddings the foundation for a wide range of applications: semantic search, retrieval-augmented generation, classification, clustering, and recommendation systems.

​
How embeddings work

The OpenAI embeddings API converts a string of text into a list of floating-point numbers. That list — the embedding vector — encodes the meaning of the input text in a way that mathematical operations can act on. The cosine similarity between two vectors measures how semantically related their source texts are, with values ranging from -1 (opposite meaning) to 1 (identical meaning).

​
Creating an embedding

Install the Python client and set your API key, then call client.embeddings.create: 
pip install openai

from openai import OpenAI

client = OpenAI()

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="The food was delicious and the waiter was friendly."
)

embedding = response.data[0].embedding
print(len(embedding))  # 1536
The input field accepts a string or a list of strings. When you pass a list, the API returns one embedding per item in response.data, which is more efficient than making one request per string.

​
Available models

OpenAI provides three embedding models. Choose based on the trade-off between performance, dimensionality, and cost.
ModelDimensionsMax tokensBest for
text-embedding-3-small15368191Latency-sensitive applications, high-volume workloads
text-embedding-3-large30728191Highest accuracy, benchmarks, research
text-embedding-ada-00215368191Legacy workloads already using this model
For new projects, prefer text-embedding-3-small or text-embedding-3-large. The text-embedding-3 series outperforms ada-002 on standard benchmarks at lower cost per token.

​
Shortening embeddings

The text-embedding-3 models support a dimensions parameter that lets you reduce the output vector length without retraining. Shorter vectors lower storage and retrieval costs while retaining most of the model’s accuracy: 
response = client.embeddings.create(
    model="text-embedding-3-large",
    input="The food was delicious and the waiter was friendly.",
    dimensions=256
)

​
Handling rate limits with exponential backoff

When embedding large datasets, calling the API in a tight loop will trigger rate limits. Use the tenacity library to automatically retry with exponential backoff: 
from tenacity import retry, wait_random_exponential, stop_after_attempt
from openai import OpenAI

client = OpenAI()

@retry(wait=wait_random_exponential(min=1, max=20), stop=stop_after_attempt(6))
def get_embedding(text: str, model: str = "text-embedding-3-small") -> list[float]:
    return client.embeddings.create(input=[text], model=model).data[0].embedding

embedding = get_embedding("Your text goes here")
print(len(embedding))  # 1536
Pass inputs as a list rather than calling the API once per string. Batching reduces the number of HTTP round trips and makes it easier to stay within rate limits.

​
Use cases

Semantic search

Embed a query and a document corpus, then rank documents by cosine similarity to surface the most relevant results — even when the query and document share no words.

Retrieval-Augmented Generation

Retrieve the most relevant chunks from a knowledge base and inject them into a prompt so a model can answer questions grounded in your own data.

Classification

Use embeddings as feature vectors for a classifier such as a random forest or logistic regression. The model learns to separate classes in the embedding space without you writing any feature engineering code.

Clustering

Group similar documents together using k-means or other clustering algorithms on their embedding vectors. Useful for discovering topics in large unstructured corpora.

Recommendations

Find the items most similar to a seed item by embedding all items and retrieving the nearest neighbors. Works for articles, products, support tickets, and more.

Anomaly detection

Flag documents whose embeddings are far from the centroid of their expected cluster. Useful for detecting off-topic content, spam, or unusual user inputs.

​
Token limits

Each text-embedding-3 model accepts up to 8,191 tokens. Inputs longer than this limit will return an error. Use tiktoken to count tokens before embedding: 
import tiktoken

def count_tokens(text: str, model: str = "text-embedding-3-small") -> int:
    enc = tiktoken.encoding_for_model(model)
    return len(enc.encode(text))

print(count_tokens("The food was delicious."))  # 6
For documents that exceed the limit, split the text into smaller chunks before embedding. See Semantic text search for chunking strategies.

​
Next steps

  • Semantic text search — build a full search system with cosine similarity ranking
  • RAG patterns — retrieve context from your own documents to ground model responses

Build docs developers (and LLMs) love

Get started for freeTalk to us