diff --git a/__mocks__/@huggingface/transformers.ts b/__mocks__/@huggingface/transformers.ts index debd57addf..b078e93f70 100644 --- a/__mocks__/@huggingface/transformers.ts +++ b/__mocks__/@huggingface/transformers.ts @@ -1,4 +1,8 @@ -throw Object.assign( - new Error("Cannot find package '@huggingface/transformers'"), - { code: "ERR_MODULE_NOT_FOUND" }, +import { getTransformersImportError } from "../../test/fixtures/transformers-import-error.js"; + +throw ( + getTransformersImportError() ?? + Object.assign(new Error("Cannot find package '@huggingface/transformers'"), { + code: "ERR_MODULE_NOT_FOUND", + }) ); diff --git a/src/providers/embedding/_transformers.ts b/src/providers/embedding/_transformers.ts new file mode 100644 index 0000000000..c06f9581de --- /dev/null +++ b/src/providers/embedding/_transformers.ts @@ -0,0 +1,40 @@ +import { homedir } from "node:os"; +import { join } from "node:path"; +import type * as TransformersType from "@huggingface/transformers"; + +function isDirectTransformersModuleNotFound(err: unknown): err is Error { + return ( + err instanceof Error && + (err as NodeJS.ErrnoException).code === "ERR_MODULE_NOT_FOUND" && + /^(?:Cannot find package|Cannot find module) (['"])@huggingface\/transformers\1(?:$|\n| imported from )/.test( + err.message, + ) + ); +} + +export async function loadTransformers( + purpose = "local embeddings", +): Promise { + let transformers: any; + try { + transformers = await import("@huggingface/transformers"); + } catch (err) { + if (isDirectTransformersModuleNotFound(err)) { + throw new Error( + `Install @huggingface/transformers for ${purpose}: npm install @huggingface/transformers`, + { cause: err }, + ); + } + throw err; + } + try { + if (transformers && "env" in transformers && transformers.env) { + transformers.env.cacheDir = + process.env.TRANSFORMERS_CACHE || + process.env.HF_HOME || + join(homedir(), ".cache", "huggingface", "transformers"); + } + } catch { + } + return transformers; +} diff --git a/src/providers/embedding/clip.ts b/src/providers/embedding/clip.ts index 4ee102bce2..f1fac0c9cd 100644 --- a/src/providers/embedding/clip.ts +++ b/src/providers/embedding/clip.ts @@ -1,6 +1,7 @@ import { readFile } from "node:fs/promises"; import type { RawImage } from "@huggingface/transformers"; import type { EmbeddingProvider } from "../../types.js"; +import { loadTransformers } from "./_transformers.js"; type TransformersModule = typeof import("@huggingface/transformers"); type ClipPipeline = ( @@ -33,7 +34,7 @@ export class ClipEmbeddingProvider implements EmbeddingProvider { } async embedImage(src: string): Promise { - const t = await loadTransformers(); + const t = await loadTransformers("CLIP embeddings"); const image = await loadImage(t, src); const extractor = await this.getImageExtractor(); const output = await extractor(image); @@ -43,32 +44,19 @@ export class ClipEmbeddingProvider implements EmbeddingProvider { private async getTextExtractor(): Promise { if (this.textExtractor) return this.textExtractor; - const t = await loadTransformers(); + const t = await loadTransformers("CLIP embeddings"); this.textExtractor = (await t.pipeline("feature-extraction", this.modelId, { dtype: "q8" })) as ClipPipeline; return this.textExtractor; } private async getImageExtractor(): Promise { if (this.imageExtractor) return this.imageExtractor; - const t = await loadTransformers(); + const t = await loadTransformers("CLIP embeddings"); this.imageExtractor = (await t.pipeline("image-feature-extraction", this.modelId, { dtype: "q8" })) as ClipPipeline; return this.imageExtractor; } } -async function loadTransformers(): Promise { - try { - return await import("@huggingface/transformers"); - } catch (err) { - if ((err as NodeJS.ErrnoException).code === "ERR_MODULE_NOT_FOUND") { - throw new Error( - "Install @huggingface/transformers for CLIP embeddings: npm install @huggingface/transformers", - ); - } - throw err; - } -} - async function loadImage( t: TransformersModule, src: string, diff --git a/src/providers/embedding/local.ts b/src/providers/embedding/local.ts index 7646815df6..12445f1b1a 100644 --- a/src/providers/embedding/local.ts +++ b/src/providers/embedding/local.ts @@ -1,4 +1,5 @@ import type { EmbeddingProvider } from "../../types.js"; +import { loadTransformers } from "./_transformers.js"; type FeatureExtractor = ( texts: string[], @@ -26,17 +27,7 @@ export class LocalEmbeddingProvider implements EmbeddingProvider { private async getExtractor() { if (this.extractor) return this.extractor; - let transformers: typeof import("@huggingface/transformers"); - try { - transformers = await import("@huggingface/transformers"); - } catch (err) { - if ((err as NodeJS.ErrnoException).code === "ERR_MODULE_NOT_FOUND") { - throw new Error( - "Install @huggingface/transformers for local embeddings: npm install @huggingface/transformers", - ); - } - throw err; - } + const transformers = await loadTransformers(); this.extractor = (await transformers.pipeline( "feature-extraction", "Xenova/all-MiniLM-L6-v2", diff --git a/src/state/reranker.ts b/src/state/reranker.ts index ae92f8e452..b07aae1142 100644 --- a/src/state/reranker.ts +++ b/src/state/reranker.ts @@ -1,4 +1,5 @@ import type { HybridSearchResult } from "../types.js"; +import { loadTransformers } from "../providers/embedding/_transformers.js"; let pipeline: any = null; let pipelineLoading: Promise | null = null; @@ -11,10 +12,8 @@ async function loadPipeline(): Promise { pipelineLoading = (async () => { try { - const { pipeline: createPipeline } = await import( - "@huggingface/transformers" - ); - pipeline = await createPipeline( + const transformers = await loadTransformers(); + pipeline = await transformers.pipeline( "text-classification", "Xenova/ms-marco-MiniLM-L-6-v2", { dtype: "q8" }, diff --git a/test/fixtures/transformers-import-error.ts b/test/fixtures/transformers-import-error.ts new file mode 100644 index 0000000000..39d509d39c --- /dev/null +++ b/test/fixtures/transformers-import-error.ts @@ -0,0 +1,13 @@ +let transformersImportError: Error | undefined; + +export function setTransformersImportError(error: Error): void { + transformersImportError = error; +} + +export function getTransformersImportError(): Error | undefined { + return transformersImportError; +} + +export function clearTransformersImportError(): void { + transformersImportError = undefined; +} diff --git a/test/local-embedding-provider.test.ts b/test/local-embedding-provider.test.ts index 69ce049d8b..2c1700dd54 100644 --- a/test/local-embedding-provider.test.ts +++ b/test/local-embedding-provider.test.ts @@ -1,6 +1,33 @@ -import { describe, it, expect, vi, afterEach } from "vitest"; +import { homedir } from "node:os"; +import { join } from "node:path"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; -afterEach(() => { +const previousTransformersCache = process.env.TRANSFORMERS_CACHE; +const previousHfHome = process.env.HF_HOME; + +function restoreEnvironmentVariable( + name: string, + previousValue: string | undefined, +): void { + if (previousValue === undefined) { + delete process.env[name]; + } else { + process.env[name] = previousValue; + } +} + +beforeEach(() => { + delete process.env.TRANSFORMERS_CACHE; + delete process.env.HF_HOME; +}); + +afterEach(async () => { + restoreEnvironmentVariable("TRANSFORMERS_CACHE", previousTransformersCache); + restoreEnvironmentVariable("HF_HOME", previousHfHome); + const { clearTransformersImportError } = await import( + "./fixtures/transformers-import-error.js" + ); + clearTransformersImportError(); vi.doUnmock("@huggingface/transformers"); vi.resetModules(); }); @@ -16,6 +43,82 @@ describe("LocalEmbeddingProvider (package unavailable)", () => { "Install @huggingface/transformers for local embeddings", ); }); + + it("preserves missing transitive dependency errors", async () => { + const transitiveError = Object.assign( + new Error( + "Cannot find package 'sharp' imported from @huggingface/transformers", + ), + { code: "ERR_MODULE_NOT_FOUND" }, + ); + vi.doMock("@huggingface/transformers"); + vi.resetModules(); + const { setTransformersImportError } = await import( + "./fixtures/transformers-import-error.js" + ); + setTransformersImportError(transitiveError); + const { LocalEmbeddingProvider: Fresh } = await import( + "../src/providers/embedding/local.js" + ); + + await expect(new Fresh().embed("hello")).rejects.toBe(transitiveError); + }); +}); + +describe("Transformers cache initialization", () => { + async function loadTransformersWithMock( + module: Record, + ) { + vi.doMock("@huggingface/transformers", () => module); + vi.resetModules(); + const { loadTransformers } = await import( + "../src/providers/embedding/_transformers.js" + ); + return loadTransformers(); + } + + it("prefers TRANSFORMERS_CACHE over HF_HOME", async () => { + process.env.TRANSFORMERS_CACHE = "/tmp/transformers-cache"; + process.env.HF_HOME = "/tmp/hf-home"; + const env = { cacheDir: "" }; + + await loadTransformersWithMock({ env }); + + expect(env.cacheDir).toBe("/tmp/transformers-cache"); + }); + + it("uses HF_HOME when TRANSFORMERS_CACHE is absent", async () => { + process.env.HF_HOME = "/tmp/hf-home"; + const env = { cacheDir: "" }; + + await loadTransformersWithMock({ env }); + + expect(env.cacheDir).toBe("/tmp/hf-home"); + }); + + it("falls back to the user cache when both variables are absent", async () => { + const env = { cacheDir: "" }; + + await loadTransformersWithMock({ env }); + + expect(env.cacheDir).toBe( + join(homedir(), ".cache", "huggingface", "transformers"), + ); + }); + + it("keeps the module usable when cacheDir is not writable", async () => { + const pipeline = vi.fn(); + const setCacheDir = vi.fn(() => { + throw new TypeError("cacheDir is read-only"); + }); + const env = {}; + Object.defineProperty(env, "cacheDir", { set: setCacheDir }); + + const transformers = await loadTransformersWithMock({ env, pipeline }); + + expect(setCacheDir).toHaveBeenCalledOnce(); + expect(transformers.pipeline).toBe(pipeline); + }); }); describe("LocalEmbeddingProvider (with loaded pipeline)", () => {