Skip to content

OpenAiEmbeddingModel

The OpenAiEmbeddingModel module adapts OpenAI-compatible embeddings endpoints to Effect's embedding model service. It sends embedding requests through OpenAiClient, exposes constructors for layers and AiModel values, supports scoped request configuration overrides, and checks that the provider returns one numeric vector for each requested input.

6 exports Added in v4.0.0 Source

Configuration

withConfigOverride

Added in v4.0.0 Source

Provides scoped request config overrides for OpenAI-compatible embedding model operations.

When to use

Use to apply embedding request options to one effect without changing the model's default configuration.

Details

The overrides are merged with any existing Config service for the duration of the supplied effect. Fields in overrides take precedence over existing config, and the helper supports both effect.pipe(withConfigOverride(overrides)) and withConfigOverride(effect, overrides).

See

  • Config for available OpenAI-compatible embedding request configuration fields

Signature

declare const withConfigOverride: {
  (
    overrides: {
      readonly dimensions?: number;
      readonly encoding_format?: "float" | "base64";
      readonly model?: string;
      readonly user?: string;
    } & {
      [x: string]: unknown;
    },
  ): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, Exclude<R, Config>>;
  <A, E, R>(
    self: Effect<A, E, R>,
    overrides: {
      readonly dimensions?: number;
      readonly encoding_format?: "float" | "base64";
      readonly model?: string;
      readonly user?: string;
    } & {
      [x: string]: unknown;
    },
  ): Effect<A, E, Exclude<R, Config>>;
};

Constructors

make

Added in v4.0.0 Source

Creates an OpenAI-compatible embedding model service backed by OpenAiClient.

When to use

Use when you need to build or provide an EmbeddingModel service directly from an existing OpenAiClient.

Details

The service sends embedding requests through OpenAiClient.createEmbedding. Request config is merged as the selected model, constructor config, then scoped Config, so scoped overrides take precedence. Provider usage prompt_tokens is exposed as usage.inputTokens.

Gotchas

Provider responses must contain one numeric vector for every requested input with unique, in-range index values; otherwise embedding operations fail with AiError.InvalidOutputError.

See

  • model for the higher-level AiModel descriptor that also provides EmbeddingModel.Dimensions
  • layer for providing the service as a Layer
  • withConfigOverride for scoping embedding request overrides

Signature

declare const make: (
  ...args: [
    {
      readonly config?: ModelConfig;
      readonly model: string;
    },
  ]
) => Effect<Service, never, OpenAiClient>;

model

Added in v4.0.0 Source

Creates an AiModel for an OpenAI-compatible embedding model with its configured vector dimensions.

When to use

Use to provide an OpenAI-compatible EmbeddingModel and its Dimensions service to an Effect program.

See

Signature

declare function model(
  model: string,
  options: Omit<
    {
      readonly dimensions?: number;
      readonly encoding_format?: "float" | "base64";
      readonly model?: string;
      readonly user?: string;
    },
    "model" | "dimensions"
  > & {
    [x: string]: unknown;
    readonly dimensions: number;
  },
): Model<"openai", EmbeddingModel | Dimensions, OpenAiClient>;

Layers

layer

Added in v4.0.0 Source

Creates a layer for an OpenAI-compatible embedding model service.

When to use

Use when composing application layers and you want an OpenAI-compatible embeddings endpoint to satisfy EmbeddingModel.EmbeddingModel while supplying OpenAiClient from another layer.

See

  • make for constructing the embedding model service effectfully
  • model for creating an AiModel with configured dimensions

Signature

declare function layer(options: {
  readonly config?: ModelConfig;
  readonly model: string;
}): Layer<EmbeddingModel, never, OpenAiClient>;

Models

Model type

Added in v4.0.0 Source

A model identifier accepted by an OpenAI-compatible embeddings endpoint.

Signature

type Model = string;

Services

Config

Added in v4.0.0 Source

Context service for OpenAI embedding model configuration.

When to use

Use when you need to provide shared default request options for OpenAI-compatible embedding operations through the Effect context, such as dimensions, encoding_format, or user.

Details

The service stores the embedding request payload without input. Requests combine the selected model, layer or constructor config, and scoped context config, with scoped context config taking precedence.

See

Signature

declare class Config extends Shape<
  "@effect/ai-openai-compat/OpenAiEmbeddingModel/Config",
  {
    readonly dimensions?: number;
    readonly encoding_format?: "float" | "base64";
    readonly model?: string;
    readonly user?: string;
  } & {
    [x: string]: unknown;
  },
  this
> {
  constructor(_: never);
}