Documentation
¶
Overview ¶
Package hf implements the runtime/classify interfaces against the HuggingFace Inference API.
One Client backs every task interface — audio, text, image, video, embedder — because they all share authentication, retry, and rate limiting. Each interface method routes to the right HF endpoint for the configured model.
Index ¶
- Constants
- Variables
- type Client
- func (c *Client) ClassifyAudio(ctx context.Context, audio []byte, opts classify.AudioOptions) ([]classify.LabelScore, error)
- func (c *Client) ClassifyImage(ctx context.Context, img []byte, opts classify.ImageOptions) ([]classify.LabelScore, error)
- func (c *Client) ClassifyText(ctx context.Context, text string, opts classify.TextOptions) ([]classify.LabelScore, error)
- func (c *Client) Embed(ctx context.Context, inputs []string, opts classify.EmbedOptions) ([][]float32, error)
- type Config
Constants ¶
const DefaultBaseURL = "https://router.huggingface.co/hf-inference"
DefaultBaseURL is the canonical HF Inference API endpoint. HF deprecated the older `api-inference.huggingface.co/models/{id}` URL in favor of the Inference Providers router; `hf-inference` is the provider that serves the same free-tier serverless models. Override via Config.BaseURL for HF Inference Endpoints (dedicated paid hosts) or to pin a different provider (e.g. replicate, fireworks).
Variables ¶
var ErrModelLoading = errors.New("hf: model still loading after retries")
ErrModelLoading is returned when HF reports the model is still warming up after exhausting retries. Eval handlers that see this should produce a skipped result, not a failed one — the model isn't broken, it just hasn't initialized yet.
var ErrModelNotSupported = errors.New("hf: model not supported by the configured inference path")
ErrModelNotSupported is returned when HF rejects the request because the configured model isn't supported on the targeted inference path — typically a retired free-tier audio model on `router.huggingface.co/hf-inference` (HF retired most audio classifiers from serverless in early 2026). Distinct from ErrModelLoading: the model isn't going to become available by waiting. Eval handlers should treat it as Skipped so demos run cleanly when no Inference Endpoint is deployed, rather than failing the scenario.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a HuggingFace Inference API client. It satisfies every task interface in runtime/classify; methods that the configured model doesn't support fail at call time with an HF error, not at construction.
func (*Client) ClassifyAudio ¶
func (c *Client) ClassifyAudio( ctx context.Context, audio []byte, opts classify.AudioOptions, ) ([]classify.LabelScore, error)
ClassifyAudio submits raw audio bytes to the HF Inference API audio-classification endpoint for the configured model. Audio preparation (resampling to 16 kHz mono WAV, etc.) is the caller's responsibility — the handler upstream knows the source format from message metadata and converts before calling.
HF returns `[{"label": "...", "score": ...}, ...]` sorted by descending score; we pass that order through.
func (*Client) ClassifyImage ¶
func (c *Client) ClassifyImage( ctx context.Context, img []byte, opts classify.ImageOptions, ) ([]classify.LabelScore, error)
ClassifyImage submits image bytes to the HF image-classification endpoint. Same response shape as audio (flat [{label, score}] array).
func (*Client) ClassifyText ¶
func (c *Client) ClassifyText( ctx context.Context, text string, opts classify.TextOptions, ) ([]classify.LabelScore, error)
ClassifyText submits text to the HF text-classification endpoint. HF returns nested arrays — `[[{label, score}, ...]]` — one inner array per input. We send one input so the outer array has length 1; flattening returns the inner labels directly.
func (*Client) Embed ¶
func (c *Client) Embed( ctx context.Context, inputs []string, opts classify.EmbedOptions, ) ([][]float32, error)
Embed turns text inputs into dense float32 vectors. HF's feature- extraction endpoint returns one vector per input — either as a flat float array for a single input or a nested array for a batch. We always send a list and unmarshal the batch shape so callers see a uniform `[][]float32`.
Some HF embedding models (sentence-transformers) return per-token embeddings as `[[[float]]]` (batch × tokens × dims) and require the caller to mean-pool. The MVP only supports models that already return one vector per input; per-token responses surface as a decode error.
type Config ¶
type Config struct {
// APIKey is the HF token. Falls back to HF_TOKEN /
// HUGGING_FACE_HUB_TOKEN env vars in the factory wrapper; bare
// Client construction requires the caller to pass it.
APIKey string
// BaseURL overrides DefaultBaseURL. Used for HF Inference
// Endpoints (e.g. https://my-endpoint.xxx.endpoints.huggingface.cloud)
// and the Inference Providers routing layer.
BaseURL string
// Dedicated, when true, treats BaseURL as a fully-specified
// inference endpoint and skips the /models/{model_id} suffix
// that the public Inference API requires. Set this when pointing
// at HF Inference Endpoints (the paid dedicated host shape).
// Default false matches the public Inference API.
Dedicated bool
// HTTPClient lets the caller provide a custom transport (test
// httptest server, timeouts, retry middleware). Default
// is a 60s-timeout client.
HTTPClient *http.Client
}
Config holds construction parameters for Client.
Source Files