Skip to content
PaPy

PydanticAI: Embeddings

Embedder, EmbeddingModel, EmbeddingResult, and EmbeddingSettings — generate text embeddings with every major provider using a single API.

Verified against pydantic-ai 2.68.0 (checked 2026-11-19) — source module: pydantic_ai.embeddings.

The Embedder class provides a high-level, provider-agnostic API for generating vector embeddings. Specify a model name with provider:model-name syntax and call embed_query() or embed_documents() — the same interface works across OpenAI, Cohere, Google, Bedrock, and SentenceTransformers.

import asyncio
from pydantic_ai import Embedder
embedder = Embedder('openai:text-embedding-3-small')
async def main():
result = await embedder.embed_query('What is machine learning?')
print(result.embeddings[0][:5]) # first 5 dimensions
print(result.model_name) # 'text-embedding-3-small'
print(result.usage.input_tokens) # tokens billed for the input
asyncio.run(main())

Synchronous variant:

from pydantic_ai import Embedder
embedder = Embedder('openai:text-embedding-3-small')
result = embedder.embed_query_sync('What is machine learning?')
print(result.embeddings[0][:5])
from pydantic_ai import Embedder
# OpenAI
Embedder('openai:text-embedding-3-small')
Embedder('openai:text-embedding-3-large')
Embedder('openai:text-embedding-ada-002')
# Cohere
Embedder('cohere:embed-v4.0')
Embedder('cohere:embed-english-v3.0')
Embedder('cohere:embed-multilingual-v3.0')
# Google
Embedder('google:gemini-embedding-001')
Embedder('google:gemini-embedding-2-preview')
# Amazon Bedrock
Embedder('bedrock:amazon.titan-embed-text-v2:0')
Embedder('bedrock:cohere.embed-english-v3')
# SentenceTransformers (local / no API key needed)
# pip install "pydantic-ai[sentence-transformers]"
Embedder('sentence-transformers:all-MiniLM-L6-v2')

The string form is shorthand for a model class plus a provider. Build it yourself to point at an OpenAI-compatible embeddings endpoint (Azure, vLLM, Ollama, a gateway) or to fix default settings:

from pydantic_ai import Embedder
from pydantic_ai.embeddings import EmbeddingSettings
from pydantic_ai.embeddings.openai import OpenAIEmbeddingModel
from pydantic_ai.providers.openai import OpenAIProvider
model = OpenAIEmbeddingModel(
'text-embedding-3-small',
provider=OpenAIProvider(base_url='http://localhost:11434/v1', api_key='unused'),
settings=EmbeddingSettings(dimensions=512), # also: truncate, extra_headers, extra_body
)
embedder = Embedder(model)

OpenAIEmbeddingSettings adds OpenAI-specific keys; other providers have their own model classes under pydantic_ai.embeddings (cohere, google, bedrock, voyageai, sentence_transformers).

The input_type distinction tells the model whether the text is a search query or a document to index. Providers that distinguish these (Cohere, Voyage) optimise differently:

import asyncio
import math
from pydantic_ai import Embedder
embedder = Embedder('cohere:embed-v4.0')
async def main():
# Embed a user search query
q_result = await embedder.embed_query('best Italian restaurants')
# Embed documents for indexing
docs = ['Trattoria Roma: authentic pasta', 'Osteria del Sole: seafood specialist']
d_result = await embedder.embed_documents(docs)
# Compute cosine similarity
q_vec = q_result.embeddings[0]
for i, doc_vec in enumerate(d_result.embeddings):
dot = sum(a * b for a, b in zip(q_vec, doc_vec))
norm = math.sqrt(sum(a * a for a in q_vec)) * math.sqrt(sum(b * b for b in doc_vec))
print(f'doc[{i}] similarity: {dot / norm:.4f}')
asyncio.run(main())

Pass a list to batch embed in a single API call:

from pydantic_ai import Embedder
embedder = Embedder('openai:text-embedding-3-small')
async def batch_embed(texts: list[str]) -> list[list[float]]:
result = await embedder.embed_documents(texts)
return result.embeddings # list of float vectors, one per input

EmbeddingSettings — customise model parameters

Section titled “EmbeddingSettings — customise model parameters”

EmbeddingSettings is a TypedDict with four provider-neutral keys: dimensions (output size; honoured by OpenAI, Cohere, Google, Sentence Transformers and Bedrock models that support it), truncate (whether over-long input is cut down instead of failing), extra_headers and extra_body. Provider-specific keys live on OpenAIEmbeddingSettings, CohereEmbeddingSettings and so on.

from pydantic_ai import Embedder
from pydantic_ai.embeddings import EmbeddingSettings
embedder = Embedder('openai:text-embedding-3-large', settings=EmbeddingSettings(dimensions=256))
# Per-call settings are merged over the embedder's
result = embedder.embed_query_sync('hello world', settings=EmbeddingSettings(dimensions=512))
print(len(result.embeddings[0]))
from pydantic_ai import Embedder
embedder = Embedder('openai:text-embedding-3-small')
token_count = embedder.count_tokens_sync('How many tokens is this?') # await embedder.count_tokens(...) in async code
print(token_count)
max_tokens = embedder.max_input_tokens_sync() # the model's input limit, or None if unknown
print(max_tokens)
from pydantic_ai import Embedder
embedder = Embedder('openai:text-embedding-3-small')
result = embedder.embed_query_sync('test')
result.embeddings # Sequence[Sequence[float]] — one vector per input text
result.inputs # the texts that were embedded
result.input_type # 'query' or 'document'
result.model_name # e.g. 'text-embedding-3-small'
result.provider_name # e.g. 'openai'
result.usage # RequestUsage (input_tokens, …)
result.cost() # estimated price via genai-prices (LookupError if it has no price for the model)
result.provider_details # raw provider details, if available
from pydantic_ai import Embedder
from pydantic_ai.embeddings import TestEmbeddingModel
test_model = TestEmbeddingModel(dimensions=128) # deterministic vectors, no network (default 8 dims)
embedder = Embedder(test_model)
result = embedder.embed_query_sync('anything')
print(len(result.embeddings[0])) # 128

Use embedder.override() in tests to avoid hitting the API:

from pydantic_ai import Embedder
from pydantic_ai.embeddings import TestEmbeddingModel
embedder = Embedder('openai:text-embedding-3-small')
def test_my_pipeline():
with embedder.override(model=TestEmbeddingModel(dimensions=1536)):
result = embedder.embed_query_sync('test query')
assert len(result.embeddings[0]) == 1536

Custom EmbeddingModel — implementing your own

Section titled “Custom EmbeddingModel — implementing your own”

Subclass EmbeddingModel and implement model_name, system and embed(); prepare_embed() normalises the inputs and merges settings for you. This one is a dependency-free feature-hashing model, handy as a deterministic stand-in or for keyword-style similarity:

import hashlib
import math
from collections.abc import Sequence
from pydantic_ai import Embedder
from pydantic_ai.embeddings.base import EmbeddingModel
from pydantic_ai.embeddings.result import EmbeddingResult, EmbedInputType
from pydantic_ai.embeddings.settings import EmbeddingSettings
class HashingEmbeddingModel(EmbeddingModel):
"""Bag-of-words feature hashing: each word adds 1 to one of `dim` buckets."""
def __init__(self, dim: int = 256):
super().__init__()
self._dim = dim
@property
def model_name(self) -> str:
return f'hashing-{self._dim}'
@property
def system(self) -> str:
return 'local'
def _vector(self, text: str) -> list[float]:
vec = [0.0] * self._dim
for word in text.lower().split():
vec[int(hashlib.md5(word.encode()).hexdigest(), 16) % self._dim] += 1.0
norm = math.sqrt(sum(v * v for v in vec)) or 1.0
return [v / norm for v in vec]
async def embed(
self,
inputs: str | Sequence[str],
*,
input_type: EmbedInputType,
settings: EmbeddingSettings | None = None,
) -> EmbeddingResult:
texts, _ = self.prepare_embed(inputs, settings)
return EmbeddingResult(
[self._vector(t) for t in texts],
inputs=texts,
input_type=input_type,
model_name=self.model_name,
provider_name=self.system,
)
embedder = Embedder(HashingEmbeddingModel())
result = embedder.embed_documents_sync(['the cat sat', 'a dog barked'])
print(len(result.embeddings), len(result.embeddings[0]))
#> 2 256
from pydantic_ai import Embedder
# Enable for a single embedder
embedder = Embedder('openai:text-embedding-3-small', instrument=True)
# Enable globally for all embedders created after this call
Embedder.instrument_all(True)
# Customise the settings (e.g. keep input texts out of spans)
from pydantic_ai.models.instrumented import InstrumentationSettings
Embedder.instrument_all(InstrumentationSettings(include_content=False))

A complete example: embed a corpus, embed queries, return top-k by cosine similarity.

import asyncio
import math
from pydantic_ai import Embedder
embedder = Embedder('openai:text-embedding-3-small')
def cosine_similarity(a: list[float], b: list[float]) -> float:
dot = sum(x * y for x, y in zip(a, b))
norm_a = math.sqrt(sum(x * x for x in a))
norm_b = math.sqrt(sum(x * x for x in b))
return dot / (norm_a * norm_b + 1e-9)
async def build_and_search(corpus: list[str], query: str, top_k: int = 3):
corpus_result = await embedder.embed_documents(corpus)
query_result = await embedder.embed_query(query)
q_vec = query_result.embeddings[0]
scored = [
(cosine_similarity(q_vec, doc_vec), doc)
for doc_vec, doc in zip(corpus_result.embeddings, corpus)
]
scored.sort(reverse=True)
return scored[:top_k]
docs = [
'Python is a high-level programming language.',
'Machine learning uses statistical methods.',
'The Eiffel Tower is in Paris.',
'Deep learning is a subset of machine learning.',
]
async def main():
results = await build_and_search(docs, 'neural networks and deep learning')
for score, doc in results:
print(f'{score:.3f} {doc}')
asyncio.run(main())

Generate embeddings alongside an agent run to persist semantic representations of agent outputs:

import asyncio
from pydantic_ai import Agent, Embedder
agent = Agent('openai:gpt-6.1-sol', output_type=str)
embedder = Embedder('openai:text-embedding-3-small')
async def run_and_embed(prompt: str):
result = await agent.run(prompt)
embedding = await embedder.embed_documents([result.output])
return result.output, embedding.embeddings[0]
asyncio.run(run_and_embed('Summarise the Python programming language in one sentence.'))

VoyageAI embeddings — domain-specific models

Section titled “VoyageAI embeddings — domain-specific models”

VoyageAI offers specialised embedding models for code, legal text, and finance:

# pip install "pydantic-ai-slim[voyageai]" (needs VOYAGE_API_KEY)
import asyncio
from pydantic_ai import Embedder
async def main():
# General-purpose, high quality
gen_embedder = Embedder('voyageai:voyage-4')
# Optimised for code snippets
code_embedder = Embedder('voyageai:voyage-code-3')
# Optimised for legal documents
legal_embedder = Embedder('voyageai:voyage-law-2')
code_snippet = 'def fibonacci(n): return n if n <= 1 else fibonacci(n-1) + fibonacci(n-2)'
result = await code_embedder.embed_query(code_snippet)
print(f'Code embedding dimensions: {len(result.embeddings[0])}')
asyncio.run(main())

Cohere’s models embed multiple languages into the same vector space, enabling cross-lingual retrieval:

import asyncio
from pydantic_ai import Embedder
embedder = Embedder('cohere:embed-multilingual-v3.0')
async def cross_lingual_search():
# Documents in different languages
docs = [
'Python is a high-level programming language.', # English
'Python est un langage de programmation de haut niveau.', # French
'Python ist eine höhere Programmiersprache.', # German
'Pythonは高レベルのプログラミング言語です。', # Japanese
]
# Query in English — finds semantically similar docs in all languages
doc_result = await embedder.embed_documents(docs)
query_result = await embedder.embed_query('high level scripting language')
import math
def cosine_sim(a, b):
dot = sum(x*y for x, y in zip(a, b))
return dot / (math.sqrt(sum(x*x for x in a)) * math.sqrt(sum(x*x for x in b)) + 1e-9)
q_vec = query_result.embeddings[0]
scored = sorted(
[(cosine_sim(q_vec, dvec), doc) for dvec, doc in zip(doc_result.embeddings, docs)],
reverse=True,
)
for score, doc in scored:
print(f'{score:.4f} {doc[:60]}')
asyncio.run(cross_lingual_search())

EmbeddingResult — full property reference

Section titled “EmbeddingResult — full property reference”
import asyncio
from pydantic_ai import Embedder
embedder = Embedder('openai:text-embedding-3-small')
async def main():
result = await embedder.embed_query('What is machine learning?')
# Core embedding data
print(result.embeddings) # list[list[float]] — one vector per input
print(result.inputs) # list[str] — the original input texts
print(result.input_type) # 'query' or 'document'
# Model metadata
print(result.model_name) # e.g. 'text-embedding-3-small'
print(result.provider_name) # e.g. 'openai'
print(result.timestamp) # datetime of the request
# Usage statistics
print(result.usage.input_tokens) # tokens consumed (embeddings have no output tokens)
# Provider-specific metadata
print(result.provider_details) # raw provider response dict, or None
print(result.provider_response_id) # provider's response ID, or None
# Access by index or by input text
print(result[0]) # first embedding vector
print(result['What is machine learning?']) # embedding for this exact input
asyncio.run(main())

Embedding multiple input types in one call

Section titled “Embedding multiple input types in one call”
import asyncio
from pydantic_ai import Embedder
from pydantic_ai.embeddings.result import EmbedInputType
embedder = Embedder('openai:text-embedding-3-large')
async def embed_mixed_corpus():
"""Embed a corpus with explicit input_type control."""
# Documents for indexing — use 'document' type for best retrieval performance
documents = [
'Introduction to machine learning with Python.',
'Advanced neural network architectures.',
'Practical data preprocessing techniques.',
]
doc_result = await embedder.embed(
documents,
input_type='document',
)
print(f'Embedded {len(doc_result.embeddings)} documents')
print(f'Input type: {doc_result.input_type}') # 'document'
# Single query — use 'query' type
query_result = await embedder.embed(
'deep learning best practices',
input_type='query',
)
print(f'Query embedding dims: {len(query_result.embeddings[0])}')
asyncio.run(embed_mixed_corpus())

OpenAI’s text-embedding-3-* models support truncating the output dimension. Lower dimensions reduce storage and similarity computation cost with minimal quality loss:

import asyncio
from pydantic_ai import Embedder
from pydantic_ai.embeddings import EmbeddingSettings
async def main():
# Full dimensions: 3072 for text-embedding-3-large
full_embedder = Embedder('openai:text-embedding-3-large')
full_result = await full_embedder.embed_query('hello world')
print(f'Full dims: {len(full_result.embeddings[0])}') # 3072
# Reduced to 256 dims — 12x smaller, still high quality
compact_embedder = Embedder(
'openai:text-embedding-3-large',
settings=EmbeddingSettings(dimensions=256),
)
compact_result = await compact_embedder.embed_query('hello world')
print(f'Compact dims: {len(compact_result.embeddings[0])}') # 256
asyncio.run(main())
import asyncio
from pydantic_ai import Embedder
embedder = Embedder('openai:text-embedding-3-small')
async def embed_corpus_in_batches(
texts: list[str],
batch_size: int = 100,
) -> list[list[float]]:
"""Embed a large corpus in batches to avoid rate limits."""
all_vectors: list[list[float]] = []
for i in range(0, len(texts), batch_size):
batch = texts[i:i + batch_size]
result = await embedder.embed_documents(batch)
all_vectors.extend(result.embeddings)
print(f'Processed {min(i + batch_size, len(texts))}/{len(texts)} texts')
return all_vectors
async def main():
corpus = [f'Document about topic {i}' for i in range(350)]
vectors = await embed_corpus_in_batches(corpus, batch_size=100)
print(f'Total vectors: {len(vectors)}, each dim: {len(vectors[0])}')
asyncio.run(main())

End-to-end example: embed a knowledge base, then use an agent to answer questions via semantic search:

import asyncio
import math
from pydantic_ai import Agent, Embedder, RunContext
from dataclasses import dataclass, field
@dataclass
class KnowledgeBase:
documents: list[str]
vectors: list[list[float]] = field(default_factory=list)
def cosine_similarity(self, a: list[float], b: list[float]) -> float:
dot = sum(x * y for x, y in zip(a, b))
na = math.sqrt(sum(x * x for x in a))
nb = math.sqrt(sum(x * x for x in b))
return dot / (na * nb + 1e-9)
def search(self, query_vec: list[float], top_k: int = 3) -> list[str]:
scored = [
(self.cosine_similarity(query_vec, doc_vec), doc)
for doc_vec, doc in zip(self.vectors, self.documents)
]
scored.sort(reverse=True)
return [doc for _, doc in scored[:top_k]]
embedder = Embedder('openai:text-embedding-3-small')
agent = Agent('openai:gpt-6.1-sol', deps_type=KnowledgeBase)
@agent.system_prompt
def knowledge_base_prompt(ctx: RunContext[KnowledgeBase]) -> str:
return f'You answer questions using a knowledge base of {len(ctx.deps.documents)} documents.'
@agent.tool
async def retrieve_docs(ctx: RunContext[KnowledgeBase], query: str) -> list[str]:
"""Search the knowledge base for relevant documents."""
query_result = await embedder.embed_query(query)
return ctx.deps.search(query_result.embeddings[0], top_k=3)
async def main():
# Build knowledge base
docs = [
'Python was created by Guido van Rossum and first released in 1991.',
'Python 3.0 was released in 2008 and broke backward compatibility with Python 2.',
'PEP 8 is the official Python style guide, promoting code readability.',
'Python uses indentation to define code blocks instead of braces.',
'The Python Package Index (PyPI) hosts over 500,000 packages.',
]
kb = KnowledgeBase(documents=docs)
kb_result = await embedder.embed_documents(docs)
kb.vectors = list(kb_result.embeddings)
result = await agent.run('When was Python first released?', deps=kb)
print(result.output)
asyncio.run(main())
SymbolModuleNotes
Embedderpydantic_ai.embeddingsHigh-level embedding interface
EmbeddingModelpydantic_ai.embeddingsAbstract base — subclass for custom models
EmbeddingResultpydantic_ai.embeddingsHolds embeddings, inputs, input_type, model_name, provider_name, usage; cost()
EmbeddingSettingspydantic_ai.embeddingsdimensions, truncate, extra_headers, extra_body
TestEmbeddingModelpydantic_ai.embeddingsDeterministic unit vectors for tests
KnownEmbeddingModelNamepydantic_ai.embeddingsLiteral type of all known model strings
WrapperEmbeddingModelpydantic_ai.embeddingsBase class for custom model wrappers
InstrumentedEmbeddingModelpydantic_ai.embeddingsOTel-instrumented model wrapper