HF URIs

URI HF là một chuỗi dạng URI xác định một vị trí trên Hugging Face Hub. Trong thư viện và CLI, các chuỗi hf://... được dùng để trỏ đến:

• một kho lưu trữ mô hình, bộ dữ liệu, không gian hoặc kernel (tuỳ chọn cố định tại một phiên bản);
• một tệp hoặc thư mục con bên trong kho lưu trữ như vậy;
• một bucket hoặc một thư mục con bên trong bucket.

Một HF mount bao bọc một URI của HF với một đường dẫn gắn cục bộ và một cờ tùy chọn :ro / :rw, được sử dụng bởi các volume của Spaces và Jobs.

Trang này tài liệu hóa cú pháp chuẩn của URI HF và các điểm gắn HF. Trình phân tích (parser) giống nhau được sử dụng ở mọi nơi trong thư viện, do đó một URI hợp lệ trong ngữ cảnh này (ví dụ HfFileSystem) sẽ được phân tích y hệt trong ngữ cảnh khác.

parse_hf_uri() cũng chấp nhận URL web của Hugging Face (ví dụ: https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv) để bạn có thể sao chép và dán liên kết từ trang web. Xem URL web bên dưới.

Cú pháp URI của HF

hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]

Cú pháp gắn HF

hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]:<MOUNT_PATH>[:ro|:rw]

Một mount là một URI HF được theo sau bởi :<MOUNT_PATH> và một cờ tùy chọn :ro / :rw.

URI của HF là gì

Dưới đây là tất cả các URI HF hợp lệ:

# Models (type prefix is optional, but the id is always 'namespace/name')
hf://my-org/my-model                            # implicit type prefix
hf://models/my-org/my-model                     # explicit type prefix
hf://models/my-org/my-model/config.json         # file inside a model repo
hf://models/my-org/my-model@v1.0/config.json    # pinned to a revision

# Datasets, Spaces, Kernels (type prefix is required)
hf://datasets/my-org/my-dataset
hf://datasets/my-org/my-dataset@dev/train.csv
hf://spaces/my-user/my-space
hf://kernels/my-org/my-kernel

# Special revisions (preserved as-is)
hf://datasets/my-org/my-dataset@refs/pr/10/data.csv
hf://datasets/my-org/my-dataset@refs/convert/parquet/data.parquet

# Buckets (always 'namespace/name', no revision)
hf://buckets/my-org/my-bucket
hf://buckets/my-org/my-bucket/sub/folder

Dưới đây là các điểm gắn HF hợp lệ (các thông số cấu hình volume):

hf://my-org/my-model:/data
hf://datasets/my-org/my-dataset:/mnt:ro
hf://datasets/my-org/my-dataset/train:/mnt:rw    # mount a sub-folder
hf://buckets/my-org/my-bucket:/storage:rw

Điều gì không phải là URI của HF

Trình phân tích được thiết kế chặt chẽ một cách có chủ đích. Các trường hợp sau sẽ bị từ chối:

URL web

Để tiện lợi, parse_hf_uri() cũng chấp nhận các URL web của Hugging Face mà bạn sao chép từ trình duyệt. Chúng được chuẩn hóa về dạng hf:// chính thức, nên bạn có thể dán trực tiếp URL vào CLI hoặc thư viện và “nó hoạt động ngay”:

>>> from huggingface_hub import parse_hf_uri
>>> parse_hf_uri("https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv")
HfUri(type='dataset', id='my-org/my-dataset', revision='main', path_in_repo='train.csv')

Các URL từ huggingface.co (cùng với tên miền rút gọn hf.co, máy chủ staging và máy chủ của HF_ENDPOINT tùy chỉnh) được nhận diện, có hoặc không kèm theo lược đồ https://. Chuỗi truy vấn (?download=true) và phần tử (#L10) bị bỏ qua.

Để phân tích cú pháp một URL từ một bản triển khai Hub khác (ví dụ: Hub tự lưu trữ hoặc được proxy), hãy truyền URL gốc của nó dưới dạng endpoint. Khi đó, host của nó sẽ được nhận diện bên cạnh các host mặc định, và một tiền tố đường dẫn (ví dụ: http://localhost:8080/hf) sẽ bị loại bỏ trước khi phân tích:

>>> parse_hf_uri("https://hub.my-company.com/datasets/my-org/my-dataset", endpoint="https://hub.my-company.com")
HfUri(type='dataset', id='my-org/my-dataset', revision=None, path_in_repo='')

Các định dạng URL được hỗ trợ

Bảng dưới đây liệt kê các route được hỗ trợ. Để ngắn gọn, chỉ hiển thị đường dẫn URL (phần sau host, ví dụ huggingface.co); host được nhận dạng là ngầm hiểu.

Phiên bản được lấy từ đoạn duy nhất ngay sau blob/resolve/raw/tree/blame. Các ref đặc biệt (refs/pr/N, refs/convert/...) được khớp ngay lập tức mặc dù chúng chứa /; bất kỳ tên branch/tag nào khác chứa / đều phải được mã hóa URL (feature%2Ffoo).

Các URL không được phân tích

Khi một URL mơ hồ hoặc không trỏ đến một vị trí cụ thể trên Hub, nó sẽ bị từ chối (không bao giờ đoán):

Các đường dẫn bên dưới một lần nữa được hiển thị không kèm host, ngoại trừ hàng cuối cùng, nơi chính host là lý do cho việc từ chối.

Hiển thị một URL web

HfUri.to_url() là hàm ngược của việc phân tích cú pháp URL: nó hiển thị URL web có thể duyệt được cho một URI HF.

>>> uri = parse_hf_uri("hf://datasets/my-org/my-dataset@v1/train.csv")
>>> uri.to_url()
'https://huggingface.co/datasets/my-org/my-dataset/blob/v1/train.csv'

Nó trỏ đến trang chính của kho / bucket khi chưa đặt đường dẫn hoặc phiên bản, đến trình xem thư mục (/tree/<rev>) khi chỉ đặt phiên bản, đến trình xem tệp (/blob/<rev>/<path>, phiên bản mặc định là main) cho các tệp trong kho, và đến tuyến cây (/tree/<path>) cho các tệp trong bucket. Các ký tự đặc biệt trong đường dẫn (khoảng trắng, #, …) được mã hóa phần trăm. Truyền endpoint=... để nhắm đến một host tùy chỉnh.

Phân tích cú pháp trong Python

Phân tích URI

parse_hf_uri() là trình phân tích URI tập trung. Đây là trình phân tích chuỗi thuần túy (không có các cuộc gọi mạng) và trả về dataclass HfUri bất biến.

>>> from huggingface_hub import parse_hf_uri
>>> parse_hf_uri("hf://datasets/my-org/my-dataset@refs/pr/3/train.json")
HfUri(type='dataset', id='my-org/my-dataset', revision='refs/pr/3', path_in_repo='train.json')

HfUri có thể chuyển đổi qua lại thông qua HfUri.to_uri(), hàm này luôn xuất ra dạng chuẩn (có tiền tố kiểu rõ ràng):

>>> uri = parse_hf_uri("hf://my-org/my-model@v1/config.json")
>>> uri.to_uri()
'hf://models/my-org/my-model@v1/config.json'

Sử dụng trực tiếp các trường type và id. Các thuộc tính boolean is_repo và is_bucket giúp phân biệt giữa URI của repository và URI của bucket khi cần.

Phân tích các điểm gắn

parse_hf_mount phân tích một thông số mount (một HF URI kèm đường dẫn mount cục bộ và cờ tùy chọn :ro/:rw) và trả về một dataclass HfMount bất biến. Hàm này sử dụng parse_hf_uri() bên trong.

>>> from huggingface_hub.utils import parse_hf_mount
>>> parse_hf_mount("hf://buckets/my-org/my-bucket/sub/dir:/mnt:ro")
HfMount(source=HfUri(type='bucket', id='my-org/my-bucket', revision=None, path_in_repo='sub/dir'), mount_path='/mnt', read_only=True)

HfMount có thể chuyển đổi qua lại thông qua HfMount.to_uri:

>>> mount = parse_hf_mount("hf://my-org/my-model:/data:ro")
>>> mount.to_uri()
'hf://models/my-org/my-model:/data:ro'

Tham khảo

>>> from huggingface_hub import parse_hf_uri
>>> parse_hf_uri("hf://datasets/my-org/my-dataset@v1/train.csv").to_url()
'https://huggingface.co/datasets/my-org/my-dataset/blob/v1/train.csv'

hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]

>>> from huggingface_hub.utils import parse_hf_uri
>>> parse_hf_uri("hf://my-org/my-model")
HfUri(type='model', id='my-org/my-model', revision=None, path_in_repo='')
>>> parse_hf_uri("hf://datasets/my-org/my-dataset@refs/pr/3/train.json")
HfUri(type='dataset', id='my-org/my-dataset', revision='refs/pr/3', path_in_repo='train.json')
>>> parse_hf_uri("https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv")
HfUri(type='dataset', id='my-org/my-dataset', revision='main', path_in_repo='train.csv')

hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]:<MOUNT_PATH>[:ro|:rw]

hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]:<MOUNT_PATH>[:ro|:rw]

>>> from huggingface_hub.utils import parse_hf_mount
>>> parse_hf_mount("hf://my-org/my-model:/data:ro")
HfMount(source=HfUri(type='model', id='my-org/my-model', revision=None, path_in_repo=''), mount_path='/data', read_only=True)
>>> parse_hf_mount("hf://buckets/my-org/my-bucket/sub/dir:/mnt:rw")
HfMount(source=HfUri(type='bucket', id='my-org/my-bucket', revision=None, path_in_repo='sub/dir'), mount_path='/mnt', read_only=False)