@huggingface/inference 2.6.4 → 2.6.6

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,36 @@ 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:
+```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'});
+```
 
-```ts
-import {textGeneration} from "@huggingface/inference";
+By default, all calls to the inference endpoint will wait until the model is
+loaded. When [scaling to
+0](https://huggingface.co/docs/inference-endpoints/en/autoscaling#scaling-to-0)
+is enabled on the endpoint, this can result in non-trivial waiting time. If
+you'd rather disable this behavior and handle the endpoint's returned 500 HTTP
+errors yourself, you can do so like so:
 
-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'},
+  {retry_on_error: false},
+);
 ```
 
-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