Configure Hugging Face with Nexus

Configure Hugging Face with Nexus

Tip
Some files in Hugging Face model repositories may have filename extensions that do not match their actual content type. When strict content validation is enabled, Nexus Repository rejects these files. If you encounter a content type mismatch error, such as 404 Detected content type [image/png], but expected [image/jpeg], disable Strict Content Validation for the affected proxy repository.

Configure the Hugging Face client to connect to and authenticate with a Nexus Hugging Face proxy repository. Note that you must create a Hugging Face proxy repository in Nexus before configuring your Hugging Face client. Refer to Create a Hugging Face Repository for more details.

Environment Variables

Configure your Hugging Face client using environment variables to point to your Nexus repository.

Basic Configuration

export HF_ENDPOINT="http://<nexus-host>/repository/<repo-name>"

Where,

Example:

export HF_ENDPOINT="http://example.nexus.com/repository/huggingface-proxy"

Configuration with Authentication

For repositories requiring authentication, include credentials in the URL:

export HF_ENDPOINT="http://<token>:<password>@<nexus-host>/repository/<repo-name>"

Where,

Example:

export HF_ENDPOINT="http://myuser:mypassword@example.nexus.com/repository/huggingface-proxy"

Sonatype recommends using usertoken name code and usertoken pass code instead of username/password. Navigate to Account → User Token → Access User Token → Authenticate to access your user token.

Timeout Configuration

Hugging Face models can be large, requiring increased timeout values.

Variable Purpose Recommended Value
HF_HUB_DOWNLOAD_TIMEOUT Download timeout in seconds 120 or higher
HF_HUB_ETAG_TIMEOUT ETag timeout in seconds 1800

Example:

export HF_HUB_DOWNLOAD_TIMEOUT=120
export HF_HUB_ETAG_TIMEOUT=1800

Retry Timeout for Large Files

You may experience timeout errors on the client side for larger models as model files are not retrieved by the client until they are cached in Nexus Repository. Retry download after a couple of minutes and increase the retry timeout:

export HF_HUB_DOWNLOAD_TIMEOUT=300

Disable XET Support

Nexus Repository does not support XET yet. (Extended Execution Time). Disable XET when using Hugging Face clients:

export HF_HUB_DISABLE_XET=1

Python Client Configuration

For Python clients using huggingface_hub, you can pass timeout parameters directly to function calls.

snapshot_download with Timeout

from huggingface_hub import snapshot_download
snapshot_download(repo_id="microsoft/OmniParser", repo_type="model", local_dir="/Users/Documents/hugging", etag_timeout=900)

Where,

Transformers and Diffusers Configuration

Set timeout for transformers and diffusers libraries with custom HTTP backend:

from diffusers import StableDiffusionPipeline
from huggingface_hub import configure_http_backend
from requests.adapters import HTTPAdapter
from requests import Session
from urllib3.util.retry import Retry
 
timeout = 900
session = Session()
retries = Retry(total=5, backoff_factor=0.5, status_forcelist=[500, 502, 503, 504])
 
class TimeoutHTTPAdapter(HTTPAdapter):
    def __init__(self, *args, **kwargs):
        self.timeout = kwargs.pop("timeout", timeout)
        super().__init__(*args, **kwargs)

def send(self, request, **kwargs):
        kwargs["timeout"] = self.timeout
        return super().send(request, **kwargs)

adapter = TimeoutHTTPAdapter(max_retries=retries, timeout=timeout)
session.mount("https://", adapter)
session.mount("http://", adapter)
 
def get_custom_session():
    return session

configure_http_backend(get_custom_session)
pipeline = StableDiffusionPipeline.from_pretrained("CompVis/stable-diffusion-v1-4")

Header Authorization (Alternative Method)

You can also configure authentication through base64 encoded token.

import base64
import os
from huggingface_hub import snapshot_download

base64_token = base64.b64encode("<token_user>:<token_pass>".encode('utf-8')).decode('utf-8')
headers = {"Authorization": f"Basic {base64_token}"}
model_path = snapshot_download(repo_id="repo_id", repo_type="model", endpoint=os.environ["HF_ENDPOINT"], headers=headers)

Where,

Bearer Token Authentication

Nexus Repository can issue a Hugging Face Bearer token for an authenticated Nexus user. The user must have read permission for the target Hugging Face repository. See Realms for more details.

Activate Hugging Face Bearer Token Realm

Take the following steps for self-hosted Nexus Repository:

  1. Navigate to Settings → Security → Realms.
  2. Move HuggingFace Bearer Token Realm (HuggingFaceToken) to the Active list.
  3. Select Save.

Sonatype manages security realm configuration for Sonatype Cloud deployments.

Obtain the Token

Use the following command to obtain the bearer token:

curl -u <username>:<password> \
  https://<nexus-host>/repository/<repo-name>/api/token

Where,

The response returns the Hugging Face token in the following format:

{"token":"HuggingFaceToken.<opaque>"}

Use the Token

Use Bearer token authentication for huggingface-cli login and hf auth login workflows. Paste the obtained token response when prompted or use it directly in HTTP requests.

curl -H "Authorization: Bearer HuggingFaceToken.<opaque>" \
  https://<nexus-host>/repository/<repo-name>/api/whoami-v2

Where,

Note
The /api/token endpoint is a Nexus Repository–specific convenience endpoint and has no equivalent in the Hugging Face API. As a result, scripts written for the native Hugging Face API are not directly compatible with Nexus Repository and must be modified to use the /api/token endpoint instead.