Huggingface.js documentation

🤗 Hugging Face Inference

Huggingface.js

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

🤗 Hugging Face Inference

Um wrapper com suporte a Typescript que fornece uma interface unificada para executar inferência em vários serviços para modelos hospedados no Hugging Face Hub:

Provedores de Inferência: acesso simplificado e unificado a centenas de modelos de machine learning, impulsionado por nossos parceiros de inferência serverless. Essa nova abordagem se baseia na nossa anterior API de Inferência Serverless, oferecendo mais modelos, desempenho aprimorado e maior confiabilidade graças a provedores de classe mundial. Consulte a documentação para obter a lista de provedores suportados.
Inference Endpoints: um produto para implantar modelos em produção com facilidade. A inferência é executada pela Hugging Face em uma infraestrutura dedicada e totalmente gerenciada em um provedor de nuvem de sua escolha.
Endpoints locais: você também pode executar inferência com servidores de inferência locais, como llama.cpp, Ollama, vLLM, LiteLLM ou Text Generation Inference (TGI), conectando o cliente a esses endpoints locais.

Começando

Instalar

Node

npm install @huggingface/inference

pnpm add @huggingface/inference

yarn add @huggingface/inference

Deno

// esm.sh
import { InferenceClient } from "https://esm.sh/@huggingface/inference";
// or npm:
import { InferenceClient } from "npm:@huggingface/inference";

Inicializar

import { InferenceClient } from '@huggingface/inference';

const hf = new InferenceClient('your access token');

❗Observação importante: Sempre passe um token de acesso. Inscreva-se no Hugging Face e, em seguida, visite tokens de acesso para gerar seu token de acesso gratuitamente.

Seu token de acesso deve ser mantido em sigilo. Se você precisar protegê-lo em aplicações front-end, sugerimos configurar um servidor proxy que armazene o token de acesso.

Usando provedores de inferência

Você pode enviar solicitações de inferência para provedores de terceiros com o cliente de inferência.

Atualmente, suportamos os seguintes provedores:

Para enviar solicitações a um provedor de terceiros, você deve passar o parâmetro provider para a função de inferência. O valor padrão do parâmetro provider é “auto”, que selecionará o primeiro dos provedores disponíveis para o modelo, ordenados pela sua ordem de preferência em https://hf.co/settings/inference-providers.

const accessToken = "hf_..."; // Either a HF access token, or an API key from the third-party provider (Replicate in this example)

const client = new InferenceClient(accessToken);
await client.textToImage({
  provider: "replicate",
  model:"black-forest-labs/Flux.1-dev",
  inputs: "A black forest cake"
})

Você também deve garantir que sua solicitação esteja autenticada com um token de acesso. Quando autenticado com um token de acesso do Hugging Face, a solicitação é roteada por meio de https://huggingface.co. Quando autenticado com uma chave de provedor de terceiros, a solicitação é feita diretamente à API de inferência desse provedor.

Apenas um subconjunto de modelos é suportado ao solicitar provedores de terceiros. Você pode verificar a lista de modelos suportados por tarefa de pipeline aqui:

❗Observação importante: Para ser compatível, a API de terceiros deve seguir a forma “padrão” da API que esperamos nas páginas de modelos do HF para cada tipo de tarefa de pipeline. Isso não é um problema para LLMs, já que todos convergiram para a API da OpenAI de qualquer forma, mas pode ser mais complicado para outras tarefas, como “text-to-image” ou “automatic-speech-recognition”, onde não existe uma API padrão. Avise-nos se precisar de ajuda ou se podemos facilitar as coisas para você!

👋Deseja adicionar outro provedor? Entre em contato se quiser adicionar suporte a outro provedor de Inferência e/ou solicite-o em https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49

Tree-shaking

Você pode importar as funções de que precisa diretamente do módulo, em vez de usar a classe InferenceClient.

import { textGeneration } from "@huggingface/inference";

await textGeneration({
  accessToken: "hf_...",
  model: "model_or_endpoint",
  inputs: ...,
  parameters: ...
})

Isso permitirá o tree-shaking pelo seu bundler.

Tratamento de erros

O pacote de inferência fornece tipos de erro específicos para ajudar você a lidar com diferentes cenários de erro de forma eficaz.

Tipos de Erro

O pacote define vários tipos de erro que estendem a classe base Error:

InferenceClientError: Classe de erro base para todos os erros de Inferência do Hugging Face
InferenceClientInputError: Lançado quando há problemas com os parâmetros de entrada
InferenceClientProviderApiError: Lançado quando há erros no nível da API dos provedores
InferenceClientHubApiError: Lançado quando há erros em nível de API do Hugging Face Hub
InferenceClientProviderOutputError: Lançado quando há problemas com o formato das respostas de API dos provedores

Exemplo de uso

import { InferenceClient } from "@huggingface/inference";
import {
  InferenceClientError,
  InferenceClientInputError,
  InferenceClientProviderApiError,
  InferenceClientProviderOutputError,
  InferenceClientHubApiError,
} from "@huggingface/inference";

const client = new InferenceClient();

try {
  const result = await client.textGeneration({
    model: "gpt2",
    inputs: "Hello, I'm a language model",
  });
} catch (error) {
  if (error instanceof InferenceClientProviderApiError) {
    // Handle API errors (e.g., rate limits, authentication issues)
    console.error("Provider API Error:", error.message);
    console.error("HTTP Request details:", error.httpRequest);
    console.error("HTTP Response details:", error.httpResponse);
  } else if (error instanceof InferenceClientHubApiError) {
    // Handle API errors (e.g., rate limits, authentication issues)
    console.error("Hub API Error:", error.message);
    console.error("HTTP Request details:", error.httpRequest);
    console.error("HTTP Response details:", error.httpResponse);
  } else if (error instanceof InferenceClientProviderOutputError) {
    // Handle malformed responses from providers
    console.error("Provider Output Error:", error.message);
  } else if (error instanceof InferenceClientInputError) {
    // Handle invalid input parameters
    console.error("Input Error:", error.message);
  } else {
    // Handle unexpected errors
    console.error("Unexpected error:", error);
  }
}

/// Catch all errors from @huggingface/inference
try {
  const result = await client.textGeneration({
    model: "gpt2",
    inputs: "Hello, I'm a language model",
  });
} catch (error) {
  if (error instanceof InferenceClientError) {
    // Handle errors from @huggingface/inference
    console.error("Error from InferenceClient:", error);
  } else {
    // Handle unexpected errors
    console.error("Unexpected error:", error);
  }
}

Detalhes do erro

InferenceClientProviderApiError

Esse erro ocorre quando há problemas com a solicitação de API ao executar inferência no provedor selecionado.

Ele possui várias propriedades:

message: uma mensagem de erro descritiva
httpRequest: Detalhes sobre a solicitação falha (URL, método, cabeçalhos)
httpResponse: Detalhes da resposta, incluindo o código de status e o corpo

InferenceClientHubApiError

Esse erro ocorre quando há problemas com a solicitação de API ao solicitar a API do Hugging Face Hub.

Ele possui várias propriedades:

message: uma mensagem de erro descritiva
httpRequest: Detalhes sobre a solicitação falha (URL, método, cabeçalhos)
httpResponse: Detalhes da resposta, incluindo o código de status e o corpo

InferenceClientProviderOutputError

Esse erro ocorre quando um provedor retorna uma resposta em um formato inesperado.

InferenceClientInputError

Esse erro ocorre quando os parâmetros de entrada são inválidos ou ausentes. A mensagem de erro descreve o que há de errado com a entrada.

Processamento de Linguagem Natural

Geração de Texto

Gera texto a partir de um prompt de entrada.

await hf.textGeneration({
  model: 'mistralai/Mixtral-8x7B-v0.1',
  provider: "together",
  inputs: 'The answer to the universe is'
})

for await (const output of hf.textGenerationStream({
  model: "mistralai/Mixtral-8x7B-v0.1",
  provider: "together",
  inputs: 'repeat "one two three four"',
  parameters: { max_new_tokens: 250 }
})) {
  console.log(output.token.text, output.generated_text);
}

Conclusão do Chat

Gere uma resposta do modelo a partir de uma lista de mensagens que compõem uma conversa.

// Non-streaming API
const out = await hf.chatCompletion({
  model: "Qwen/Qwen3-32B",
  provider: "cerebras",
  messages: [{ role: "user", content: "Hello, nice to meet you!" }],
  max_tokens: 512,
  temperature: 0.1,
});

// Streaming API
let out = "";
for await (const chunk of hf.chatCompletionStream({
  model: "Qwen/Qwen3-32B",
  provider: "cerebras",
  messages: [
    { role: "user", content: "Can you help me solve an equation?" },
  ],
  max_tokens: 512,
  temperature: 0.1,
})) {
  if (chunk.choices && chunk.choices.length > 0) {
    out += chunk.choices[0].delta.content;
  }
}

Extração de recursos

Esta tarefa lê algum texto e produz valores float brutos, que geralmente são consumidos como parte de um banco de dados semântico/busca semântica.

await hf.featureExtraction({
  model: "sentence-transformers/distilbert-base-nli-mean-tokens",
  inputs: "That is a happy person",
});

Preencher Máscara

Tenta preencher um buraco com uma palavra ausente (mais precisamente, um token).

await hf.fillMask({
  model: 'bert-base-uncased',
  inputs: '[MASK] world!'
})

Resumo

Resume textos mais longos em textos mais curtos. Tenha cuidado, alguns modelos possuem um comprimento máximo de entrada.

await hf.summarization({
  model: 'facebook/bart-large-cnn',
  inputs:
    'The tower is 324 metres (1,063 ft) tall, about the same height as an 81-storey building, and the tallest structure in Paris. Its base is square, measuring 125 metres (410 ft) on each side. During its construction, the Eiffel Tower surpassed the Washington Monument to become the tallest man-made structure in the world, a title it held for 41 years until the Chrysler Building in New York City was finished in 1930.',
  parameters: {
    max_length: 100
  }
})

Resposta a Perguntas

Responde perguntas com base no contexto que você fornece.

await hf.questionAnswering({
  model: 'deepset/roberta-base-squad2',
  inputs: {
    question: 'What is the capital of France?',
    context: 'The capital of France is Paris.'
  }
})

Respostas a perguntas sobre tabelas

await hf.tableQuestionAnswering({
  model: 'google/tapas-base-finetuned-wtq',
  inputs: {
    query: 'How many stars does the transformers repository have?',
    table: {
      Repository: ['Transformers', 'Datasets', 'Tokenizers'],
      Stars: ['36542', '4512', '3934'],
      Contributors: ['651', '77', '34'],
      'Programming language': ['Python', 'Python', 'Rust, Python and NodeJS']
    }
  }
})

Classificação de Texto

Frequentemente usado para análise de sentimento, este método atribuirá rótulos ao texto fornecido, juntamente com uma pontuação de probabilidade para cada rótulo.

await hf.textClassification({
  model: 'distilbert-base-uncased-finetuned-sst-2-english',
  inputs: 'I like you. I love you.'
})

Classificação de Tokens

Usado para análise de sentenças, seja gramatical, seja Reconhecimento de Entidades Nomeadas (NER), para entender as palavras-chave contidas no texto.

await hf.tokenClassification({
  model: 'dbmdz/bert-large-cased-finetuned-conll03-english',
  inputs: 'My name is Sarah Jessica Parker but you can call me Jessica'
})

Tradução

Converte texto de um idioma para outro.

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"
 }
})

Classificação Zero-Shot

Verifica o quão bem um texto de entrada se encaixa em um conjunto de rótulos que você fornece.

await hf.zeroShotClassification({
  model: 'facebook/bart-large-mnli',
  inputs: [
    'Hi, I recently bought a device from your company but it is not working as advertised and I would like to get reimbursed!'
  ],
  parameters: { candidate_labels: ['refund', 'legal', 'faq'] }
})

Similaridade de Sentenças

Calcule a similaridade semântica entre um texto e uma lista de outras frases.

await hf.sentenceSimilarity({
  model: 'sentence-transformers/paraphrase-xlm-r-multilingual-v1',
  inputs: {
    source_sentence: 'That is a happy person',
    sentences: [
      'That is a happy dog',
      'That is a very happy person',
      'Today is a sunny day'
    ]
  }
})

Ranking de Texto

Classifique documentos pela sua relevância em relação a uma consulta.

await hf.textRanking({
  model: 'cross-encoder/ettin-reranker-68m-v1',
  inputs: {
    query: 'Which planet is known as the Red Planet?',
    texts: [
      "Venus is often called Earth's twin because of its similar size and proximity.",
      'Mars, known for its reddish appearance, is often referred to as the Red Planet.',
      'Jupiter, the largest planet in our solar system, has a prominent red spot.',
      'Saturn, famous for its rings, is sometimes mistaken for the Red Planet.'
    ]
  }
})

Áudio

Reconhecimento Automático de Fala

Transcreve fala de um arquivo de áudio.

Demonstração

await hf.automaticSpeechRecognition({
  model: 'facebook/wav2vec2-large-960h-lv60-self',
  data: readFileSync('test/sample1.flac')
})

Classificação de Áudio

Atribui rótulos ao áudio fornecido, juntamente com uma pontuação de probabilidade para cada rótulo.

Demonstração

await hf.audioClassification({
  model: 'superb/hubert-large-superb-er',
  data: readFileSync('test/sample1.flac')
})

Texto para Fala

Gera fala com aparência natural a partir de texto de entrada.

Tutorial interativo

await hf.textToSpeech({
  model: 'espnet/kan-bayashi_ljspeech_vits',
  inputs: 'Hello world!'
})

Áudio Para Áudio

Gera um ou vários áudios a partir de um áudio de entrada, comumente usado para aprimoramento de fala e separação de fontes.

await hf.audioToAudio({
  model: 'speechbrain/sepformer-wham',
  data: readFileSync('test/sample1.flac')
})

Visão Computacional

Classificação de Imagens

Atribui rótulos a uma imagem específica, juntamente com uma pontuação de probabilidade para cada rótulo.

Demonstração

await hf.imageClassification({
  data: readFileSync('test/cheetah.png'),
  model: 'google/vit-base-patch16-224'
})

Detecção de Objetos

Detecta objetos em uma imagem e retorna rótulos com as caixas delimitadoras correspondentes e as pontuações de probabilidade.

Demonstração

await hf.objectDetection({
  data: readFileSync('test/cats.png'),
  model: 'facebook/detr-resnet-50'
})

Segmentação de Imagens

Detecta segmentos em uma imagem e retorna rótulos com as caixas delimitadoras correspondentes e as pontuações de probabilidade.

await hf.imageSegmentation({
  data: readFileSync('test/cats.png'),
  model: 'facebook/detr-resnet-50-panoptic'
})

Imagem Para Texto

Gera texto a partir de uma imagem fornecida, comumente usado para legendas ou reconhecimento óptico de caracteres.

await hf.imageToText({
  data: readFileSync('test/cats.png'),
  model: 'nlpconnect/vit-gpt2-image-captioning'
})

Texto para Imagem

Cria uma imagem a partir de um prompt de texto.

Demonstração

await hf.textToImage({
  model: 'black-forest-labs/FLUX.1-dev',
  inputs: 'a picture of a green bird'
})

Imagem para Imagem

Image-to-image é a tarefa de transformar uma imagem de origem para que ela corresponda às características de uma imagem de destino ou de um domínio de imagem de destino.

Tutorial interativo

await hf.imageToImage({
  inputs: new Blob([readFileSync("test/stormtrooper_depth.png")]),
  parameters: {
    prompt: "elmo's lecture",
  },
  model: "lllyasviel/sd-controlnet-depth",
});

Classificação de Imagens Zero Shot

Verifica o quão bem uma imagem de entrada se encaixa em um conjunto de rótulos que você fornece.

await hf.zeroShotImageClassification({
  model: 'openai/clip-vit-large-patch14-336',
  inputs: {
    image: await (await fetch('https://placekitten.com/300/300')).blob()
  },
  parameters: {
    candidate_labels: ['cat', 'dog']
  }
})

Multimodal

Resposta a Perguntas Visuais

Visual Question Answering é a tarefa de responder a perguntas abertas com base em uma imagem. Eles geram respostas em linguagem natural para perguntas em linguagem natural.

Demonstração

await hf.visualQuestionAnswering({
  model: 'dandelin/vilt-b32-finetuned-vqa',
  inputs: {
    question: 'How many cats are lying down?',
    image: await (await fetch('https://placekitten.com/300/300')).blob()
  }
})

Resposta a Perguntas sobre Documentos

Modelos de resposta a perguntas sobre documentos recebem um par (documento, pergunta) como entrada e retornam uma resposta em linguagem natural.

Demonstração

await hf.documentQuestionAnswering({
  model: 'impira/layoutlm-document-qa',
  inputs: {
    question: 'Invoice number?',
    image: await (await fetch('https://huggingface.co/spaces/impira/docquery/resolve/2359223c1837a7587402bda0f2643382a6eefeab/invoice.png')).blob(),
  }
})

Tabular

Regressão Tabular

A regressão tabular é a tarefa de prever um valor numérico dado um conjunto de atributos.

await hf.tabularRegression({
  model: "scikit-learn/Fish-Weight",
  inputs: {
    data: {
      "Height": ["11.52", "12.48", "12.3778"],
      "Length1": ["23.2", "24", "23.9"],
      "Length2": ["25.4", "26.3", "26.5"],
      "Length3": ["30", "31.2", "31.1"],
      "Species": ["Bream", "Bream", "Bream"],
      "Width": ["4.02", "4.3056", "4.6961"]
    },
  },
})

Classificação Tabular

A classificação tabular é a tarefa de classificar uma categoria-alvo (um grupo) com base em um conjunto de atributos.

await hf.tabularClassification({
  model: "vvmnnnkv/wine-quality",
  inputs: {
    data: {
      "fixed_acidity": ["7.4", "7.8", "10.3"],
      "volatile_acidity": ["0.7", "0.88", "0.32"],
      "citric_acid": ["0", "0", "0.45"],
      "residual_sugar": ["1.9", "2.6", "6.4"],
      "chlorides": ["0.076", "0.098", "0.073"],
      "free_sulfur_dioxide": ["11", "25", "5"],
      "total_sulfur_dioxide": ["34", "67", "13"],
      "density": ["0.9978", "0.9968", "0.9976"],
      "pH": ["3.51", "3.2", "3.23"],
      "sulphates": ["0.56", "0.68", "0.82"],
      "alcohol": ["9.4", "9.8", "12.6"]
    },
  },
})

Você pode usar qualquer provedor compatível com a API de Chat Completion com o método chatCompletion.

// Chat Completion Example
const MISTRAL_KEY = process.env.MISTRAL_KEY;
const hf = new InferenceClient(MISTRAL_KEY, {
  endpointUrl: "https://api.mistral.ai",
});
const stream = hf.chatCompletionStream({
  model: "mistral-tiny",
  messages: [{ role: "user", content: "Complete the equation one + one = , just the answer" }],
});
let out = "";
for await (const chunk of stream) {
  if (chunk.choices && chunk.choices.length > 0) {
    out += chunk.choices[0].delta.content;
    console.log(out);
  }
}

Usando Inference Endpoints

Os exemplos que vimos acima usam provedores de inferência. Embora sejam muito úteis para prototipagem e testes rápidos, quando estiver pronto para implantar seu modelo em produção, será necessário usar uma infraestrutura dedicada. É aí que os Inference Endpoints entram em ação. Eles permitem implantar qualquer modelo e expô-lo como uma API privada. Após a implantação, você receberá uma URL para conexão:

import { InferenceClient } from '@huggingface/inference';

const hf = new InferenceClient("hf_xxxxxxxxxxxxxx", {
	endpointUrl: "https://j3z5luu0ooo76jnl.us-east-1.aws.endpoints.huggingface.cloud/v1/",
});

const response = await hf.chatCompletion({
	messages: [
		{
			role: "user",
			content: "What is the capital of France?",
		},
	],
});

console.log(response.choices[0].message.content);

Por padrão, todas as chamadas ao endpoint de inferência aguardam até que o modelo seja carregado. Quando o scaling to 0 está habilitado no endpoint, isso pode resultar em tempos de espera significativos. Se você preferir desabilitar esse comportamento e tratar os erros HTTP 500 retornados pelo endpoint por conta própria, pode fazer o seguinte:

const hf = new InferenceClient("hf_xxxxxxxxxxxxxx", {
	endpointUrl: "https://j3z5luu0ooo76jnl.us-east-1.aws.endpoints.huggingface.cloud/v1/",
});

const response = await hf.chatCompletion(
	{
		messages: [
			{
				role: "user",
				content: "What is the capital of France?",
			},
		],
	},
	{
		retry_on_error: false,
	}
);

Usando endpoints locais

Você pode usar InferenceClient para executar chat completion com servidores de inferência locais (llama.cpp, vllm, litellm server, TGI, mlx, etc.) executando na sua própria máquina. A API deve ser compatível com a OpenAI API.

import { InferenceClient } from '@huggingface/inference';

const hf = new InferenceClient(undefined, {
	endpointUrl: "http://localhost:8080",
});

const response = await hf.chatCompletion({
	messages: [
		{
			role: "user",
			content: "What is the capital of France?",
		},
	],
});

console.log(response.choices[0].message.content);

De forma semelhante ao cliente JS da OpenAI, o InferenceClient pode ser usado para executar inferência de Chat Completion em qualquer endpoint compatível com a API REST da OpenAI.

Executando testes

HF_TOKEN="your access token" pnpm run test

Encontrando modelos adequados

Temos um projeto de documentação informativo chamado Tasks para listar os modelos disponíveis para cada tarefa e explicar em detalhes como cada tarefa funciona.

Ele também contém demonstrações, exemplos de saída e outros recursos, caso você queira se aprofundar mais no lado de ML.

Dependências

@huggingface/tasks : Apenas tipagens

Update on GitHub

←🤗 Bibliotecas JS do Hugging Face Referência da API→