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(value1: tokenIds, value2: 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}");
}

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.