EmbeddingModel.ts overview

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.

Example

import { EmbeddingModel } from "@effect/ai"
import { Effect } from "effect"

// Basic embedding usage
const program = Effect.gen(function* () {
  const embedding = yield* EmbeddingModel.EmbeddingModel

  const vector = yield* embedding.embed("Hello world!")
  console.log(vector) // [0.123, -0.456, 0.789, ...]

  return vector
})

Example

import { EmbeddingModel } from "@effect/ai"
import { Effect, Duration } from "effect"

declare const generateVectorFor: (text: string) => Array<number>

// Create embedding service with batching and caching
const embeddingService = EmbeddingModel.make({
  embedMany: (texts) =>
    Effect.succeed(
      texts.map((text, index) => ({
        index,
        embeddings: generateVectorFor(text)
      }))
    ),
  maxBatchSize: 50,
  cache: {
    capacity: 1000,
    timeToLive: Duration.minutes(30)
  }
})

Since v1.0.0

Exports Grouped by Category

Constructors
- make
- makeDataLoader
Context
- EmbeddingModel (class)
Models
- Result (interface)
- Service (interface)

Constructors

make

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.

Signature

declare const make: (options: {
  readonly embedMany: (input: ReadonlyArray<string>) => Effect.Effect<Array<Result>, AiError.AiError>
  readonly maxBatchSize?: number
  readonly cache?: { readonly capacity: number; readonly timeToLive: Duration.DurationInput }
}) => Effect.Effect<Service, never, never>

Source

Since v1.0.0

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 const makeDataLoader: (options: {
  readonly embedMany: (input: ReadonlyArray<string>) => Effect.Effect<Array<Result>, AiError.AiError>
  readonly window: Duration.DurationInput
  readonly maxBatchSize?: number
}) => Effect.Effect<Service, never, Scope>

Source

Since v1.0.0

Context

EmbeddingModel (class)

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.

Example

import { EmbeddingModel } from "@effect/ai"
import { Effect } from "effect"

const useEmbeddings = Effect.gen(function* () {
  const embedder = yield* 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
})

Signature

declare class EmbeddingModel

Source

Since v1.0.0

Models

Result (interface)

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.

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, 2

Signature

export interface Result {
  /**
   * The position index of this result in the original batch request.
   */
  readonly index: number

  /**
   * The vector embedding for the text at this index.
   */
  readonly embeddings: Array<number>
}

Source

Since v1.0.0

Service (interface)

The 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

export interface Service {
  /**
   * Converts a text string into a vector embedding.
   */
  readonly embed: (input: string) => Effect.Effect<Array<number>, AiError.AiError>
  /**
   * Converts a batch of text strings into a chunk of vector embeddings.
   */
  readonly embedMany: (
    input: ReadonlyArray<string>,
    options?: {
      /**
       * The concurrency level to use while batching requests.
       */
      readonly concurrency?: Types.Concurrency | undefined
    }
  ) => Effect.Effect<Array<Array<number>>, AiError.AiError>
}

Source

Since v1.0.0