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.
Minimal runnable example
Section titled “Minimal runnable example”import asynciofrom 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])Provider prefixes
Section titled “Provider prefixes”from pydantic_ai import Embedder
# OpenAIEmbedder('openai:text-embedding-3-small')Embedder('openai:text-embedding-3-large')Embedder('openai:text-embedding-ada-002')
# CohereEmbedder('cohere:embed-v4.0')Embedder('cohere:embed-english-v3.0')Embedder('cohere:embed-multilingual-v3.0')
# GoogleEmbedder('google:gemini-embedding-001')Embedder('google:gemini-embedding-2-preview')
# Amazon BedrockEmbedder('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')Explicit model construction
Section titled “Explicit model construction”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 Embedderfrom pydantic_ai.embeddings import EmbeddingSettingsfrom pydantic_ai.embeddings.openai import OpenAIEmbeddingModelfrom 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).
embed_query vs embed_documents
Section titled “embed_query vs embed_documents”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 asyncioimport 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())Embedding multiple texts at once
Section titled “Embedding multiple texts at once”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 inputEmbeddingSettings — 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 Embedderfrom pydantic_ai.embeddings import EmbeddingSettings
embedder = Embedder('openai:text-embedding-3-large', settings=EmbeddingSettings(dimensions=256))
# Per-call settings are merged over the embedder'sresult = embedder.embed_query_sync('hello world', settings=EmbeddingSettings(dimensions=512))print(len(result.embeddings[0]))Token counting
Section titled “Token counting”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 codeprint(token_count)
max_tokens = embedder.max_input_tokens_sync() # the model's input limit, or None if unknownprint(max_tokens)EmbeddingResult — what you get back
Section titled “EmbeddingResult — what you get back”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 textresult.inputs # the texts that were embeddedresult.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 availableTesting with TestEmbeddingModel
Section titled “Testing with TestEmbeddingModel”from pydantic_ai import Embedderfrom 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])) # 128Use embedder.override() in tests to avoid hitting the API:
from pydantic_ai import Embedderfrom 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]) == 1536Custom 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 hashlibimport mathfrom collections.abc import Sequence
from pydantic_ai import Embedderfrom pydantic_ai.embeddings.base import EmbeddingModelfrom pydantic_ai.embeddings.result import EmbeddingResult, EmbedInputTypefrom 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 256OpenTelemetry instrumentation
Section titled “OpenTelemetry instrumentation”from pydantic_ai import Embedder
# Enable for a single embedderembedder = Embedder('openai:text-embedding-3-small', instrument=True)
# Enable globally for all embedders created after this callEmbedder.instrument_all(True)
# Customise the settings (e.g. keep input texts out of spans)from pydantic_ai.models.instrumented import InstrumentationSettingsEmbedder.instrument_all(InstrumentationSettings(include_content=False))Similarity search pipeline
Section titled “Similarity search pipeline”A complete example: embed a corpus, embed queries, return top-k by cosine similarity.
import asyncioimport mathfrom 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())Hybrid: embeddings + agent output
Section titled “Hybrid: embeddings + agent output”Generate embeddings alongside an agent run to persist semantic representations of agent outputs:
import asynciofrom 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 asynciofrom 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 multi-lingual embeddings
Section titled “Cohere multi-lingual embeddings”Cohere’s models embed multiple languages into the same vector space, enabling cross-lingual retrieval:
import asynciofrom 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 asynciofrom 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 asynciofrom pydantic_ai import Embedderfrom 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())Dimensionality reduction with OpenAI
Section titled “Dimensionality reduction with OpenAI”OpenAI’s text-embedding-3-* models support truncating the output dimension. Lower dimensions reduce storage and similarity computation cost with minimal quality loss:
import asynciofrom pydantic_ai import Embedderfrom 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())Production batch processing
Section titled “Production batch processing”import asynciofrom 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())Complete RAG pipeline
Section titled “Complete RAG pipeline”End-to-end example: embed a knowledge base, then use an agent to answer questions via semantic search:
import asyncioimport mathfrom pydantic_ai import Agent, Embedder, RunContextfrom dataclasses import dataclass, field
@dataclassclass 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_promptdef knowledge_base_prompt(ctx: RunContext[KnowledgeBase]) -> str: return f'You answer questions using a knowledge base of {len(ctx.deps.documents)} documents.'
@agent.toolasync 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())Reference
Section titled “Reference”| Symbol | Module | Notes |
|---|---|---|
Embedder | pydantic_ai.embeddings | High-level embedding interface |
EmbeddingModel | pydantic_ai.embeddings | Abstract base — subclass for custom models |
EmbeddingResult | pydantic_ai.embeddings | Holds embeddings, inputs, input_type, model_name, provider_name, usage; cost() |
EmbeddingSettings | pydantic_ai.embeddings | dimensions, truncate, extra_headers, extra_body |
TestEmbeddingModel | pydantic_ai.embeddings | Deterministic unit vectors for tests |
KnownEmbeddingModelName | pydantic_ai.embeddings | Literal type of all known model strings |
WrapperEmbeddingModel | pydantic_ai.embeddings | Base class for custom model wrappers |
InstrumentedEmbeddingModel | pydantic_ai.embeddings | OTel-instrumented model wrapper |