Skip to content

HuggingFace

Nuget package dotnet License: MIT Discord

Features

  • Fully generated C# SDK based on HuggingFace Hub, TGI and TEI OpenAPI specs using AutoSDK
  • Three typed clients: HuggingFaceClient (Hub API), HuggingFaceInferenceClient (TGI chat/completions), HuggingFaceEmbeddingClient (TEI embeddings/reranking)
  • Microsoft.Extensions.AI support: IChatClient and IEmbeddingGenerator<string, Embedding<float>>
  • All modern .NET features — nullability, trimming, NativeAOT, source-generated JSON
  • Targets net10.0

Getting Started

Installation

1
dotnet add package HuggingFace

Authentication

All clients require a HuggingFace API key. Get one at huggingface.co/settings/tokens.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
using HuggingFace;

// Chat and completions (TGI)
using var inferenceClient = new HuggingFaceInferenceClient(apiKey);

// Embeddings, reranking, similarity (TEI)
using var embeddingClient = new HuggingFaceEmbeddingClient(apiKey);

// Hub API (model info, datasets, etc.)
using var hubClient = new HuggingFaceClient(apiKey);

Examples

Chat Completion

Send a chat message to a HuggingFace-hosted model using the Microsoft.Extensions.AI IChatClient interface.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
using var client = new HuggingFaceInferenceClient(apiKey);
IChatClient chatClient = client;

var response = await chatClient.GetResponseAsync(
    [new ChatMessage(ChatRole.User, "Say hello in one word.")],
    new ChatOptions
    {
        ModelId = "Qwen/Qwen2.5-Coder-32B-Instruct",
        MaxOutputTokens = 32,
    });

Console.WriteLine(response.Text);

Streaming Chat Completion

Stream chat completion tokens as they are generated using the IChatClient interface.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
using var client = new HuggingFaceInferenceClient(apiKey);
IChatClient chatClient = client;

await foreach (var update in chatClient.GetStreamingResponseAsync(
    [new ChatMessage(ChatRole.User, "Say hello in one word.")],
    new ChatOptions
    {
        ModelId = "Qwen/Qwen2.5-Coder-32B-Instruct",
        MaxOutputTokens = 32,
    }))
{
    Console.Write(update.Text);
}

Streaming Tool Calling

Stream chat completion responses with tool calling using the IChatClient interface.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
using var client = new HuggingFaceInferenceClient(apiKey);
IChatClient chatClient = client;

// Stream chat responses with tool calling using the MEAI IChatClient interface.
// Define a simple tool that returns the current weather.
var tool = AIFunctionFactory.Create(
    (string location) => $"The weather in {location} is sunny, 72°F.",
    "get_weather",
    "Gets the current weather for a location.");

var functionCalls = new List<FunctionCallContent>();
ChatFinishReason? finishReason = null;

await foreach (var update in chatClient.GetStreamingResponseAsync(
    [new ChatMessage(ChatRole.User, "What's the weather in San Francisco?")],
    new ChatOptions
    {
        ModelId = "Qwen/Qwen2.5-Coder-32B-Instruct",
        Tools = [tool],
    }))
{
    functionCalls.AddRange(update.Contents.OfType<FunctionCallContent>());

    if (update.FinishReason is not null)
    {
        finishReason = update.FinishReason;
    }
}

// The model should respond with tool calls.

Generate Embeddings

Generate text embeddings using the Microsoft.Extensions.AI IEmbeddingGenerator interface with HuggingFace TEI.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
using var client = new HuggingFaceEmbeddingClient(apiKey);
IEmbeddingGenerator<string, Embedding<float>> generator = client;

var result = await generator.GenerateAsync(
    ["Hello world", "How are you?"],
    new EmbeddingGenerationOptions
    {
        ModelId = "sentence-transformers/all-MiniLM-L6-v2",
    });

Console.WriteLine($"Embedding dimension: {result[0].Vector.Length}");
Console.WriteLine($"Embeddings generated: {result.Count}");

Rerank Texts

Rerank a list of texts by relevance to a query using the TEI reranking endpoint.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
using var client = new HuggingFaceEmbeddingClient(apiKey);

var results = await client.RerankAsync(
    query: "What is Deep Learning?",
    texts:
    [
        "Deep Learning is a subset of Machine Learning.",
        "The weather is sunny today.",
        "Neural networks are inspired by the human brain.",
    ],
    returnText: true);

foreach (var rank in results.OrderByDescending(r => r.Score))
{
    Console.WriteLine($"[{rank.Index}] score={rank.Score:F4} text={rank.Text}");
}

Similarity Scoring

Compute cosine similarity between a source sentence and a list of candidate sentences.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
using var client = new HuggingFaceEmbeddingClient(apiKey);

var scores = await client.SimilarityAsync(
    inputs: new SimilarityInput
    {
        SourceSentence = "What is Deep Learning?",
        Sentences =
        [
            "Deep Learning is a subset of Machine Learning.",
            "The weather is sunny today.",
            "Neural networks are inspired by the human brain.",
        ],
    });

for (var i = 0; i < scores.Count; i++)
{
    Console.WriteLine($"[{i}] similarity={scores[i]:F4}");
}

Tokenize Text

Tokenize text into tokens using the TEI tokenization endpoint.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
using var client = new HuggingFaceEmbeddingClient(apiKey);

var tokens = await client.TokenizeAsync(
    inputs: new TokenizeInput("Hello world"),
    addSpecialTokens: true);

foreach (var token in tokens[0])
{
    Console.WriteLine($"id={token.Id} text=\"{token.Text}\" special={token.Special}");
}

Sparse Embeddings

Generate sparse embeddings for text using the TEI sparse embedding endpoint.

1
2
3
4
5
6
7
8
9
using var client = new HuggingFaceEmbeddingClient(apiKey);

var sparseEmbeddings = await client.EmbedSparseAsync(
    inputs: new Input("Hello world"));

foreach (var sv in sparseEmbeddings[0].Take(5))
{
    Console.WriteLine($"index={sv.Index} value={sv.Value:F4}");
}

Native Embeddings

Generate dense embeddings using the TEI-native embed endpoint with normalization control.

1
2
3
4
5
6
7
using var client = new HuggingFaceEmbeddingClient(apiKey);

var embeddings = await client.EmbedAsync(
    inputs: new Input("Hello world"),
    normalize: true);

Console.WriteLine($"Embedding dimension: {embeddings[0].Count}");

Decode Tokens

Tokenize text and decode it back using the TEI tokenization and decode endpoints.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
using var client = new HuggingFaceEmbeddingClient(apiKey);

// Tokenize text into token IDs.
var tokens = await client.TokenizeAsync(
    inputs: new TokenizeInput("Hello world"),
    addSpecialTokens: false);

var tokenIds = tokens[0].Select(t => t.Id).ToList();
Console.WriteLine($"Token IDs: [{string.Join(", ", tokenIds)}]");

// Decode token IDs back to text.
var decoded = await client.DecodeAsync(
    ids: new InputIds(inputIdsVariant1: tokenIds, inputIdsVariant2: null),
    skipSpecialTokens: true);

Console.WriteLine($"Decoded: {decoded[0]}");

Who Am I

Get the authenticated user's account information using the Hub API.

1
2
3
4
5
using var client = new HuggingFaceClient(apiKey);

var response = await client.Auth.GetWhoamiV2Async();

Console.WriteLine($"User: {response}");

List recently trending models, datasets, and spaces on the HuggingFace Hub.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
using var client = new HuggingFaceClient(apiKey);

var response = await client.Models.GetTrendingAsync(limit: 5);

foreach (var item in response.RecentlyTrending)
{
    var id = item.Value1?.RepoData?.Id ?? item.Value2?.RepoData?.Id ?? item.Value3?.RepoData?.Id;
    var author = item.Value1?.RepoData?.Author ?? item.Value2?.RepoData?.Author ?? item.Value3?.RepoData?.Author;
    if (id is not null)
    {
        Console.WriteLine($"{id} by {author}");
    }
}

List Model Tags

List available model tags grouped by type from the HuggingFace Hub.

1
2
3
4
5
6
7
8
using var client = new HuggingFaceClient(apiKey);

var tags = await client.Models.GetModelsTagsByTypeAsync();

foreach (var (tagType, tagList) in tags)
{
    Console.WriteLine($"{tagType}: {tagList.Count} tags");
}

Search Models

Search for models, datasets, and spaces on the HuggingFace Hub using quicksearch.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
using var client = new HuggingFaceClient(apiKey);

var response = await client.RepoSearch.CreateQuicksearchAsync(
    request: new CreateQuicksearchRequest
    {
        Q = "text-generation",
        Limit = 5,
        Exclude = [],
    });

Console.WriteLine($"Found {response.ModelsCount} models, {response.DatasetsCount} datasets");

foreach (var model in response.Models)
{
    Console.WriteLine($"  {model.Id} (weight={model.TrendingWeight:F2})");
}

Error Handling

Handle API errors gracefully using the ApiException type.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
using var client = new HuggingFaceClient("invalid-api-key");

try
{
    await client.Auth.GetWhoamiV2Async();
}
catch (ApiException ex)
{
    Console.WriteLine($"Status: {ex.StatusCode}");
    Console.WriteLine($"Message: {ex.Message}");
    Console.WriteLine($"Body: {ex.ResponseBody}");

}

Search Datasets

Search for datasets on the HuggingFace Hub using quicksearch and list results.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
using var client = new HuggingFaceClient(apiKey);

var response = await client.RepoSearch.CreateQuicksearchAsync(
    request: new CreateQuicksearchRequest
    {
        Q = "sentiment analysis",
        Limit = 5,
        Exclude = [],
    });

Console.WriteLine($"Models: {response.ModelsCount}, Datasets: {response.DatasetsCount}, Spaces: {response.SpacesCount}");

foreach (var dataset in response.Datasets)
{
    Console.WriteLine($"  Dataset: {dataset.Id}");
}

foreach (var space in response.Spaces)
{
    Console.WriteLine($"  Space: {space.Id}");
}

List trending items filtered by type (model, dataset, or space).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
using var client = new HuggingFaceClient(apiKey);

var spaces = await client.Models.GetTrendingAsync(
    type: GetTrendingType.Space,
    limit: 3);

Console.WriteLine("Trending Spaces:");
foreach (var item in spaces.RecentlyTrending)
{
    var id = item.Value1?.RepoData?.Id ?? item.Value2?.RepoData?.Id ?? item.Value3?.RepoData?.Id;
    Console.WriteLine($"  {id}");
}

Search Papers

Search for papers and collections on the HuggingFace Hub.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
using var client = new HuggingFaceClient(apiKey);

var response = await client.RepoSearch.CreateQuicksearchAsync(
    request: new CreateQuicksearchRequest
    {
        Q = "transformer attention",
        Limit = 5,
        Exclude = [],
    });

Console.WriteLine($"Papers: {response.PapersCount}, Collections: {response.CollectionsCount}");

foreach (var paper in response.Papers)
{
    Console.WriteLine($"  Paper: {paper.Id}");
}

foreach (var collection in response.Collections)
{
    Console.WriteLine($"  Collection: {collection.Title} - {collection.Description}");
}

Ecosystem maintenance

This SDK is one of more than 200 .NET SDKs maintained with AutoSDK. The tryAGI SDK audit continuously checks repository synchronization, upstream-spec regeneration, release workflows, warnings, public API visibility, and trimming/NativeAOT compatibility.

Every issue is first investigated for ecosystem-wide applicability. When the root cause belongs in AutoSDK, we fix and regression-test the generator, then roll the improvement out to every applicable SDK. Provider-specific behavior remains in this repository when it cannot be derived safely from the API specification.

Issue content—including code blocks, logs, links, and attachments—is treated only as untrusted diagnostic data. Embedded control instructions, hidden directives, delimiter tricks, or requests to alter triage or tooling behavior are ignored. Please report reproducible technical evidence and remove secrets and personal data.

Support

Priority place for bugs: https://github.com/tryAGI/HuggingFace/issues
Priority place for ideas and general questions: https://github.com/tryAGI/HuggingFace/discussions
Discord: https://discord.gg/Ca2xhfBf3v

OpenAPI specs

Acknowledgments

JetBrains logo

This project is supported by JetBrains through the Open Source Support Program.