Embeddings and Reranking

Purpose and Scope

Embeddings turn values such as text, phrases, or images into numeric vectors that can be compared, clustered, indexed, or passed into later retrieval workflows. In the AI SDK, the simplest public entry point is embed, which generates one embedding for one value using an embedding model. The reference page positions this as the right API when a caller needs a single vector for finding similar items or for a downstream task that expects vector input. Sources: content/docs/07-reference/01-ai-sdk-core/05-embed.mdx

Reranking solves a related but different problem. Instead of creating vectors for long-term storage, a reranking model receives a query and a set of candidate documents, then returns those documents ordered by relevance. In retrieval-augmented generation, embeddings are often used first to find plausible candidates from a vector store, while reranking is used second to improve precision before sending context to a language model. Cosine similarity is the common scoring technique for comparing embedding vectors when the application owns the vector search step.

Relevant Source Files

• content/docs/07-reference/01-ai-sdk-core/05-embed.mdx — API reference for embed(), including its import, single-value example, parameters, retry and cancellation controls, provider options, telemetry controls, and lifecycle callbacks.

Core Primitives

The core primitive on this page is embed, imported from ai. It accepts an EmbeddingModel and a value, then returns an object containing embedding, a numeric vector for the supplied value. The documentation example uses model: 'openai/text-embedding-3-small' and value: 'sunny day at the beach', demonstrating the provider-agnostic model string form. The same reference also notes that provider package factories can supply embedding models, for example an OpenAI embedding model factory. Sources: content/docs/07-reference/01-ai-sdk-core/05-embed.mdx

embedMany is the batching counterpart used when loading or processing multiple values. A typical ingestion pipeline reads documents, chunks them, calls an embedding model for the chunks, and writes the resulting vectors into a database or search index. The distinction matters operationally: embed is easy to use for an individual query or one-off comparison, while embedMany is better suited to bulk preparation where the application wants consistent model settings across many values and fewer application-level loops.

Cosine similarity is not a model call; it is a vector comparison. After two values have embeddings, cosine similarity measures how close their directions are in vector space. That makes it useful for local ranking, deduplication, nearest-neighbor search, semantic cache lookup, and lightweight relevance scoring. The AI SDK’s embedding functions provide the vectors, while the application or vector database decides how to store, compare, filter, and combine those vectors with metadata such as tenant, document type, timestamp, or permissions.

API Components

The embed reference exposes a compact but important call surface. Required fields are model, typed as EmbeddingModel, and value, whose type depends on the selected model. Optional reliability and transport controls include maxRetries, where 0 disables retries and the default is 2, abortSignal for cancellation, and headers for extra HTTP headers with HTTP-based providers. providerOptions carries provider-specific settings through the unified AI SDK call shape. Sources: content/docs/07-reference/01-ai-sdk-core/05-embed.mdx

Telemetry and lifecycle hooks are also part of the public contract. telemetry can enable or disable telemetry, control input and output recording, assign a functionId, and provide per-call telemetry integrations. The onStart callback receives an EmbedStartEvent before the model is called, including identifiers such as callId and an operation id for the embedding operation. The reference states that errors thrown from this callback are silently caught, so instrumentation should not be used as the only enforcement point for business-critical validation. Sources: content/docs/07-reference/01-ai-sdk-core/05-embed.mdx

Compact reference

Execution Flow

A common retrieval flow starts during ingestion. The application splits source content into chunks, normalizes each chunk with metadata, and calls an embedding model to produce vectors. For a small or interactive path, embed can create one vector; for larger ingestion work, embedMany is the natural fit. Those vectors are then written to a vector database, a relational database extension, or an in-memory index, along with document identifiers and authorization metadata that should be checked before results are shown or used.

At query time, the application embeds the user query, compares that query vector with stored document vectors, and retrieves the top candidates. Cosine similarity can be used directly when the application performs comparison itself, or indirectly through a vector database that implements nearest-neighbor search. The result of this stage should be treated as candidate retrieval, not final answer generation. Candidate lists frequently need filtering by access control, freshness, product area, language, or source quality before they are passed on.

Reranking fits after candidate retrieval. The application sends the user query and candidate documents to a reranking model, optionally limiting the response with topN. The supplied official Cohere example uses cohere.reranking('rerank-v3.5') with rerank, returning items that include originalIndex, score, and document. That shape is useful because callers can preserve the relationship between the reranked item and the original candidate list, then fetch full records, citations, or metadata for the final prompt.

import { embed } from 'ai';
 
const { embedding } = await embed({
  model: 'openai/text-embedding-3-small',
  value: 'sunny day at the beach',
});

import { rerank } from 'ai';
import { cohere } from '@ai-sdk/cohere';
 
const { ranking } = await rerank({
  model: cohere.reranking('rerank-v3.5'),
  documents: [
    'sunny day at the beach',
    'rainy afternoon in the city',
    'snowy night in the mountains',
  ],
  query: 'talk about rain',
  topN: 2,
});

Provider Capabilities and Options

Embedding support depends on the selected provider and model. The embed API accepts the abstract EmbeddingModel, which lets the application keep its call site stable while switching provider packages or model identifiers. Provider options are deliberately passed through under providerOptions, so model-specific controls do not have to become top-level AI SDK parameters. This is the same pattern used across other AI SDK Core APIs: keep the cross-provider contract small, then allow provider-specific capabilities where a model exposes them. Sources: content/docs/07-reference/01-ai-sdk-core/05-embed.mdx

Reranking support is provider-specific as well. The supplied Cohere documentation shows reranking models created with cohere.reranking('rerank-v3.5'), and it documents Cohere-specific options under providerOptions.cohere, including maxTokensPerDoc and priority. That distinction is important when designing portable code. The application can keep the high-level retrieval pipeline provider-agnostic, but provider-specific tuning should be isolated at the model construction or call-options boundary so it can be changed without rewriting the rest of the pipeline.

Implementation Guidance and Next Steps

Use embed for single-query vectors, one-off semantic comparisons, or small downstream tasks where the caller immediately needs one embedding. Use embedMany when preparing a corpus, because batching values keeps ingestion logic explicit and makes it easier to track which vector belongs to which chunk. Use cosine similarity when the application controls vector comparison, and use reranking when the first retrieval step returns too many plausible but loosely matched candidates. These tools compose best when each stage has a clear responsibility.

For production retrieval, do not rely on vector scores alone. Store metadata with each vector, filter candidates before reranking, preserve original document identifiers, and log enough information to debug poor matches. If the call is user-facing, pass abortSignal so cancelled requests can stop work, configure maxRetries according to latency requirements, and use telemetry settings intentionally when inputs or outputs contain sensitive content. Sources: content/docs/07-reference/01-ai-sdk-core/05-embed.mdx

Next, read the provider pages for the embedding or reranking model you plan to use, then connect this page with the broader Core references for generateText, tool calling, and provider options. In a retrieval-augmented application, embeddings and reranking usually feed the context-selection stage, while text generation turns that selected context into the final answer.