# Hugging Face JS kütüphaneleri

Bu, TS tipleri dahil olmak üzere Hugging Face API'siyle etkileşime girmek için kullanılan JS kütüphanelerinin bir koleksiyonudur.

- [@huggingface/hub](hub/README): huggingface.co ile etkileşime girerek depolar oluşturmak veya silmek ve dosyaları commit / indirmek
- [@huggingface/inference](inference/README): Desteklenen tüm (sunucusuz) Inference Providers'ı kullanın veya 100.000'den fazla Makine Öğrenimi modeline çağrılar yapmak için Inference Endpoints'e (özel) geçin
- [@huggingface/mcp-client](mcp-client/README): InferenceClient üzerine inşa edilmiş bir Model Context Protocol (MCP) istemcisi ve küçük bir Agent kütüphanesi.
- [@huggingface/gguf](gguf/README): Uzaktan barındırılan dosyalar üzerinde çalışan bir GGUF ayrıştırıcısı.
- [@huggingface/dduf](dduf/README): DDUF (DDUF Diffusers Unified Format) için benzer bir paket
- [@huggingface/lerobot](lerobot/README): LeRobot robotik veri kümeleri için bir ayrıştırıcı; aralıklı HTTP istekleri üzerinden v2.x ve v3.0 yerleşimlerini okur.
- [@huggingface/usd-web-viewer](usd-web-viewer/README): Web için bir OpenUSD görüntüleyici: `.usd`, `.usda`, `.usdc` ve `.usdz` dosyalarını WebAssembly ile birleştirir ve three.js ile render eder.
- [@huggingface/tasks](tasks/README): Hub'un pipeline görevleri, model kütüphaneleri gibi ana yapı taşlarının tanım dosyaları ve tek doğruluk kaynağı.
- [@huggingface/jinja](jinja/README): ML sohbet şablonları için kullanılacak, Jinja şablonlama motorunun minimal bir JS uygulaması.
- [@huggingface/space-header](space-header/README): Hugging Face dışında `mini_header` bileşenini kullanın
- [@huggingface/ollama-utils](ollama-utils/README): Hugging Face Hub'daki modellerle Ollama uyumluluğunu korumak için çeşitli yardımcılar.
- [@huggingface/tiny-agents](tiny-agents/README): Araçları kullanabilen yapay zeka ajanları oluşturmak için küçük, model bağımsız bir kütüphane.

Polyfill ve bağımlılıklardan kaçınmak için modern özellikler kullanıyoruz; bu nedenle kütüphaneler yalnızca modern tarayıcılarda / Node.js >= 18 / Bun / Deno üzerinde çalışır.

Kütüphaneler hâlâ çok yeni, lütfen sorunlar açarak bize yardımcı olun!

## Kurulum

### NPM'den

NPM üzerinden yüklemek için kütüphaneleri ihtiyaç duydukça indirebilirsiniz:

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

Ardından kodunuzda kütüphaneleri içe aktarın:

```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 veya Statik barındırma üzerinden

Paketlerimizi, bir derleyici (bundler) kullanmadan, bir CDN veya statik barındırma ile saf JS üzerinde çalıştırabilirsiniz. [ES modülleri](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/)ni, yani `<script type="module">` etiketini kullanarak, kütüphaneleri kodunuza içe aktarabilirsiniz:

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

## Kullanım örnekleri

HF erişim tokeninizi [hesap ayarlarınızda](https://huggingface.co/settings/tokens) edinin.

### @huggingface/inference örnekleri

```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(
  "https://router.huggingface.co/hf-inference/models/meta-llama/Llama-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 örnekleri

```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 örneği

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

Elbette daha fazla özellik var, her kütüphanenin README dosyasını kontrol edin!

## Biçimlendirme ve test

```console
sudo corepack enable
pnpm install

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

## Derleme

```
pnpm -r build
```

Bu işlem, `packages/*/dist` içinde ESM ve CJS javascript dosyaları oluşturur; örneğin `packages/inference/dist/index.mjs`.