# JS-библиотеки Hugging Face

Это набор JS-библиотек для взаимодействия с Hugging Face API, включая типы TS.

- [@huggingface/hub](hub/README): взаимодействие с huggingface.co для создания или удаления репозиториев, а также коммитирования и загрузки файлов
- [@huggingface/inference](inference/README): используйте все поддерживаемые (serverless) Inference Providers или переключитесь на Inference Endpoints (dedicated), чтобы делать запросы к более чем 100 000 моделей машинного обучения
- [@huggingface/mcp-client](mcp-client/README): клиент Model Context Protocol (MCP) и небольшая библиотека Agent, построенная на базе InferenceClient.
- [@huggingface/gguf](gguf/README): парсер GGUF, работающий с файлами, размещёнными на удалённых хостах.
- [@huggingface/dduf](dduf/README): Аналогичный пакет для DDUF (DDUF Diffusers Unified Format)
- [@huggingface/lerobot](lerobot/README): парсер для наборов данных робототехники LeRobot, читающий структуры v2.x и v3.0 через HTTP-запросы с указанием диапазона.
- [@huggingface/usd-web-viewer](usd-web-viewer/README): веб-просмотрщик OpenUSD: собирает файлы `.usd`, `.usda`, `.usdc` и `.usdz` в WebAssembly и рендерит их с помощью three.js.
- [@huggingface/tasks](tasks/README): файлы определений и источник истины для основных примитивов Hub, таких как задачи pipeline, библиотеки моделей и т. д.
- [@huggingface/jinja](jinja/README): минималистичная реализация шаблонного движка Jinja на JS, предназначенная для использования в ML-шаблонах чатов.
- [@huggingface/space-header](space-header/README): использование Space `mini_header` вне Hugging Face
- [@huggingface/ollama-utils](ollama-utils/README): Различные утилиты для поддержания совместимости Ollama с моделями на Hugging Face Hub.
- [@huggingface/tiny-agents](tiny-agents/README): компактная модельно-независимая библиотека для создания ИИ-агентов, способных использовать инструменты.

Мы используем современные возможности, чтобы избежать полифиллов и зависимостей, поэтому библиотеки будут работать только в современных браузерах / Node.js >= 18 / Bun / Deno.

Библиотеки всё ещё очень молодые, пожалуйста, помогите нам, создавая issues!

## Установка

### Из NPM

Для установки через NPM вы можете скачивать библиотеки по мере необходимости:

```bash
npm install @huggingface/hub
npm install @huggingface/inference
npm install @huggingface/mcp-client
```

Затем импортируйте библиотеки в вашем коде:

```ts
import { createRepo, commit, deleteRepo, listFiles } from "@huggingface/hub";
import { InferenceClient } from "@huggingface/inference";
import { McpClient } from "@huggingface/mcp-client";
import type { RepoId } from "@huggingface/hub";
```

### Из CDN или статического хостинга

Вы можете использовать наши пакеты с обычным JS, без сборщика, с помощью CDN или статического хостинга. С использованием [ES-модулей](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/), то есть `<script type="module">`, вы можете импортировать библиотеки в свой код:

```html
<script type="module">
    import { InferenceClient } from 'https://cdn.jsdelivr.net/npm/@huggingface/inference@4.13.32/+esm';
    import { createRepo, commit, deleteRepo, listFiles } from "https://cdn.jsdelivr.net/npm/@huggingface/hub@2.17.10/+esm";
</script>
```

### Deno

```ts
// esm.sh
import { InferenceClient } from "https://esm.sh/@huggingface/inference"

import { createRepo, commit, deleteRepo, listFiles } from "https://esm.sh/@huggingface/hub"
// or npm:
import { InferenceClient } from "npm:@huggingface/inference"

import { createRepo, commit, deleteRepo, listFiles } from "npm:@huggingface/hub"
```

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

Получите токен доступа HF в [настройках аккаунта](https://huggingface.co/settings/tokens).

### примеры @huggingface/inference

```ts
import { InferenceClient } from "@huggingface/inference";

const HF_TOKEN = "hf_...";

const client = new InferenceClient(HF_TOKEN);

// Chat completion API
const out = await client.chatCompletion({
  model: "meta-llama/Llama-3.1-8B-Instruct",
  messages: [{ role: "user", content: "Hello, nice to meet you!" }],
  max_tokens: 512
});
console.log(out.choices[0].message);

// Streaming chat completion API
for await (const chunk of client.chatCompletionStream({
  model: "meta-llama/Llama-3.1-8B-Instruct",
  messages: [{ role: "user", content: "Hello, nice to meet you!" }],
  max_tokens: 512
})) {
  console.log(chunk.choices[0].delta.content);
}

/// Using a third-party provider:
await client.chatCompletion({
  model: "meta-llama/Llama-3.1-8B-Instruct",
  messages: [{ role: "user", content: "Hello, nice to meet you!" }],
  max_tokens: 512,
  provider: "sambanova", // or together, fal-ai, replicate, cohere …
})

await client.textToImage({
  model: "black-forest-labs/FLUX.1-dev",
  inputs: "a picture of a green bird",
  provider: "fal-ai",
})

// You can also omit "model" to use the recommended model for the task
await client.translation({
  inputs: "My name is Wolfgang and I live in Amsterdam",
  parameters: {
    src_lang: "en",
    tgt_lang: "fr",
  },
});

// pass multimodal files or URLs as inputs
await client.imageToText({
  model: 'nlpconnect/vit-gpt2-image-captioning',
  data: await (await fetch('https://picsum.photos/300/300')).blob(),
})

// Using your own dedicated inference endpoint: https://hf.co/docs/inference-endpoints/
const gpt2Client = client.endpoint('https://xyz.eu-west-1.aws.endpoints.huggingface.cloud/gpt2');
const { generated_text } = await gpt2Client.textGeneration({ inputs: 'The answer to the universe is' });

// Chat Completion
const llamaEndpoint = client.endpoint(
  "/static-proxy?url=https%3A%2F%2Frouter.huggingface.co%2Fhf-inference%2Fmodels%2Fmeta-llama%2FLlama-3.1-8B-Instruct"
);
const out = await llamaEndpoint.chatCompletion({
  model: "meta-llama/Llama-3.1-8B-Instruct",
  messages: [{ role: "user", content: "Hello, nice to meet you!" }],
  max_tokens: 512,
});
console.log(out.choices[0].message);
```

### примеры @huggingface/hub

```ts
import { createRepo, uploadFile, deleteFiles } from "@huggingface/hub";

const HF_TOKEN = "hf_...";

await createRepo({
  repo: "my-user/nlp-model", // or { type: "model", name: "my-user/nlp-test" },
  accessToken: HF_TOKEN
});

await uploadFile({
  repo: "my-user/nlp-model",
  accessToken: HF_TOKEN,
  // Can work with native File in browsers
  file: {
    path: "pytorch_model.bin",
    content: new Blob(...)
  }
});

await deleteFiles({
  repo: { type: "space", name: "my-user/my-space" }, // or "spaces/my-user/my-space"
  accessToken: HF_TOKEN,
  paths: ["README.md", ".gitattributes"]
});
```

### пример @huggingface/mcp-client

```ts
import { Agent } from '@huggingface/mcp-client';

const HF_TOKEN = "hf_...";

const agent = new Agent({
  provider: "auto",
  model: "Qwen/Qwen2.5-72B-Instruct",
  apiKey: HF_TOKEN,
  servers: [
    {
      // Playwright MCP
      command: "npx",
      args: ["@playwright/mcp@latest"],
    },
  ],
});

await agent.loadTools();

for await (const chunk of agent.run("What are the top 5 trending models on Hugging Face?")) {
    if ("choices" in chunk) {
        const delta = chunk.choices[0]?.delta;
        if (delta.content) {
            console.log(delta.content);
        }
    }
}
```

Конечно, есть и другие возможности — загляните в README каждой библиотеки!

## Форматирование и тестирование

```console
sudo corepack enable
pnpm install

pnpm -r format:check
pnpm -r lint:check
pnpm -r test
```

## Сборка

```
pnpm -r build
```

Это сгенерирует файлы ESM и CJS javascript в `packages/*/dist`, например `packages/inference/dist/index.mjs`.