Model downloads from the Hugging Face Hub, into a local cache that later runs, and offline runs, read from: a model by name, as Python's from_pretrained does, with no Python. Compile with -lib gen_collect,cipher,json,net,ai_hub.
HubClient
Downloads files of a Hugging Face model repository into a local cache and gives back their paths: a snapshot folder that TextClassifier and the other pipelines open as they open any model folder.
Each call asks the Hub API which commit the revision ("main" unless named) is at, and downloads from that commit, so every file of a snapshot comes from the same commit. A file already in the cache at the right size is not downloaded again. A downloaded file is checked before it is kept: SHA-256 for a large (LFS) file, the git blob hash for a small one, and the size for both; a file that does not match is deleted and the call fails. Downloads stream to disk, so a file's size is limited only by the disk.
The cache, by environment:
- OBJECK_HUB_CACHE: the cache folder; default .objeck/hub in the user's home folder. The layout is the one Python's huggingface_hub uses -- models--org--name/refs/main holds the commit, models--org--name/snapshots/commit/ the files -- with real files, not symbolic links; - OBJECK_HUB_OFFLINE or HF_HUB_OFFLINE set to 1: no network at all; revisions resolve through the cache's refs. Offline, and when the Hub cannot be reached, a file the cache does not hold is looked for in Python's cache (HF_HUB_CACHE, else HF_HOME/hub, else .cache/huggingface/hub in the home folder), which is read and never written; - OBJECK_HUB_TOKEN or HF_TOKEN: a token for gated and private repositories. It is sent to the Hub only: a redirect to another origin, such as the Hub's file CDN, drops it; - HF_ENDPOINT: another Hub, e.g. a mirror; default https://huggingface.co.
Example
hub := HubClient->New();
folder := hub->Snapshot("Xenova/distilbert-base-uncased-finetuned-sst-2-english",
["config.json", "tokenizer.json", "tokenizer_config.json", "onnx/model.onnx"]);
if(folder = Nil) {
hub->GetError()->ErrorLine();
return;
};
folder->PrintLine(); # .../models--Xenova--distilbert-.../snapshots/0b6928ef...Operations
- New
- Download
- GetCacheDir
- GetCommit
- GetDownloadCount
- GetEndpoint
- GetError
- IsOffline
- SetEndpoint
- SetOffline
- SetToken
- Snapshot
Download #
Downloads one file of a repository at "main".
method : public : Download(repo:String, file:String) ~ StringParameters
| Name | Type | Description |
|---|---|---|
| repo | String | the repository, e.g. Xenova/bert-base-uncased |
| file | String | the file's path in the repository, e.g. onnx/model.onnx |
Return
| Type | Description |
|---|---|
| String | the file's path in the cache; Nil on failure (see GetError) |
Download #
Downloads one file of a repository at a revision.
method : public : Download(repo:String, file:String, revision:String) ~ StringParameters
| Name | Type | Description |
|---|---|---|
| repo | String | the repository, e.g. Xenova/bert-base-uncased |
| file | String | the file's path in the repository, e.g. onnx/model.onnx |
| revision | String | a branch, tag or commit |
Return
| Type | Description |
|---|---|
| String | the file's path in the cache; Nil on failure (see GetError) |
GetCacheDir #
The cache folder.
method : public : GetCacheDir() ~ StringReturn
| Type | Description |
|---|---|
| String | path |
GetCommit #
The commit the last Snapshot or Download used.
method : public : GetCommit() ~ StringReturn
| Type | Description |
|---|---|
| String | a 40-character commit hash, or Nil |
GetDownloadCount #
How many files the last Snapshot or Download fetched from the network; the rest came from the cache.
method : public : GetDownloadCount() ~ IntReturn
| Type | Description |
|---|---|
| Int | files downloaded |
GetEndpoint #
The Hub's address.
method : public : GetEndpoint() ~ StringReturn
| Type | Description |
|---|---|
| String | e.g. https://huggingface.co |
GetError #
Why the last call returned Nil.
method : public : GetError() ~ StringReturn
| Type | Description |
|---|---|
| String | the reason, or Nil |
IsOffline #
Whether the client works from the cache alone.
method : public : IsOffline() ~ BoolReturn
| Type | Description |
|---|---|
| Bool | true when offline |
New # constructor
A client with the cache, token, endpoint and offline mode from the environment.
New()New # constructor
A client with a cache folder of the caller's; token, endpoint and offline mode from the environment.
New(cache_dir:String)Parameters
| Name | Type | Description |
|---|---|---|
| cache_dir | String | the cache folder |
SetEndpoint #
Sets the Hub's address, e.g. a mirror.
method : public : SetEndpoint(endpoint:String) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| endpoint | String | e.g. https://huggingface.co |
SetOffline #
Sets whether the client works from the cache alone.
method : public : SetOffline(offline:Bool) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| offline | Bool | true for no network |
SetToken #
Sets the token sent to the Hub for gated and private repositories; Nil sends none.
method : public : SetToken(token:String) ~ NilParameters
| Name | Type | Description |
|---|---|---|
| token | String | the token |
Snapshot #
Downloads files of a repository at "main" into one snapshot folder.
method : public : Snapshot(repo:String, files:String[]) ~ StringParameters
| Name | Type | Description |
|---|---|---|
| repo | String | the repository, e.g. Xenova/bert-base-uncased |
| files | String | the files' paths in the repository |
Return
| Type | Description |
|---|---|
| String | the snapshot folder; Nil on failure (see GetError) |
Snapshot #
Downloads files of a repository at a revision into one snapshot folder. Every file comes from the commit the revision is at when the call is made.
method : public : Snapshot(repo:String, files:String[], revision:String) ~ StringParameters
| Name | Type | Description |
|---|---|---|
| repo | String | the repository, e.g. Xenova/bert-base-uncased |
| files | String | the files' paths in the repository |
| revision | String | a branch, tag or commit |
Return
| Type | Description |
|---|---|
| String | the snapshot folder; Nil on failure (see GetError) |