@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 |

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

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"
  }
});

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";

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

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;
    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. |

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.