# 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](../guides/buckets) 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](../guides/manage-spaces) và [Jobs](../guides/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](/docs/huggingface_hub/main/vi/package_reference/hf_file_system#huggingface_hub.HfFileSystem)) sẽ được phân tích y hệt trong ngữ cảnh khác. [parse_hf_uri()](/docs/huggingface_hub/main/vi/package_reference/hf_uris#huggingface_hub.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](#web-urls) bên dưới. ## Cú pháp URI của HF ```text hf://[/][@][/] ``` | Thành phần | Bắt buộc | Các giá trị được phép | | --------------- | -------- | ------------------------------------------------------------------- | | `hf://` | yes | Tiền tố giao thức Literal. | | `/` | không | `models/`, `datasets/`, `spaces/`, `kernels/`, `buckets/` (số nhiều). | | `` | yes | `/` | | `@` | không | Branch, tag, commit SHA, hoặc ref đặc biệt (`refs/pr/N`, `refs/convert/...`). Chỉ dành cho kho. | | `/` | không | Đường dẫn bên trong kho hoặc bucket. | ## Cú pháp gắn HF ```text hf://[/][@][/]:[:ro|:rw] ``` Một mount là một URI HF được theo sau bởi `:` và một cờ tùy chọn `:ro` / `:rw`. | Thành phần | Bắt buộc | Các giá trị được phép | | --------------- | -------- | ------------------------------------------------------------------- | | `` | yes | Đường dẫn gắn tuyệt đối (phải bắt đầu bằng `/`). | | `:ro` / `:rw` | không | Cờ chỉ đọc / đọc-ghi. | ## URI của HF là gì Dưới đây là **tất cả các URI HF hợp lệ**: ```text # 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): ```text 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**: | URI không hợp lệ | Lý do | | ------------------------------------------------- | ----------------------------------------------------------------------- | | `my-org/my-model`, `./local/path` | Thiếu tiền tố `hf://` và không phải là URL Hugging Face được công nhận. | | `hf://dataset/org/m`, `hf://model/org/m` | Các dạng loại đơn số bị cấm, hãy dùng dạng số nhiều (`datasets/`, ...). | | `hf://datasets`, `hf://buckets/` | Chỉ một tiền tố kiểu không phải là URI hợp lệ, cần có ``. | | `hf://gpt2`, `hf://datasets/squad` | Các kho chính tắc (không có namespace) không được hỗ trợ. | | `hf://buckets/single-segment` | Bucket luôn phải có dạng `namespace/name`. | | `hf://buckets/org/b@v1` | Buckets không hỗ trợ dấu hiệu phiên bản. | | `hf://org/m@`, `hf://datasets/foo/bar@/x` | Phiên bản trống sau `@`. | | `hf://a/b/c@v1` | ID của kho phải có dạng `namespace/name`, các phân đoạn bổ sung là đường dẫn. | | `hf://org/m:/` | Đường dẫn gắn phải là một đường dẫn tuyệt đối không rỗng. | ## URL web Để tiện lợi, [parse_hf_uri()](/docs/huggingface_hub/main/vi/package_reference/hf_uris#huggingface_hub.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, vì vậy bạn có thể dán trực tiếp một URL vào CLI hoặc thư viện và "nó hoạt động ngay": ```python >>> 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: ```python >>> 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. | Chỉ đến | Đường dẫn URL | | -------------------------------------------------------------- | ---------------------------------------------- | | Kho lưu trữ mô hình | `//` | | Kho dữ liệu (tương tự cho `spaces/`, `kernels/`, `models/`) | `/datasets//` | | Thư mục bên trong một kho, được ghim tại `` | `///tree/[/]` | | File trong kho (tuyến trình xem file) | `///blob//` | | File trong kho (tải xuống) | `///resolve//` | | File trong kho (tuyến đường thô) | `///raw//` | | File trong kho (tuyến lỗi) | `///blame//` | | Bucket | `/buckets//` | | File bên trong một bucket (các bucket không được phiên bản hóa) | `/buckets///resolve/` | | Thư mục bên trong một bucket | `/buckets///tree/` | 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. | Lý do | Đường dẫn URL | | -------------------------------------------------------------------------------- | --------------------------------------- | | URL một phân đoạn: trang user/org, trang danh sách, hoặc kho chính thức — không rõ ràng. | `/` | | Trang danh sách, không có `/`. | `/datasets` | | Các kho chính tắc (không có namespace) không được hỗ trợ. | `/gpt2` | | Không phải vị trí tệp/thư mục (tương tự với `commits`, `discussions`, `settings`, …). | `///commit/` | | Bộ sưu tập không phải là kho lưu trữ. | `/collections//` | | Host không phải là host Hugging Face được công nhận. | `https://example.com//` | ## Hiển thị một URL web [HfUri.to_url()](/docs/huggingface_hub/main/vi/package_reference/hf_uris#huggingface_hub.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. ```python >>> 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/`) khi chỉ đặt phiên bản, đến trình xem tệp (`/blob//`, phiên bản mặc định là `main`) cho các tệp trong kho, và đến tuyến cây (`/tree/`) 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()](/docs/huggingface_hub/main/vi/package_reference/hf_uris#huggingface_hub.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](/docs/huggingface_hub/main/vi/package_reference/hf_uris#huggingface_hub.HfUri) bất biến. ```python >>> 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](/docs/huggingface_hub/main/vi/package_reference/hf_uris#huggingface_hub.HfUri) có thể chuyển đổi qua lại thông qua [HfUri.to_uri()](/docs/huggingface_hub/main/vi/package_reference/hf_uris#huggingface_hub.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): ```python >>> 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()](/docs/huggingface_hub/main/vi/package_reference/hf_uris#huggingface_hub.parse_hf_uri) bên trong. ```python >>> 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`: ```python >>> 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[[huggingface_hub.HfUri]] #### huggingface_hub.HfUri[[huggingface_hub.HfUri]] ```python huggingface_hub.HfUri(type: typing.Literal['model', 'dataset', 'space', 'kernel', 'bucket'], id: str, revision: str | None = None, path_in_repo: str = '', _raw: str | None = None) ``` [Nguồn](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_hf_uris.py#L79) **Tham số:** type (`str`) : Một trong các giá trị 'model', 'dataset', 'space', 'kernel' hoặc 'bucket'. id (`str`) : id của kho ('namespace/name', ví dụ 'my-org/my-model') cho các URI kho, hoặc id của bucket ('namespace/name') cho các URI bucket. revision (`str`, *tùy chọn*) : Bản sửa được chỉ định sau '@' trong URI, đã được giải mã URL. 'None' nếu không có bản sửa nào được chỉ định, hoặc đối với các URI bucket (không bao giờ chứa bản sửa). Các tham chiếu đặc biệt như 'refs/pr/10' và 'refs/convert/parquet' được giữ nguyên. path_in_repo (`str`) : Đường dẫn bên trong repo hoặc bucket. Chuỗi rỗng nếu URI trỏ đến gốc. Biểu diễn đã phân tích của URI Hugging Face Hub ('hf://...'). #### to_uri[[huggingface_hub.HfUri.to_uri]] ```python to_uri() ``` [Nguồn](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_hf_uris.py#L137) Hiển thị URI dưới dạng chuỗi 'hf://' chính tắc. Tiền tố kiểu luôn được viết rõ ràng (ví dụ: 'hf://models/my-org/my-model'). #### to_url[[huggingface_hub.HfUri.to_url]] ```python to_url(endpoint: str | None = None) ``` [Nguồn](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_hf_uris.py#L155) **Tham số:** endpoint (`str`, *tùy chọn*) : Endpoint gốc để sử dụng. Mặc định là 'constants.ENDPOINT' (tức là 'https://huggingface.co'). **Trả về:** `str` URL web. Hiển thị URI dưới dạng **URL web** của Hugging Face (loại URL bạn mở trong trình duyệt). Đây là thao tác ngược lại của việc phân tích cú pháp URL bằng [parse_hf_uri()](/docs/huggingface_hub/main/vi/package_reference/hf_uris#huggingface_hub.parse_hf_uri). URL được trả về trỏ đến: - trang chủ của kho / bucket khi chưa đặt đường dẫn hoặc phiên bản; - trình xem thư mục ('/tree/') khi chỉ đặt một phiên bản; - trình xem tệp ('/blob//') cho các tệp trong kho (phiên bản mặc định là 'main'); - tuyến cây ('/tree/') cho các tệp trong bucket (bucket không được phiên bản hóa). Ví dụ: ```py >>> 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' ``` #### huggingface_hub.parse_hf_uri[[huggingface_hub.parse_hf_uri]] ```python huggingface_hub.parse_hf_uri(uri: str, endpoint: str | None = None) ``` **Tham số:** uri (`str`) : URI cần phân tích. Phải bắt đầu bằng 'hf://', hoặc là một URL của Hugging Face (ví dụ: 'https://huggingface.co/...'). endpoint (`str`, *tùy chọn*) : Một endpoint Hub tùy chỉnh (ví dụ: một Hub tự lưu trữ hoặc được proxy như 'https://hub.my-company.com' hoặc 'http://localhost:8080/hf'). Khi được cung cấp, các URL web trên endpoint đó sẽ được nhận diện bên cạnh các host Hugging Face mặc định. Không có tác dụng đối với các URI 'hf://'. **Trả về:** [HfUri](/docs/huggingface_hub/main/vi/package_reference/hf_uris#huggingface_hub.HfUri) URI đã được phân tích. **Gây ra:** `HfUriError` - `HfUriError` -- Nếu URI không hợp lệ (thiếu tiền tố, loại không hợp lệ, thiếu id, tuyến URL không được hỗ trợ, v.v.). Phân tích URI của Hugging Face Hub ('hf://...') hoặc URL web của Hugging Face. Một URI HF là một chuỗi dạng URI xác định một vị trí trên Hugging Face Hub. Ngữ pháp đầy đủ là: ``` hf://[/][@][/] ``` Để tiện lợi, các **đường dẫn web** của Hugging Face (loại bạn sao chép từ trang web) cũng được chấp nhận và chuẩn hóa về dạng 'hf://' chính tắc, ví dụ 'https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv'. Chỉ các URL không gây nhầm lẫn (trang repository / bucket và các route xem tệp/thư mục) mới được chấp nhận; mọi route khác sẽ bị từ chối. Xem 'docs/source/en/package_reference/hf_uris.md' để biết thông số kỹ thuật đầy đủ. Ví dụ: ```py >>> 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') ``` #### huggingface_hub.utils.HfMount[[huggingface_hub.utils.HfMount]] ```python huggingface_hub.utils.HfMount(source: HfUri, mount_path: str, read_only: bool | None = None, _raw: str | None = None) ``` [Nguồn](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_hf_uris.py#L207) **Tham số:** source ([HfUri](/docs/huggingface_hub/main/vi/package_reference/hf_uris#huggingface_hub.HfUri)) : URI HF đã được phân tích, xác định tài nguyên Hub cần gắn (mount). mount_path (`str`) : Đường dẫn gắn cục bộ (luôn bắt đầu bằng '/'). read_only (`bool`, *tuỳ chọn*) : True nếu mount kết thúc bằng ':ro', False nếu kết thúc bằng ':rw', 'None' nếu không có cờ nào được cung cấp. Một URI HF kết hợp với đường dẫn gắn cục bộ và cờ chỉ đọc tùy chọn. Được sử dụng bởi Spaces và Jobs để mô tả các ổ đĩa gắn. Cú pháp đầy đủ là: ``` hf://[/][@][/]:[:ro|:rw] ``` #### to_uri[[huggingface_hub.utils.HfMount.to_uri]] ```python to_uri() ``` [Nguồn](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_hf_uris.py#L238) Hiển thị điểm gắn dưới dạng chuỗi 'hf://' chính tắc. Ví dụ: 'hf://models/my-org/my-model:/data:ro' #### huggingface_hub.utils.parse_hf_mount[[huggingface_hub.utils.parse_hf_mount]] ```python huggingface_hub.utils.parse_hf_mount(mount_str: str) ``` [Nguồn](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_hf_uris.py#L443) **Tham số:** mount_str (`str`) : Chuỗi mount cần phân tích. Bắt buộc phải bắt đầu bằng 'hf://' và chứa đoạn ':'. **Trả về:** `HfMount` điểm gắn đã được phân tích. **Gây ra:** `HfUriError` - `HfUriError` -- Nếu chuỗi mount không hợp lệ (thiếu đường dẫn mount, URI không hợp lệ, v.v.). Phân tích thông số cấu hình gắn HF ('hf://...:[:ro|:rw]'). Một quy định mount là một URI HF theo sau bởi một đường dẫn mount cục bộ và một cờ tùy chọn chỉ đọc/đọc-ghi. Toàn bộ ngữ pháp là: ``` hf://[/][@][/]:[:ro|:rw] ``` Xem 'docs/source/en/package_reference/hf_uris.md' để biết thông số kỹ thuật đầy đủ. Ví dụ: ```py >>> 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) ```