- 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:
IChatClientandIEmbeddingGenerator<string, Embedding<float>> - All modern .NET features — nullability, trimming, NativeAOT, source-generated JSON
- Targets net10.0
dotnet add package HuggingFaceAll clients require a HuggingFace API key. Get one at huggingface.co/settings/tokens.
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);Send a chat message to a HuggingFace-hosted model using the Microsoft.Extensions.AI IChatClient interface.
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);Stream chat completion tokens as they are generated using the IChatClient interface.
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);
}Generate text embeddings using the Microsoft.Extensions.AI IEmbeddingGenerator interface with HuggingFace TEI.
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 a list of texts by relevance to a query using the TEI reranking endpoint.
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}");
}Compute cosine similarity between a source sentence and a list of candidate sentences.
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 into tokens using the TEI tokenization endpoint.
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}");
}Generate sparse embeddings for text using the TEI sparse embedding endpoint.
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}");
}Generate dense embeddings using the TEI-native embed endpoint with normalization control.
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}");Tokenize text and decode it back using the TEI tokenization and decode endpoints.
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]}");Get the authenticated user's account information using the Hub API.
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.
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 available model tags grouped by type from the HuggingFace Hub.
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 for models, datasets, and spaces on the HuggingFace Hub using quicksearch.
using var client = new HuggingFaceClient(apiKey);
var response = await client.RepoSearch.CreateQuicksearchAsync(
request: new Request45
{
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})");
}Handle API errors gracefully using the ApiException type.
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 for datasets on the HuggingFace Hub using quicksearch and list results.
using var client = new HuggingFaceClient(apiKey);
var response = await client.RepoSearch.CreateQuicksearchAsync(
request: new Request45
{
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).
using var client = new HuggingFaceClient(apiKey);
var spaces = await client.Models.GetTrendingAsync(
type: Type5.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 for papers and collections on the HuggingFace Hub.
using var client = new HuggingFaceClient(apiKey);
var response = await client.RepoSearch.CreateQuicksearchAsync(
request: new Request45
{
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}");
}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.
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
- Serverless Inference OpenAPI spec - (Can't find the link)
- Local Text Generation Inference OpenAPI spec
- Local Text Embeddings Inference OpenAPI spec
- Inference Endpoints (dedicated) OpenAPI spec
This project is supported by JetBrains through the Open Source Support Program.