v0.15.1: InferenceClient and background uploads!

InferenceClient

We introduce InferenceClient, a new client to run inference on the Hub. The objective is to:

• support both InferenceAPI and Inference Endpoints services in a single client.
• offer a nice interface with:
  • 1 method per task (e.g. summary = client.summarization("this is a long text"))
  • 1 default model per task (i.e. easy to prototype)
  • explicit and documented parameters
  • convenient binary inputs (from url, path, file-like object,...)
• be flexible and support custom requests if needed

Check out the Inference guide to get a complete overview.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()

>>> image = client.text_to_image("An astronaut riding a horse on the moon.")
>>> image.save("astronaut.png")

>>> client.image_classification("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg")
[{'score': 0.9779096841812134, 'label': 'Blenheim spaniel'}, ...]

The short-term goal is to add support for more tasks (here is the current list), especially text-generation and handle asyncio calls. The mid-term goal is to deprecate and replace InferenceAPI.

• Enhanced InferenceClient by @Wauplin in #1474

Non-blocking uploads

It is now possible to run HfApi calls in the background! The goal is to make it easier to upload files periodically without blocking the main thread during a training. The was previously possible when using Repository but is now available for HTTP-based methods like upload_file, upload_folder and create_commit. If run_as_future=True is passed:

• the job is queued in a background thread. Only 1 worker is spawned to ensure no race condition. The goal is NOT to speed up a process by parallelizing concurrent calls to the Hub.
• a Future object is returned to check the job status
• main thread is not interrupted, even if an exception occurs during the upload

In addition to this parameter, a run_as_future(...) method is available to queue any other calls to the Hub. More details in this guide.

>>> from huggingface_hub import HfApi

>>> api = HfApi()
>>> api.upload_file(...)  # takes Xs
# URL to upload file

>>> future = api.upload_file(..., run_as_future=True) # instant
>>> future.result() # wait until complete
# URL to upload file

• Run HfApi methods in the background (run_as_future) by @Wauplin in #1458
• fix docs for run_as_future by @Wauplin (direct commit on main)

Breaking changes

Some (announced) breaking changes have been introduced:

• list_models, list_datasets and list_spaces return an iterable instead of a list (lazy-loading of paginated results)
• The parameter cardData in list_datasets has been removed in favor of the parameter full.

Both changes had a deprecation cycle for a few releases now.

• Remove deprecated code + adapt tests by @Wauplin in #1450

Bugfixes and small improvements

Token permission

New parameters in login() :

• new_session : skip login if new_session=False and user is already logged in
• write_permission : write permission is required (login fails otherwise)

Also added a new HfApi().get_token_permission() method that returns "read" or "write" (or None if not logged in).

• Add new_session, write_permission args by @aliabid94 in #1476

List files with details

New parameter to get more details when listing files: list_repo_files(..., expand=True).
API call is slower but lastCommit and security fields are returned as well.

• Add expand parameter to list_repo_files by @Wauplin in #1451

Docs fixes

• Resolve broken link to 'filesystem' by @tomaarsen in #1461
• Fix broken link in docs to hf_file_system guide by @albertvillanova in #1469
• Remove hffs from docs by @albertvillanova in #1468

Misc

• Fix consistency check when downloading a file by @Wauplin in #1449
• Fix discussion URL on datasets and spaces by @Wauplin in #1465
• FIX user agent not passed in snapshot_download by @Wauplin in #1478
• Avoid ImportError when importing WebhooksServer and Gradio is not installed by @mariosasko in #1482
• add utf8 encoding when opening files for windows by @abidlabs in #1484
• Fix incorrect syntax in _deprecation.py warning message for _deprecate_list_output() by @x11kjm in #1485
• Update _hf_folder.py by @SimonKitSangChu in #1487
• fix pause_and_restart test by @Wauplin (direct commit on main)
• Support image-to-image task in InferenceApi by @Wauplin in #1489