@objectstack/embedder-openai 6.7.0

package/dist/index.js

@@ -0,0 +1,124 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  OPENAI_COMPATIBLE_PRESETS: () => OPENAI_COMPATIBLE_PRESETS,
+  OpenAIEmbedder: () => OpenAIEmbedder,
+  createOpenAIEmbedder: () => createOpenAIEmbedder,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var KNOWN_DIMENSIONS = {
+  // OpenAI
+  "text-embedding-3-small": 1536,
+  "text-embedding-3-large": 3072,
+  "text-embedding-ada-002": 1536,
+  // 阿里通义
+  "text-embedding-v3": 1024,
+  "text-embedding-v2": 1536,
+  "text-embedding-v1": 1536,
+  // 智谱
+  "embedding-3": 2048,
+  "embedding-2": 1024,
+  // 硅基流动 / BGE 家族
+  "BAAI/bge-m3": 1024,
+  "BAAI/bge-large-zh-v1.5": 1024,
+  "BAAI/bge-large-en-v1.5": 1024,
+  "BAAI/bge-base-zh-v1.5": 768,
+  "BAAI/bge-small-zh-v1.5": 512,
+  "bge-m3": 1024,
+  // 火山 Doubao
+  "doubao-embedding-large-text-240915": 4096,
+  "doubao-embedding-text-240715": 2048,
+  // Nomic / Ollama defaults
+  "nomic-embed-text": 768,
+  // MiniMax
+  "embo-01": 1536
+};
+var OpenAIEmbedder = class {
+  constructor(opts) {
+    if (!opts.apiKey) throw new Error("OpenAIEmbedder: apiKey required");
+    this.apiKey = opts.apiKey;
+    this.id = opts.id ?? "openai";
+    this.model = opts.model ?? "text-embedding-3-small";
+    this.baseUrl = (opts.baseUrl ?? "https://api.openai.com/v1").replace(/\/+$/, "");
+    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+    this.requestedDims = opts.dimensions;
+    this.extraHeaders = opts.headers ?? {};
+    this.dimensions = opts.dimensions ?? KNOWN_DIMENSIONS[this.model] ?? 1536;
+    if (!this.fetchImpl) {
+      throw new Error(
+        "OpenAIEmbedder: no fetch available; pass options.fetch or run on Node 18+ / a fetch-capable runtime"
+      );
+    }
+  }
+  async embed(texts) {
+    if (texts.length === 0) return [];
+    const body = { model: this.model, input: texts };
+    if (this.requestedDims) body.dimensions = this.requestedDims;
+    const res = await this.fetchImpl(`${this.baseUrl}/embeddings`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${this.apiKey}`,
+        ...this.extraHeaders
+      },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(
+        `OpenAIEmbedder (${this.baseUrl}) \u2192 ${res.status} ${res.statusText}${text ? `: ${text.slice(0, 200)}` : ""}`
+      );
+    }
+    const json = await res.json();
+    const data = json.data ?? [];
+    if (data.length !== texts.length) {
+      throw new Error(
+        `OpenAIEmbedder: expected ${texts.length} vectors, got ${data.length}`
+      );
+    }
+    return data.map((d) => d.embedding);
+  }
+};
+var OPENAI_COMPATIBLE_PRESETS = {
+  openai: "https://api.openai.com/v1",
+  azure: "",
+  // user must provide full deployment URL via baseUrl
+  dashscope: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+  zhipu: "https://open.bigmodel.cn/api/paas/v4",
+  siliconflow: "https://api.siliconflow.cn/v1",
+  doubao: "https://ark.cn-beijing.volces.com/api/v3",
+  minimax: "https://api.minimax.chat/v1",
+  ollama: "http://localhost:11434/v1"
+};
+function createOpenAIEmbedder(opts) {
+  const baseUrl = opts.baseUrl ?? (opts.preset ? OPENAI_COMPATIBLE_PRESETS[opts.preset] : void 0);
+  return new OpenAIEmbedder({ ...opts, baseUrl, id: opts.id ?? opts.preset ?? "openai" });
+}
+var index_default = OpenAIEmbedder;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  OPENAI_COMPATIBLE_PRESETS,
+  OpenAIEmbedder,
+  createOpenAIEmbedder
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * `@objectstack/embedder-openai`\n *\n * OpenAI-compatible embedder. Drop-in for any endpoint that speaks the\n * `POST /v1/embeddings` shape:\n *\n *   - OpenAI                  https://api.openai.com/v1\n *   - Azure OpenAI            https://{resource}.openai.azure.com/openai/deployments/{deployment}\n *   - 阿里通义 DashScope       https://dashscope.aliyuncs.com/compatible-mode/v1\n *   - 智谱 BigModel            https://open.bigmodel.cn/api/paas/v4\n *   - 硅基流动 SiliconFlow     https://api.siliconflow.cn/v1\n *   - 火山引擎 Doubao          https://ark.cn-beijing.volces.com/api/v3\n *   - MiniMax                 https://api.minimax.chat/v1\n *   - Ollama (openai shim)    http://localhost:11434/v1\n *   - LiteLLM / vLLM / 任何兼容服务\n *\n * Implements the `IEmbedder` contract from `@objectstack/spec/contracts`.\n */\n\nimport type { IEmbedder } from '@objectstack/spec/contracts';\n\nexport interface OpenAIEmbedderOptions {\n  /** Bearer token sent as `Authorization: Bearer <apiKey>`. Required. */\n  apiKey: string;\n  /**\n   * Model id sent in the request body. Choose to match your provider:\n   *  - OpenAI:        `'text-embedding-3-small'` (default), `'text-embedding-3-large'`\n   *  - 阿里通义:       `'text-embedding-v3'`\n   *  - 智谱:           `'embedding-3'`\n   *  - 硅基流动:       `'BAAI/bge-m3'`, `'BAAI/bge-large-zh-v1.5'`\n   *  - 火山 Doubao:    `'doubao-embedding-large-text-240915'`\n   *  - Ollama:        `'bge-m3'`, `'nomic-embed-text'`\n   *\n   * @default 'text-embedding-3-small'\n   */\n  model?: string;\n  /**\n   * Override dimensions. Only Matryoshka-style models (OpenAI v3, 智谱 embedding-3,\n   * BGE-m3 dense) support truncation. When set, also forwarded to the upstream\n   * `dimensions` body field for providers that honour it.\n   */\n  dimensions?: number;\n  /**\n   * Endpoint base URL (without `/embeddings`). Defaults to OpenAI's. Set this\n   * to point at any compatible provider.\n   *\n   * @default 'https://api.openai.com/v1'\n   */\n  baseUrl?: string;\n  /** Stable id surfaced as `IEmbedder.id`. @default 'openai' */\n  id?: string;\n  /** Inject for tests. Defaults to `globalThis.fetch`. */\n  fetch?: typeof fetch;\n  /** Additional headers (e.g. provider-specific keys, tracing). */\n  headers?: Record<string, string>;\n}\n\n/**\n * Known dimensions for popular models. Used as the default when the\n * caller doesn't pass `dimensions` explicitly.\n */\nconst KNOWN_DIMENSIONS: Record<string, number> = {\n  // OpenAI\n  'text-embedding-3-small': 1536,\n  'text-embedding-3-large': 3072,\n  'text-embedding-ada-002': 1536,\n  // 阿里通义\n  'text-embedding-v3': 1024,\n  'text-embedding-v2': 1536,\n  'text-embedding-v1': 1536,\n  // 智谱\n  'embedding-3': 2048,\n  'embedding-2': 1024,\n  // 硅基流动 / BGE 家族\n  'BAAI/bge-m3': 1024,\n  'BAAI/bge-large-zh-v1.5': 1024,\n  'BAAI/bge-large-en-v1.5': 1024,\n  'BAAI/bge-base-zh-v1.5': 768,\n  'BAAI/bge-small-zh-v1.5': 512,\n  'bge-m3': 1024,\n  // 火山 Doubao\n  'doubao-embedding-large-text-240915': 4096,\n  'doubao-embedding-text-240715': 2048,\n  // Nomic / Ollama defaults\n  'nomic-embed-text': 768,\n  // MiniMax\n  'embo-01': 1536,\n};\n\n/**\n * `OpenAIEmbedder` — OpenAI-compatible embedder. One instance per\n * upstream provider + model combination. Pass into any knowledge\n * adapter that expects `IEmbedder`.\n *\n * @example\n * // OpenAI\n * new OpenAIEmbedder({ apiKey: process.env.OPENAI_API_KEY! });\n *\n * @example\n * // 阿里通义 DashScope\n * new OpenAIEmbedder({\n *   apiKey: process.env.DASHSCOPE_API_KEY!,\n *   baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1',\n *   model: 'text-embedding-v3',\n * });\n *\n * @example\n * // 硅基流动 SiliconFlow + BGE-m3\n * new OpenAIEmbedder({\n *   apiKey: process.env.SILICONFLOW_API_KEY!,\n *   baseUrl: 'https://api.siliconflow.cn/v1',\n *   model: 'BAAI/bge-m3',\n * });\n *\n * @example\n * // Local Ollama\n * new OpenAIEmbedder({\n *   apiKey: 'ollama',\n *   baseUrl: 'http://localhost:11434/v1',\n *   model: 'bge-m3',\n * });\n */\nexport class OpenAIEmbedder implements IEmbedder {\n  readonly id: string;\n  readonly dimensions: number;\n  private readonly model: string;\n  private readonly baseUrl: string;\n  private readonly apiKey: string;\n  private readonly fetchImpl: typeof fetch;\n  private readonly requestedDims?: number;\n  private readonly extraHeaders: Record<string, string>;\n\n  constructor(opts: OpenAIEmbedderOptions) {\n    if (!opts.apiKey) throw new Error('OpenAIEmbedder: apiKey required');\n    this.apiKey = opts.apiKey;\n    this.id = opts.id ?? 'openai';\n    this.model = opts.model ?? 'text-embedding-3-small';\n    this.baseUrl = (opts.baseUrl ?? 'https://api.openai.com/v1').replace(/\\/+$/, '');\n    this.fetchImpl = opts.fetch ?? (globalThis.fetch as typeof fetch);\n    this.requestedDims = opts.dimensions;\n    this.extraHeaders = opts.headers ?? {};\n    this.dimensions =\n      opts.dimensions ?? KNOWN_DIMENSIONS[this.model] ?? 1536;\n    if (!this.fetchImpl) {\n      throw new Error(\n        'OpenAIEmbedder: no fetch available; pass options.fetch or run on Node 18+ / a fetch-capable runtime',\n      );\n    }\n  }\n\n  async embed(texts: string[]): Promise<number[][]> {\n    if (texts.length === 0) return [];\n    const body: Record<string, unknown> = { model: this.model, input: texts };\n    if (this.requestedDims) body.dimensions = this.requestedDims;\n    const res = await this.fetchImpl(`${this.baseUrl}/embeddings`, {\n      method: 'POST',\n      headers: {\n        'content-type': 'application/json',\n        authorization: `Bearer ${this.apiKey}`,\n        ...this.extraHeaders,\n      },\n      body: JSON.stringify(body),\n    });\n    if (!res.ok) {\n      const text = await res.text().catch(() => '');\n      throw new Error(\n        `OpenAIEmbedder (${this.baseUrl}) → ${res.status} ${res.statusText}${text ? `: ${text.slice(0, 200)}` : ''}`,\n      );\n    }\n    const json = (await res.json()) as { data?: Array<{ embedding: number[] }> };\n    const data = json.data ?? [];\n    if (data.length !== texts.length) {\n      throw new Error(\n        `OpenAIEmbedder: expected ${texts.length} vectors, got ${data.length}`,\n      );\n    }\n    return data.map((d) => d.embedding);\n  }\n}\n\n/**\n * Convenience presets for popular Chinese providers — saves callers\n * from memorising base URLs. Pass through `createXxxEmbedder({...})`.\n */\nexport const OPENAI_COMPATIBLE_PRESETS = {\n  openai: 'https://api.openai.com/v1',\n  azure: '', // user must provide full deployment URL via baseUrl\n  dashscope: 'https://dashscope.aliyuncs.com/compatible-mode/v1',\n  zhipu: 'https://open.bigmodel.cn/api/paas/v4',\n  siliconflow: 'https://api.siliconflow.cn/v1',\n  doubao: 'https://ark.cn-beijing.volces.com/api/v3',\n  minimax: 'https://api.minimax.chat/v1',\n  ollama: 'http://localhost:11434/v1',\n} as const;\n\nexport type OpenAICompatiblePreset = keyof typeof OPENAI_COMPATIBLE_PRESETS;\n\nexport interface PresetEmbedderOptions\n  extends Omit<OpenAIEmbedderOptions, 'baseUrl'> {\n  /** Pick a known provider; sets `baseUrl` automatically. */\n  preset?: OpenAICompatiblePreset;\n  /** Explicit override; takes precedence over `preset`. */\n  baseUrl?: string;\n}\n\n/**\n * Helper: pick a provider by preset name. Equivalent to constructing\n * `OpenAIEmbedder` with the matching `baseUrl`.\n *\n * @example\n * createOpenAIEmbedder({ preset: 'dashscope', apiKey, model: 'text-embedding-v3' })\n */\nexport function createOpenAIEmbedder(opts: PresetEmbedderOptions): OpenAIEmbedder {\n  const baseUrl =\n    opts.baseUrl ??\n    (opts.preset ? OPENAI_COMPATIBLE_PRESETS[opts.preset] : undefined);\n  return new OpenAIEmbedder({ ...opts, baseUrl, id: opts.id ?? opts.preset ?? 'openai' });\n}\n\nexport default OpenAIEmbedder;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA+DA,IAAM,mBAA2C;AAAA;AAAA,EAE/C,0BAA0B;AAAA,EAC1B,0BAA0B;AAAA,EAC1B,0BAA0B;AAAA;AAAA,EAE1B,qBAAqB;AAAA,EACrB,qBAAqB;AAAA,EACrB,qBAAqB;AAAA;AAAA,EAErB,eAAe;AAAA,EACf,eAAe;AAAA;AAAA,EAEf,eAAe;AAAA,EACf,0BAA0B;AAAA,EAC1B,0BAA0B;AAAA,EAC1B,yBAAyB;AAAA,EACzB,0BAA0B;AAAA,EAC1B,UAAU;AAAA;AAAA,EAEV,sCAAsC;AAAA,EACtC,gCAAgC;AAAA;AAAA,EAEhC,oBAAoB;AAAA;AAAA,EAEpB,WAAW;AACb;AAmCO,IAAM,iBAAN,MAA0C;AAAA,EAU/C,YAAY,MAA6B;AACvC,QAAI,CAAC,KAAK,OAAQ,OAAM,IAAI,MAAM,iCAAiC;AACnE,SAAK,SAAS,KAAK;AACnB,SAAK,KAAK,KAAK,MAAM;AACrB,SAAK,QAAQ,KAAK,SAAS;AAC3B,SAAK,WAAW,KAAK,WAAW,6BAA6B,QAAQ,QAAQ,EAAE;AAC/E,SAAK,YAAY,KAAK,SAAU,WAAW;AAC3C,SAAK,gBAAgB,KAAK;AAC1B,SAAK,eAAe,KAAK,WAAW,CAAC;AACrC,SAAK,aACH,KAAK,cAAc,iBAAiB,KAAK,KAAK,KAAK;AACrD,QAAI,CAAC,KAAK,WAAW;AACnB,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAAA,EAEA,MAAM,MAAM,OAAsC;AAChD,QAAI,MAAM,WAAW,EAAG,QAAO,CAAC;AAChC,UAAM,OAAgC,EAAE,OAAO,KAAK,OAAO,OAAO,MAAM;AACxE,QAAI,KAAK,cAAe,MAAK,aAAa,KAAK;AAC/C,UAAM,MAAM,MAAM,KAAK,UAAU,GAAG,KAAK,OAAO,eAAe;AAAA,MAC7D,QAAQ;AAAA,MACR,SAAS;AAAA,QACP,gBAAgB;AAAA,QAChB,eAAe,UAAU,KAAK,MAAM;AAAA,QACpC,GAAG,KAAK;AAAA,MACV;AAAA,MACA,MAAM,KAAK,UAAU,IAAI;AAAA,IAC3B,CAAC;AACD,QAAI,CAAC,IAAI,IAAI;AACX,YAAM,OAAO,MAAM,IAAI,KAAK,EAAE,MAAM,MAAM,EAAE;AAC5C,YAAM,IAAI;AAAA,QACR,mBAAmB,KAAK,OAAO,YAAO,IAAI,MAAM,IAAI,IAAI,UAAU,GAAG,OAAO,KAAK,KAAK,MAAM,GAAG,GAAG,CAAC,KAAK,EAAE;AAAA,MAC5G;AAAA,IACF;AACA,UAAM,OAAQ,MAAM,IAAI,KAAK;AAC7B,UAAM,OAAO,KAAK,QAAQ,CAAC;AAC3B,QAAI,KAAK,WAAW,MAAM,QAAQ;AAChC,YAAM,IAAI;AAAA,QACR,4BAA4B,MAAM,MAAM,iBAAiB,KAAK,MAAM;AAAA,MACtE;AAAA,IACF;AACA,WAAO,KAAK,IAAI,CAAC,MAAM,EAAE,SAAS;AAAA,EACpC;AACF;AAMO,IAAM,4BAA4B;AAAA,EACvC,QAAQ;AAAA,EACR,OAAO;AAAA;AAAA,EACP,WAAW;AAAA,EACX,OAAO;AAAA,EACP,aAAa;AAAA,EACb,QAAQ;AAAA,EACR,SAAS;AAAA,EACT,QAAQ;AACV;AAmBO,SAAS,qBAAqB,MAA6C;AAChF,QAAM,UACJ,KAAK,YACJ,KAAK,SAAS,0BAA0B,KAAK,MAAM,IAAI;AAC1D,SAAO,IAAI,eAAe,EAAE,GAAG,MAAM,SAAS,IAAI,KAAK,MAAM,KAAK,UAAU,SAAS,CAAC;AACxF;AAEA,IAAO,gBAAQ;","names":[]}

package/dist/index.mjs

@@ -0,0 +1,97 @@
+// src/index.ts
+var KNOWN_DIMENSIONS = {
+  // OpenAI
+  "text-embedding-3-small": 1536,
+  "text-embedding-3-large": 3072,
+  "text-embedding-ada-002": 1536,
+  // 阿里通义
+  "text-embedding-v3": 1024,
+  "text-embedding-v2": 1536,
+  "text-embedding-v1": 1536,
+  // 智谱
+  "embedding-3": 2048,
+  "embedding-2": 1024,
+  // 硅基流动 / BGE 家族
+  "BAAI/bge-m3": 1024,
+  "BAAI/bge-large-zh-v1.5": 1024,
+  "BAAI/bge-large-en-v1.5": 1024,
+  "BAAI/bge-base-zh-v1.5": 768,
+  "BAAI/bge-small-zh-v1.5": 512,
+  "bge-m3": 1024,
+  // 火山 Doubao
+  "doubao-embedding-large-text-240915": 4096,
+  "doubao-embedding-text-240715": 2048,
+  // Nomic / Ollama defaults
+  "nomic-embed-text": 768,
+  // MiniMax
+  "embo-01": 1536
+};
+var OpenAIEmbedder = class {
+  constructor(opts) {
+    if (!opts.apiKey) throw new Error("OpenAIEmbedder: apiKey required");
+    this.apiKey = opts.apiKey;
+    this.id = opts.id ?? "openai";
+    this.model = opts.model ?? "text-embedding-3-small";
+    this.baseUrl = (opts.baseUrl ?? "https://api.openai.com/v1").replace(/\/+$/, "");
+    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+    this.requestedDims = opts.dimensions;
+    this.extraHeaders = opts.headers ?? {};
+    this.dimensions = opts.dimensions ?? KNOWN_DIMENSIONS[this.model] ?? 1536;
+    if (!this.fetchImpl) {
+      throw new Error(
+        "OpenAIEmbedder: no fetch available; pass options.fetch or run on Node 18+ / a fetch-capable runtime"
+      );
+    }
+  }
+  async embed(texts) {
+    if (texts.length === 0) return [];
+    const body = { model: this.model, input: texts };
+    if (this.requestedDims) body.dimensions = this.requestedDims;
+    const res = await this.fetchImpl(`${this.baseUrl}/embeddings`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${this.apiKey}`,
+        ...this.extraHeaders
+      },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(
+        `OpenAIEmbedder (${this.baseUrl}) \u2192 ${res.status} ${res.statusText}${text ? `: ${text.slice(0, 200)}` : ""}`
+      );
+    }
+    const json = await res.json();
+    const data = json.data ?? [];
+    if (data.length !== texts.length) {
+      throw new Error(
+        `OpenAIEmbedder: expected ${texts.length} vectors, got ${data.length}`
+      );
+    }
+    return data.map((d) => d.embedding);
+  }
+};
+var OPENAI_COMPATIBLE_PRESETS = {
+  openai: "https://api.openai.com/v1",
+  azure: "",
+  // user must provide full deployment URL via baseUrl
+  dashscope: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+  zhipu: "https://open.bigmodel.cn/api/paas/v4",
+  siliconflow: "https://api.siliconflow.cn/v1",
+  doubao: "https://ark.cn-beijing.volces.com/api/v3",
+  minimax: "https://api.minimax.chat/v1",
+  ollama: "http://localhost:11434/v1"
+};
+function createOpenAIEmbedder(opts) {
+  const baseUrl = opts.baseUrl ?? (opts.preset ? OPENAI_COMPATIBLE_PRESETS[opts.preset] : void 0);
+  return new OpenAIEmbedder({ ...opts, baseUrl, id: opts.id ?? opts.preset ?? "openai" });
+}
+var index_default = OpenAIEmbedder;
+export {
+  OPENAI_COMPATIBLE_PRESETS,
+  OpenAIEmbedder,
+  createOpenAIEmbedder,
+  index_default as default
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * `@objectstack/embedder-openai`\n *\n * OpenAI-compatible embedder. Drop-in for any endpoint that speaks the\n * `POST /v1/embeddings` shape:\n *\n *   - OpenAI                  https://api.openai.com/v1\n *   - Azure OpenAI            https://{resource}.openai.azure.com/openai/deployments/{deployment}\n *   - 阿里通义 DashScope       https://dashscope.aliyuncs.com/compatible-mode/v1\n *   - 智谱 BigModel            https://open.bigmodel.cn/api/paas/v4\n *   - 硅基流动 SiliconFlow     https://api.siliconflow.cn/v1\n *   - 火山引擎 Doubao          https://ark.cn-beijing.volces.com/api/v3\n *   - MiniMax                 https://api.minimax.chat/v1\n *   - Ollama (openai shim)    http://localhost:11434/v1\n *   - LiteLLM / vLLM / 任何兼容服务\n *\n * Implements the `IEmbedder` contract from `@objectstack/spec/contracts`.\n */\n\nimport type { IEmbedder } from '@objectstack/spec/contracts';\n\nexport interface OpenAIEmbedderOptions {\n  /** Bearer token sent as `Authorization: Bearer <apiKey>`. Required. */\n  apiKey: string;\n  /**\n   * Model id sent in the request body. Choose to match your provider:\n   *  - OpenAI:        `'text-embedding-3-small'` (default), `'text-embedding-3-large'`\n   *  - 阿里通义:       `'text-embedding-v3'`\n   *  - 智谱:           `'embedding-3'`\n   *  - 硅基流动:       `'BAAI/bge-m3'`, `'BAAI/bge-large-zh-v1.5'`\n   *  - 火山 Doubao:    `'doubao-embedding-large-text-240915'`\n   *  - Ollama:        `'bge-m3'`, `'nomic-embed-text'`\n   *\n   * @default 'text-embedding-3-small'\n   */\n  model?: string;\n  /**\n   * Override dimensions. Only Matryoshka-style models (OpenAI v3, 智谱 embedding-3,\n   * BGE-m3 dense) support truncation. When set, also forwarded to the upstream\n   * `dimensions` body field for providers that honour it.\n   */\n  dimensions?: number;\n  /**\n   * Endpoint base URL (without `/embeddings`). Defaults to OpenAI's. Set this\n   * to point at any compatible provider.\n   *\n   * @default 'https://api.openai.com/v1'\n   */\n  baseUrl?: string;\n  /** Stable id surfaced as `IEmbedder.id`. @default 'openai' */\n  id?: string;\n  /** Inject for tests. Defaults to `globalThis.fetch`. */\n  fetch?: typeof fetch;\n  /** Additional headers (e.g. provider-specific keys, tracing). */\n  headers?: Record<string, string>;\n}\n\n/**\n * Known dimensions for popular models. Used as the default when the\n * caller doesn't pass `dimensions` explicitly.\n */\nconst KNOWN_DIMENSIONS: Record<string, number> = {\n  // OpenAI\n  'text-embedding-3-small': 1536,\n  'text-embedding-3-large': 3072,\n  'text-embedding-ada-002': 1536,\n  // 阿里通义\n  'text-embedding-v3': 1024,\n  'text-embedding-v2': 1536,\n  'text-embedding-v1': 1536,\n  // 智谱\n  'embedding-3': 2048,\n  'embedding-2': 1024,\n  // 硅基流动 / BGE 家族\n  'BAAI/bge-m3': 1024,\n  'BAAI/bge-large-zh-v1.5': 1024,\n  'BAAI/bge-large-en-v1.5': 1024,\n  'BAAI/bge-base-zh-v1.5': 768,\n  'BAAI/bge-small-zh-v1.5': 512,\n  'bge-m3': 1024,\n  // 火山 Doubao\n  'doubao-embedding-large-text-240915': 4096,\n  'doubao-embedding-text-240715': 2048,\n  // Nomic / Ollama defaults\n  'nomic-embed-text': 768,\n  // MiniMax\n  'embo-01': 1536,\n};\n\n/**\n * `OpenAIEmbedder` — OpenAI-compatible embedder. One instance per\n * upstream provider + model combination. Pass into any knowledge\n * adapter that expects `IEmbedder`.\n *\n * @example\n * // OpenAI\n * new OpenAIEmbedder({ apiKey: process.env.OPENAI_API_KEY! });\n *\n * @example\n * // 阿里通义 DashScope\n * new OpenAIEmbedder({\n *   apiKey: process.env.DASHSCOPE_API_KEY!,\n *   baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1',\n *   model: 'text-embedding-v3',\n * });\n *\n * @example\n * // 硅基流动 SiliconFlow + BGE-m3\n * new OpenAIEmbedder({\n *   apiKey: process.env.SILICONFLOW_API_KEY!,\n *   baseUrl: 'https://api.siliconflow.cn/v1',\n *   model: 'BAAI/bge-m3',\n * });\n *\n * @example\n * // Local Ollama\n * new OpenAIEmbedder({\n *   apiKey: 'ollama',\n *   baseUrl: 'http://localhost:11434/v1',\n *   model: 'bge-m3',\n * });\n */\nexport class OpenAIEmbedder implements IEmbedder {\n  readonly id: string;\n  readonly dimensions: number;\n  private readonly model: string;\n  private readonly baseUrl: string;\n  private readonly apiKey: string;\n  private readonly fetchImpl: typeof fetch;\n  private readonly requestedDims?: number;\n  private readonly extraHeaders: Record<string, string>;\n\n  constructor(opts: OpenAIEmbedderOptions) {\n    if (!opts.apiKey) throw new Error('OpenAIEmbedder: apiKey required');\n    this.apiKey = opts.apiKey;\n    this.id = opts.id ?? 'openai';\n    this.model = opts.model ?? 'text-embedding-3-small';\n    this.baseUrl = (opts.baseUrl ?? 'https://api.openai.com/v1').replace(/\\/+$/, '');\n    this.fetchImpl = opts.fetch ?? (globalThis.fetch as typeof fetch);\n    this.requestedDims = opts.dimensions;\n    this.extraHeaders = opts.headers ?? {};\n    this.dimensions =\n      opts.dimensions ?? KNOWN_DIMENSIONS[this.model] ?? 1536;\n    if (!this.fetchImpl) {\n      throw new Error(\n        'OpenAIEmbedder: no fetch available; pass options.fetch or run on Node 18+ / a fetch-capable runtime',\n      );\n    }\n  }\n\n  async embed(texts: string[]): Promise<number[][]> {\n    if (texts.length === 0) return [];\n    const body: Record<string, unknown> = { model: this.model, input: texts };\n    if (this.requestedDims) body.dimensions = this.requestedDims;\n    const res = await this.fetchImpl(`${this.baseUrl}/embeddings`, {\n      method: 'POST',\n      headers: {\n        'content-type': 'application/json',\n        authorization: `Bearer ${this.apiKey}`,\n        ...this.extraHeaders,\n      },\n      body: JSON.stringify(body),\n    });\n    if (!res.ok) {\n      const text = await res.text().catch(() => '');\n      throw new Error(\n        `OpenAIEmbedder (${this.baseUrl}) → ${res.status} ${res.statusText}${text ? `: ${text.slice(0, 200)}` : ''}`,\n      );\n    }\n    const json = (await res.json()) as { data?: Array<{ embedding: number[] }> };\n    const data = json.data ?? [];\n    if (data.length !== texts.length) {\n      throw new Error(\n        `OpenAIEmbedder: expected ${texts.length} vectors, got ${data.length}`,\n      );\n    }\n    return data.map((d) => d.embedding);\n  }\n}\n\n/**\n * Convenience presets for popular Chinese providers — saves callers\n * from memorising base URLs. Pass through `createXxxEmbedder({...})`.\n */\nexport const OPENAI_COMPATIBLE_PRESETS = {\n  openai: 'https://api.openai.com/v1',\n  azure: '', // user must provide full deployment URL via baseUrl\n  dashscope: 'https://dashscope.aliyuncs.com/compatible-mode/v1',\n  zhipu: 'https://open.bigmodel.cn/api/paas/v4',\n  siliconflow: 'https://api.siliconflow.cn/v1',\n  doubao: 'https://ark.cn-beijing.volces.com/api/v3',\n  minimax: 'https://api.minimax.chat/v1',\n  ollama: 'http://localhost:11434/v1',\n} as const;\n\nexport type OpenAICompatiblePreset = keyof typeof OPENAI_COMPATIBLE_PRESETS;\n\nexport interface PresetEmbedderOptions\n  extends Omit<OpenAIEmbedderOptions, 'baseUrl'> {\n  /** Pick a known provider; sets `baseUrl` automatically. */\n  preset?: OpenAICompatiblePreset;\n  /** Explicit override; takes precedence over `preset`. */\n  baseUrl?: string;\n}\n\n/**\n * Helper: pick a provider by preset name. Equivalent to constructing\n * `OpenAIEmbedder` with the matching `baseUrl`.\n *\n * @example\n * createOpenAIEmbedder({ preset: 'dashscope', apiKey, model: 'text-embedding-v3' })\n */\nexport function createOpenAIEmbedder(opts: PresetEmbedderOptions): OpenAIEmbedder {\n  const baseUrl =\n    opts.baseUrl ??\n    (opts.preset ? OPENAI_COMPATIBLE_PRESETS[opts.preset] : undefined);\n  return new OpenAIEmbedder({ ...opts, baseUrl, id: opts.id ?? opts.preset ?? 'openai' });\n}\n\nexport default OpenAIEmbedder;\n"],"mappings":";AA+DA,IAAM,mBAA2C;AAAA;AAAA,EAE/C,0BAA0B;AAAA,EAC1B,0BAA0B;AAAA,EAC1B,0BAA0B;AAAA;AAAA,EAE1B,qBAAqB;AAAA,EACrB,qBAAqB;AAAA,EACrB,qBAAqB;AAAA;AAAA,EAErB,eAAe;AAAA,EACf,eAAe;AAAA;AAAA,EAEf,eAAe;AAAA,EACf,0BAA0B;AAAA,EAC1B,0BAA0B;AAAA,EAC1B,yBAAyB;AAAA,EACzB,0BAA0B;AAAA,EAC1B,UAAU;AAAA;AAAA,EAEV,sCAAsC;AAAA,EACtC,gCAAgC;AAAA;AAAA,EAEhC,oBAAoB;AAAA;AAAA,EAEpB,WAAW;AACb;AAmCO,IAAM,iBAAN,MAA0C;AAAA,EAU/C,YAAY,MAA6B;AACvC,QAAI,CAAC,KAAK,OAAQ,OAAM,IAAI,MAAM,iCAAiC;AACnE,SAAK,SAAS,KAAK;AACnB,SAAK,KAAK,KAAK,MAAM;AACrB,SAAK,QAAQ,KAAK,SAAS;AAC3B,SAAK,WAAW,KAAK,WAAW,6BAA6B,QAAQ,QAAQ,EAAE;AAC/E,SAAK,YAAY,KAAK,SAAU,WAAW;AAC3C,SAAK,gBAAgB,KAAK;AAC1B,SAAK,eAAe,KAAK,WAAW,CAAC;AACrC,SAAK,aACH,KAAK,cAAc,iBAAiB,KAAK,KAAK,KAAK;AACrD,QAAI,CAAC,KAAK,WAAW;AACnB,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAAA,EAEA,MAAM,MAAM,OAAsC;AAChD,QAAI,MAAM,WAAW,EAAG,QAAO,CAAC;AAChC,UAAM,OAAgC,EAAE,OAAO,KAAK,OAAO,OAAO,MAAM;AACxE,QAAI,KAAK,cAAe,MAAK,aAAa,KAAK;AAC/C,UAAM,MAAM,MAAM,KAAK,UAAU,GAAG,KAAK,OAAO,eAAe;AAAA,MAC7D,QAAQ;AAAA,MACR,SAAS;AAAA,QACP,gBAAgB;AAAA,QAChB,eAAe,UAAU,KAAK,MAAM;AAAA,QACpC,GAAG,KAAK;AAAA,MACV;AAAA,MACA,MAAM,KAAK,UAAU,IAAI;AAAA,IAC3B,CAAC;AACD,QAAI,CAAC,IAAI,IAAI;AACX,YAAM,OAAO,MAAM,IAAI,KAAK,EAAE,MAAM,MAAM,EAAE;AAC5C,YAAM,IAAI;AAAA,QACR,mBAAmB,KAAK,OAAO,YAAO,IAAI,MAAM,IAAI,IAAI,UAAU,GAAG,OAAO,KAAK,KAAK,MAAM,GAAG,GAAG,CAAC,KAAK,EAAE;AAAA,MAC5G;AAAA,IACF;AACA,UAAM,OAAQ,MAAM,IAAI,KAAK;AAC7B,UAAM,OAAO,KAAK,QAAQ,CAAC;AAC3B,QAAI,KAAK,WAAW,MAAM,QAAQ;AAChC,YAAM,IAAI;AAAA,QACR,4BAA4B,MAAM,MAAM,iBAAiB,KAAK,MAAM;AAAA,MACtE;AAAA,IACF;AACA,WAAO,KAAK,IAAI,CAAC,MAAM,EAAE,SAAS;AAAA,EACpC;AACF;AAMO,IAAM,4BAA4B;AAAA,EACvC,QAAQ;AAAA,EACR,OAAO;AAAA;AAAA,EACP,WAAW;AAAA,EACX,OAAO;AAAA,EACP,aAAa;AAAA,EACb,QAAQ;AAAA,EACR,SAAS;AAAA,EACT,QAAQ;AACV;AAmBO,SAAS,qBAAqB,MAA6C;AAChF,QAAM,UACJ,KAAK,YACJ,KAAK,SAAS,0BAA0B,KAAK,MAAM,IAAI;AAC1D,SAAO,IAAI,eAAe,EAAE,GAAG,MAAM,SAAS,IAAI,KAAK,MAAM,KAAK,UAAU,SAAS,CAAC;AACxF;AAEA,IAAO,gBAAQ;","names":[]}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@objectstack/embedder-openai",
+  "version": "6.7.0",
+  "license": "Apache-2.0",
+  "description": "OpenAI-compatible embedder for ObjectStack — works against OpenAI, 阿里通义 DashScope, 智谱 BigModel, 硅基流动 SiliconFlow, 火山引擎 Doubao, MiniMax, Ollama, and any drop-in OpenAI-shape endpoint.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@objectstack/spec": "6.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  },
+  "keywords": [
+    "objectstack",
+    "embedder",
+    "embedding",
+    "openai",
+    "rag",
+    "vector",
+    "dashscope",
+    "zhipu",
+    "siliconflow",
+    "ollama"
+  ],
+  "scripts": {
+    "build": "tsup --config ../../../tsup.config.ts",
+    "dev": "tsc -w",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/openai-embedder.test.ts

@@ -0,0 +1,166 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, vi } from 'vitest';
+import {
+  OpenAIEmbedder,
+  createOpenAIEmbedder,
+  OPENAI_COMPATIBLE_PRESETS,
+} from '../index';
+
+function mockFetch(body: unknown, status = 200): typeof fetch {
+  return vi.fn(async () =>
+    new Response(JSON.stringify(body), {
+      status,
+      headers: { 'content-type': 'application/json' },
+    }),
+  ) as unknown as typeof fetch;
+}
+
+describe('OpenAIEmbedder', () => {
+  it('requires apiKey', () => {
+    expect(() => new OpenAIEmbedder({ apiKey: '' })).toThrow(/apiKey required/);
+  });
+
+  it('exposes id and known dimensions for default model', () => {
+    const e = new OpenAIEmbedder({ apiKey: 'k', fetch: mockFetch({ data: [] }) });
+    expect(e.id).toBe('openai');
+    expect(e.dimensions).toBe(1536);
+  });
+
+  it('looks up dimensions for known Chinese models', () => {
+    const e = new OpenAIEmbedder({
+      apiKey: 'k',
+      model: 'text-embedding-v3',
+      fetch: mockFetch({ data: [] }),
+    });
+    expect(e.dimensions).toBe(1024);
+  });
+
+  it('honours explicit dimensions override', () => {
+    const e = new OpenAIEmbedder({
+      apiKey: 'k',
+      dimensions: 256,
+      fetch: mockFetch({ data: [] }),
+    });
+    expect(e.dimensions).toBe(256);
+  });
+
+  it('returns [] for empty input without calling fetch', async () => {
+    const fetchImpl = vi.fn() as unknown as typeof fetch;
+    const e = new OpenAIEmbedder({ apiKey: 'k', fetch: fetchImpl });
+    const out = await e.embed([]);
+    expect(out).toEqual([]);
+    expect(fetchImpl).not.toHaveBeenCalled();
+  });
+
+  it('POSTs to the configured baseUrl with bearer auth', async () => {
+    const fetchImpl = vi.fn(async () =>
+      new Response(JSON.stringify({ data: [{ embedding: [0.1, 0.2] }] }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      }),
+    ) as unknown as typeof fetch;
+
+    const e = new OpenAIEmbedder({
+      apiKey: 'sk-test',
+      baseUrl: 'https://api.siliconflow.cn/v1',
+      model: 'BAAI/bge-m3',
+      fetch: fetchImpl,
+    });
+    const out = await e.embed(['hello']);
+
+    expect(out).toEqual([[0.1, 0.2]]);
+    const call = (fetchImpl as unknown as ReturnType<typeof vi.fn>).mock.calls[0];
+    expect(call[0]).toBe('https://api.siliconflow.cn/v1/embeddings');
+    const init = call[1] as RequestInit;
+    expect(init.method).toBe('POST');
+    expect((init.headers as Record<string, string>).authorization).toBe('Bearer sk-test');
+    expect(JSON.parse(init.body as string)).toEqual({ model: 'BAAI/bge-m3', input: ['hello'] });
+  });
+
+  it('forwards dimensions in the request body when overridden', async () => {
+    const fetchImpl = mockFetch({ data: [{ embedding: [1, 2] }] });
+    const e = new OpenAIEmbedder({
+      apiKey: 'k',
+      dimensions: 512,
+      fetch: fetchImpl,
+    });
+    await e.embed(['x']);
+    const body = JSON.parse(
+      (fetchImpl as unknown as ReturnType<typeof vi.fn>).mock.calls[0][1].body as string,
+    );
+    expect(body.dimensions).toBe(512);
+  });
+
+  it('throws a useful error on non-2xx', async () => {
+    const fetchImpl = mockFetch({ error: 'bad key' }, 401);
+    const e = new OpenAIEmbedder({ apiKey: 'k', fetch: fetchImpl });
+    await expect(e.embed(['x'])).rejects.toThrow(/401/);
+  });
+
+  it('throws when response vector count mismatches input', async () => {
+    const fetchImpl = mockFetch({ data: [{ embedding: [1] }] });
+    const e = new OpenAIEmbedder({ apiKey: 'k', fetch: fetchImpl });
+    await expect(e.embed(['a', 'b'])).rejects.toThrow(/expected 2 vectors/);
+  });
+
+  it('strips trailing slashes from baseUrl', async () => {
+    const fetchImpl = mockFetch({ data: [{ embedding: [1] }] });
+    const e = new OpenAIEmbedder({
+      apiKey: 'k',
+      baseUrl: 'https://x.example/v1///',
+      fetch: fetchImpl,
+    });
+    await e.embed(['x']);
+    expect(
+      (fetchImpl as unknown as ReturnType<typeof vi.fn>).mock.calls[0][0],
+    ).toBe('https://x.example/v1/embeddings');
+  });
+
+  it('merges extra headers', async () => {
+    const fetchImpl = mockFetch({ data: [{ embedding: [1] }] });
+    const e = new OpenAIEmbedder({
+      apiKey: 'k',
+      fetch: fetchImpl,
+      headers: { 'x-trace-id': 't1' },
+    });
+    await e.embed(['x']);
+    const headers = (fetchImpl as unknown as ReturnType<typeof vi.fn>).mock
+      .calls[0][1].headers as Record<string, string>;
+    expect(headers['x-trace-id']).toBe('t1');
+    expect(headers.authorization).toBe('Bearer k');
+  });
+});
+
+describe('createOpenAIEmbedder presets', () => {
+  it('maps preset names to baseUrl', () => {
+    const e = createOpenAIEmbedder({
+      preset: 'dashscope',
+      apiKey: 'k',
+      model: 'text-embedding-v3',
+      fetch: mockFetch({ data: [] }),
+    });
+    expect(e.id).toBe('dashscope');
+    expect(e.dimensions).toBe(1024);
+  });
+
+  it('exposes well-known preset URLs', () => {
+    expect(OPENAI_COMPATIBLE_PRESETS.siliconflow).toContain('siliconflow.cn');
+    expect(OPENAI_COMPATIBLE_PRESETS.zhipu).toContain('bigmodel.cn');
+    expect(OPENAI_COMPATIBLE_PRESETS.ollama).toContain('localhost:11434');
+  });
+
+  it('explicit baseUrl wins over preset', async () => {
+    const fetchImpl = mockFetch({ data: [{ embedding: [1] }] });
+    const e = createOpenAIEmbedder({
+      preset: 'openai',
+      baseUrl: 'https://my-proxy.example/v1',
+      apiKey: 'k',
+      fetch: fetchImpl,
+    });
+    await e.embed(['x']);
+    expect(
+      (fetchImpl as unknown as ReturnType<typeof vi.fn>).mock.calls[0][0],
+    ).toBe('https://my-proxy.example/v1/embeddings');
+  });
+});