@huggingface/inference 2.5.2 → 2.6.0

package/dist/index.d.ts

@@ -26,7 +26,39 @@ export interface Options {
 	fetch?: typeof fetch;
 }
 
-export type InferenceTask = "text-classification" | "feature-extraction" | "sentence-similarity";
+export type InferenceTask =
+	| "audio-classification"
+	| "audio-to-audio"
+	| "automatic-speech-recognition"
+	| "conversational"
+	| "depth-estimation"
+	| "document-question-answering"
+	| "feature-extraction"
+	| "fill-mask"
+	| "image-classification"
+	| "image-segmentation"
+	| "image-to-image"
+	| "image-to-text"
+	| "object-detection"
+	| "video-classification"
+	| "question-answering"
+	| "reinforcement-learning"
+	| "sentence-similarity"
+	| "summarization"
+	| "table-question-answering"
+	| "tabular-classification"
+	| "tabular-regression"
+	| "text-classification"
+	| "text-generation"
+	| "text-to-image"
+	| "text-to-speech"
+	| "text-to-video"
+	| "token-classification"
+	| "translation"
+	| "unconditional-image-generation"
+	| "visual-question-answering"
+	| "zero-shot-classification"
+	| "zero-shot-image-classification";
 
 export interface BaseArgs {
 	/**
@@ -37,8 +69,10 @@ export interface BaseArgs {
 	accessToken?: string;
 	/**
 	 * The model to use. Can be a full URL for HF inference endpoints.
+	 *
+	 * If not specified, will call huggingface.co/api/tasks to get the default model for the task.
 	 */
-	model: string;
+	model?: string;
 }
 
 export type RequestArgs = BaseArgs &
@@ -144,6 +178,8 @@ export function request<T>(
 		includeCredentials?: boolean;
 		/** When a model can be used for multiple tasks, and we want to run a non-default task */
 		task?: string | InferenceTask;
+		/** To load default model if needed */
+		taskHint?: InferenceTask;
 	}
 ): Promise<T>;
 /**
@@ -156,6 +192,8 @@ export function streamingRequest<T>(
 		includeCredentials?: boolean;
 		/** When a model can be used for multiple tasks, and we want to run a non-default task */
 		task?: string | InferenceTask;
+		/** To load default model if needed */
+		taskHint?: InferenceTask;
 	}
 ): AsyncGenerator<T>;
 export type ImageClassificationArgs = BaseArgs & {
@@ -1020,6 +1058,8 @@ export class HfInference {
 			includeCredentials?: boolean;
 			/** When a model can be used for multiple tasks, and we want to run a non-default task */
 			task?: string | InferenceTask;
+			/** To load default model if needed */
+			taskHint?: InferenceTask;
 		}
 	): Promise<T>;
 	/**
@@ -1032,6 +1072,8 @@ export class HfInference {
 			includeCredentials?: boolean;
 			/** When a model can be used for multiple tasks, and we want to run a non-default task */
 			task?: string | InferenceTask;
+			/** To load default model if needed */
+			taskHint?: InferenceTask;
 		}
 	): AsyncGenerator<T>;
 	/**
@@ -1225,6 +1267,8 @@ export class HfInferenceEndpoint {
 			includeCredentials?: boolean;
 			/** When a model can be used for multiple tasks, and we want to run a non-default task */
 			task?: string | InferenceTask;
+			/** To load default model if needed */
+			taskHint?: InferenceTask;
 		}
 	): Promise<T>;
 	/**
@@ -1237,6 +1281,8 @@ export class HfInferenceEndpoint {
 			includeCredentials?: boolean;
 			/** When a model can be used for multiple tasks, and we want to run a non-default task */
 			task?: string | InferenceTask;
+			/** To load default model if needed */
+			taskHint?: InferenceTask;
 		}
 	): AsyncGenerator<T>;
 	/**

package/dist/index.js

@@ -97,15 +97,63 @@ function isUrl(modelOrUrl) {
   return /^http(s?):/.test(modelOrUrl) || modelOrUrl.startsWith("/");
 }
 
+// src/lib/getDefaultTask.ts
+var taskCache = /* @__PURE__ */ new Map();
+var CACHE_DURATION = 10 * 60 * 1e3;
+var MAX_CACHE_ITEMS = 1e3;
+var HF_HUB_URL = "https://huggingface.co";
+async function getDefaultTask(model, accessToken) {
+  if (isUrl(model)) {
+    return null;
+  }
+  const key = `${model}:${accessToken}`;
+  let cachedTask = taskCache.get(key);
+  if (cachedTask && cachedTask.date < new Date(Date.now() - CACHE_DURATION)) {
+    taskCache.delete(key);
+    cachedTask = void 0;
+  }
+  if (cachedTask === void 0) {
+    const modelTask = await fetch(`${HF_HUB_URL}/api/models/${model}?expand[]=pipeline_tag`, {
+      headers: accessToken ? { Authorization: `Bearer ${accessToken}` } : {}
+    }).then((resp) => resp.json()).then((json) => json.pipeline_tag).catch(() => null);
+    if (!modelTask) {
+      return null;
+    }
+    cachedTask = { task: modelTask, date: /* @__PURE__ */ new Date() };
+    taskCache.set(key, { task: modelTask, date: /* @__PURE__ */ new Date() });
+    if (taskCache.size > MAX_CACHE_ITEMS) {
+      taskCache.delete(taskCache.keys().next().value);
+    }
+  }
+  return cachedTask.task;
+}
+
 // src/lib/makeRequestOptions.ts
 var HF_INFERENCE_API_BASE_URL = "https://api-inference.huggingface.co";
-function makeRequestOptions(args, options) {
-  const { model, accessToken, ...otherArgs } = args;
-  const { task, includeCredentials, ...otherOptions } = options ?? {};
+var tasks = null;
+async function makeRequestOptions(args, options) {
+  const { accessToken, model: _model, ...otherArgs } = args;
+  let { model } = args;
+  const { forceTask: task, includeCredentials, taskHint, ...otherOptions } = options ?? {};
   const headers = {};
   if (accessToken) {
     headers["Authorization"] = `Bearer ${accessToken}`;
   }
+  if (!model && !tasks && taskHint) {
+    const res = await fetch(`${HF_HUB_URL}/api/tasks`);
+    if (res.ok) {
+      tasks = await res.json();
+    }
+  }
+  if (!model && tasks && taskHint) {
+    const taskInfo = tasks[taskHint];
+    if (taskInfo) {
+      model = taskInfo.models[0].id;
+    }
+  }
+  if (!model) {
+    throw new Error("No model provided, and no default model found for this task");
+  }
   const binary = "data" in args && !!args.data;
   if (!binary) {
     headers["Content-Type"] = "application/json";
@@ -143,7 +191,7 @@ function makeRequestOptions(args, options) {
 
 // src/tasks/custom/request.ts
 async function request(args, options) {
-  const { url, info } = makeRequestOptions(args, options);
+  const { url, info } = await makeRequestOptions(args, options);
   const response = await (options?.fetch ?? fetch)(url, info);
   if (options?.retry_on_error !== false && response.status === 503 && !options?.wait_for_model) {
     return request(args, {
@@ -267,7 +315,7 @@ function newMessage() {
 
 // src/tasks/custom/streamingRequest.ts
 async function* streamingRequest(args, options) {
-  const { url, info } = makeRequestOptions({ ...args, stream: true }, options);
+  const { url, info } = await makeRequestOptions({ ...args, stream: true }, options);
   const response = await (options?.fetch ?? fetch)(url, info);
   if (options?.retry_on_error !== false && response.status === 503 && !options?.wait_for_model) {
     return streamingRequest(args, {
@@ -340,7 +388,10 @@ var InferenceOutputError = class extends TypeError {
 
 // src/tasks/audio/audioClassification.ts
 async function audioClassification(args, options) {
-  const res = await request(args, options);
+  const res = await request(args, {
+    ...options,
+    taskHint: "audio-classification"
+  });
   const isValidOutput = Array.isArray(res) && res.every((x) => typeof x.label === "string" && typeof x.score === "number");
   if (!isValidOutput) {
     throw new InferenceOutputError("Expected Array<{label: string, score: number}>");
@@ -350,7 +401,10 @@ async function audioClassification(args, options) {
 
 // src/tasks/audio/automaticSpeechRecognition.ts
 async function automaticSpeechRecognition(args, options) {
-  const res = await request(args, options);
+  const res = await request(args, {
+    ...options,
+    taskHint: "automatic-speech-recognition"
+  });
   const isValidOutput = typeof res?.text === "string";
   if (!isValidOutput) {
     throw new InferenceOutputError("Expected {text: string}");
@@ -360,7 +414,10 @@ async function automaticSpeechRecognition(args, options) {
 
 // src/tasks/audio/textToSpeech.ts
 async function textToSpeech(args, options) {
-  const res = await request(args, options);
+  const res = await request(args, {
+    ...options,
+    taskHint: "text-to-speech"
+  });
   const isValidOutput = res && res instanceof Blob;
   if (!isValidOutput) {
     throw new InferenceOutputError("Expected Blob");
@@ -370,7 +427,10 @@ async function textToSpeech(args, options) {
 
 // src/tasks/audio/audioToAudio.ts
 async function audioToAudio(args, options) {
-  const res = await request(args, options);
+  const res = await request(args, {
+    ...options,
+    taskHint: "audio-to-audio"
+  });
   const isValidOutput = Array.isArray(res) && res.every(
     (x) => typeof x.label === "string" && typeof x.blob === "string" && typeof x["content-type"] === "string"
   );
@@ -382,7 +442,10 @@ async function audioToAudio(args, options) {
 
 // src/tasks/cv/imageClassification.ts
 async function imageClassification(args, options) {
-  const res = await request(args, options);
+  const res = await request(args, {
+    ...options,
+    taskHint: "image-classification"
+  });
   const isValidOutput = Array.isArray(res) && res.every((x) => typeof x.label === "string" && typeof x.score === "number");
   if (!isValidOutput) {
     throw new InferenceOutputError("Expected Array<{label: string, score: number}>");
@@ -392,7 +455,10 @@ async function imageClassification(args, options) {
 
 // src/tasks/cv/imageSegmentation.ts
 async function imageSegmentation(args, options) {
-  const res = await request(args, options);
+  const res = await request(args, {
+    ...options,
+    taskHint: "image-segmentation"
+  });
   const isValidOutput = Array.isArray(res) && res.every((x) => typeof x.label === "string" && typeof x.mask === "string" && typeof x.score === "number");
   if (!isValidOutput) {
     throw new InferenceOutputError("Expected Array<{label: string, mask: string, score: number}>");
@@ -402,7 +468,10 @@ async function imageSegmentation(args, options) {
 
 // src/tasks/cv/imageToText.ts
 async function imageToText(args, options) {
-  const res = (await request(args, options))?.[0];
+  const res = (await request(args, {
+    ...options,
+    taskHint: "image-to-text"
+  }))?.[0];
   if (typeof res?.generated_text !== "string") {
     throw new InferenceOutputError("Expected {generated_text: string}");
   }
@@ -411,7 +480,10 @@ async function imageToText(args, options) {
 
 // src/tasks/cv/objectDetection.ts
 async function objectDetection(args, options) {
-  const res = await request(args, options);
+  const res = await request(args, {
+    ...options,
+    taskHint: "object-detection"
+  });
   const isValidOutput = Array.isArray(res) && res.every(
     (x) => typeof x.label === "string" && typeof x.score === "number" && typeof x.box.xmin === "number" && typeof x.box.ymin === "number" && typeof x.box.xmax === "number" && typeof x.box.ymax === "number"
   );
@@ -425,7 +497,10 @@ async function objectDetection(args, options) {
 
 // src/tasks/cv/textToImage.ts
 async function textToImage(args, options) {
-  const res = await request(args, options);
+  const res = await request(args, {
+    ...options,
+    taskHint: "text-to-image"
+  });
   const isValidOutput = res && res instanceof Blob;
   if (!isValidOutput) {
     throw new InferenceOutputError("Expected Blob");
@@ -467,7 +542,10 @@ async function imageToImage(args, options) {
       )
     };
   }
-  const res = await request(reqArgs, options);
+  const res = await request(reqArgs, {
+    ...options,
+    taskHint: "image-to-image"
+  });
   const isValidOutput = res && res instanceof Blob;
   if (!isValidOutput) {
     throw new InferenceOutputError("Expected Blob");
@@ -487,7 +565,10 @@ async function zeroShotImageClassification(args, options) {
       )
     }
   };
-  const res = await request(reqArgs, options);
+  const res = await request(reqArgs, {
+    ...options,
+    taskHint: "zero-shot-image-classification"
+  });
   const isValidOutput = Array.isArray(res) && res.every((x) => typeof x.label === "string" && typeof x.score === "number");
   if (!isValidOutput) {
     throw new InferenceOutputError("Expected Array<{label: string, score: number}>");
@@ -497,7 +578,7 @@ async function zeroShotImageClassification(args, options) {
 
 // src/tasks/nlp/conversational.ts
 async function conversational(args, options) {
-  const res = await request(args, options);
+  const res = await request(args, { ...options, taskHint: "conversational" });
   const isValidOutput = Array.isArray(res.conversation.generated_responses) && res.conversation.generated_responses.every((x) => typeof x === "string") && Array.isArray(res.conversation.past_user_inputs) && res.conversation.past_user_inputs.every((x) => typeof x === "string") && typeof res.generated_text === "string" && Array.isArray(res.warnings) && res.warnings.every((x) => typeof x === "string");
   if (!isValidOutput) {
     throw new InferenceOutputError(
@@ -507,47 +588,14 @@ async function conversational(args, options) {
   return res;
 }
 
-// src/lib/getDefaultTask.ts
-var taskCache = /* @__PURE__ */ new Map();
-var CACHE_DURATION = 10 * 60 * 1e3;
-var MAX_CACHE_ITEMS = 1e3;
-var HF_HUB_URL = "https://huggingface.co";
-async function getDefaultTask(model, accessToken) {
-  if (isUrl(model)) {
-    return null;
-  }
-  const key = `${model}:${accessToken}`;
-  let cachedTask = taskCache.get(key);
-  if (cachedTask && cachedTask.date < new Date(Date.now() - CACHE_DURATION)) {
-    taskCache.delete(key);
-    cachedTask = void 0;
-  }
-  if (cachedTask === void 0) {
-    const modelTask = await fetch(`${HF_HUB_URL}/api/models/${model}?expand[]=pipeline_tag`, {
-      headers: accessToken ? { Authorization: `Bearer ${accessToken}` } : {}
-    }).then((resp) => resp.json()).then((json) => json.pipeline_tag).catch(() => null);
-    if (!modelTask) {
-      return null;
-    }
-    cachedTask = { task: modelTask, date: /* @__PURE__ */ new Date() };
-    taskCache.set(key, { task: modelTask, date: /* @__PURE__ */ new Date() });
-    if (taskCache.size > MAX_CACHE_ITEMS) {
-      taskCache.delete(taskCache.keys().next().value);
-    }
-  }
-  return cachedTask.task;
-}
-
 // src/tasks/nlp/featureExtraction.ts
 async function featureExtraction(args, options) {
-  const defaultTask = await getDefaultTask(args.model, args.accessToken);
-  const res = await request(
-    args,
-    defaultTask === "sentence-similarity" ? {
-      ...options,
-      task: "feature-extraction"
-    } : options
-  );
+  const defaultTask = args.model ? await getDefaultTask(args.model, args.accessToken) : void 0;
+  const res = await request(args, {
+    ...options,
+    taskHint: "feature-extraction",
+    ...defaultTask === "sentence-similarity" && { forceTask: "feature-extraction" }
+  });
   let isValidOutput = true;
   const isNumArrayRec = (arr, maxDepth, curDepth = 0) => {
     if (curDepth > maxDepth)
@@ -567,7 +615,10 @@ async function featureExtraction(args, options) {
 
 // src/tasks/nlp/fillMask.ts
 async function fillMask(args, options) {
-  const res = await request(args, options);
+  const res = await request(args, {
+    ...options,
+    taskHint: "fill-mask"
+  });
   const isValidOutput = Array.isArray(res) && res.every(
     (x) => typeof x.score === "number" && typeof x.sequence === "string" && typeof x.token === "number" && typeof x.token_str === "string"
   );
@@ -581,7 +632,10 @@ async function fillMask(args, options) {
 
 // src/tasks/nlp/questionAnswering.ts
 async function questionAnswering(args, options) {
-  const res = await request(args, options);
+  const res = await request(args, {
+    ...options,
+    taskHint: "question-answering"
+  });
   const isValidOutput = typeof res === "object" && !!res && typeof res.answer === "string" && typeof res.end === "number" && typeof res.score === "number" && typeof res.start === "number";
   if (!isValidOutput) {
     throw new InferenceOutputError("Expected {answer: string, end: number, score: number, start: number}");
@@ -591,14 +645,12 @@ async function questionAnswering(args, options) {
 
 // src/tasks/nlp/sentenceSimilarity.ts
 async function sentenceSimilarity(args, options) {
-  const defaultTask = await getDefaultTask(args.model, args.accessToken);
-  const res = await request(
-    args,
-    defaultTask === "feature-extraction" ? {
-      ...options,
-      task: "sentence-similarity"
-    } : options
-  );
+  const defaultTask = args.model ? await getDefaultTask(args.model, args.accessToken) : void 0;
+  const res = await request(args, {
+    ...options,
+    taskHint: "sentence-similarity",
+    ...defaultTask === "feature-extraction" && { forceTask: "sentence-similarity" }
+  });
   const isValidOutput = Array.isArray(res) && res.every((x) => typeof x === "number");
   if (!isValidOutput) {
     throw new InferenceOutputError("Expected number[]");
@@ -608,7 +660,10 @@ async function sentenceSimilarity(args, options) {
 
 // src/tasks/nlp/summarization.ts
 async function summarization(args, options) {
-  const res = await request(args, options);
+  const res = await request(args, {
+    ...options,
+    taskHint: "summarization"
+  });
   const isValidOutput = Array.isArray(res) && res.every((x) => typeof x?.summary_text === "string");
   if (!isValidOutput) {
     throw new InferenceOutputError("Expected Array<{summary_text: string}>");
@@ -618,7 +673,10 @@ async function summarization(args, options) {
 
 // src/tasks/nlp/tableQuestionAnswering.ts
 async function tableQuestionAnswering(args, options) {
-  const res = await request(args, options);
+  const res = await request(args, {
+    ...options,
+    taskHint: "table-question-answering"
+  });
   const isValidOutput = typeof res?.aggregator === "string" && typeof res.answer === "string" && Array.isArray(res.cells) && res.cells.every((x) => typeof x === "string") && Array.isArray(res.coordinates) && res.coordinates.every((coord) => Array.isArray(coord) && coord.every((x) => typeof x === "number"));
   if (!isValidOutput) {
     throw new InferenceOutputError(
@@ -630,7 +688,10 @@ async function tableQuestionAnswering(args, options) {
 
 // src/tasks/nlp/textClassification.ts
 async function textClassification(args, options) {
-  const res = (await request(args, options))?.[0];
+  const res = (await request(args, {
+    ...options,
+    taskHint: "text-classification"
+  }))?.[0];
   const isValidOutput = Array.isArray(res) && res.every((x) => typeof x?.label === "string" && typeof x.score === "number");
   if (!isValidOutput) {
     throw new InferenceOutputError("Expected Array<{label: string, score: number}>");
@@ -640,7 +701,10 @@ async function textClassification(args, options) {
 
 // src/tasks/nlp/textGeneration.ts
 async function textGeneration(args, options) {
-  const res = await request(args, options);
+  const res = await request(args, {
+    ...options,
+    taskHint: "text-generation"
+  });
   const isValidOutput = Array.isArray(res) && res.every((x) => typeof x?.generated_text === "string");
   if (!isValidOutput) {
     throw new InferenceOutputError("Expected Array<{generated_text: string}>");
@@ -650,7 +714,10 @@ async function textGeneration(args, options) {
 
 // src/tasks/nlp/textGenerationStream.ts
 async function* textGenerationStream(args, options) {
-  yield* streamingRequest(args, options);
+  yield* streamingRequest(args, {
+    ...options,
+    taskHint: "text-generation"
+  });
 }
 
 // src/utils/toArray.ts
@@ -663,7 +730,12 @@ function toArray(obj) {
 
 // src/tasks/nlp/tokenClassification.ts
 async function tokenClassification(args, options) {
-  const res = toArray(await request(args, options));
+  const res = toArray(
+    await request(args, {
+      ...options,
+      taskHint: "token-classification"
+    })
+  );
   const isValidOutput = Array.isArray(res) && res.every(
     (x) => typeof x.end === "number" && typeof x.entity_group === "string" && typeof x.score === "number" && typeof x.start === "number" && typeof x.word === "string"
   );
@@ -677,7 +749,10 @@ async function tokenClassification(args, options) {
 
 // src/tasks/nlp/translation.ts
 async function translation(args, options) {
-  const res = await request(args, options);
+  const res = await request(args, {
+    ...options,
+    taskHint: "translation"
+  });
   const isValidOutput = Array.isArray(res) && res.every((x) => typeof x?.translation_text === "string");
   if (!isValidOutput) {
     throw new InferenceOutputError("Expected type Array<{translation_text: string}>");
@@ -688,7 +763,10 @@ async function translation(args, options) {
 // src/tasks/nlp/zeroShotClassification.ts
 async function zeroShotClassification(args, options) {
   const res = toArray(
-    await request(args, options)
+    await request(args, {
+      ...options,
+      taskHint: "zero-shot-classification"
+    })
   );
   const isValidOutput = Array.isArray(res) && res.every(
     (x) => Array.isArray(x.labels) && x.labels.every((_label) => typeof _label === "string") && Array.isArray(x.scores) && x.scores.every((_score) => typeof _score === "number") && typeof x.sequence === "string"
@@ -714,7 +792,10 @@ async function documentQuestionAnswering(args, options) {
     }
   };
   const res = toArray(
-    await request(reqArgs, options)
+    await request(reqArgs, {
+      ...options,
+      taskHint: "document-question-answering"
+    })
   )?.[0];
   const isValidOutput = typeof res?.answer === "string" && (typeof res.end === "number" || typeof res.end === "undefined") && (typeof res.score === "number" || typeof res.score === "undefined") && (typeof res.start === "number" || typeof res.start === "undefined");
   if (!isValidOutput) {
@@ -737,7 +818,10 @@ async function visualQuestionAnswering(args, options) {
       )
     }
   };
-  const res = (await request(reqArgs, options))?.[0];
+  const res = (await request(reqArgs, {
+    ...options,
+    taskHint: "visual-question-answering"
+  }))?.[0];
   const isValidOutput = typeof res?.answer === "string" && typeof res.score === "number";
   if (!isValidOutput) {
     throw new InferenceOutputError("Expected Array<{answer: string, score: number}>");
@@ -747,7 +831,10 @@ async function visualQuestionAnswering(args, options) {
 
 // src/tasks/tabular/tabularRegression.ts
 async function tabularRegression(args, options) {
-  const res = await request(args, options);
+  const res = await request(args, {
+    ...options,
+    taskHint: "tabular-regression"
+  });
   const isValidOutput = Array.isArray(res) && res.every((x) => typeof x === "number");
   if (!isValidOutput) {
     throw new InferenceOutputError("Expected number[]");
@@ -757,7 +844,10 @@ async function tabularRegression(args, options) {
 
 // src/tasks/tabular/tabularClassification.ts
 async function tabularClassification(args, options) {
-  const res = await request(args, options);
+  const res = await request(args, {
+    ...options,
+    taskHint: "tabular-classification"
+  });
   const isValidOutput = Array.isArray(res) && res.every((x) => typeof x === "number");
   if (!isValidOutput) {
     throw new InferenceOutputError("Expected number[]");