[ Skip to content ](https://ai.pydantic.dev/embeddings/#embeddings)
**Join us at the inaugural PyAI Conf in San Francisco on March 10th![Learn More](https://pyai.events/?utm_source=pydantic-ai) **
[ ![logo](https://ai.pydantic.dev/img/logo-white.svg) ](https://ai.pydantic.dev/ "Pydantic AI")
Pydantic AI
Embeddings
Type to start searching
[ pydantic/pydantic-ai
  * v1.63.0
  * 15.1k
  * 1.7k

](https://github.com/pydantic/pydantic-ai "Go to repository")
[ ![logo](https://ai.pydantic.dev/img/logo-white.svg) ](https://ai.pydantic.dev/ "Pydantic AI") Pydantic AI
[ pydantic/pydantic-ai
  * v1.63.0
  * 15.1k
  * 1.7k

](https://github.com/pydantic/pydantic-ai "Go to repository")
  * [ Pydantic AI  ](https://ai.pydantic.dev/)
  * [ Installation  ](https://ai.pydantic.dev/install/)
  * [ Getting Help  ](https://ai.pydantic.dev/help/)
  * [ Troubleshooting  ](https://ai.pydantic.dev/troubleshooting/)
  * [ Pydantic AI Gateway  ](https://ai.pydantic.dev/gateway/)
  * Documentation
    * Core Concepts
      * [ Agents  ](https://ai.pydantic.dev/agent/)
      * [ Dependencies  ](https://ai.pydantic.dev/dependencies/)
      * [ Function Tools  ](https://ai.pydantic.dev/tools/)
      * [ Output  ](https://ai.pydantic.dev/output/)
      * [ Messages and chat history  ](https://ai.pydantic.dev/message-history/)
      * [ Direct Model Requests  ](https://ai.pydantic.dev/direct/)
    * Models & Providers
      * [ Overview  ](https://ai.pydantic.dev/models/overview/)
      * [ OpenAI  ](https://ai.pydantic.dev/models/openai/)
      * [ Anthropic  ](https://ai.pydantic.dev/models/anthropic/)
      * [ Google  ](https://ai.pydantic.dev/models/google/)
      * [ xAI  ](https://ai.pydantic.dev/models/xai/)
      * [ Bedrock  ](https://ai.pydantic.dev/models/bedrock/)
      * [ Cerebras  ](https://ai.pydantic.dev/models/cerebras/)
      * [ Cohere  ](https://ai.pydantic.dev/models/cohere/)
      * [ Groq  ](https://ai.pydantic.dev/models/groq/)
      * [ Hugging Face  ](https://ai.pydantic.dev/models/huggingface/)
      * [ Mistral  ](https://ai.pydantic.dev/models/mistral/)
      * [ OpenRouter  ](https://ai.pydantic.dev/models/openrouter/)
      * [ Outlines  ](https://ai.pydantic.dev/models/outlines/)
    * Tools & Toolsets
      * [ Function Tools  ](https://ai.pydantic.dev/tools/)
      * [ Advanced Tool Features  ](https://ai.pydantic.dev/tools-advanced/)
      * [ Toolsets  ](https://ai.pydantic.dev/toolsets/)
      * [ Deferred Tools  ](https://ai.pydantic.dev/deferred-tools/)
      * [ Built-in Tools  ](https://ai.pydantic.dev/builtin-tools/)
      * [ Common Tools  ](https://ai.pydantic.dev/common-tools/)
      * [ Third-Party Tools  ](https://ai.pydantic.dev/third-party-tools/)
    * Advanced Features
      * [ Image, Audio, Video & Document Input  ](https://ai.pydantic.dev/input/)
      * [ Thinking  ](https://ai.pydantic.dev/thinking/)
      * [ HTTP Request Retries  ](https://ai.pydantic.dev/retries/)
    * MCP
      * [ Overview  ](https://ai.pydantic.dev/mcp/overview/)
      * [ Client  ](https://ai.pydantic.dev/mcp/client/)
      * [ FastMCP Client  ](https://ai.pydantic.dev/mcp/fastmcp-client/)
      * [ Server  ](https://ai.pydantic.dev/mcp/server/)
    * [ Multi-Agent Patterns  ](https://ai.pydantic.dev/multi-agent-applications/)
    * [ Web Chat UI  ](https://ai.pydantic.dev/web/)
    * Embeddings  [ Embeddings  ](https://ai.pydantic.dev/embeddings/)
      * [ Quick Start  ](https://ai.pydantic.dev/embeddings/#quick-start)
      * [ Embedding Result  ](https://ai.pydantic.dev/embeddings/#embedding-result)
      * [ Providers  ](https://ai.pydantic.dev/embeddings/#providers)
        * [ OpenAI  ](https://ai.pydantic.dev/embeddings/#openai)
          * [ Install  ](https://ai.pydantic.dev/embeddings/#install)
          * [ Configuration  ](https://ai.pydantic.dev/embeddings/#configuration)
          * [ Dimension Control  ](https://ai.pydantic.dev/embeddings/#dimension-control)
          * [ OpenAI-Compatible Providers  ](https://ai.pydantic.dev/embeddings/#openai-compatible)
        * [ Google  ](https://ai.pydantic.dev/embeddings/#google)
          * [ Install  ](https://ai.pydantic.dev/embeddings/#install_1)
          * [ Configuration  ](https://ai.pydantic.dev/embeddings/#configuration_1)
            * [ Vertex AI  ](https://ai.pydantic.dev/embeddings/#vertex-ai)
          * [ Dimension Control  ](https://ai.pydantic.dev/embeddings/#dimension-control_1)
          * [ Google-Specific Settings  ](https://ai.pydantic.dev/embeddings/#google-specific-settings)
        * [ Cohere  ](https://ai.pydantic.dev/embeddings/#cohere)
          * [ Install  ](https://ai.pydantic.dev/embeddings/#install_2)
          * [ Configuration  ](https://ai.pydantic.dev/embeddings/#configuration_2)
          * [ Cohere-Specific Settings  ](https://ai.pydantic.dev/embeddings/#cohere-specific-settings)
        * [ VoyageAI  ](https://ai.pydantic.dev/embeddings/#voyageai)
          * [ Install  ](https://ai.pydantic.dev/embeddings/#install_3)
          * [ Configuration  ](https://ai.pydantic.dev/embeddings/#configuration_3)
          * [ VoyageAI-Specific Settings  ](https://ai.pydantic.dev/embeddings/#voyageai-specific-settings)
        * [ Bedrock  ](https://ai.pydantic.dev/embeddings/#bedrock)
          * [ Install  ](https://ai.pydantic.dev/embeddings/#install_4)
          * [ Configuration  ](https://ai.pydantic.dev/embeddings/#configuration_4)
          * [ Basic Usage  ](https://ai.pydantic.dev/embeddings/#basic-usage)
          * [ Supported Models  ](https://ai.pydantic.dev/embeddings/#supported-models)
          * [ Titan-Specific Settings  ](https://ai.pydantic.dev/embeddings/#titan-specific-settings)
          * [ Cohere-Specific Settings  ](https://ai.pydantic.dev/embeddings/#cohere-specific-settings_1)
          * [ Nova-Specific Settings  ](https://ai.pydantic.dev/embeddings/#nova-specific-settings)
          * [ Concurrency Settings  ](https://ai.pydantic.dev/embeddings/#concurrency-settings)
          * [ Regional Prefixes (Cross-Region Inference)  ](https://ai.pydantic.dev/embeddings/#regional-prefixes-cross-region-inference)
          * [ Using a Custom Provider  ](https://ai.pydantic.dev/embeddings/#using-a-custom-provider)
        * [ Sentence Transformers (Local)  ](https://ai.pydantic.dev/embeddings/#sentence-transformers-local)
          * [ Install  ](https://ai.pydantic.dev/embeddings/#install_5)
          * [ Usage  ](https://ai.pydantic.dev/embeddings/#usage)
          * [ Device Selection  ](https://ai.pydantic.dev/embeddings/#device-selection)
          * [ Using an Existing Model Instance  ](https://ai.pydantic.dev/embeddings/#using-an-existing-model-instance)
      * [ Settings  ](https://ai.pydantic.dev/embeddings/#settings)
      * [ Token Counting  ](https://ai.pydantic.dev/embeddings/#token-counting)
      * [ Testing  ](https://ai.pydantic.dev/embeddings/#testing)
      * [ Instrumentation  ](https://ai.pydantic.dev/embeddings/#instrumentation)
      * [ Building Custom Embedding Models  ](https://ai.pydantic.dev/embeddings/#building-custom-embedding-models)
    * [ Testing  ](https://ai.pydantic.dev/testing/)
  * Pydantic Evals
    * [ Overview  ](https://ai.pydantic.dev/evals/)
    * Getting Started
      * [ Quick Start  ](https://ai.pydantic.dev/evals/quick-start/)
      * [ Core Concepts  ](https://ai.pydantic.dev/evals/core-concepts/)
    * Evaluators
      * [ Overview  ](https://ai.pydantic.dev/evals/evaluators/overview/)
      * [ Built-in Evaluators  ](https://ai.pydantic.dev/evals/evaluators/built-in/)
      * [ LLM Judge  ](https://ai.pydantic.dev/evals/evaluators/llm-judge/)
      * [ Custom Evaluators  ](https://ai.pydantic.dev/evals/evaluators/custom/)
      * [ Report Evaluators  ](https://ai.pydantic.dev/evals/evaluators/report-evaluators/)
      * [ Span-Based  ](https://ai.pydantic.dev/evals/evaluators/span-based/)
    * How-To Guides
      * [ Logfire Integration  ](https://ai.pydantic.dev/evals/how-to/logfire-integration/)
      * [ Dataset Management  ](https://ai.pydantic.dev/evals/how-to/dataset-management/)
      * [ Dataset Serialization  ](https://ai.pydantic.dev/evals/how-to/dataset-serialization/)
      * [ Concurrency & Performance  ](https://ai.pydantic.dev/evals/how-to/concurrency/)
      * [ Multi-Run Evaluation  ](https://ai.pydantic.dev/evals/how-to/multi-run/)
      * [ Retry Strategies  ](https://ai.pydantic.dev/evals/how-to/retry-strategies/)
      * [ Metrics & Attributes  ](https://ai.pydantic.dev/evals/how-to/metrics-attributes/)
    * Examples
      * [ Simple Validation  ](https://ai.pydantic.dev/evals/examples/simple-validation/)
  * Pydantic Graph
    * [ Overview  ](https://ai.pydantic.dev/graph/)
    * [ Beta API  ](https://ai.pydantic.dev/graph/beta/)
      * [ Steps  ](https://ai.pydantic.dev/graph/beta/steps/)
      * [ Joins & Reducers  ](https://ai.pydantic.dev/graph/beta/joins/)
      * [ Decisions  ](https://ai.pydantic.dev/graph/beta/decisions/)
      * [ Parallel Execution  ](https://ai.pydantic.dev/graph/beta/parallel/)
  * Integrations
    * [ Debugging & Monitoring with Pydantic Logfire  ](https://ai.pydantic.dev/logfire/)
    * Durable Execution
      * [ Overview  ](https://ai.pydantic.dev/durable_execution/overview/)
      * [ Temporal  ](https://ai.pydantic.dev/durable_execution/temporal/)
      * [ DBOS  ](https://ai.pydantic.dev/durable_execution/dbos/)
      * [ Prefect  ](https://ai.pydantic.dev/durable_execution/prefect/)
    * UI Event Streams
      * [ Overview  ](https://ai.pydantic.dev/ui/overview/)
      * [ AG-UI  ](https://ai.pydantic.dev/ui/ag-ui/)
      * [ Vercel AI  ](https://ai.pydantic.dev/ui/vercel-ai/)
    * [ Agent2Agent (A2A)  ](https://ai.pydantic.dev/a2a/)
  * Related Packages
    * [ clai  ](https://ai.pydantic.dev/cli/)
  * Examples
    * [ Setup  ](https://ai.pydantic.dev/examples/setup/)
    * Getting Started
      * [ Pydantic Model  ](https://ai.pydantic.dev/examples/pydantic-model/)
      * [ Weather agent  ](https://ai.pydantic.dev/examples/weather-agent/)
    * Conversational Agents
      * [ Chat App with FastAPI  ](https://ai.pydantic.dev/examples/chat-app/)
      * [ Bank support  ](https://ai.pydantic.dev/examples/bank-support/)
    * Data & Analytics
      * [ SQL Generation  ](https://ai.pydantic.dev/examples/sql-gen/)
      * [ Data Analyst  ](https://ai.pydantic.dev/examples/data-analyst/)
      * [ RAG  ](https://ai.pydantic.dev/examples/rag/)
    * Streaming
      * [ Stream markdown  ](https://ai.pydantic.dev/examples/stream-markdown/)
      * [ Stream whales  ](https://ai.pydantic.dev/examples/stream-whales/)
    * Complex Workflows
      * [ Flight booking  ](https://ai.pydantic.dev/examples/flight-booking/)
      * [ Question Graph  ](https://ai.pydantic.dev/examples/question-graph/)
    * Business Applications
      * [ Slack Lead Qualifier with Modal  ](https://ai.pydantic.dev/examples/slack-lead-qualifier/)
    * UI Examples
      * [ Agent User Interaction (AG-UI)  ](https://ai.pydantic.dev/examples/ag-ui/)
  * API Reference
    * pydantic_ai
      * [ pydantic_ai.ag_ui  ](https://ai.pydantic.dev/api/ag_ui/)
      * [ pydantic_ai.agent  ](https://ai.pydantic.dev/api/agent/)
      * [ pydantic_ai.builtin_tools  ](https://ai.pydantic.dev/api/builtin_tools/)
      * [ pydantic_ai.common_tools  ](https://ai.pydantic.dev/api/common_tools/)
      * [ pydantic_ai — Concurrency  ](https://ai.pydantic.dev/api/concurrency/)
      * [ pydantic_ai.direct  ](https://ai.pydantic.dev/api/direct/)
      * [ pydantic_ai.durable_exec  ](https://ai.pydantic.dev/api/durable_exec/)
      * [ pydantic_ai.embeddings  ](https://ai.pydantic.dev/api/embeddings/)
      * [ pydantic_ai.exceptions  ](https://ai.pydantic.dev/api/exceptions/)
      * [ pydantic_ai.ext  ](https://ai.pydantic.dev/api/ext/)
      * [ pydantic_ai.format_prompt  ](https://ai.pydantic.dev/api/format_prompt/)
      * [ pydantic_ai.mcp  ](https://ai.pydantic.dev/api/mcp/)
      * [ pydantic_ai.messages  ](https://ai.pydantic.dev/api/messages/)
      * [ pydantic_ai.models.anthropic  ](https://ai.pydantic.dev/api/models/anthropic/)
      * [ pydantic_ai.models  ](https://ai.pydantic.dev/api/models/base/)
      * [ pydantic_ai.models.bedrock  ](https://ai.pydantic.dev/api/models/bedrock/)
      * [ pydantic_ai.models.cerebras  ](https://ai.pydantic.dev/api/models/cerebras/)
      * [ pydantic_ai.models.cohere  ](https://ai.pydantic.dev/api/models/cohere/)
      * [ pydantic_ai.models.fallback  ](https://ai.pydantic.dev/api/models/fallback/)
      * [ pydantic_ai.models.function  ](https://ai.pydantic.dev/api/models/function/)
      * [ pydantic_ai.models.google  ](https://ai.pydantic.dev/api/models/google/)
      * [ pydantic_ai.models.xai  ](https://ai.pydantic.dev/api/models/xai/)
      * [ pydantic_ai.models.groq  ](https://ai.pydantic.dev/api/models/groq/)
      * [ pydantic_ai.models.huggingface  ](https://ai.pydantic.dev/api/models/huggingface/)
      * [ pydantic_ai.models.instrumented  ](https://ai.pydantic.dev/api/models/instrumented/)
      * [ pydantic_ai.models.mcp_sampling  ](https://ai.pydantic.dev/api/models/mcp-sampling/)
      * [ pydantic_ai.models.mistral  ](https://ai.pydantic.dev/api/models/mistral/)
      * [ pydantic_ai.models.openai  ](https://ai.pydantic.dev/api/models/openai/)
      * [ pydantic_ai.models.openrouter  ](https://ai.pydantic.dev/api/models/openrouter/)
      * [ pydantic_ai.models.outlines  ](https://ai.pydantic.dev/api/models/outlines/)
      * [ pydantic_ai.models.test  ](https://ai.pydantic.dev/api/models/test/)
      * [ pydantic_ai.models.wrapper  ](https://ai.pydantic.dev/api/models/wrapper/)
      * [ pydantic_ai.output  ](https://ai.pydantic.dev/api/output/)
      * [ pydantic_ai.profiles  ](https://ai.pydantic.dev/api/profiles/)
      * [ pydantic_ai.providers  ](https://ai.pydantic.dev/api/providers/)
      * [ pydantic_ai.result  ](https://ai.pydantic.dev/api/result/)
      * [ pydantic_ai.retries  ](https://ai.pydantic.dev/api/retries/)
      * [ pydantic_ai.run  ](https://ai.pydantic.dev/api/run/)
      * [ pydantic_ai.settings  ](https://ai.pydantic.dev/api/settings/)
      * [ pydantic_ai.tools  ](https://ai.pydantic.dev/api/tools/)
      * [ pydantic_ai.toolsets  ](https://ai.pydantic.dev/api/toolsets/)
      * [ pydantic_ai.ui.ag_ui  ](https://ai.pydantic.dev/api/ui/ag_ui/)
      * [ pydantic_ai.ui  ](https://ai.pydantic.dev/api/ui/base/)
      * [ pydantic_ai.ui.vercel_ai  ](https://ai.pydantic.dev/api/ui/vercel_ai/)
      * [ pydantic_ai.usage  ](https://ai.pydantic.dev/api/usage/)
    * pydantic_evals
      * [ pydantic_evals.dataset  ](https://ai.pydantic.dev/api/pydantic_evals/dataset/)
      * [ pydantic_evals.evaluators  ](https://ai.pydantic.dev/api/pydantic_evals/evaluators/)
      * [ pydantic_evals.reporting  ](https://ai.pydantic.dev/api/pydantic_evals/reporting/)
      * [ pydantic_evals.otel  ](https://ai.pydantic.dev/api/pydantic_evals/otel/)
      * [ pydantic_evals.generation  ](https://ai.pydantic.dev/api/pydantic_evals/generation/)
    * pydantic_graph
      * [ pydantic_graph  ](https://ai.pydantic.dev/api/pydantic_graph/graph/)
      * [ pydantic_graph.nodes  ](https://ai.pydantic.dev/api/pydantic_graph/nodes/)
      * [ pydantic_graph.persistence  ](https://ai.pydantic.dev/api/pydantic_graph/persistence/)
      * [ pydantic_graph.mermaid  ](https://ai.pydantic.dev/api/pydantic_graph/mermaid/)
      * [ pydantic_graph.exceptions  ](https://ai.pydantic.dev/api/pydantic_graph/exceptions/)
      * Beta API
        * [ pydantic_graph.beta  ](https://ai.pydantic.dev/api/pydantic_graph/beta/)
        * [ pydantic_graph.beta.graph  ](https://ai.pydantic.dev/api/pydantic_graph/beta_graph/)
        * [ pydantic_graph.beta.graph_builder  ](https://ai.pydantic.dev/api/pydantic_graph/beta_graph_builder/)
        * [ pydantic_graph.beta.step  ](https://ai.pydantic.dev/api/pydantic_graph/beta_step/)
        * [ pydantic_graph.beta.join  ](https://ai.pydantic.dev/api/pydantic_graph/beta_join/)
        * [ pydantic_graph.beta.decision  ](https://ai.pydantic.dev/api/pydantic_graph/beta_decision/)
        * [ pydantic_graph.beta.node  ](https://ai.pydantic.dev/api/pydantic_graph/beta_node/)
    * fasta2a
      * [ fasta2a  ](https://ai.pydantic.dev/api/fasta2a/)
  * Project
    * [ Contributing  ](https://ai.pydantic.dev/contributing/)
    * [ Upgrade Guide  ](https://ai.pydantic.dev/changelog/)
    * [ Version policy  ](https://ai.pydantic.dev/version-policy/)


  * [ Quick Start  ](https://ai.pydantic.dev/embeddings/#quick-start)
  * [ Embedding Result  ](https://ai.pydantic.dev/embeddings/#embedding-result)
  * [ Providers  ](https://ai.pydantic.dev/embeddings/#providers)
    * [ OpenAI  ](https://ai.pydantic.dev/embeddings/#openai)
      * [ Install  ](https://ai.pydantic.dev/embeddings/#install)
      * [ Configuration  ](https://ai.pydantic.dev/embeddings/#configuration)
      * [ Dimension Control  ](https://ai.pydantic.dev/embeddings/#dimension-control)
      * [ OpenAI-Compatible Providers  ](https://ai.pydantic.dev/embeddings/#openai-compatible)
    * [ Google  ](https://ai.pydantic.dev/embeddings/#google)
      * [ Install  ](https://ai.pydantic.dev/embeddings/#install_1)
      * [ Configuration  ](https://ai.pydantic.dev/embeddings/#configuration_1)
        * [ Vertex AI  ](https://ai.pydantic.dev/embeddings/#vertex-ai)
      * [ Dimension Control  ](https://ai.pydantic.dev/embeddings/#dimension-control_1)
      * [ Google-Specific Settings  ](https://ai.pydantic.dev/embeddings/#google-specific-settings)
    * [ Cohere  ](https://ai.pydantic.dev/embeddings/#cohere)
      * [ Install  ](https://ai.pydantic.dev/embeddings/#install_2)
      * [ Configuration  ](https://ai.pydantic.dev/embeddings/#configuration_2)
      * [ Cohere-Specific Settings  ](https://ai.pydantic.dev/embeddings/#cohere-specific-settings)
    * [ VoyageAI  ](https://ai.pydantic.dev/embeddings/#voyageai)
      * [ Install  ](https://ai.pydantic.dev/embeddings/#install_3)
      * [ Configuration  ](https://ai.pydantic.dev/embeddings/#configuration_3)
      * [ VoyageAI-Specific Settings  ](https://ai.pydantic.dev/embeddings/#voyageai-specific-settings)
    * [ Bedrock  ](https://ai.pydantic.dev/embeddings/#bedrock)
      * [ Install  ](https://ai.pydantic.dev/embeddings/#install_4)
      * [ Configuration  ](https://ai.pydantic.dev/embeddings/#configuration_4)
      * [ Basic Usage  ](https://ai.pydantic.dev/embeddings/#basic-usage)
      * [ Supported Models  ](https://ai.pydantic.dev/embeddings/#supported-models)
      * [ Titan-Specific Settings  ](https://ai.pydantic.dev/embeddings/#titan-specific-settings)
      * [ Cohere-Specific Settings  ](https://ai.pydantic.dev/embeddings/#cohere-specific-settings_1)
      * [ Nova-Specific Settings  ](https://ai.pydantic.dev/embeddings/#nova-specific-settings)
      * [ Concurrency Settings  ](https://ai.pydantic.dev/embeddings/#concurrency-settings)
      * [ Regional Prefixes (Cross-Region Inference)  ](https://ai.pydantic.dev/embeddings/#regional-prefixes-cross-region-inference)
      * [ Using a Custom Provider  ](https://ai.pydantic.dev/embeddings/#using-a-custom-provider)
    * [ Sentence Transformers (Local)  ](https://ai.pydantic.dev/embeddings/#sentence-transformers-local)
      * [ Install  ](https://ai.pydantic.dev/embeddings/#install_5)
      * [ Usage  ](https://ai.pydantic.dev/embeddings/#usage)
      * [ Device Selection  ](https://ai.pydantic.dev/embeddings/#device-selection)
      * [ Using an Existing Model Instance  ](https://ai.pydantic.dev/embeddings/#using-an-existing-model-instance)
  * [ Settings  ](https://ai.pydantic.dev/embeddings/#settings)
  * [ Token Counting  ](https://ai.pydantic.dev/embeddings/#token-counting)
  * [ Testing  ](https://ai.pydantic.dev/embeddings/#testing)
  * [ Instrumentation  ](https://ai.pydantic.dev/embeddings/#instrumentation)
  * [ Building Custom Embedding Models  ](https://ai.pydantic.dev/embeddings/#building-custom-embedding-models)


  1. [ Pydantic AI  ](https://ai.pydantic.dev/)
  2. [ Documentation  ](https://ai.pydantic.dev/agent/)


# Embeddings
Embeddings are vector representations of text that capture semantic meaning. They're essential for building:
  * **Semantic search** — Find documents based on meaning, not just keyword matching
  * **RAG (Retrieval-Augmented Generation)** — Retrieve relevant context for your AI agents
  * **Similarity detection** — Find similar documents, detect duplicates, or cluster content
  * **Classification** — Use embeddings as features for downstream ML models


Pydantic AI provides a unified interface for generating embeddings across multiple providers.
## Quick Start
The [`Embedder`](https://ai.pydantic.dev/api/embeddings/#pydantic_ai.embeddings.Embedder "Embedder



      dataclass
  ") class is the high-level interface for generating embeddings:
embeddings_quickstart.py```
from pydantic_ai import Embedder

embedder = Embedder('openai:text-embedding-3-small')


async def main():
    # Embed a search query
    result = await embedder.embed_query('What is machine learning?')
    print(f'Embedding dimensions: {len(result.embeddings[0])}')
    #> Embedding dimensions: 1536

    # Embed multiple documents at once
    docs = [
        'Machine learning is a subset of AI.',
        'Deep learning uses neural networks.',
        'Python is a programming language.',
    ]
    result = await embedder.embed_documents(docs)
    print(f'Embedded {len(result.embeddings)} documents')
    #> Embedded 3 documents

```

_(This example is complete, it can be run "as is" — you'll need to add`asyncio.run(main())` to run `main`)_
Queries vs Documents
Some embedding models optimize differently for queries and documents. Use [`embed_query()`](https://ai.pydantic.dev/api/embeddings/#pydantic_ai.embeddings.Embedder.embed_query "embed_query



      async
  ") for search queries and [`embed_documents()`](https://ai.pydantic.dev/api/embeddings/#pydantic_ai.embeddings.Embedder.embed_documents "embed_documents



      async
  ") for content you're indexing.
## Embedding Result
All embed methods return an [`EmbeddingResult`](https://ai.pydantic.dev/api/embeddings/#pydantic_ai.embeddings.EmbeddingResult "EmbeddingResult



      dataclass
  ") containing the embeddings along with useful metadata.
For convenience, you can access embeddings either by index (`result[0]`) or by the original input text (`result['Hello world']`).
embedding_result.py```
from pydantic_ai import Embedder

embedder = Embedder('openai:text-embedding-3-small')


async def main():
    result = await embedder.embed_query('Hello world')

    # Access embeddings - each is a sequence of floats
    embedding = result.embeddings[0]  # By index via .embeddings
    embedding = result[0]  # Or directly via __getitem__
    embedding = result['Hello world']  # Or by original input text
    print(f'Dimensions: {len(embedding)}')
    #> Dimensions: 1536

    # Check usage
    print(f'Tokens used: {result.usage.input_tokens}')
    #> Tokens used: 2

    # Calculate cost (requires `genai-prices` to have pricing data for the model)
    cost = result.cost()
    print(f'Cost: ${cost.total_price:.6f}')
    #> Cost: $0.000000

```

_(This example is complete, it can be run "as is" — you'll need to add`asyncio.run(main())` to run `main`)_
## Providers
### OpenAI
[`OpenAIEmbeddingModel`](https://ai.pydantic.dev/api/embeddings/#pydantic_ai.embeddings.openai.OpenAIEmbeddingModel "OpenAIEmbeddingModel



      dataclass
  ") works with OpenAI's embeddings API and any [OpenAI-compatible provider](https://ai.pydantic.dev/models/openai/#openai-compatible-models).
#### Install
To use OpenAI embedding models, you need to either install `pydantic-ai`, or install `pydantic-ai-slim` with the `openai` optional group:
[pip](https://ai.pydantic.dev/embeddings/#__tabbed_1_1)[uv](https://ai.pydantic.dev/embeddings/#__tabbed_1_2)
```
pip install "pydantic-ai-slim[openai]"

```

```
uv add "pydantic-ai-slim[openai]"

```

#### Configuration
To use `OpenAIEmbeddingModel` with the OpenAI API, go to [platform.openai.com](https://platform.openai.com/) and follow your nose until you find the place to generate an API key. Once you have the API key, you can set it as an environment variable:
```
export OPENAI_API_KEY='your-api-key'

```

You can then use the model:
openai_embeddings.py```
from pydantic_ai import Embedder

embedder = Embedder('openai:text-embedding-3-small')


async def main():
    result = await embedder.embed_query('Hello world')
    print(len(result.embeddings[0]))
    #> 1536

```

_(This example is complete, it can be run "as is" — you'll need to add`asyncio.run(main())` to run `main`)_
See [OpenAI's embedding models](https://platform.openai.com/docs/guides/embeddings) for available models.
#### Dimension Control
OpenAI's `text-embedding-3-*` models support dimension reduction via the `dimensions` setting:
openai_dimensions.py```
from pydantic_ai import Embedder
from pydantic_ai.embeddings import EmbeddingSettings

embedder = Embedder(
    'openai:text-embedding-3-small',
    settings=EmbeddingSettings(dimensions=256),
)


async def main():
    result = await embedder.embed_query('Hello world')
    print(len(result.embeddings[0]))
    #> 256

```

_(This example is complete, it can be run "as is" — you'll need to add`asyncio.run(main())` to run `main`)_
#### OpenAI-Compatible Providers
Since [`OpenAIEmbeddingModel`](https://ai.pydantic.dev/api/embeddings/#pydantic_ai.embeddings.openai.OpenAIEmbeddingModel "OpenAIEmbeddingModel



      dataclass
  ") uses the same provider system as [`OpenAIChatModel`](https://ai.pydantic.dev/api/models/openai/#pydantic_ai.models.openai.OpenAIChatModel "OpenAIChatModel



      dataclass
  "), you can use it with any [OpenAI-compatible provider](https://ai.pydantic.dev/models/openai/#openai-compatible-models):
openai_compatible_embeddings.py```
# Using Azure OpenAI
from openai import AsyncAzureOpenAI

from pydantic_ai import Embedder
from pydantic_ai.embeddings.openai import OpenAIEmbeddingModel
from pydantic_ai.providers.openai import OpenAIProvider

azure_client = AsyncAzureOpenAI(
    azure_endpoint='https://your-resource.openai.azure.com',
    api_version='2024-02-01',
    api_key='your-azure-key',
)
model = OpenAIEmbeddingModel(
    'text-embedding-3-small',
    provider=OpenAIProvider(openai_client=azure_client),
)
embedder = Embedder(model)


# Using any OpenAI-compatible API
model = OpenAIEmbeddingModel(
    'your-model-name',
    provider=OpenAIProvider(
        base_url='https://your-provider.com/v1',
        api_key='your-api-key',
    ),
)
embedder = Embedder(model)

```

For providers with dedicated provider classes (like [`OllamaProvider`](https://ai.pydantic.dev/api/providers/#pydantic_ai.providers.ollama.OllamaProvider) or [`AzureProvider`](https://ai.pydantic.dev/api/providers/#pydantic_ai.providers.azure.AzureProvider "AzureProvider")), you can use the shorthand syntax:
```
from pydantic_ai import Embedder

embedder = Embedder('azure:text-embedding-3-small')
embedder = Embedder('ollama:nomic-embed-text')

```

See [OpenAI-compatible Models](https://ai.pydantic.dev/models/openai/#openai-compatible-models) for the full list of supported providers.
### Google
[`GoogleEmbeddingModel`](https://ai.pydantic.dev/api/embeddings/#pydantic_ai.embeddings.google.GoogleEmbeddingModel "GoogleEmbeddingModel



      dataclass
  ") works with Google's embedding models via the Gemini API (Google AI Studio) or Vertex AI.
#### Install
To use Google embedding models, you need to either install `pydantic-ai`, or install `pydantic-ai-slim` with the `google` optional group:
[pip](https://ai.pydantic.dev/embeddings/#__tabbed_2_1)[uv](https://ai.pydantic.dev/embeddings/#__tabbed_2_2)
```
pip install "pydantic-ai-slim[google]"

```

```
uv add "pydantic-ai-slim[google]"

```

#### Configuration
To use `GoogleEmbeddingModel` with the Gemini API, go to [aistudio.google.com](https://aistudio.google.com/) and generate an API key. Once you have the API key, you can set it as an environment variable:
```
export GOOGLE_API_KEY='your-api-key'

```

You can then use the model:
google_embeddings.py```
from pydantic_ai import Embedder

embedder = Embedder('google-gla:gemini-embedding-001')


async def main():
    result = await embedder.embed_query('Hello world')
    print(len(result.embeddings[0]))
    #> 3072

```

_(This example is complete, it can be run "as is" — you'll need to add`asyncio.run(main())` to run `main`)_
See the [Google Embeddings documentation](https://ai.google.dev/gemini-api/docs/embeddings) for available models.
##### Vertex AI
To use Google's embedding models via Vertex AI instead of the Gemini API, use the `google-vertex` provider prefix:
google_vertex_embeddings.py```
from pydantic_ai import Embedder
from pydantic_ai.embeddings.google import GoogleEmbeddingModel
from pydantic_ai.providers.google import GoogleProvider

# Using provider prefix
embedder = Embedder('google-vertex:gemini-embedding-001')

# Or with explicit provider configuration
model = GoogleEmbeddingModel(
    'gemini-embedding-001',
    provider=GoogleProvider(vertexai=True, project='my-project', location='us-central1'),
)
embedder = Embedder(model)

```

See the [Google provider documentation](https://ai.pydantic.dev/models/google/#vertex-ai-enterprisecloud) for more details on Vertex AI authentication options, including application default credentials, service accounts, and API keys.
#### Dimension Control
Google's embedding models support dimension reduction via the `dimensions` setting:
google_dimensions.py```
from pydantic_ai import Embedder
from pydantic_ai.embeddings import EmbeddingSettings

embedder = Embedder(
    'google-gla:gemini-embedding-001',
    settings=EmbeddingSettings(dimensions=768),
)


async def main():
    result = await embedder.embed_query('Hello world')
    print(len(result.embeddings[0]))
    #> 768

```

_(This example is complete, it can be run "as is" — you'll need to add`asyncio.run(main())` to run `main`)_
#### Google-Specific Settings
Google models support additional settings via [`GoogleEmbeddingSettings`](https://ai.pydantic.dev/api/embeddings/#pydantic_ai.embeddings.google.GoogleEmbeddingSettings "GoogleEmbeddingSettings"):
google_settings.py```
from pydantic_ai import Embedder
from pydantic_ai.embeddings.google import GoogleEmbeddingSettings

embedder = Embedder(
    'google-gla:gemini-embedding-001',
    settings=GoogleEmbeddingSettings(
        dimensions=768,
        google_task_type='SEMANTIC_SIMILARITY',  # Optimize for similarity comparison
    ),
)

```

See [Google's task type documentation](https://ai.google.dev/gemini-api/docs/embeddings#task-types) for available task types. By default, `embed_query()` uses `RETRIEVAL_QUERY` and `embed_documents()` uses `RETRIEVAL_DOCUMENT`.
### Cohere
[`CohereEmbeddingModel`](https://ai.pydantic.dev/api/embeddings/#pydantic_ai.embeddings.cohere.CohereEmbeddingModel "CohereEmbeddingModel



      dataclass
  ") provides access to Cohere's embedding models, which offer multilingual support and various model sizes.
#### Install
To use Cohere embedding models, you need to either install `pydantic-ai`, or install `pydantic-ai-slim` with the `cohere` optional group:
[pip](https://ai.pydantic.dev/embeddings/#__tabbed_3_1)[uv](https://ai.pydantic.dev/embeddings/#__tabbed_3_2)
```
pip install "pydantic-ai-slim[cohere]"

```

```
uv add "pydantic-ai-slim[cohere]"

```

#### Configuration
To use `CohereEmbeddingModel`, go to [dashboard.cohere.com/api-keys](https://dashboard.cohere.com/api-keys) and follow your nose until you find the place to generate an API key. Once you have the API key, you can set it as an environment variable:
```
export CO_API_KEY='your-api-key'

```

You can then use the model:
cohere_embeddings.py```
from pydantic_ai import Embedder

embedder = Embedder('cohere:embed-v4.0')


async def main():
    result = await embedder.embed_query('Hello world')
    print(len(result.embeddings[0]))
    #> 1024

```

_(This example is complete, it can be run "as is" — you'll need to add`asyncio.run(main())` to run `main`)_
See the [Cohere Embed documentation](https://docs.cohere.com/docs/cohere-embed) for available models.
#### Cohere-Specific Settings
Cohere models support additional settings via [`CohereEmbeddingSettings`](https://ai.pydantic.dev/api/embeddings/#pydantic_ai.embeddings.cohere.CohereEmbeddingSettings "CohereEmbeddingSettings"):
cohere_settings.py```
from pydantic_ai import Embedder
from pydantic_ai.embeddings.cohere import CohereEmbeddingSettings

embedder = Embedder(
    'cohere:embed-v4.0',
    settings=CohereEmbeddingSettings(
        dimensions=512,
        cohere_truncate='END',  # Truncate long inputs instead of erroring
        cohere_max_tokens=256,  # Limit tokens per input
    ),
)

```

### VoyageAI
[`VoyageAIEmbeddingModel`](https://ai.pydantic.dev/api/embeddings/#pydantic_ai.embeddings.voyageai.VoyageAIEmbeddingModel "VoyageAIEmbeddingModel



      dataclass
  ") provides access to VoyageAI's embedding models, which are optimized for retrieval with specialized models for code, finance, and legal domains.
#### Install
To use VoyageAI embedding models, you need to install `pydantic-ai-slim` with the `voyageai` optional group:
[pip](https://ai.pydantic.dev/embeddings/#__tabbed_4_1)[uv](https://ai.pydantic.dev/embeddings/#__tabbed_4_2)
```
pip install "pydantic-ai-slim[voyageai]"

```

```
uv add "pydantic-ai-slim[voyageai]"

```

#### Configuration
To use `VoyageAIEmbeddingModel`, go to [dash.voyageai.com](https://dash.voyageai.com/) to generate an API key. Once you have the API key, you can set it as an environment variable:
```
export VOYAGE_API_KEY='your-api-key'

```

You can then use the model:
voyageai_embeddings.py```
from pydantic_ai import Embedder

embedder = Embedder('voyageai:voyage-3.5')


async def main():
    result = await embedder.embed_query('Hello world')
    print(len(result.embeddings[0]))
    #> 1024

```

_(This example is complete, it can be run "as is" — you'll need to add`asyncio.run(main())` to run `main`)_
See the [VoyageAI Embeddings documentation](https://docs.voyageai.com/docs/embeddings) for available models.
#### VoyageAI-Specific Settings
VoyageAI models support additional settings via [`VoyageAIEmbeddingSettings`](https://ai.pydantic.dev/api/embeddings/#pydantic_ai.embeddings.voyageai.VoyageAIEmbeddingSettings "VoyageAIEmbeddingSettings"):
voyageai_settings.py```
from pydantic_ai import Embedder
from pydantic_ai.embeddings.voyageai import VoyageAIEmbeddingSettings

embedder = Embedder(
    'voyageai:voyage-3.5',
    settings=VoyageAIEmbeddingSettings(
        dimensions=512,  # Reduce output dimensions
        voyageai_input_type='document',  # Override input type for all requests
    ),
)

```

### Bedrock
[`BedrockEmbeddingModel`](https://ai.pydantic.dev/api/embeddings/#pydantic_ai.embeddings.bedrock.BedrockEmbeddingModel "BedrockEmbeddingModel



      dataclass
  ") provides access to embedding models through AWS Bedrock, including Amazon Titan, Cohere, and Amazon Nova models.
#### Install
To use Bedrock embedding models, you need to either install `pydantic-ai`, or install `pydantic-ai-slim` with the `bedrock` optional group:
[pip](https://ai.pydantic.dev/embeddings/#__tabbed_5_1)[uv](https://ai.pydantic.dev/embeddings/#__tabbed_5_2)
```
pip install "pydantic-ai-slim[bedrock]"

```

```
uv add "pydantic-ai-slim[bedrock]"

```

#### Configuration
Authentication with AWS Bedrock uses standard AWS credentials. See the [Bedrock provider documentation](https://ai.pydantic.dev/models/bedrock/#environment-variables) for details on configuring credentials via environment variables, AWS credentials file, or IAM roles.
Ensure your AWS account has access to the Bedrock embedding models you want to use. See [AWS Bedrock model access](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html) for details.
#### Basic Usage
bedrock_embeddings.py```
from pydantic_ai import Embedder

# Using Amazon Titan
embedder = Embedder('bedrock:amazon.titan-embed-text-v2:0')


async def main():
    result = await embedder.embed_query('Hello world')
    print(len(result.embeddings[0]))
    #> 1024

```

_(This example requires AWS credentials configured)_
#### Supported Models
Bedrock supports three families of embedding models. See the [AWS Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html) for the full list of available models.
**Amazon Titan:**
  * `amazon.titan-embed-text-v1` — 1536 dimensions (fixed), 8K tokens
  * `amazon.titan-embed-text-v2:0` — 256/384/1024 dimensions (configurable, default: 1024), 8K tokens


**Cohere Embed:**
  * `cohere.embed-english-v3` — English-only, 1024 dimensions (fixed), 512 tokens
  * `cohere.embed-multilingual-v3` — Multilingual, 1024 dimensions (fixed), 512 tokens
  * `cohere.embed-v4:0` — 256/512/1024/1536 dimensions (configurable, default: 1536), 128K tokens


**Amazon Nova:**
  * `amazon.nova-2-multimodal-embeddings-v1:0` — 256/384/1024/3072 dimensions (configurable, default: 3072), 8K tokens


#### Titan-Specific Settings
Titan v2 supports vector normalization for direct similarity calculations via `bedrock_titan_normalize` (default: `True`). Titan v1 does not support this setting.
bedrock_titan.py```
from pydantic_ai import Embedder
from pydantic_ai.embeddings.bedrock import BedrockEmbeddingSettings

embedder = Embedder(
    'bedrock:amazon.titan-embed-text-v2:0',
    settings=BedrockEmbeddingSettings(
        dimensions=512,
        bedrock_titan_normalize=True,
    ),
)

```

Note
Titan models do not support the `truncate` setting. The `dimensions` setting is only supported by Titan v2.
#### Cohere-Specific Settings
Cohere models on Bedrock support additional settings via [`BedrockEmbeddingSettings`](https://ai.pydantic.dev/api/embeddings/#pydantic_ai.embeddings.bedrock.BedrockEmbeddingSettings "BedrockEmbeddingSettings"):
  * `bedrock_cohere_input_type` — By default, `embed_query()` uses `'search_query'` and `embed_documents()` uses `'search_document'`. Also accepts `'classification'` or `'clustering'`.
  * `bedrock_cohere_truncate` — Fine-grained truncation control: `'NONE'` (default, error on overflow), `'START'`, or `'END'`. Overrides the base `truncate` setting.
  * `bedrock_cohere_max_tokens` — Limits tokens per input (default: 128000). Only supported by Cohere v4.


bedrock_cohere.py```
from pydantic_ai import Embedder
from pydantic_ai.embeddings.bedrock import BedrockEmbeddingSettings

embedder = Embedder(
    'bedrock:cohere.embed-v4:0',
    settings=BedrockEmbeddingSettings(
        dimensions=512,
        bedrock_cohere_max_tokens=1000,
        bedrock_cohere_truncate='END',
    ),
)

```

Note
The `dimensions` and `bedrock_cohere_max_tokens` settings are only supported by Cohere v4. Cohere v3 models have fixed 1024 dimensions.
#### Nova-Specific Settings
Nova models on Bedrock support additional settings via [`BedrockEmbeddingSettings`](https://ai.pydantic.dev/api/embeddings/#pydantic_ai.embeddings.bedrock.BedrockEmbeddingSettings "BedrockEmbeddingSettings"):
  * `bedrock_nova_truncate` — Fine-grained truncation control: `'NONE'` (default, error on overflow), `'START'`, or `'END'`. Overrides the base `truncate` setting.
  * `bedrock_nova_embedding_purpose` — By default, `embed_query()` uses `'GENERIC_RETRIEVAL'` and `embed_documents()` uses `'GENERIC_INDEX'`. Also accepts `'TEXT_RETRIEVAL'`, `'CLASSIFICATION'`, or `'CLUSTERING'`.


bedrock_nova.py```
from pydantic_ai import Embedder
from pydantic_ai.embeddings.bedrock import BedrockEmbeddingSettings

embedder = Embedder(
    'bedrock:amazon.nova-2-multimodal-embeddings-v1:0',
    settings=BedrockEmbeddingSettings(
        dimensions=1024,
        bedrock_nova_embedding_purpose='TEXT_RETRIEVAL',
        truncate=True,
    ),
)

```

#### Concurrency Settings
Models that don't support batch embedding (Titan and Nova) make individual API requests for each input text. By default, these requests run concurrently with a maximum of 5 parallel requests.
You can adjust this with the `bedrock_max_concurrency` setting:
bedrock_concurrency.py```
from pydantic_ai import Embedder
from pydantic_ai.embeddings.bedrock import BedrockEmbeddingSettings

# Increase concurrency for faster throughput
embedder = Embedder(
    'bedrock:amazon.titan-embed-text-v2:0',
    settings=BedrockEmbeddingSettings(bedrock_max_concurrency=10),
)

# Or reduce concurrency to avoid rate limits
embedder = Embedder(
    'bedrock:amazon.nova-2-multimodal-embeddings-v1:0',
    settings=BedrockEmbeddingSettings(bedrock_max_concurrency=2),
)

```

#### Regional Prefixes (Cross-Region Inference)
Bedrock supports cross-region inference using geographic prefixes like `us.`, `eu.`, or `apac.`:
bedrock_regional.py```
from pydantic_ai import Embedder

embedder = Embedder('bedrock:us.amazon.titan-embed-text-v2:0')

```

#### Using a Custom Provider
For advanced configuration like explicit credentials or a custom boto3 client, you can create a [`BedrockProvider`](https://ai.pydantic.dev/api/providers/#pydantic_ai.providers.bedrock.BedrockProvider "BedrockProvider") directly. See the [Bedrock provider documentation](https://ai.pydantic.dev/models/bedrock/#provider-argument) for more details.
bedrock_provider.py```
from pydantic_ai import Embedder
from pydantic_ai.embeddings.bedrock import BedrockEmbeddingModel
from pydantic_ai.providers.bedrock import BedrockProvider

provider = BedrockProvider(
    region_name='us-west-2',
    aws_access_key_id='your-access-key',
    aws_secret_access_key='your-secret-key',
)

model = BedrockEmbeddingModel('amazon.titan-embed-text-v2:0', provider=provider)
embedder = Embedder(model)

```

Token Counting
Bedrock embedding models do not support the `count_tokens()` method because AWS Bedrock's token counting API only works with text generation models (Claude, Llama, etc.), not embedding models. Calling `count_tokens()` will raise `NotImplementedError`.
### Sentence Transformers (Local)
[`SentenceTransformerEmbeddingModel`](https://ai.pydantic.dev/api/embeddings/#pydantic_ai.embeddings.sentence_transformers.SentenceTransformerEmbeddingModel "SentenceTransformerEmbeddingModel



      dataclass
  ") runs embeddings locally using the [sentence-transformers](https://www.sbert.net/) library. This is ideal for:
  * **Privacy** — Data never leaves your infrastructure
  * **Cost** — No API charges for high-volume workloads
  * **Offline use** — No internet connection required after model download


#### Install
To use Sentence Transformers embedding models, you need to install `pydantic-ai-slim` with the `sentence-transformers` optional group:
[pip](https://ai.pydantic.dev/embeddings/#__tabbed_6_1)[uv](https://ai.pydantic.dev/embeddings/#__tabbed_6_2)
```
pip install "pydantic-ai-slim[sentence-transformers]"

```

```
uv add "pydantic-ai-slim[sentence-transformers]"

```

#### Usage
sentence_transformers_embeddings.py```
from pydantic_ai import Embedder

# Model is downloaded from Hugging Face on first use
embedder = Embedder('sentence-transformers:all-MiniLM-L6-v2')


async def main():
    result = await embedder.embed_query('Hello world')
    print(len(result.embeddings[0]))
    #> 384

```

_(This example is complete, it can be run "as is" — you'll need to add`asyncio.run(main())` to run `main`)_
See the [Sentence-Transformers pretrained models](https://www.sbert.net/docs/sentence_transformer/pretrained_models.html) documentation for available models.
#### Device Selection
Control which device to use for inference:
sentence_transformers_device.py```
from pydantic_ai import Embedder
from pydantic_ai.embeddings.sentence_transformers import (
    SentenceTransformersEmbeddingSettings,
)

embedder = Embedder(
    'sentence-transformers:all-MiniLM-L6-v2',
    settings=SentenceTransformersEmbeddingSettings(
        sentence_transformers_device='cuda',  # Use GPU
        sentence_transformers_normalize_embeddings=True,  # L2 normalize
    ),
)

```

#### Using an Existing Model Instance
If you need more control over model initialization:
sentence_transformers_instance.py```
from sentence_transformers import SentenceTransformer

from pydantic_ai import Embedder
from pydantic_ai.embeddings.sentence_transformers import (
    SentenceTransformerEmbeddingModel,
)

# Create and configure the model yourself
st_model = SentenceTransformer('all-MiniLM-L6-v2', device='cpu')

# Wrap it for use with Pydantic AI
model = SentenceTransformerEmbeddingModel(st_model)
embedder = Embedder(model)

```

## Settings
[`EmbeddingSettings`](https://ai.pydantic.dev/api/embeddings/#pydantic_ai.embeddings.EmbeddingSettings "EmbeddingSettings") provides common configuration options that work across providers:
  * `dimensions`: Reduce the output embedding dimensions (supported by OpenAI, Google, Cohere, Bedrock, VoyageAI)
  * `truncate`: When `True`, truncate input text that exceeds the model's context length instead of raising an error (supported by Cohere, Bedrock, VoyageAI)


Settings can be specified at the embedder level (applied to all calls) or per-call:
embedding_settings.py```
from pydantic_ai import Embedder
from pydantic_ai.embeddings import EmbeddingSettings

# Default settings for all calls
embedder = Embedder(
    'openai:text-embedding-3-small',
    settings=EmbeddingSettings(dimensions=512),
)


async def main():
    # Override for a specific call
    result = await embedder.embed_query(
        'Hello world',
        settings=EmbeddingSettings(dimensions=256),
    )
    print(len(result.embeddings[0]))
    #> 256

```

_(This example is complete, it can be run "as is" — you'll need to add`asyncio.run(main())` to run `main`)_
## Token Counting
You can check token counts before embedding to avoid exceeding model limits:
token_counting.py```
from pydantic_ai import Embedder

embedder = Embedder('openai:text-embedding-3-small')


async def main():
    text = 'Hello world, this is a test.'

    # Count tokens in text
    token_count = await embedder.count_tokens(text)
    print(f'Tokens: {token_count}')
    #> Tokens: 7

    # Check model's maximum input tokens (returns None if unknown)
    max_tokens = await embedder.max_input_tokens()
    print(f'Max tokens: {max_tokens}')
    #> Max tokens: 1024

```

_(This example is complete, it can be run "as is" — you'll need to add`asyncio.run(main())` to run `main`)_
## Testing
Use [`TestEmbeddingModel`](https://ai.pydantic.dev/api/embeddings/#pydantic_ai.embeddings.TestEmbeddingModel "TestEmbeddingModel



      dataclass
  ") for testing without making API calls:
testing_embeddings.py```
from pydantic_ai import Embedder
from pydantic_ai.embeddings import TestEmbeddingModel


async def test_my_rag_system():
    embedder = Embedder('openai:text-embedding-3-small')
    test_model = TestEmbeddingModel()

    with embedder.override(model=test_model):
        result = await embedder.embed_query('test query')

        # TestEmbeddingModel returns deterministic embeddings
        assert result.embeddings[0] == [1.0] * 8

        # Check what settings were used
        assert test_model.last_settings is not None

```

## Instrumentation
Enable OpenTelemetry instrumentation for debugging and monitoring:
instrumented_embeddings.py```
import logfire

from pydantic_ai import Embedder

logfire.configure()

# Instrument a specific embedder
embedder = Embedder('openai:text-embedding-3-small', instrument=True)

# Or instrument all embedders globally
Embedder.instrument_all()

```

See the [Debugging and Monitoring guide](https://ai.pydantic.dev/logfire/) for more details on using Logfire with Pydantic AI.
## Building Custom Embedding Models
To integrate a custom embedding provider, subclass [`EmbeddingModel`](https://ai.pydantic.dev/api/embeddings/#pydantic_ai.embeddings.EmbeddingModel "EmbeddingModel"):
custom_embedding_model.py```
from collections.abc import Sequence

from pydantic_ai.embeddings import EmbeddingModel, EmbeddingResult, EmbeddingSettings
from pydantic_ai.embeddings.result import EmbedInputType


class MyCustomEmbeddingModel(EmbeddingModel):
    @property
    def model_name(self) -> str:
        return 'my-custom-model'

    @property
    def system(self) -> str:
        return 'my-provider'

    async def embed(
        self,
        inputs: str | Sequence[str],
        *,
        input_type: EmbedInputType,
        settings: EmbeddingSettings | None = None,
    ) -> EmbeddingResult:
        inputs, settings = self.prepare_embed(inputs, settings)

        # Call your embedding API here
        embeddings = [[0.1, 0.2, 0.3] for _ in inputs]  # Placeholder

        return EmbeddingResult(
            embeddings=embeddings,
            inputs=inputs,
            input_type=input_type,
            model_name=self.model_name,
            provider_name=self.system,
        )

```

Use [`WrapperEmbeddingModel`](https://ai.pydantic.dev/api/embeddings/#pydantic_ai.embeddings.WrapperEmbeddingModel "WrapperEmbeddingModel



      dataclass
  ") if you want to wrap an existing model to add custom behavior like caching or logging.
© Pydantic Services Inc. 2024 to present
