@huggingface/inference 2.6.4 → 2.6.5

package/README.md

@@ -1,12 +1,17 @@
-# 🤗 Hugging Face Inference API
+# 🤗 Hugging Face Inference Endpoints
 
-A Typescript powered wrapper for the Hugging Face Inference API. Learn more about the Inference API at [Hugging Face](https://huggingface.co/docs/api-inference/index). It also works with [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index).
+A Typescript powered wrapper for the Hugging Face Inference Endpoints API. Learn more about Inference Endpoints at [Hugging Face](https://huggingface.co/inference-endpoints).
+It works with both [Inference API (serverless)](https://huggingface.co/docs/api-inference/index) and [Inference Endpoints (dedicated)](https://huggingface.co/docs/inference-endpoints/index).
 
 Check out the [full documentation](https://huggingface.co/docs/huggingface.js/inference/README).
 
-You can also try out a live [interactive notebook](https://observablehq.com/@huggingface/hello-huggingface-js-inference) or see some demos on [hf.co/huggingfacejs](https://huggingface.co/huggingfacejs).
+You can also try out a live [interactive notebook](https://observablehq.com/@huggingface/hello-huggingface-js-inference), see some demos on [hf.co/huggingfacejs](https://huggingface.co/huggingfacejs), or watch a [Scrimba tutorial that explains how Inference Endpoints works](https://scrimba.com/scrim/cod8248f5adfd6e129582c523). 
 
-## Install
+## Getting Started
+
+### Install
+
+#### Node
 
 ```console
 npm install @huggingface/inference
@@ -16,7 +21,7 @@ pnpm add @huggingface/inference
 yarn add @huggingface/inference
 ```
 
-### Deno
+#### Deno
 
 ```ts
 // esm.sh
@@ -25,26 +30,55 @@ import { HfInference } from "https://esm.sh/@huggingface/inference"
 import { HfInference } from "npm:@huggingface/inference"
 ```
 
-## Usage
+
+### Initialize
+
+```typescript
+import { HfInference } from '@huggingface/inference'
+
+const hf = new HfInference('your access token')
+```
 
 ❗**Important note:** Using an access token is optional to get started, however you will be rate limited eventually. Join [Hugging Face](https://huggingface.co/join) and then visit [access tokens](https://huggingface.co/settings/tokens) to generate your access token for **free**.
 
 Your access token should be kept private. If you need to protect it in front-end applications, we suggest setting up a proxy server that stores the access token.
 
-### Basic examples
 
-```typescript
-import { HfInference } from '@huggingface/inference'
+#### Tree-shaking
 
-const hf = new HfInference('your access token')
+You can import the functions you need directly from the module instead of using the `HfInference` class.
+
+```ts
+import { textGeneration } from "@huggingface/inference";
+
+await textGeneration({
+  accessToken: "hf_...",
+  model: "model_or_endpoint",
+  inputs: ...,
+  parameters: ...
+})
+```
+
+This will enable tree-shaking by your bundler.
 
-// Natural Language
+## Natural Language Processing
 
+### Fill Mask
+
+Tries to fill in a hole with a missing word (token to be precise).
+
+```typescript
 await hf.fillMask({
   model: 'bert-base-uncased',
   inputs: '[MASK] world!'
 })
+```
+
+### Summarization
+
+Summarizes longer text into shorter text. Be careful, some models have a maximum length of input.
 
+```typescript
 await hf.summarization({
   model: 'facebook/bart-large-cnn',
   inputs:
@@ -53,7 +87,13 @@ await hf.summarization({
     max_length: 100
   }
 })
+```
+
+### Question Answering
 
+Answers questions based on the context you provide.
+
+```typescript
 await hf.questionAnswering({
   model: 'deepset/roberta-base-squad2',
   inputs: {
@@ -61,7 +101,11 @@ await hf.questionAnswering({
     context: 'The capital of France is Paris.'
   }
 })
+```
 
+### Table Question Answering
+
+```typescript
 await hf.tableQuestionAnswering({
   model: 'google/tapas-base-finetuned-wtq',
   inputs: {
@@ -74,12 +118,26 @@ await hf.tableQuestionAnswering({
     }
   }
 })
+```
 
+### Text Classification
+
+Often used for sentiment analysis, this method will assign labels to the given text along with a probability score of that label.
+
+```typescript
 await hf.textClassification({
   model: 'distilbert-base-uncased-finetuned-sst-2-english',
   inputs: 'I like you. I love you.'
 })
+```
+
+### Text Generation
+
+Generates text from an input prompt.
 
+[Demo](https://huggingface.co/spaces/huggingfacejs/streaming-text-generation)
+
+```typescript
 await hf.textGeneration({
   model: 'gpt2',
   inputs: 'The answer to the universe is'
@@ -92,17 +150,44 @@ for await (const output of hf.textGenerationStream({
 })) {
   console.log(output.token.text, output.generated_text);
 }
+```
 
+### Token Classification
+
+Used for sentence parsing, either grammatical, or Named Entity Recognition (NER) to understand keywords contained within text.
+
+```typescript
 await hf.tokenClassification({
   model: 'dbmdz/bert-large-cased-finetuned-conll03-english',
   inputs: 'My name is Sarah Jessica Parker but you can call me Jessica'
 })
+```
+
+### Translation
+
+Converts text from one language to another.
 
+```typescript
 await hf.translation({
   model: 't5-base',
   inputs: 'My name is Wolfgang and I live in Berlin'
 })
 
+await hf.translation({
+  model: 'facebook/mbart-large-50-many-to-many-mmt',
+  inputs: textToTranslate,
+  parameters: {
+		"src_lang": "en_XX",
+		"tgt_lang": "fr_XX"
+	}
+})
+```
+
+### Zero-Shot Classification
+
+Checks how well an input text fits into a set of labels you provide.
+
+```typescript
 await hf.zeroShotClassification({
   model: 'facebook/bart-large-mnli',
   inputs: [
@@ -110,7 +195,13 @@ await hf.zeroShotClassification({
   ],
   parameters: { candidate_labels: ['refund', 'legal', 'faq'] }
 })
+```
+
+### Conversational
+
+This task corresponds to any chatbot-like structure. Models tend to have shorter max_length, so please check with caution when using a given model if you need long-range dependency or not.
 
+```typescript
 await hf.conversational({
   model: 'microsoft/DialoGPT-large',
   inputs: {
@@ -119,7 +210,13 @@ await hf.conversational({
     text: 'Can you explain why ?'
   }
 })
+```
+
+### Sentence Similarity
 
+Calculate the semantic similarity between one text and a list of other sentences.
+
+```typescript
 await hf.sentenceSimilarity({
   model: 'sentence-transformers/paraphrase-xlm-r-multilingual-v1',
   inputs: {
@@ -131,51 +228,117 @@ await hf.sentenceSimilarity({
     ]
   }
 })
+```
 
-await hf.featureExtraction({
-  model: "sentence-transformers/distilbert-base-nli-mean-tokens",
-  inputs: "That is a happy person",
-});
+## Audio
+
+### Automatic Speech Recognition
+
+Transcribes speech from an audio file.
 
-// Audio
+[Demo](https://huggingface.co/spaces/huggingfacejs/speech-recognition-vue)
 
+```typescript
 await hf.automaticSpeechRecognition({
   model: 'facebook/wav2vec2-large-960h-lv60-self',
   data: readFileSync('test/sample1.flac')
 })
+```
+
+### Audio Classification
 
+Assigns labels to the given audio along with a probability score of that label.
+
+[Demo](https://huggingface.co/spaces/huggingfacejs/audio-classification-vue)
+
+```typescript
 await hf.audioClassification({
   model: 'superb/hubert-large-superb-er',
   data: readFileSync('test/sample1.flac')
 })
+```
+
+### Text To Speech
+
+Generates natural-sounding speech from text input.
 
+[Interactive tutorial](https://scrimba.com/scrim/co8da4d23b49b648f77f4848a?pl=pkVnrP7uP)
+
+```typescript
 await hf.textToSpeech({
   model: 'espnet/kan-bayashi_ljspeech_vits',
   inputs: 'Hello world!'
 })
+```
 
+### Audio To Audio
+
+Outputs one or multiple generated audios from an input audio, commonly used for speech enhancement and source separation.
+
+```typescript
 await hf.audioToAudio({
   model: 'speechbrain/sepformer-wham',
   data: readFileSync('test/sample1.flac')
 })
+```
+
+## Computer Vision
+
+### Image Classification
 
-// Computer Vision
+Assigns labels to a given image along with a probability score of that label.
 
+[Demo](https://huggingface.co/spaces/huggingfacejs/image-classification-vue)
+
+```typescript
 await hf.imageClassification({
   data: readFileSync('test/cheetah.png'),
   model: 'google/vit-base-patch16-224'
 })
+```
+
+### Object Detection
+
+Detects objects within an image and returns labels with corresponding bounding boxes and probability scores.
+
+[Demo](https://huggingface.co/spaces/huggingfacejs/object-detection-vue)
 
+```typescript
 await hf.objectDetection({
   data: readFileSync('test/cats.png'),
   model: 'facebook/detr-resnet-50'
 })
+```
+
+### Image Segmentation
 
+Detects segments within an image and returns labels with corresponding bounding boxes and probability scores.
+
+```typescript
 await hf.imageSegmentation({
   data: readFileSync('test/cats.png'),
   model: 'facebook/detr-resnet-50-panoptic'
 })
+```
+
+### Image To Text
+
+Outputs text from a given image, commonly used for captioning or optical character recognition.
+
+```typescript
+await hf.imageToText({
+  data: readFileSync('test/cats.png'),
+  model: 'nlpconnect/vit-gpt2-image-captioning'
+})
+```
+
+### Text To Image
+
+Creates an image from a text prompt.
+
+[Demo](https://huggingface.co/spaces/huggingfacejs/image-to-text)
 
+```typescript
 await hf.textToImage({
   inputs: 'award winning high resolution photo of a giant tortoise/((ladybird)) hybrid, [trending on artstation]',
   model: 'stabilityai/stable-diffusion-2',
@@ -183,12 +346,15 @@ await hf.textToImage({
     negative_prompt: 'blurry',
   }
 })
+```
 
-await hf.imageToText({
-  data: readFileSync('test/cats.png'),
-  model: 'nlpconnect/vit-gpt2-image-captioning'
-})
+### Image To Image
 
+Image-to-image is the task of transforming a source image to match the characteristics of a target image or a target image domain.
+
+[Interactive tutorial](https://scrimba.com/scrim/co4834bf9a91cc81cfab07969?pl=pkVnrP7uP)
+
+```typescript
 await hf.imageToImage({
   inputs: new Blob([readFileSync("test/stormtrooper_depth.png")]),
   parameters: {
@@ -196,7 +362,13 @@ await hf.imageToImage({
   },
   model: "lllyasviel/sd-controlnet-depth",
 });
+```
+
+### Zero Shot Image Classification
+
+Checks how well an input image fits into a set of labels you provide.
 
+```typescript
 await hf.zeroShotImageClassification({
   model: 'openai/clip-vit-large-patch14-336',
   inputs: {
@@ -206,9 +378,28 @@ await hf.zeroShotImageClassification({
     candidate_labels: ['cat', 'dog']
   }
 })
+```
+
+## Multimodal
+
+### Feature Extraction
+
+This task reads some text and outputs raw float values, that are usually consumed as part of a semantic database/semantic search.
+
+```typescript
+await hf.featureExtraction({
+  model: "sentence-transformers/distilbert-base-nli-mean-tokens",
+  inputs: "That is a happy person",
+});
+```
 
-// Multimodal
+### Visual Question Answering
 
+Visual Question Answering is the task of answering open-ended questions based on an image. They output natural language responses to natural language questions.
+
+[Demo](https://huggingface.co/spaces/huggingfacejs/doc-vis-qa)
+
+```typescript
 await hf.visualQuestionAnswering({
   model: 'dandelin/vilt-b32-finetuned-vqa',
   inputs: {
@@ -216,7 +407,15 @@ await hf.visualQuestionAnswering({
     image: await (await fetch('https://placekitten.com/300/300')).blob()
   }
 })
+```
+
+### Document Question Answering
+
+Document question answering models take a (document, question) pair as input and return an answer in natural language.
 
+[Demo](https://huggingface.co/spaces/huggingfacejs/doc-vis-qa)
+
+```typescript
 await hf.documentQuestionAnswering({
   model: 'impira/layoutlm-document-qa',
   inputs: {
@@ -224,9 +423,15 @@ await hf.documentQuestionAnswering({
     image: await (await fetch('https://huggingface.co/spaces/impira/docquery/resolve/2359223c1837a7587402bda0f2643382a6eefeab/invoice.png')).blob(),
   }
 })
+```
 
-// Tabular
+## Tabular
 
+### Tabular Regression
+
+Tabular regression is the task of predicting a numerical value given a set of attributes.
+
+```typescript
 await hf.tabularRegression({
   model: "scikit-learn/Fish-Weight",
   inputs: {
@@ -240,7 +445,13 @@ await hf.tabularRegression({
     },
   },
 })
+```
+
+### Tabular Classification
+
+Tabular classification is the task of classifying a target category (a group) based on set of attributes.
 
+```typescript
 await hf.tabularClassification({
   model: "vvmnnnkv/wine-quality",
   inputs: {
@@ -259,8 +470,13 @@ await hf.tabularClassification({
     },
   },
 })
+```
+
+## Custom Calls
 
-// Custom call, for models with custom parameters / outputs
+For models with custom parameters / outputs.
+
+```typescript
 await hf.request({
   model: 'my-custom-model',
   inputs: 'hello world',
@@ -279,79 +495,21 @@ for await (const output of hf.streamingRequest({
 })) {
   ...
 }
-
-// Using your own inference endpoint: https://hf.co/docs/inference-endpoints/
-const gpt2 = hf.endpoint('https://xyz.eu-west-1.aws.endpoints.huggingface.cloud/gpt2');
-const { generated_text } = await gpt2.textGeneration({inputs: 'The answer to the universe is'});
 ```
 
-## Supported Tasks
-
-### Natural Language Processing
+## Custom Inference Endpoints
 
-- [x] Fill mask
-- [x] Summarization
-- [x] Question answering
-- [x] Table question answering
-- [x] Text classification
-- [x] Text generation - [demo](https://huggingface.co/spaces/huggingfacejs/streaming-text-generation)
-- [x] Text2Text generation
-- [x] Token classification
-- [x] Named entity recognition
-- [x] Translation
-- [x] Zero-shot classification
-- [x] Conversational
-- [x] Feature extraction
-- [x] Sentence Similarity
+Learn more about using your own inference endpoints [here](https://hf.co/docs/inference-endpoints/)
 
-### Audio
-
-- [x] Automatic speech recognition
-- [x] Audio classification
-- [x] Text to speech
-- [x] Audio to audio
-
-### Computer Vision
-
-- [x] Image classification
-- [x] Object detection
-- [x] Image segmentation
-- [x] Text to image
-- [x] Image to text - [demo](https://huggingface.co/spaces/huggingfacejs/image-to-text)
-- [x] Image to Image
-- [x] Zero-shot image classification
-
-### Multimodal
-
-- [x] Document question answering - [demo](https://huggingface.co/spaces/huggingfacejs/doc-vis-qa)
-- [x] Visual question answering - [demo](https://huggingface.co/spaces/huggingfacejs/doc-vis-qa)
-
-### Tabular
-
-- [x] Tabular regression
-- [x] Tabular classification
-
-## Tree-shaking
-
-You can import the functions you need directly from the module, rather than using the `HfInference` class:
-
-```ts
-import {textGeneration} from "@huggingface/inference";
-
-await textGeneration({
-  accessToken: "hf_...",
-  model: "model_or_endpoint",
-  inputs: ...,
-  parameters: ...
-})
+```typescript
+const gpt2 = hf.endpoint('https://xyz.eu-west-1.aws.endpoints.huggingface.cloud/gpt2');
+const { generated_text } = await gpt2.textGeneration({inputs: 'The answer to the universe is'});
 ```
 
-This will enable tree-shaking by your bundler.
-
 ## Running tests
 
 ```console
-HF_ACCESS_TOKEN="your access token" pnpm run test
+HF_TOKEN="your access token" pnpm run test
 ```
 
 ## Finding appropriate models

package/dist/{index.mjs → index.cjs}

@@ -1,9 +1,60 @@
 /// <reference path="./index.d.ts" />
+"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 src_exports = {};
+__export(src_exports, {
+  HfInference: () => HfInference,
+  HfInferenceEndpoint: () => HfInferenceEndpoint,
+  InferenceOutputError: () => InferenceOutputError,
+  audioClassification: () => audioClassification,
+  audioToAudio: () => audioToAudio,
+  automaticSpeechRecognition: () => automaticSpeechRecognition,
+  documentQuestionAnswering: () => documentQuestionAnswering,
+  featureExtraction: () => featureExtraction,
+  fillMask: () => fillMask,
+  imageClassification: () => imageClassification,
+  imageSegmentation: () => imageSegmentation,
+  imageToImage: () => imageToImage,
+  imageToText: () => imageToText,
+  objectDetection: () => objectDetection,
+  questionAnswering: () => questionAnswering,
+  request: () => request,
+  sentenceSimilarity: () => sentenceSimilarity,
+  streamingRequest: () => streamingRequest,
+  summarization: () => summarization,
+  tableQuestionAnswering: () => tableQuestionAnswering,
+  tabularClassification: () => tabularClassification,
+  tabularRegression: () => tabularRegression,
+  textClassification: () => textClassification,
+  textGeneration: () => textGeneration,
+  textGenerationStream: () => textGenerationStream,
+  textToImage: () => textToImage,
+  textToSpeech: () => textToSpeech,
+  tokenClassification: () => tokenClassification,
+  translation: () => translation,
+  visualQuestionAnswering: () => visualQuestionAnswering,
+  zeroShotClassification: () => zeroShotClassification,
+  zeroShotImageClassification: () => zeroShotImageClassification
+});
+module.exports = __toCommonJS(src_exports);
 
 // src/tasks/index.ts
 var tasks_exports = {};
@@ -11,7 +62,6 @@ __export(tasks_exports, {
   audioClassification: () => audioClassification,
   audioToAudio: () => audioToAudio,
   automaticSpeechRecognition: () => automaticSpeechRecognition,
-  conversational: () => conversational,
   documentQuestionAnswering: () => documentQuestionAnswering,
   featureExtraction: () => featureExtraction,
   fillMask: () => fillMask,
@@ -275,7 +325,7 @@ async function* streamingRequest(args, 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, {
+    return yield* streamingRequest(args, {
       ...options,
       wait_for_model: true
     });
@@ -533,18 +583,6 @@ async function zeroShotImageClassification(args, options) {
   return res;
 }
 
-// src/tasks/nlp/conversational.ts
-async function conversational(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" && (typeof res.warnings === "undefined" || Array.isArray(res.warnings) && res.warnings.every((x) => typeof x === "string"));
-  if (!isValidOutput) {
-    throw new InferenceOutputError(
-      "Expected {conversation: {generated_responses: string[], past_user_inputs: string[]}, generated_text: string, warnings: string[]}"
-    );
-  }
-  return res;
-}
-
 // src/tasks/nlp/featureExtraction.ts
 async function featureExtraction(args, options) {
   const defaultTask = args.model ? await getDefaultTask(args.model, args.accessToken, options) : void 0;
@@ -714,7 +752,7 @@ async function translation(args, options) {
   if (!isValidOutput) {
     throw new InferenceOutputError("Expected type Array<{translation_text: string}>");
   }
-  return res?.[0];
+  return res?.length === 1 ? res?.[0] : res;
 }
 
 // src/tasks/nlp/zeroShotClassification.ts
@@ -851,14 +889,14 @@ var HfInferenceEndpoint = class {
     }
   }
 };
-export {
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
   HfInference,
   HfInferenceEndpoint,
   InferenceOutputError,
   audioClassification,
   audioToAudio,
   automaticSpeechRecognition,
-  conversational,
   documentQuestionAnswering,
   featureExtraction,
   fillMask,
@@ -885,4 +923,4 @@ export {
   visualQuestionAnswering,
   zeroShotClassification,
   zeroShotImageClassification
-};
+});