@metrio-ai/embedding-sdk

Unified TypeScript SDK for generating text embeddings with optional Redis caching.

Install

npm install @metrio-ai/embedding-sdk

Quick Start

import { createEmbeddingClient } from "@metrio-ai/embedding-sdk";

const client = createEmbeddingClient();

const result = await client.embed("hello world", {
  provider: "openai",
  model: "text-embedding-3-small",
  dimensions: 1536
});

console.log(result.embedding);
console.log(result.cache.hit);

Sample Code

See examples/basic.ts for a runnable example that shows:

• One OpenAI embedding request.
• Batch Vertex Gemini embedding requests.
• Redis cache hit metadata.
• metadata.taskType for retrieval document embeddings.

Supported Models

| Provider | Model | Default dimensions | Max dimensions | | --- | --- | ---: | ---: | | openai | text-embedding-3-small | 1536 | 1536 | | openai | text-embedding-3-large | 3072 | 3072 | | vertex-microsoft | multilingual-e5-large | 1024 | 1024 | | vertex-gemini | gemini-embedding-001 | 3072 | 3072 | | vertex-gemini-2 | gemini-embedding-2 | 3072 | 3072 |

OpenAI text-embedding-3 models support smaller requested dimensions through the OpenAI dimensions parameter.

Vertex location constraints

Some Vertex models are only served from specific locations; requesting another location throws before any network call.

| Model | Allowed google.location | | --- | --- | | multilingual-e5-large | us-central1, europe-west4 | | gemini-embedding-2 | global (default), us, eu | | gemini-embedding-001 | any single region (e.g. us-central1, asia-east1) plus global/us/eu |

gemini-embedding-2 has no single-region endpoint; the SDK routes it to the global host (aiplatform.googleapis.com) or the multi-region hosts (aiplatform.us.rep.googleapis.com / aiplatform.eu.rep.googleapis.com). It defaults to global when no location is configured.

API Reference

createEmbeddingClient(config?)

Creates an embedding client. With no config, the SDK reads provider credentials and Redis settings from environment variables.

import { createEmbeddingClient } from "@metrio-ai/embedding-sdk";

const client = createEmbeddingClient({
  redis: {
    host: "localhost",
    port: 6379,
    keyPrefix: "embedding-sdk",
    ttlSeconds: 86400
  },
  openai: {
    apiKey: process.env.OPENAI_API_KEY
  },
  google: {
    projectId: "my-gcp-project",
    location: "us-central1"
  }
});

client.embed(input, options)

Generates one embedding.

const result = await client.embed("hello world", {
  provider: "vertex-gemini",
  model: "gemini-embedding-001",
  dimensions: 768,
  metadata: {
    taskType: "RETRIEVAL_DOCUMENT"
  }
});

Task type (Gemini models)

The Gemini embedding models (gemini-embedding-001 and gemini-embedding-2) accept an optional task type that tunes the vector for a specific use. Pass it via metadata.taskType. It is opt-in: when omitted, no task type is sent. The SDK maps it to the right field per model — task_type for the :predict API (gemini-embedding-001) and taskType for the :embedContent API (gemini-embedding-2).

The vertex-microsoft (e5) provider also forwards metadata.taskType as task_type on its :predict request, but e5 does not document task-type support, so the backend may ignore it. The OpenAI provider does not read metadata at all.

Common values: RETRIEVAL_DOCUMENT, RETRIEVAL_QUERY, SEMANTIC_SIMILARITY, CLASSIFICATION, CLUSTERING, QUESTION_ANSWERING, FACT_VERIFICATION, CODE_RETRIEVAL_QUERY.

For semantic search, embed stored items as documents and incoming searches as queries:

const productDescription = "Durable waterproof hiking backpack, 40L";
const searchText = "waterproof backpack for hiking";

// Indexing stored items
await client.embed(productDescription, {
  provider: "vertex-gemini-2",
  model: "gemini-embedding-2",
  metadata: { taskType: "RETRIEVAL_DOCUMENT" }
});

// Embedding a user's search
await client.embed(searchText, {
  provider: "vertex-gemini-2",
  model: "gemini-embedding-2",
  metadata: { taskType: "RETRIEVAL_QUERY" }
});

client.embedMany(inputs, options)

Generates embeddings for multiple inputs while preserving input order.

const results = await client.embedMany(["first", "second"], {
  provider: "openai",
  model: "text-embedding-3-small",
  dimensions: 512,
  concurrency: 2
});

Types

export type EmbeddingProvider =
  | "openai"
  | "vertex-microsoft"
  | "vertex-gemini"
  | "vertex-gemini-2";

export type SupportedEmbeddingModel =
  | "text-embedding-3-small"
  | "text-embedding-3-large"
  | "multilingual-e5-large"
  | "gemini-embedding-001"
  | "gemini-embedding-2";

export interface EmbedOptions {
  provider: EmbeddingProvider;
  model: SupportedEmbeddingModel;
  dimensions?: number;
  cache?: boolean;
  metadata?: Record<string, string | number | boolean>;
}

export interface EmbedManyOptions extends EmbedOptions {
  concurrency?: number;
}

export interface EmbedResult {
  embedding: number[];
  provider: EmbeddingProvider;
  model: SupportedEmbeddingModel;
  dimensions: number;
  cache: {
    enabled: boolean;
    hit: boolean;
    key?: string;
  };
  usage?: {
    inputTokens?: number;
    providerRaw?: unknown;
  };
}

export interface EmbeddingClientConfig {
  redis?: {
    url?: string;
    host?: string;
    port?: number;
    tls?: boolean;
    cluster?: boolean;
    keyPrefix?: string;
    /** Sliding TTL: reset on every hit. Unset = never expires (not evictable under volatile-lru). */
    ttlSeconds?: number;
    enabled?: boolean;
  };
  openai?: {
    apiKey?: string;
    baseURL?: string;
    organization?: string;
    project?: string;
  };
  google?: {
    projectId?: string;
    location?: string;
  };
}

metadata.taskType is passed to Vertex providers as task_type when it is a string. Metadata that affects provider requests is included in cache keys to avoid cross-task cache collisions.

Environment Variables

Redis:

| Name | Description | | --- | --- | | REDIS_HOST | Redis, Redis Cluster, or Memorystore Valkey host. Cache is disabled when neither this nor EMBEDDING_SDK_REDIS_URL is set. | | REDIS_PORT | Redis port. Defaults to 6379 when REDIS_HOST is set. | | REDIS_TLS | Set to true for TLS endpoints. | | REDIS_CLUSTER | Set to true for Redis Cluster or Valkey Cluster endpoints. | | EMBEDDING_SDK_REDIS_URL | Optional full Redis URL override. Takes precedence over REDIS_HOST and REDIS_PORT. | | EMBEDDING_SDK_REDIS_KEY_PREFIX | Redis key prefix. Defaults to embedding-sdk. | | EMBEDDING_SDK_REDIS_TTL_SECONDS | Optional TTL for cached embeddings. The TTL is sliding: every cache hit resets it (GETEX), so hot keys stay alive and only cold keys expire. If unset, keys never expire and cannot be evicted under volatile-lru. |

OpenAI:

| Name | Description | | --- | --- | | OPENAI_API_KEY | API key for OpenAI embeddings. | | OPENAI_BASE_URL | Optional OpenAI-compatible endpoint. | | OPENAI_ORG_ID | Optional organization id. | | OPENAI_PROJECT_ID | Optional project id. |

Google Vertex AI:

| Name | Description | | --- | --- | | GOOGLE_CLOUD_PROJECT | Google Cloud project id. | | GOOGLE_CLOUD_LOCATION | Vertex AI location, for example us-central1. | | GOOGLE_APPLICATION_CREDENTIALS | Optional path for service account credentials. |

Cache Behavior

When Redis is configured, the SDK checks Redis before calling a provider. The key includes the provider, model, dimensions, and a SHA-256 hash of the input text:

embedding-sdk:v1:openai:text-embedding-3-small:d1536:sha256:<input-hash>

Raw input text is not stored in the Redis key. Redis failures are treated as cache misses by default, so provider calls can continue.

For GCP Memorystore for Valkey cluster mode, set REDIS_HOST to the discovery endpoint address, set REDIS_PORT to the endpoint port, and set REDIS_CLUSTER=true. If the instance has in-transit encryption enabled, also set REDIS_TLS=true.

Errors

The SDK exports typed errors:

• EmbeddingConfigError
• EmbeddingValidationError
• EmbeddingProviderError
• EmbeddingCacheError

import { EmbeddingValidationError } from "@metrio-ai/embedding-sdk";

try {
  await client.embed("", {
    provider: "openai",
    model: "text-embedding-3-small"
  });
} catch (error) {
  if (error instanceof EmbeddingValidationError) {
    console.error(error.code, error.message);
  }
}

Publishing

Releases are designed for GitHub Actions:

• release.yml bumps package.json, commits, tags, and pushes.
• publish.yml publishes tagged releases to NPM.
• NPM trusted publishing through GitHub Actions OIDC is preferred over long-lived tokens.