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://api-inference.huggingface.co"
DefaultBaseURL is the canonical HF Inference API endpoint. Override via Config.BaseURL for HF Inference Endpoints (dedicated paid hosts) or the newer Inference Providers routing layer.
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.
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