HF URIs

يُعدّ معرّف URI الخاص بـ HF سلسلةً تشبه URI تحدد موقعًا على Hugging Face Hub. في جميع أنحاء المكتبة وأداة سطر الأوامر، تُستخدم سلاسل hf://... للإشارة إلى:

• مستودع نموذج أو مجموعة بيانات أو مساحة أو نواة (مع إمكانية التثبيت عند إصدار محدد بشكل اختياري)؛
• ملف أو مجلد فرعي داخل مستودع من هذا النوع؛
• a bucket or a sub-folder inside a bucket.

يُغلّف HF mount عنوان URI الخاص بـ HF مع مسار تثبيت محلي وعلامة اختيارية :ro / :rw، وتُستخدم هذه العلامة في أحجام Spaces وJobs.

توثّق هذه الصفحة الصياغة القياسية لمعرّفات HF URI والجبال HF. يُستخدم نفس المُحلِّل في جميع أنحاء المكتبة، لذا فإن أي URI صالح في سياق واحد (مثل HfFileSystem) يُحلَّل بنفس الطريقة في سياق آخر.

يقبل parse_hf_uri() أيضًا روابط ويب من Hugging Face (مثل https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv) بحيث يمكنك نسخ رابط من الموقع ولصقه. راجع روابط الويب أدناه.

صياغة URI الخاصة بـ HF

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

HF mount syntax

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

المُثبّت هو URI خاص بـ HF يتبعه :<MOUNT_PATH> وعلامة اختيارية :ro / :rw.

ما هو URI الخاص بـ HF

ما يلي هي جميع URIs الصالحة لـ HF:

# 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

ما يلي هي وحدات HF الصالحة (مواصفات الأحجام):

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

ما ليس URI لـ HF

المحلل صارم عمداً. ما يلي مرفوض:

عناوين ويب

للسهولة، يقبل parse_hf_uri() أيضاً عناوين ويب الخاصة بـ Hugging Face التي تنسخها وتلصقها من متصفحك. يتم تطبيعها إلى الصيغة القياسية hf://، لذا يمكنك لصق عنوان URL مباشرة في سطر الأوامر أو المكتبة و«يعمل الأمر ببساطة»:

>>> 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')

تُعرَّف العناوين من huggingface.co (ومجاله المختصر hf.co، ومضيف المرحلة التجريبية، ومضيف HF_ENDPOINT المخصص) سواءً مع بروتوكول https:// أو بدونه. وتُتجاهل سلاسل الاستعلام (?download=true) والمقتطفات (#L10).

لتحليل عنوان URL من نشر آخر لمنصة Hub (مثل النشر الذاتي أو عبر وكيل)، مرر عنوانه الأساسي كـendpoint. يتم بعد ذلك التعرف على مضيفه بالإضافة إلى المضيفين الافتراضيين، ويُستبعد بادئة المسار (مثل http://localhost:8080/hf) قبل التحليل:

>>> 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='')

صيغ عناوين URL المدعومة

تُدرج الجدول أدناه المسارات المدعومة. ولإيجاز الأمر، يُعرض مسار URL فقط (الجزء الذي يلي المضيف، مثل huggingface.co)؛ ويُفهم المضيف المعترف به ضمناً.

يُستخلص التعديل من الجزء الفردي الذي يلي مباشرةً blob/resolve/raw/tree/blame. تُطابَق المراجع الخاصة (refs/pr/N، refs/convert/...) بحماس حتى وإن احتوت على /؛ أما أي اسم فرع/وسم آخر يحتوي على / فيجب ترميزه في عنوان URL (feature%2Ffoo).

عناوين URL التي لم يتم تحليلها

عندما يكون عنوان URL غامضاً أو لا يشير إلى موقع محدد على Hub، يتم رفضه (لا يتم التخمين أبداً):

تُعرض المسارات أدناه مرة أخرى دون تضمين المضيف، باستثناء الصف الأخير حيث يكون المضيف نفسه هو سبب الرفض.

عرض عنوان ويب

HfUri.to_url() is the inverse of parsing a URL: it renders the browsable web URL for a HF URI.

>>> 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'

يشير إلى صفحة هبوط المستودع / الدلو عند عدم تعيين مسار أو مراجعة، وإلى عارض المجلد (/tree/<rev>) عند تعيين مراجعة فقط، وإلى عارض الملف (/blob/<rev>/<path>، حيث تكون المراجعة الافتراضية main) لملفات المستودع، وإلى مسار الشجرة (/tree/<path>) لملفات الدلو. يتم ترميز الأحرف الخاصة في المسار (المسافات، #، ...) باستخدام النسبة المئوية. مرّر endpoint=... لاستهداف مضيف مخصص.

التحليل في Python

تحليل معرّفات الموارد الموحّدة

parse_hf_uri() هو محلل URI المركزي. إنه محلل نصوص خالص (لا يتضمن أي استدعاءات شبكة) ويعيد كائن HfUri من نوع dataclass غير قابل للتعديل.

>>> 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 قابل للتحويل ذهاباً وإياباً عبر HfUri.to_uri()، والذي يُخرج دائماً الشكل القياسي (مع بادئة نوع صريحة):

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

استخدم حقلي type وid مباشرةً. وتُوضِّح الخصائص المنطقية is_repo وis_bucket الفرق بين معرِّفات المستودعات ومعرِّفات الدلاء عند الحاجة.

تحليل نقاط التركيب

parse_hf_mount يحلل مواصفة نقطة التثبيت (URI خاص بـ HF مع مسار تثبيت محلي وعلامة اختيارية :ro/:rw) ويعيد كائن HfMount من نوع dataclass غير قابل للتعديل. يستخدم parse_hf_uri() في الخلفية.

>>> 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 قابل للتحويل ذهاباً وإياباً عبر 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'

مرجع

>>> 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)