Skip to main content
View as MarkdownOpen in ChatGPTOpen in Claude

HuggingFace Provider

HuggingFace's Router exposes an OpenAI Responses-API-compatible endpoint (https://router.huggingface.co/v1/responses) that proxies to open-source models hosted across HuggingFace's Inference Providers. This is the only API the Go SDK's HuggingFace provider talks to — it mirrors @ai-sdk/huggingface.

The HuggingFace Router Responses API does not offer text embeddings or image generation. EmbeddingModel/ImageModel return an error; use the HuggingFace Inference API directly for those.

Setup​

Installation​

import (
    "github.com/digitallysavvy/go-ai/pkg/ai"
    "github.com/digitallysavvy/go-ai/pkg/providers/huggingface"
)

Configuration​

provider := huggingface.New(huggingface.Config{
    APIKey: os.Getenv("HUGGINGFACE_API_KEY"), // falls back to this env var if empty
})

model, err := provider.LanguageModel("deepseek-ai/DeepSeek-V3-0324")

Get API Key​

  1. Sign up at huggingface.co
  2. Create a token in settings
  3. Set the environment variable:
export HUGGINGFACE_API_KEY=hf_...

Example​

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/digitallysavvy/go-ai/pkg/ai"
    "github.com/digitallysavvy/go-ai/pkg/providers/huggingface"
)

func main() {
    provider := huggingface.New(huggingface.Config{
        APIKey: os.Getenv("HUGGINGFACE_API_KEY"),
    })

    model, err := provider.LanguageModel("deepseek-ai/DeepSeek-V3-0324")
    if err != nil {
        log.Fatal(err)
    }

    result, err := ai.GenerateText(context.Background(), ai.GenerateTextOptions{
        Model:  model,
        Prompt: "Explain transformers",
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text)
}

Streaming (ai.StreamText) uses the Responses API's real Server-Sent Events stream — text, reasoning, tool-call, and source deltas are emitted as they arrive rather than being chunked after the fact.

Tool calls, reasoning, and sources​

The Responses API returns tool calls (function_call), MCP tool calls/lists (mcp_call, mcp_list_tools), reasoning blocks, and URL citation sources alongside text. The Go SDK surfaces all of these through the standard ai.GenerateTextResult/ai.StreamTextResult content and tool-call APIs.

Provider Options​

result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model:  model,
    Prompt: "...",
    ProviderOptions: map[string]interface{}{
        "huggingface": map[string]interface{}{
            "metadata":         map[string]interface{}{"key": "value"},
            "instructions":     "Be concise",
            "strictJsonSchema": true,
            "reasoningEffort":  "high",
        },
    },
})

Available Models​

The Responses API accepts any model ID listed at router.huggingface.co/v1/models, including:

Model IDBest For
meta-llama/Llama-3.3-70B-InstructGeneral purpose
deepseek-ai/DeepSeek-V3-0324General purpose
deepseek-ai/DeepSeek-R1Reasoning
Qwen/Qwen3-Coder-480B-A35B-InstructCoding
moonshotai/Kimi-K2-InstructGeneral purpose

Workflow Serialization​

HuggingFace language models can cross a workflow boundary with providerutils.SerializeModel / DeserializeModel. See Provider Serialization for the mechanism.

See Also​