Skip to content

OpenAiEmbeddingModel

The OpenAiEmbeddingModel module provides the OpenAI implementation of Effect AI's EmbeddingModel service. It sends embedding requests through OpenAiClient, exposes constructors for layers and AiModel values, supports scoped request configuration overrides, and checks that OpenAI 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 config overrides for OpenAI embedding model operations.

When to use

Use when you need scoped OpenAI embedding request defaults for a single effect or workflow without rebuilding the embedding model service.

Details

Supports both data-first and data-last forms. Existing scoped config is read first, then the provided overrides are applied so override fields take precedence.

See

  • Config for the scoped embedding request configuration service

Signature

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

Constructors

make

Added in v4.0.0 Source

Creates an OpenAI embedding model service.

When to use

Use to construct the EmbeddingModel.Service effectfully when OpenAiClient is already available in the environment.

Details

The model option is sent with each embedding request. Constructor config supplies create-embedding request fields other than model and input, and scoped overrides from withConfigOverride are merged last for each request.

Gotchas

The service expects numeric embedding vectors. It fails with InvalidOutputError when the provider returns base64 embeddings, out-of-range indexes, duplicate indexes, or an unexpected number of embeddings.

See

  • layer for providing the embedding model service as a layer
  • model for creating an AiModel that also provides dimensions
  • withConfigOverride for scoped request configuration overrides

Signature

declare const make: (
  ...args: [
    {
      readonly config?: Omit<
        {
          [key: string]: unknown;
          readonly dimensions?: number;
          readonly encoding_format?: "float" | "base64";
          readonly model?: string;
          readonly user?: string;
        },
        "model"
      >;
      readonly model: (string & {}) | Model;
    },
  ]
) => Effect<Service, never, OpenAiClient>;

model

Added in v4.0.0 Source

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

When to use

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

See

Signature

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

Layers

layer

Added in v4.0.0 Source

Creates a layer for the OpenAI embedding model.

When to use

Use when composing application layers and you want OpenAI to satisfy EmbeddingModel.EmbeddingModel while supplying OpenAiClient from another layer.

Gotchas

Use the default floating-point embedding format. The service expects numeric vectors and fails with InvalidOutputError if OpenAI returns base64 embeddings.

See

  • make for constructing the embedding model service effectfully
  • model for creating an AiModel that also provides embedding dimensions

Signature

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

Models

Model type

Added in v4.0.0 Source

Model identifiers supported by OpenAI's embeddings API.

Signature

type Model = "text-embedding-ada-002" | "text-embedding-3-small" | "text-embedding-3-large";

Services

Config

Added in v4.0.0 Source

Context service for OpenAI embedding model configuration.

When to use

Use when you need scoped OpenAI request defaults or overrides for embedding requests from Effect context.

Details

The service stores the OpenAI create-embedding request payload without input, carrying options such as model, dimensions, encoding_format, and user.

See

Signature

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