embed

Generate embeddings for text using embedding models

Functions for generating vector embeddings from text.

embed

Generate an embedding for a single value.

Signature

async def embed(
    model: EmbeddingModel,
    value: str,
    provider_options: dict | None = None,
    **kwargs
) -> EmbedResult

Parameters

model · EmbeddingModel · required

The embedding model to use. Create with openai.embedding() or google.embedding().

value · str · required

The text to embed.

provider_options · dict

Provider-specific options.

**kwargs · Any

Additional parameters passed to the provider (e.g., dimensions for OpenAI).

Returns

EmbedResult · object

Show properties

value · str

The original input text.

embedding · list[float]

The embedding vector.

usage · EmbeddingUsage

Token usage statistics.

provider_metadata · dict

Provider-specific metadata.

Examples

Basic Usage

from ai_query import embed
from ai_query.providers import openai

result = await embed(
    model=openai.embedding("text-embedding-3-small"),
    value="Hello world"
)
print(len(result.embedding))  # 1536

With Custom Dimensions

result = await embed(
    model=openai.embedding("text-embedding-3-small"),
    value="Hello world",
    dimensions=256
)
print(len(result.embedding))  # 256

Using Google

from ai_query import embed
from ai_query.providers import google

result = await embed(
    model=google.embedding("gemini-embedding-001"),
    value="Hello world"
)

---

embed_many

Generate embeddings for multiple values in a single call.

Signature

async def embed_many(
    model: EmbeddingModel,
    values: list[str],
    provider_options: dict | None = None,
    **kwargs
) -> EmbedManyResult

Parameters

model · EmbeddingModel · required

The embedding model to use. Create with openai.embedding() or google.embedding().

values · list[str] · required

List of texts to embed.

provider_options · dict

Provider-specific options.

**kwargs · Any

Additional parameters passed to the provider.

Returns

EmbedManyResult · object

Show properties

values · list[str]

The original input texts.

embeddings · list[list[float]]

List of embedding vectors (same order as input).

usage · EmbeddingUsage

Token usage statistics.

provider_metadata · dict

Provider-specific metadata.

Examples

Basic Usage

from ai_query import embed_many
from ai_query.providers import openai

result = await embed_many(
    model=openai.embedding("text-embedding-3-small"),
    values=["Hello", "World", "How are you?"]
)
print(len(result.embeddings))  # 3
print(len(result.embeddings[0]))  # 1536

For Semantic Search

documents = [
    "Python is a programming language",
    "JavaScript runs in browsers",
    "Rust is known for memory safety"
]

result = await embed_many(
    model=openai.embedding("text-embedding-3-small"),
    values=documents
)

# Use embeddings for similarity search

---

Types

EmbeddingModel

A wrapper combining an embedding provider and model identifier.

from ai_query.providers import openai, google

# Create with provider embedding functions
model = openai.embedding("text-embedding-3-small")
model = google.embedding("gemini-embedding-001")

EmbedResult

Result from embed() call.

@dataclass
class EmbedResult:
    value: str              # Original input text
    embedding: list[float]  # Embedding vector
    usage: EmbeddingUsage   # Token usage
    provider_metadata: dict # Provider-specific metadata

EmbedManyResult

Result from embed_many() call.

@dataclass
class EmbedManyResult:
    values: list[str]              # Original input texts
    embeddings: list[list[float]]  # Embedding vectors
    usage: EmbeddingUsage          # Token usage
    provider_metadata: dict        # Provider-specific metadata

EmbeddingUsage

Token usage statistics for embedding operations.

@dataclass
class EmbeddingUsage:
    tokens: int  # Number of input tokens

---

Provider Options

OpenAI

Option	Type	Description
dimensions	int	Output dimensions (v3 models only)
encoding_format	str	"float" or "base64"

result = await embed(
    model=openai.embedding("text-embedding-3-small"),
    value="Hello",
    dimensions=512,
    provider_options={
        "openai": {"encoding_format": "float"}
    }
)

Google

Option	Type	Description
taskType	str	Task type for optimization
title	str	Optional document title
outputDimensionality	int	Output dimensions

Task types:

• RETRIEVAL_QUERY - Optimize for search queries
• RETRIEVAL_DOCUMENT - Optimize for documents
• SEMANTIC_SIMILARITY - Optimize for similarity comparison
• CLASSIFICATION - Optimize for classification
• CLUSTERING - Optimize for clustering

result = await embed(
    model=google.embedding("gemini-embedding-001"),
    value="Hello",
    provider_options={
        "google": {
            "taskType": "RETRIEVAL_DOCUMENT",
            "title": "My Document",
            "outputDimensionality": 768
        }
    }
)

---

Available Models

OpenAI

Model	Dimensions	Max Tokens	Description
text-embedding-3-large	3072	8192	Highest quality
text-embedding-3-small	1536	8192	Fast and affordable
text-embedding-ada-002	1536	8192	Legacy model

Google

Model	Dimensions	Max Tokens	Description
gemini-embedding-001	128-3072	2048	Latest model with flexible dimensions