Embedders API

API reference for embedders in Genkit (JavaScript/TypeScript)

Embedders convert text and documents into vector embeddings for semantic search and retrieval.

defineEmbedder()

Defines and registers an embedder.

import { defineEmbedder } from '@genkit-ai/ai';
import { z } from 'zod';

const myEmbedder = defineEmbedder(
  registry,
  {
    name: 'myEmbedder',
    configSchema: z.object({
      dimensions: z.number().optional(),
    }),
    info: {
      label: 'My Custom Embedder',
      dimensions: 768,
      supports: {
        input: ['text'],
      },
    },
  },
  async (input, options) => {
    // Generate embeddings for each document
    const embeddings = input.map(doc => ({
      embedding: generateEmbedding(doc.text()),
    }));
    
    return { embeddings };
  }
);

Parameters

registry · Registry · required

The Genkit registry instance

options · EmbedderOptions<ConfigSchema> · required

Embedder configuration

Show EmbedderOptions properties

name · string · required

Unique name for the embedder

configSchema · ZodTypeAny

Zod schema for embedder-specific configuration options

info · EmbedderInfo

Metadata about the embedder’s capabilities

Show EmbedderInfo properties

label · string

Human-readable label for the embedder

dimensions · number

Embedding vector dimension size

supports · object

input · Array<'text' | 'image' | 'video'>

Supported input types

multilingual · boolean

Whether the embedder supports multiple languages

runner · EmbedderFn<ConfigSchema> · required

Implementation function

Function signature:

(input: Document[], options?: z.infer<ConfigSchema>) => Promise<EmbedResponse>

Returns

EmbedderAction · EmbedderAction<ConfigSchema>

An embedder action that can be used with embed()

embed()

Generates embeddings for text or documents.

import { embed } from '@genkit-ai/ai';

const embeddings = await embed(registry, {
  embedder: 'myEmbedder',
  content: 'Hello, world!',
});

console.log(embeddings[0].embedding); // [0.123, 0.456, ...]

Parameters

registry · Registry · required

The Genkit registry instance

params · EmbedderParams<CustomOptions> · required

Embedding request parameters

Show EmbedderParams properties

embedder · EmbedderArgument<CustomOptions> · required

Embedder to use (string name, EmbedderAction, or EmbedderReference)

content · string | DocumentData · required

Text or document to embed

metadata · Record<string, unknown>

Metadata to attach to the document

options · z.infer<CustomOptions>

Embedder-specific configuration options

Returns

embeddings · Embedding[]

Array of embedding objects

{
  embedding: number[];  // Vector representation
  metadata?: Record<string, unknown>;
}

embedMany()

Generates embeddings for multiple documents in a batch.

import { embedMany } from '@genkit-ai/ai';

const embeddings = await embedMany(registry, {
  embedder: 'myEmbedder',
  content: ['First document', 'Second document', 'Third document'],
});

console.log(embeddings.length); // 3

Parameters

registry · Registry · required

The Genkit registry instance

params · object · required

embedder · EmbedderArgument<ConfigSchema> · required

Embedder to use

content · string[] | DocumentData[] · required

Array of texts or documents to embed

metadata · Record<string, unknown>

Metadata to attach to all documents

options · z.infer<ConfigSchema>

Embedder-specific options

Returns

embeddings · EmbeddingBatch

Batch of embeddings

type EmbeddingBatch = { embedding: number[] }[];

embedderRef()

Creates a reference to an embedder with configuration.

import { embedderRef } from '@genkit-ai/ai';
import { z } from 'zod';

const myEmbedderRef = embedderRef({
  name: 'myEmbedder',
  config: { dimensions: 512 },
  info: {
    label: 'My Embedder',
    dimensions: 512,
  },
});

// Use the reference
const embeddings = await embed(registry, {
  embedder: myEmbedderRef,
  content: 'Hello',
});

Parameters

options · EmbedderReference<CustomOptionsSchema> · required

name · string · required

Embedder name

configSchema · CustomOptionsSchema

Configuration schema

info · EmbedderInfo

Embedder metadata

config · z.infer<CustomOptionsSchema>

Configuration values

version · string

Embedder version

namespace · string

Optional namespace prefix

Returns

reference · EmbedderReference<CustomOptionsSchema>

An embedder reference that can be passed to embed()

Types

EmbedRequest

interface EmbedRequest<O = any> {
  input: Document[];
  options?: O;
}

EmbedResponse

interface EmbedResponse {
  embeddings: Embedding[];
}

Embedding

interface Embedding {
  embedding: number[];
  metadata?: Record<string, unknown>;
}

EmbedderAction

type EmbedderAction<CustomOptions extends z.ZodTypeAny = z.ZodTypeAny> = 
  Action<typeof EmbedRequestSchema, typeof EmbedResponseSchema> & {
    __configSchema?: CustomOptions;
  };

Example: Custom Embedder

import { ai } from './genkit';
import { Document } from '@genkit-ai/ai';
import { z } from 'zod';

const customEmbedder = ai.defineEmbedder(
  {
    name: 'custom/embedder',
    configSchema: z.object({
      model: z.string().default('base'),
      batchSize: z.number().default(32),
    }),
    info: {
      label: 'Custom Embedder',
      dimensions: 768,
      supports: {
        input: ['text'],
        multilingual: false,
      },
    },
  },
  async (documents, options) => {
    const embeddings = [];
    
    // Process in batches
    for (let i = 0; i < documents.length; i += options.batchSize) {
      const batch = documents.slice(i, i + options.batchSize);
      const batchEmbeddings = await generateEmbeddingsBatch(
        batch.map(d => d.text()),
        options.model
      );
      embeddings.push(...batchEmbeddings);
    }
    
    return {
      embeddings: embeddings.map((embedding, i) => ({
        embedding,
        metadata: documents[i].metadata,
      })),
    };
  }
);

// Use the embedder
const result = await ai.embed({
  embedder: customEmbedder,
  content: 'Sample text to embed',
});