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

Un wrapper basado en Typescript que proporciona una interfaz unificada para ejecutar inferencia en múltiples servicios para modelos alojados en el Hugging Face Hub:

Proveedores de inferencia: un acceso unificado y simplificado a cientos de modelos de aprendizaje automático, impulsado por nuestros socios de inferencia serverless. Este nuevo enfoque se basa en nuestra anterior API de inferencia serverless, ofreciendo más modelos, un rendimiento mejorado y una mayor fiabilidad gracias a proveedores de primer nivel. Consulta la documentación para obtener una lista de los proveedores compatibles.
Inference Endpoints: un producto para desplegar modelos en producción de forma sencilla. La inferencia se ejecuta en Hugging Face en una infraestructura dedicada y totalmente gestionada en un proveedor de nube de su elección.
Puntos finales locales: también puede ejecutar inferencia con servidores de inferencia locales como llama.cpp, Ollama, vLLM, LiteLLM o Text Generation Inference (TGI) conectando el cliente a estos puntos finales locales.

Primeros pasos

Instalación

Nodo

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');

❗Nota importante: Pasa siempre un token de acceso. Únete a Hugging Face y luego visita access tokens para generar tu token de acceso gratis.

Debes mantener tu token de acceso en privado. Si necesitas protegerlo en aplicaciones de front-end, te sugerimos configurar un servidor proxy que almacene el token de acceso.

Uso de proveedores de inferencia

Puede enviar solicitudes de inferencia a proveedores de terceros con el cliente de inferencia.

Actualmente, admitimos los siguientes proveedores:

Para enviar solicitudes a un proveedor de terceros, debe pasar el parámetro provider a la función de inferencia. El valor predeterminado del parámetro provider es “auto”, que seleccionará el primero de los proveedores disponibles para el modelo, ordenados según su preferencia en 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"
})

También debe asegurarse de que su solicitud esté autenticada con un token de acceso. Cuando se autentica con un token de acceso de Hugging Face, la solicitud se enruta a través de https://huggingface.co. Cuando se autentica con una clave de un proveedor de terceros, la solicitud se realiza directamente contra la API de inferencia de ese proveedor.

Solo se admite un subconjunto de modelos al solicitar proveedores de terceros. Puede consultar la lista de modelos admitidos por tareas de pipeline aquí:

❗Nota importante: Para ser compatible, la API de terceros debe cumplir con la forma de API “estándar” que esperamos en las páginas de modelos de HF para cada tipo de tarea de pipeline. Esto no es un problema para los LLM, ya que todos convergieron en la API de OpenAI de todos modos, pero puede ser más complicado para otras tareas como “text-to-image” o “automatic-speech-recognition”, donde no existe una API estándar. ¡Avísenos si necesitan ayuda o si podemos facilitarles las cosas!

👋¿Quieres añadir otro proveedor? Ponte en contacto si deseas añadir soporte para otro proveedor de Inference y/o solicítalo en https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49

Tree-shaking

Puedes importar las funciones que necesitas directamente del módulo en lugar de usar la clase InferenceClient.

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

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

Esto habilitará el tree-shaking en su bundler.

Gestión de errores

El paquete de inferencia proporciona tipos de error específicos para ayudarte a manejar diferentes escenarios de error de manera efectiva.

Tipos de error

El paquete define varios tipos de error que extienden la clase base Error:

InferenceClientError: Clase de error base para todos los errores de Hugging Face Inference
InferenceClientInputError: Se lanza cuando hay problemas con los parámetros de entrada
InferenceClientProviderApiError: Se lanza cuando hay errores a nivel de API de los proveedores
InferenceClientHubApiError: Se lanza cuando hay errores a nivel de API desde Hugging Face Hub
InferenceClientProviderOutputError: Se lanza cuando hay problemas con el formato de las respuestas de la API de los proveedores

Ejemplo 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);
  }
}

Detalles del error

InferenceClientProviderApiError

Este error ocurre cuando hay problemas con la solicitud de API al realizar inferencia en el proveedor seleccionado.

Tiene varias propiedades:

message: un mensaje de error descriptivo
httpRequest: Detalles sobre la solicitud fallida (URL, método, encabezados)
httpResponse: Detalles de la respuesta, incluidos el código de estado y el cuerpo

InferenceClientHubApiError

Este error ocurre cuando hay problemas con la solicitud de la API al solicitar la API de Hugging Face Hub.

Tiene varias propiedades:

message: un mensaje de error descriptivo
httpRequest: Detalles sobre la solicitud fallida (URL, método, encabezados)
httpResponse: Detalles de la respuesta, incluidos el código de estado y el cuerpo

InferenceClientProviderOutputError

Este error se produce cuando un proveedor devuelve una respuesta en un formato inesperado.

InferenceClientInputError

Este error ocurre cuando los parámetros de entrada son inválidos o faltan. El mensaje de error describe qué hay de incorrecto en la entrada.

Procesamiento del Lenguaje Natural

Generación de texto

Genera texto a partir de un 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);
}

Completación de chat

Genera una respuesta del modelo a partir de una lista de mensajes que componen una conversación.

// 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;
  }
}

Extracción de características

Esta tarea lee algún texto y genera valores flotantes crudos, que normalmente se consumen como parte de una base de datos semántica o una búsqueda semántica.

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

Rellenar máscara

Intenta rellenar un hueco con una palabra faltante (un token, para ser precisos).

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

Resumen

Resume textos más largos en textos más cortos. Ten en cuenta que algunos modelos tienen una longitud máxima 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
  }
})

Question Answering

Responde preguntas basándose en el contexto que proporciones.

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

Preguntas y respuestas sobre tablas

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']
    }
  }
})

Clasificación de texto

A menudo utilizado para el análisis de sentimiento, este método asignará etiquetas al texto proporcionado junto con una puntuación de probabilidad para cada etiqueta.

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

Clasificación de tokens

Se utiliza para el análisis de oraciones, ya sea gramatical o de reconocimiento de entidades nombradas (NER), para comprender las palabras clave contenidas en el 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'
})

Traducción

Convierte texto de un idioma a otro.

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

Clasificación Zero-Shot

Comprueba qué tan bien encaja un texto de entrada en un conjunto de etiquetas que proporciones.

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'] }
})

Similitud de oraciones

Calcule la similitud semántica entre un texto y una lista de otras oraciones.

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'
    ]
  }
})

Clasificación de texto

Rankear documentos según su relevancia para una 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.'
    ]
  }
})

Audio

Reconocimiento automático del habla

Transcribe el habla desde un archivo de audio.

Demo

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

Clasificación de audio

Asigna etiquetas al audio proporcionado junto con una puntuación de probabilidad para cada etiqueta.

Demo

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

Texto a voz

Genera un habla natural a partir de texto de entrada.

Tutorial interactivo

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

Audio a Audio

Genera uno o varios audios a partir de un audio de entrada, utilizado comúnmente para la mejora de voz y la separación de fuentes.

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

Visión por computador

Clasificación de imágenes

Asigna etiquetas a una imagen dada junto con una puntuación de probabilidad de esa etiqueta.

Demo

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

Detección de objetos

Detecta objetos dentro de una imagen y devuelve etiquetas con las cajas delimitadoras correspondientes y las puntuaciones de probabilidad.

Demo

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

Segmentación de imágenes

Detecta segmentos dentro de una imagen y devuelve etiquetas con las cajas delimitadoras y las puntuaciones de probabilidad correspondientes.

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

Imagen a texto

Genera texto a partir de una imagen dada, utilizado comúnmente para la creación de descripciones o el reconocimiento óptico de caracteres.

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

Texto a imagen

Crea una imagen a partir de un prompt de texto.

Demo

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

Imagen a imagen

Image-to-image es la tarea de transformar una imagen de origen para que coincida con las características de una imagen de destino o de un dominio de imagen de destino.

Tutorial interactivo

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

Clasificación de imágenes sin ejemplos

Comprueba qué tan bien encaja una imagen de entrada en un conjunto de etiquetas que proporcionas.

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

Visual Question Answering

Visual Question Answering es la tarea de responder preguntas abiertas basándose en una imagen. Generan respuestas en lenguaje natural a preguntas en lenguaje natural.

Demo

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

Document Question Answering

Los modelos de respuesta a preguntas sobre documentos toman como entrada un par (documento, pregunta) y devuelven una respuesta en lenguaje natural.

Demo

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

Regresión tabular

La regresión tabular es la tarea de predecir un valor numérico a partir de un 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"]
    },
  },
})

Clasificación de datos tabulares

La clasificación tabular es la tarea de clasificar una categoría objetivo (un grupo) en función de un 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"]
    },
  },
})

Puede utilizar cualquier proveedor compatible con la API de Chat Completion con el 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);
  }
}

Uso de puntos de inferencia

Los ejemplos que vimos arriba usan proveedores de inferencia. Si bien resultan muy útiles para prototipar y probar cosas rápidamente, cuando estés listo para desplegar tu modelo en producción, necesitarás usar una infraestructura dedicada. Ahí es donde entra Inference Endpoints. Te permite desplegar cualquier modelo y exponerlo como una API privada. Una vez desplegado, obtendrás una URL a la que puedes conectarte:

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 defecto, todas las llamadas al punto de inferencia esperan hasta que el modelo se carga. Cuando scaling to 0 está habilitado en el punto de inferencia, esto puede resultar en un tiempo de espera no trivial. Si prefiere deshabilitar este comportamiento y manejar usted mismo los errores HTTP 500 devueltos por el punto de inferencia, puede hacerlo de la siguiente manera:

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,
	}
);

Uso de puntos finales locales

Puede usar InferenceClient para ejecutar la finalización de chat con servidores de inferencia local (llama.cpp, vllm, litellm server, TGI, mlx, etc.) que se ejecutan en su propia máquina. La API debe ser compatible con la API de OpenAI.

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 manera similar al cliente JS de OpenAI, InferenceClient se puede usar para ejecutar inferencia de Chat Completion con cualquier endpoint compatible con la API REST de OpenAI.

Ejecutar pruebas

HF_TOKEN="your access token" pnpm run test

Encontrar modelos adecuados

Contamos con un proyecto de documentación informativo llamado Tasks que enumera los modelos disponibles para cada tarea y explica en detalle cómo funciona cada una.

También contiene demostraciones, ejemplos de resultados y otros recursos por si deseas profundizar en el lado de la ML.

Dependencias

@huggingface/tasks : Solo tipado

Update on GitHub

←🤗 Librerías JS de Hugging Face Referencia de la API→