qwen-embedder 0.1.0

package/README.md

@@ -0,0 +1,83 @@
+# qwen-embedder
+
+Local text embedding for Node.js. Runs a quantized Qwen ONNX model via [Transformers.js](https://github.com/huggingface/transformers.js) — no Python, no external services.
+
+```ts
+import { Embedder } from 'qwen-embedder'
+
+const embedder = await Embedder.create()
+
+const vector = await embedder.embed('hello world')
+// => number[1024]
+
+const batch = await embedder.embed(['cat', 'dog', 'fish'])
+// => number[][3][1024]
+```
+
+## Installation
+
+```sh
+npm install qwen-embedder
+```
+
+Node.js 20+ (ESM only).
+
+## Usage
+
+```ts
+import { Embedder } from 'qwen-embedder'
+
+// First call downloads the model (~600MB q8) to
+// ~/.qwenembedder/.cache/models/ — subsequent runs use cache
+const embedder = await Embedder.create()
+
+// Single string → number[]
+const vec = await embedder.embed('your text here')
+console.log(vec.length) // 1024
+
+// Batch → number[][]
+const vecs = await embedder.embed(['first', 'second', 'third'])
+
+// Repeated input hits the in-memory cache (FIFO, default 100 entries)
+const again = await embedder.embed('your text here')
+// same values as vec, returned instantly without inference
+```
+
+## Options
+
+```ts
+interface EmbedderOptions {
+  queue?: boolean     // serialize inference calls (concurrency: 1)
+  concurrency?: number // set a specific concurrency limit
+  cacheSize?: number  // in-memory result cache size (default 100, 0 to disable)
+}
+```
+
+```ts
+// Serial execution — safe for memory-constrained environments
+const e = await Embedder.create({ queue: true })
+
+// Limited parallelism
+const e = await Embedder.create({ concurrency: 2 })
+
+// No result caching
+const e = await Embedder.create({ cacheSize: 0 })
+```
+
+## Model
+
+- Model: [`onnx-community/Qwen3-Embedding-0.6B-ONNX`](https://huggingface.co/onnx-community/Qwen3-Embedding-0.6B-ONNX)
+- Quantization: `q8`
+- Pipeline: `feature-extraction` with mean pooling + L2 normalization
+- Output dimension: 1024
+- Cache: `~/.qwenembedder/.cache/models/` (auto-downloaded on first use)
+
+## Docs
+
+- [Architecture](docs/architecture.md)
+- [Technical spec](docs/technical-spec.md)
+- [ADRs](docs/adr/)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+interface EmbedderOptions {
+    queue?: boolean;
+    concurrency?: number;
+    cacheSize?: number;
+}
+
+declare class Embedder {
+    private pipe;
+    private cache;
+    private maxCacheSize;
+    private queue;
+    private constructor();
+    static create(options?: EmbedderOptions): Promise<Embedder>;
+    embed(text: string): Promise<number[]>;
+    embed(texts: string[]): Promise<number[][]>;
+    private embedSingle;
+    private embedBatch;
+    private runInference;
+    private setCache;
+}
+
+export { Embedder, type EmbedderOptions };

package/dist/index.js

@@ -0,0 +1,109 @@
+// src/embedder.ts
+import { pipeline } from "@huggingface/transformers";
+import PQueue from "p-queue";
+import { homedir } from "os";
+import { join } from "path";
+var MODEL_ID = "onnx-community/Qwen3-Embedding-0.6B-ONNX";
+var CACHE_DIR = join(homedir(), ".qwenembedder", ".cache", "models");
+function resolveConcurrency(options) {
+  if (options.concurrency !== void 0) return options.concurrency;
+  if (options.queue) return 1;
+  return null;
+}
+var Embedder = class _Embedder {
+  pipe;
+  cache;
+  maxCacheSize;
+  queue;
+  constructor(pipe, concurrency, maxCacheSize) {
+    this.pipe = pipe;
+    this.maxCacheSize = maxCacheSize;
+    this.cache = /* @__PURE__ */ new Map();
+    this.queue = concurrency !== null ? new PQueue({ concurrency }) : null;
+  }
+  static async create(options = {}) {
+    const cacheSize = options.cacheSize ?? 100;
+    const concurrency = resolveConcurrency(options);
+    const pipe = await pipeline("feature-extraction", MODEL_ID, {
+      cache_dir: CACHE_DIR,
+      dtype: "q8"
+    });
+    return new _Embedder(pipe, concurrency, cacheSize);
+  }
+  async embed(input) {
+    if (Array.isArray(input)) {
+      return this.embedBatch(input);
+    }
+    return this.embedSingle(input);
+  }
+  async embedSingle(text) {
+    if (text.length === 0) {
+      throw new TypeError("Input must be a non-empty string");
+    }
+    const cached = this.cache.get(text);
+    if (cached !== void 0) {
+      return cached.slice();
+    }
+    const result = await this.runInference(text);
+    this.setCache(text, result);
+    return result.slice();
+  }
+  async embedBatch(texts) {
+    if (texts.length === 0) {
+      return [];
+    }
+    const results = new Array(texts.length);
+    const uncached = [];
+    for (let i = 0; i < texts.length; i++) {
+      const t = texts[i];
+      if (typeof t !== "string" || t.length === 0) {
+        throw new TypeError("Input must be a non-empty string");
+      }
+      const cached = this.cache.get(t);
+      if (cached !== void 0) {
+        results[i] = cached;
+      } else {
+        uncached.push(i);
+      }
+    }
+    if (uncached.length === 0) {
+      return results;
+    }
+    const uncachedTexts = uncached.map((i) => texts[i]);
+    const inferred = await this.runInference(uncachedTexts);
+    for (let j = 0; j < uncached.length; j++) {
+      const vector = inferred[j];
+      this.setCache(uncachedTexts[j], vector);
+      results[uncached[j]] = vector;
+    }
+    return results;
+  }
+  async runInference(input) {
+    const exec = () => this.pipe(input, { pooling: "mean", normalize: true });
+    const output = this.queue ? await this.queue.add(exec) : await exec();
+    const data = Array.from(output.data);
+    const hiddenDim = output.dims[output.dims.length - 1];
+    if (typeof input === "string") {
+      return data;
+    }
+    const result = [];
+    for (let i = 0; i < data.length; i += hiddenDim) {
+      result.push(data.slice(i, i + hiddenDim));
+    }
+    return result;
+  }
+  setCache(key, value) {
+    if (this.maxCacheSize === 0) return;
+    if (this.cache.size >= this.maxCacheSize) {
+      const oldest = this.cache.keys().next();
+      if (!oldest.done) {
+        this.cache.delete(oldest.value);
+      }
+    }
+    this.cache.set(key, value);
+  }
+};
+export {
+  Embedder
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/embedder.ts"],"sourcesContent":["import { pipeline } from '@huggingface/transformers'\nimport PQueue from 'p-queue'\nimport { homedir } from 'os'\nimport { join } from 'path'\nimport type { EmbedderOptions } from './types.js'\n\nconst MODEL_ID = 'onnx-community/Qwen3-Embedding-0.6B-ONNX'\nconst CACHE_DIR = join(homedir(), '.qwenembedder', '.cache', 'models')\n\nfunction resolveConcurrency(options: EmbedderOptions): number | null {\n  if (options.concurrency !== undefined) return options.concurrency\n  if (options.queue) return 1\n  return null\n}\n\ninterface InferenceResult {\n  data: Float32Array | number[]\n  dims: number[]\n  tolist(): number[][]\n}\n\nexport class Embedder {\n  private pipe: (texts: string | string[], options?: Record<string, unknown>) => Promise<InferenceResult>\n  private cache: Map<string, number[]>\n  private maxCacheSize: number\n  private queue: PQueue | null\n\n  private constructor(\n    pipe: Embedder['pipe'],\n    concurrency: number | null,\n    maxCacheSize: number,\n  ) {\n    this.pipe = pipe\n    this.maxCacheSize = maxCacheSize\n    this.cache = new Map()\n    this.queue = concurrency !== null ? new PQueue({ concurrency }) : null\n  }\n\n  static async create(options: EmbedderOptions = {}): Promise<Embedder> {\n    const cacheSize = options.cacheSize ?? 100\n    const concurrency = resolveConcurrency(options)\n\n    const pipe = await pipeline('feature-extraction', MODEL_ID, {\n      cache_dir: CACHE_DIR,\n      dtype: 'q8',\n    })\n\n    return new Embedder(pipe as unknown as Embedder['pipe'], concurrency, cacheSize)\n  }\n\n  async embed(text: string): Promise<number[]>\n  async embed(texts: string[]): Promise<number[][]>\n  async embed(input: string | string[]): Promise<number[] | number[][]> {\n    if (Array.isArray(input)) {\n      return this.embedBatch(input)\n    }\n    return this.embedSingle(input)\n  }\n\n  private async embedSingle(text: string): Promise<number[]> {\n    if (text.length === 0) {\n      throw new TypeError('Input must be a non-empty string')\n    }\n\n    const cached = this.cache.get(text)\n    if (cached !== undefined) {\n      return cached.slice()\n    }\n\n    const result = await this.runInference(text)\n    this.setCache(text, result)\n    return result.slice()\n  }\n\n  private async embedBatch(texts: string[]): Promise<number[][]> {\n    if (texts.length === 0) {\n      return []\n    }\n\n    const results: (number[] | undefined)[] = new Array(texts.length)\n    const uncached: number[] = []\n\n    for (let i = 0; i < texts.length; i++) {\n      const t = texts[i]\n      if (typeof t !== 'string' || t.length === 0) {\n        throw new TypeError('Input must be a non-empty string')\n      }\n      const cached = this.cache.get(t)\n      if (cached !== undefined) {\n        results[i] = cached\n      } else {\n        uncached.push(i)\n      }\n    }\n\n    if (uncached.length === 0) {\n      return results as number[][]\n    }\n\n    const uncachedTexts = uncached.map(i => texts[i])\n    const inferred = await this.runInference(uncachedTexts)\n\n    for (let j = 0; j < uncached.length; j++) {\n      const vector = inferred[j]\n      this.setCache(uncachedTexts[j], vector)\n      results[uncached[j]] = vector\n    }\n\n    return results as number[][]\n  }\n\n  private async runInference(text: string): Promise<number[]>\n  private async runInference(texts: string[]): Promise<number[][]>\n  private async runInference(input: string | string[]): Promise<number[] | number[][]> {\n    const exec = () => this.pipe(input, { pooling: 'mean', normalize: true })\n\n    const output = this.queue\n      ? await this.queue.add(exec)\n      : await exec()\n\n    const data = Array.from(output.data) as number[]\n    const hiddenDim = output.dims[output.dims.length - 1]\n\n    if (typeof input === 'string') {\n      return data\n    }\n\n    const result: number[][] = []\n    for (let i = 0; i < data.length; i += hiddenDim) {\n      result.push(data.slice(i, i + hiddenDim))\n    }\n    return result\n  }\n\n  private setCache(key: string, value: number[]): void {\n    if (this.maxCacheSize === 0) return\n\n    if (this.cache.size >= this.maxCacheSize) {\n      const oldest = this.cache.keys().next()\n      if (!oldest.done) {\n        this.cache.delete(oldest.value)\n      }\n    }\n    this.cache.set(key, value)\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "qwen-embedder",
+  "version": "0.1.0",
+  "description": "Local text embedding with Qwen ONNX model via Transformers.js",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@huggingface/transformers": "^4.2.0",
+    "p-queue": "^9.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "allowScripts": {
+    "onnxruntime-node@1.24.3": true
+  }
+}

package/src/embedder.ts

@@ -0,0 +1,146 @@
+import { pipeline } from '@huggingface/transformers'
+import PQueue from 'p-queue'
+import { homedir } from 'os'
+import { join } from 'path'
+import type { EmbedderOptions } from './types.js'
+
+const MODEL_ID = 'onnx-community/Qwen3-Embedding-0.6B-ONNX'
+const CACHE_DIR = join(homedir(), '.qwenembedder', '.cache', 'models')
+
+function resolveConcurrency(options: EmbedderOptions): number | null {
+  if (options.concurrency !== undefined) return options.concurrency
+  if (options.queue) return 1
+  return null
+}
+
+interface InferenceResult {
+  data: Float32Array | number[]
+  dims: number[]
+  tolist(): number[][]
+}
+
+export class Embedder {
+  private pipe: (texts: string | string[], options?: Record<string, unknown>) => Promise<InferenceResult>
+  private cache: Map<string, number[]>
+  private maxCacheSize: number
+  private queue: PQueue | null
+
+  private constructor(
+    pipe: Embedder['pipe'],
+    concurrency: number | null,
+    maxCacheSize: number,
+  ) {
+    this.pipe = pipe
+    this.maxCacheSize = maxCacheSize
+    this.cache = new Map()
+    this.queue = concurrency !== null ? new PQueue({ concurrency }) : null
+  }
+
+  static async create(options: EmbedderOptions = {}): Promise<Embedder> {
+    const cacheSize = options.cacheSize ?? 100
+    const concurrency = resolveConcurrency(options)
+
+    const pipe = await pipeline('feature-extraction', MODEL_ID, {
+      cache_dir: CACHE_DIR,
+      dtype: 'q8',
+    })
+
+    return new Embedder(pipe as unknown as Embedder['pipe'], concurrency, cacheSize)
+  }
+
+  async embed(text: string): Promise<number[]>
+  async embed(texts: string[]): Promise<number[][]>
+  async embed(input: string | string[]): Promise<number[] | number[][]> {
+    if (Array.isArray(input)) {
+      return this.embedBatch(input)
+    }
+    return this.embedSingle(input)
+  }
+
+  private async embedSingle(text: string): Promise<number[]> {
+    if (text.length === 0) {
+      throw new TypeError('Input must be a non-empty string')
+    }
+
+    const cached = this.cache.get(text)
+    if (cached !== undefined) {
+      return cached.slice()
+    }
+
+    const result = await this.runInference(text)
+    this.setCache(text, result)
+    return result.slice()
+  }
+
+  private async embedBatch(texts: string[]): Promise<number[][]> {
+    if (texts.length === 0) {
+      return []
+    }
+
+    const results: (number[] | undefined)[] = new Array(texts.length)
+    const uncached: number[] = []
+
+    for (let i = 0; i < texts.length; i++) {
+      const t = texts[i]
+      if (typeof t !== 'string' || t.length === 0) {
+        throw new TypeError('Input must be a non-empty string')
+      }
+      const cached = this.cache.get(t)
+      if (cached !== undefined) {
+        results[i] = cached
+      } else {
+        uncached.push(i)
+      }
+    }
+
+    if (uncached.length === 0) {
+      return results as number[][]
+    }
+
+    const uncachedTexts = uncached.map(i => texts[i])
+    const inferred = await this.runInference(uncachedTexts)
+
+    for (let j = 0; j < uncached.length; j++) {
+      const vector = inferred[j]
+      this.setCache(uncachedTexts[j], vector)
+      results[uncached[j]] = vector
+    }
+
+    return results as number[][]
+  }
+
+  private async runInference(text: string): Promise<number[]>
+  private async runInference(texts: string[]): Promise<number[][]>
+  private async runInference(input: string | string[]): Promise<number[] | number[][]> {
+    const exec = () => this.pipe(input, { pooling: 'mean', normalize: true })
+
+    const output = this.queue
+      ? await this.queue.add(exec)
+      : await exec()
+
+    const data = Array.from(output.data) as number[]
+    const hiddenDim = output.dims[output.dims.length - 1]
+
+    if (typeof input === 'string') {
+      return data
+    }
+
+    const result: number[][] = []
+    for (let i = 0; i < data.length; i += hiddenDim) {
+      result.push(data.slice(i, i + hiddenDim))
+    }
+    return result
+  }
+
+  private setCache(key: string, value: number[]): void {
+    if (this.maxCacheSize === 0) return
+
+    if (this.cache.size >= this.maxCacheSize) {
+      const oldest = this.cache.keys().next()
+      if (!oldest.done) {
+        this.cache.delete(oldest.value)
+      }
+    }
+    this.cache.set(key, value)
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { Embedder } from './embedder.js'
+export type { EmbedderOptions } from './types.js'

package/src/types.ts

@@ -0,0 +1,5 @@
+export interface EmbedderOptions {
+  queue?: boolean
+  concurrency?: number
+  cacheSize?: number
+}