EmbeddingModel
The EmbeddingModel module provides vector embeddings for text using AI models.
This module enables efficient conversion of text into high-dimensional vector representations that capture semantic meaning. It supports batching, caching, and request optimization for production use cases like semantic search, document similarity, and clustering.
Constructors
Signature
declare function make(options: {
readonly cache?: {
readonly capacity: number;
readonly timeToLive: DurationInput;
};
readonly embedMany: (input: readonly Array<string>) => Effect<Array<Result>, AiError>;
readonly maxBatchSize?: number;
}): Effect<any, unknown, unknown>makeDataLoader
Creates an EmbeddingModel service with time-window based batching.
This constructor creates a service that uses a data loader pattern to batch embedding requests within a specified time window. This is optimal for high-throughput scenarios where you want to automatically batch requests that arrive within a short time period.
Signature
declare function makeDataLoader(options: {
readonly embedMany: (input: readonly Array<string>) => Effect<Array<Result>, AiError>;
readonly maxBatchSize?: number;
readonly window: DurationInput;
}): Effect<any, unknown, unknown>Context
EmbeddingModel
The EmbeddingModel service tag for dependency injection.
This tag provides access to vector embedding functionality throughout your application, enabling conversion of text to high-dimensional vectors for semantic analysis.
Signature
declare class EmbeddingModel extends any {
constructor();
}Example
import { EmbeddingModel } from "@effect/ai"
import * as Effect from "effect/Effect"
const cosineSimilarity = (a: ReadonlyArray<number>, b: ReadonlyArray<number>): number => {
const dot = a.reduce((sum, ai, i) => sum + ai * (b[i] ?? 0), 0)
const normA = Math.sqrt(a.reduce((sum, ai) => sum + ai * ai, 0))
const normB = Math.sqrt(b.reduce((sum, bi) => sum + bi * bi, 0))
return normA === 0 || normB === 0 ? 0 : dot / (normA * normB)
}
const useEmbeddings = Effect.gen(function* () {
const embedder = yield* EmbeddingModel.EmbeddingModel
const documentVector = yield* embedder.embed("This is a sample document")
const queryVector = yield* embedder.embed("sample query")
const similarity = cosineSimilarity(documentVector, queryVector)
return similarity
})Models
Represents the result of a batch embedding operation.
Used internally by the batching system to associate embeddings with their original request positions in the batch.
Signature
interface Result {
readonly embeddings: Array<number>;
readonly index: number;
}Example
import { EmbeddingModel } from "@effect/ai"
const batchResults: EmbeddingModel.Result[] = [
{ index: 0, embeddings: [0.1, 0.2, 0.3] },
{ index: 1, embeddings: [0.4, 0.5, 0.6] },
{ index: 2, embeddings: [0.7, 0.8, 0.9] },
]
// Results correspond to input texts at positions 0, 1, 2The service interface for vector embedding operations.
Defines the contract that all embedding model implementations must fulfill. The service provides text-to-vector conversion functionality.
Signature
interface Service {
readonly embed: (input: string) => Effect<Array<number>, AiError>;
readonly embedMany: (input: readonly Array<string>, options?: {
readonly concurrency?: Concurrency;
}) => Effect<Array<Array<number>>, AiError>;
}
Creates an EmbeddingModel service with batching and caching capabilities.
This is the primary constructor for creating embedding services. It supports automatic batching of requests for efficiency and optional caching to reduce redundant API calls.