--- title: Embeddings description: Learn how to embed values with the AI SDK. --- # Embeddings Embeddings are a way to represent words, phrases, or images as vectors in a high-dimensional space. In this space, similar words are close to each other, and the distance between words can be used to measure their similarity. ## Embedding a Single Value The AI SDK provides the [`embed`](/docs/reference/ai-sdk-core/embed) function to embed single values, which is useful for tasks such as finding similar words or phrases or clustering text. You can use it with embeddings models, e.g. `openai.embeddingModel('text-embedding-3-large')` or `mistral.embeddingModel('mistral-embed')`. ```tsx import { embed } from 'ai'; // 'embedding' is a single embedding object (number[]) const { embedding } = await embed({ model: 'openai/text-embedding-3-small', value: 'sunny day at the beach', }); ``` ## Embedding Many Values When loading data, e.g. when preparing a data store for retrieval-augmented generation (RAG), it is often useful to embed many values at once (batch embedding). The AI SDK provides the [`embedMany`](/docs/reference/ai-sdk-core/embed-many) function for this purpose. Similar to `embed`, you can use it with embeddings models, e.g. `openai.embeddingModel('text-embedding-3-large')` or `mistral.embeddingModel('mistral-embed')`. ```tsx import { embedMany } from 'ai'; // 'embeddings' is an array of embedding objects (number[][]). // It is sorted in the same order as the input values. const { embeddings } = await embedMany({ model: 'openai/text-embedding-3-small', values: [ 'sunny day at the beach', 'rainy afternoon in the city', 'snowy night in the mountains', ], }); ``` ## Embedding Similarity After embedding values, you can calculate the similarity between them using the [`cosineSimilarity`](/docs/reference/ai-sdk-core/cosine-similarity) function. This is useful to e.g. find similar words or phrases in a dataset. You can also rank and filter related items based on their similarity. ```ts highlight={"1,9"} import { cosineSimilarity, embedMany } from 'ai'; const { embeddings } = await embedMany({ model: 'openai/text-embedding-3-small', values: ['sunny day at the beach', 'rainy afternoon in the city'], }); console.log( `cosine similarity: ${cosineSimilarity(embeddings[0], embeddings[1])}`, ); ``` ## Token Usage Many providers charge based on the number of tokens used to generate embeddings. Both `embed` and `embedMany` provide token usage information in the `usage` property of the result object: ```ts highlight={"3,8"} import { embed } from 'ai'; const { embedding, usage } = await embed({ model: 'openai/text-embedding-3-small', value: 'sunny day at the beach', }); console.log(usage); // { tokens: 10 } ``` ## Settings ### Provider Options Embedding model settings can be configured using `providerOptions` for provider-specific parameters: ```ts highlight={"4-8"} import { embed } from 'ai'; const { embedding } = await embed({ model: 'openai/text-embedding-3-small', value: 'sunny day at the beach', providerOptions: { openai: { dimensions: 512, // Reduce embedding dimensions }, }, }); ``` ### Parallel Requests The `embedMany` function now supports parallel processing with configurable `maxParallelCalls` to optimize performance: ```ts highlight={"3"} import { embedMany } from 'ai'; const { embeddings, usage } = await embedMany({ maxParallelCalls: 2, // Limit parallel requests model: 'openai/text-embedding-3-small', values: [ 'sunny day at the beach', 'rainy afternoon in the city', 'snowy night in the mountains', ], }); ``` ### Retries Both `embed` and `embedMany` accept an optional `maxRetries` parameter of type `number` that you can use to set the maximum number of retries for the embedding process. It defaults to `2` retries (3 attempts in total). You can set it to `0` to disable retries. ```ts highlight={"6"} import { embed } from 'ai'; const { embedding } = await embed({ model: 'openai/text-embedding-3-small', value: 'sunny day at the beach', maxRetries: 0, // Disable retries }); ``` ### Abort Signals and Timeouts Both `embed` and `embedMany` accept an optional `abortSignal` parameter of type [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that you can use to abort the embedding process or set a timeout. ```ts highlight={"6"} import { embed } from 'ai'; const { embedding } = await embed({ model: 'openai/text-embedding-3-small', value: 'sunny day at the beach', abortSignal: AbortSignal.timeout(1000), // Abort after 1 second }); ``` ### Custom Headers Both `embed` and `embedMany` accept an optional `headers` parameter of type `Record` that you can use to add custom headers to the embedding request. ```ts highlight={"6"} import { embed } from 'ai'; const { embedding } = await embed({ model: 'openai/text-embedding-3-small', value: 'sunny day at the beach', headers: { 'X-Custom-Header': 'custom-value' }, }); ``` ## Response Information Both `embed` and `embedMany` return response information that includes the raw provider response: ```ts highlight={"3,8"} import { embed } from 'ai'; const { embedding, response } = await embed({ model: 'openai/text-embedding-3-small', value: 'sunny day at the beach', }); console.log(response); // Raw provider response ``` ## Embedding Middleware You can enhance embedding models, e.g. to set default values, using `wrapEmbeddingModel` and `EmbeddingModelMiddleware`. Here is an example that uses the built-in `defaultEmbeddingSettingsMiddleware`: ```ts import { defaultEmbeddingSettingsMiddleware, embed, wrapEmbeddingModel, gateway, } from 'ai'; const embeddingModelWithDefaults = wrapEmbeddingModel({ model: gateway.embeddingModel('google/gemini-embedding-001'), middleware: defaultEmbeddingSettingsMiddleware({ settings: { providerOptions: { google: { outputDimensionality: 256, taskType: 'CLASSIFICATION', }, }, }, }), }); ``` ## Embedding Providers & Models Several providers offer embedding models: | Provider | Model | Embedding Dimensions | Multimodal | | ----------------------------------------------------------------------------------------- | ------------------------------- | -------------------- | ------------------- | | [OpenAI](/providers/ai-sdk-providers/openai#embedding-models) | `text-embedding-3-large` | 3072 | | | [OpenAI](/providers/ai-sdk-providers/openai#embedding-models) | `text-embedding-3-small` | 1536 | | | [OpenAI](/providers/ai-sdk-providers/openai#embedding-models) | `text-embedding-ada-002` | 1536 | | | [Google Generative AI](/providers/ai-sdk-providers/google-generative-ai#embedding-models) | `gemini-embedding-001` | 3072 | | | [Google Generative AI](/providers/ai-sdk-providers/google-generative-ai#embedding-models) | `gemini-embedding-2-preview` | 3072 | | | [Mistral](/providers/ai-sdk-providers/mistral#embedding-models) | `mistral-embed` | 1024 | | | [Cohere](/providers/ai-sdk-providers/cohere#embedding-models) | `embed-english-v3.0` | 1024 | | | [Cohere](/providers/ai-sdk-providers/cohere#embedding-models) | `embed-multilingual-v3.0` | 1024 | | | [Cohere](/providers/ai-sdk-providers/cohere#embedding-models) | `embed-english-light-v3.0` | 384 | | | [Cohere](/providers/ai-sdk-providers/cohere#embedding-models) | `embed-multilingual-light-v3.0` | 384 | | | [Cohere](/providers/ai-sdk-providers/cohere#embedding-models) | `embed-english-v2.0` | 4096 | | | [Cohere](/providers/ai-sdk-providers/cohere#embedding-models) | `embed-english-light-v2.0` | 1024 | | | [Cohere](/providers/ai-sdk-providers/cohere#embedding-models) | `embed-multilingual-v2.0` | 768 | | | [Amazon Bedrock](/providers/ai-sdk-providers/amazon-bedrock#embedding-models) | `amazon.titan-embed-text-v1` | 1536 | | | [Amazon Bedrock](/providers/ai-sdk-providers/amazon-bedrock#embedding-models) | `amazon.titan-embed-text-v2:0` | 1024 | |