Hugging Face's logo

Huggingface.js documentation

🤗 Hugging Face Inference

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

🤗 Hugging Face Inference

Обёртка на Typescript, предоставляющая единый интерфейс для запуска инференса на нескольких сервисах для моделей, размещённых на Hugging Face Hub:

  1. Поставщики инференса: упрощённый и единый доступ к сотням моделей машинного обучения, обеспечиваемый нашими партнёрами по serverless-инференсу. Этот новый подход развивает наш предыдущий Serverless Inference API, предлагая больше моделей, улучшенную производительность и повышенную надёжность благодаря поставщикам мирового уровня. Список поддерживаемых поставщиков приведён в документации.
  2. Inference Endpoints: продукт для простого развёртывания моделей в продакшене. Вывод выполняется Hugging Face на выделенной полностью управляемой инфраструктуре на облачном провайдере по вашему выбору.
  3. Локальные конечные точки: вы также можете выполнять инференс с помощью локальных серверов инференса, таких как llama.cpp, Ollama, vLLM, LiteLLM или Text Generation Inference (TGI), подключив клиент к этим локальным конечным точкам.

Начало работы

Установка

Узел

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";

Инициализация

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

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

❗Важное примечание: Всегда передавайте токен доступа. Присоединяйтесь к Hugging Face, а затем перейдите на страницу access tokens, чтобы бесплатно сгенерировать свой токен доступа.

Ваш токен доступа следует хранить в секрете. Если вам необходимо защитить его во фронтенд-приложениях, мы рекомендуем настроить прокси-сервер, который будет хранить токен доступа.

Использование провайдеров инференса

Вы можете отправлять запросы на инференс сторонним провайдерам с помощью inference-клиента.

В настоящее время мы поддерживаем следующих провайдеров:

Чтобы отправлять запросы стороннему провайдеру, необходимо передать параметр provider в функцию инференса. Значение по умолчанию для параметра provider — “auto”, что означает выбор первого доступного для модели провайдера из списка, отсортированного в соответствии с вашим предпочтительным порядком на 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"
})

Также необходимо убедиться, что ваш запрос аутентифицирован с помощью токена доступа. При аутентификации с помощью токена доступа Hugging Face запрос маршрутизируется через https://huggingface.co. При аутентификации с помощью ключа стороннего провайдера запрос отправляется напрямую в API инференса этого провайдера.

Поддержка сторонних провайдеров распространяется только на часть моделей. Список поддерживаемых моделей для задач конвейеров можно найти здесь:

❗Важное примечание: Для обеспечения совместимости сторонний API должен соответствовать «стандартному» формату API, который мы ожидаем на страницах моделей HF для каждого типа задачи пайплайна. Для LLM это не проблема, так как все в итоге сошлись на API OpenAI, но для других задач, таких как «text-to-image» или «automatic-speech-recognition», где стандартный API отсутствует, ситуация может быть сложнее. Сообщите нам, если требуется помощь или если мы можем упростить вам задачу!

👋Хотите добавить другого провайдера? Свяжитесь с нами, если вы хотите добавить поддержку другого провайдера Inference, и/или создайте запрос на https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49

Tree-shaking

Вы можете импортировать нужные функции непосредственно из модуля, а не использовать класс InferenceClient.

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

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

Это позволит вашему сборщику выполнять tree-shaking.

Обработка ошибок

Пакет для инференса предоставляет специфические типы ошибок, чтобы вы могли эффективно обрабатывать различные сценарии ошибок.

Типы ошибок

Пакет определяет несколько типов ошибок, расширяющих базовый класс Error:

  • InferenceClientError: базовый класс ошибок для всех ошибок Hugging Face Inference
  • InferenceClientInputError: выбрасывается, если возникают проблемы с параметрами ввода
  • InferenceClientProviderApiError: выбрасывается при ошибках на уровне API от провайдеров
  • InferenceClientHubApiError: выбрасывается при ошибках на уровне API от Hugging Face Hub
  • InferenceClientProviderOutputError: выбрасывается, если с форматом ответов API провайдеров возникают проблемы

Пример использования

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

Детали ошибки

InferenceClientProviderApiError

Эта ошибка возникает при проблемах с запросом к API во время выполнения инференса у выбранного провайдера.

У него есть несколько свойств:

  • message: Описательное сообщение об ошибке
  • httpRequest: сведения об ошибочном запросе (URL, метод, заголовки)
  • httpResponse: сведения об ответе, включая код состояния и тело

InferenceClientHubApiError

Эта ошибка возникает при проблемах с запросом к API при обращении к API Hugging Face Hub.

У него есть несколько свойств:

  • message: Описательное сообщение об ошибке
  • httpRequest: сведения об ошибочном запросе (URL, метод, заголовки)
  • httpResponse: сведения об ответе, включая код состояния и тело

InferenceClientProviderOutputError

Эта ошибка возникает, когда провайдер возвращает ответ в неожиданном формате.

InferenceClientInputError

Эта ошибка возникает, если параметры ввода недействительны или отсутствуют. Сообщение об ошибке описывает, что именно не так с входными данными.

Обработка естественного языка

Генерация текста

Генерирует текст на основе входного запроса.

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

Завершение чата

Сгенерировать ответ модели на основе списка сообщений, составляющих диалог.

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

Извлечение признаков

Эта задача принимает на вход текст и выводит необработанные значения типа float, которые обычно используются в составе семантической базы данных или семантического поиска.

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

Заполнение маски

Пытается заполнить пропуск отсутствующим словом (точнее, токеном).

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

Суммаризация

Сжимает длинный текст в более короткий. Обратите внимание, что у некоторых моделей есть максимальная длина входных данных.

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

Вопросно-ответные системы

Отвечает на вопросы на основе предоставленного вами контекста.

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

Ответы на вопросы по таблицам

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

Классификация текста

Часто используемый для анализа тональности, этот метод присваивает заданному тексту метки вместе с вероятностной оценкой каждой метки.

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

Классификация токенов

Используется для разбора предложений, грамматического или распознавания именованных сущностей (NER), чтобы понять ключевые слова, содержащиеся в тексте.

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

Перевод

Преобразует текст с одного языка на другой.

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

Классификация без обучения

Проверяет, насколько хорошо входной текст соответствует набору меток, который вы предоставляете.

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

Сходство предложений

Вычислите семантическое сходство между одним текстом и списком других предложений.

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

Ранжирование текста

Ранжируйте документы по их релевантности запросу.

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

Аудио

Распознавание речи

Транскрибирует речь из аудиофайла.

Демо

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

Классификация аудио

Присваивает метки заданному аудио вместе с вероятностной оценкой для каждой метки.

Демо

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

Синтез речи

Генерирует естественную речь из текстового ввода.

Интерактивный учебник

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

Аудио в аудио

Генерирует один или несколько аудиосигналов на основе входного аудио; обычно используется для улучшения качества речи и разделения источников.

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

Компьютерное зрение

Классификация изображений

Присваивает метки заданному изображению вместе с вероятностной оценкой для каждой метки.

Демо

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

Обнаружение объектов

Определяет объекты на изображении и возвращает метки с соответствующими ограничивающими рамками и оценками вероятности.

Демо

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

Сегментация изображений

Определяет сегменты внутри изображения и возвращает метки с соответствующими ограничивающими рамками и оценками вероятности.

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

Изображение в текст

Выводит текст из заданного изображения, обычно используется для создания подписей или оптического распознавания символов.

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

Текст в изображение

Создаёт изображение по текстовому запросу.

Демо

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

Изображение в изображение

Image-to-image — это задача преобразования исходного изображения так, чтобы оно соответствовало характеристикам целевого изображения или целевой области изображений.

Интерактивный учебник

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

Классификация изображений без обучения

Проверяет, насколько хорошо входное изображение соответствует набору меток, который вы предоставляете.

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

Мультимодальность

Ответы на визуальные вопросы

Visual Question Answering — это задача, в которой модель отвечает на открытые вопросы, основываясь на изображении. Она генерирует ответы на естественном языке в ответ на вопросы, заданные на естественном языке.

Демо

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

Ответы на вопросы по документам

Модели документного вопросно-ответного типа принимают на вход пару (документ, вопрос) и возвращают ответ на естественном языке.

Демо

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

Табличные

Регрессия на табличных данных

Табличная регрессия — это задача предсказания числового значения по набору атрибутов.

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

Классификация табличных данных

Табличная классификация — это задача классификации целевой категории (группы) на основе набора атрибутов.

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

Вы можете использовать любого провайдера, совместимого с Chat Completion API, с методом 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);
  }
}

Использование конечных точек вывода

Приведённые выше примеры используют провайдеры инференса. Хотя они очень полезны для прототипирования и быстрого тестирования, при переходе к развёртыванию модели в продакшене потребуется выделенная инфраструктура. Именно здесь на помощь приходят Inference Endpoints. Они позволяют развернуть любую модель и опубликовать её как приватный API. После развёртывания вы получите URL, к которому можно подключиться:

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

По умолчанию все вызовы inference endpoint ожидают, пока модель не будет загружена. Если для endpoint включено scaling to 0, это может привести к значительному времени ожидания. Если вы предпочитаете отключить это поведение и самостоятельно обрабатывать возвращаемые endpoint ошибки HTTP 500, вы можете сделать это следующим образом:

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

Использование локальных конечных точек

Вы можете использовать InferenceClient для выполнения chat completion с локальными серверами инференса (llama.cpp, vllm, litellm server, TGI, mlx и т. д.), работающими на вашем компьютере. API должен быть совместим с 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);

Аналогично клиенту OpenAI JS, InferenceClient можно использовать для выполнения инференса Chat Completion с любым эндпоинтом, совместимым с REST API OpenAI.

Запуск тестов

HF_TOKEN="your access token" pnpm run test

Поиск подходящих моделей

У нас есть информативный проект документации под названием Tasks, в котором перечислены доступные модели для каждой задачи и подробно описано, как работает каждая из них.

Он также содержит демонстрации, примеры результатов и другие ресурсы, если вы хотите углубиться в машинное обучение.

Зависимости

  • @huggingface/tasks : только типизация
Update on GitHub

←🤗 Библиотеки Hugging Face на JS Справочник API→