Hugging Face's logo

Hub Python Library documentation

Tạo và chia sẻ Model Cards

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Tạo và chia sẻ Model Cards

Thư viện huggingface_hub cung cấp giao diện Python để tạo, chia sẻ và cập nhật Model Cards. Truy cập trang tài liệu chuyên biệt để tìm hiểu sâu hơn về Model Cards trên Hub là gì và cách chúng hoạt động bên trong.

Tải thẻ mô hình từ Hub

Để tải một thẻ hiện có từ Hub, bạn có thể sử dụng hàm ModelCard.load(). Ở đây, chúng ta sẽ tải thẻ từ nateraw/vit-base-beans.

from huggingface_hub import ModelCard

card = ModelCard.load('nateraw/vit-base-beans')

Thẻ này có một số thuộc tính hữu ích mà bạn có thể muốn truy cập/sử dụng:

  • card.data: Trả về một instance ModelCardData chứa metadata của model card. Gọi .to_dict() trên instance này để lấy biểu diễn dưới dạng dictionary.
  • card.text: Trả về văn bản của thẻ, không bao gồm phần tiêu đề metadata.
  • card.content: Trả về nội dung văn bản của thẻ, kể cả phần tiêu đề metadata.

Tạo Thẻ Mô hình

Từ văn bản

Để khởi tạo một Model Card từ văn bản, chỉ cần truyền nội dung văn bản của thẻ vào ModelCard khi khởi tạo.

content = """
---
language: en
license: mit
---

# My Model Card
"""

card = ModelCard(content)
card.data.to_dict() == {'language': 'en', 'license': 'mit'}  # True

Một cách khác bạn có thể muốn thực hiện điều này là bằng cách sử dụng f-strings. Trong ví dụ sau, chúng ta:

  • Sử dụng ModelCardData.to_yaml() để chuyển đổi metadata đã định nghĩa sang YAML, giúp chèn khối YAML vào model card.
  • Hiển thị cách bạn có thể sử dụng một biến template thông qua f-strings của Python.
card_data = ModelCardData(language='en', license='mit', library='timm')

example_template_var = 'nateraw'
content = f"""
---
{ card_data.to_yaml() }
---

# My Model Card

This model created by [@{example_template_var}](https://github.com/{example_template_var})
"""

card = ModelCard(content)
print(card)

Ví dụ ở trên sẽ để lại cho chúng ta một thẻ trông như thế này:

---
language: en
license: mit
library: timm
---

# My Model Card

This model created by [@nateraw](https://github.com/nateraw)

Từ một Mẫu Jinja

Nếu bạn đã cài đặt Jinja2, bạn có thể tạo Model Cards từ một tệp template jinja. Hãy xem một ví dụ cơ bản:

from pathlib import Path

from huggingface_hub import ModelCard, ModelCardData

# Define your jinja template
template_text = """
---
{{ card_data }}
---

# Model Card for MyCoolModel

This model does this and that.

This model was created by [@{{ author }}](https://hf.co/{{author}}).
""".strip()

# Write the template to a file
Path('custom_template.md').write_text(template_text)

# Define card metadata
card_data = ModelCardData(language='en', license='mit', library_name='keras')

# Create card from template, passing it any jinja template variables you want.
# In our case, we'll pass author
card = ModelCard.from_template(card_data, template_path='custom_template.md', author='nateraw')
card.save('my_model_card_1.md')
print(card)

Markdown của thẻ kết quả trông như sau:

---
language: en
license: mit
library_name: keras
---

# Model Card for MyCoolModel

This model does this and that.

This model was created by [@nateraw](https://hf.co/nateraw).

Nếu bạn cập nhật bất kỳ card.data nào, nó sẽ được phản ánh ngay trên thẻ đó.

card.data.library_name = 'timm'
card.data.language = 'fr'
card.data.license = 'apache-2.0'
print(card)

Bây giờ, như bạn có thể thấy, phần tiêu đề metadata đã được cập nhật:

---
language: fr
license: apache-2.0
library_name: timm
---

# Model Card for MyCoolModel

This model does this and that.

This model was created by [@nateraw](https://hf.co/nateraw).

Khi bạn cập nhật dữ liệu thẻ, bạn có thể kiểm tra xem thẻ có còn hợp lệ trên Hub hay không bằng cách gọi ModelCard.validate(). Điều này đảm bảo rằng thẻ đáp ứng các quy tắc kiểm tra được thiết lập trên Hugging Face Hub.

Từ Mẫu Mặc Định

Thay vì sử dụng template của riêng bạn, bạn cũng có thể dùng template mặc định, đây là một model card đầy đủ tính năng với rất nhiều phần mà bạn có thể muốn điền. Bên trong, nó sử dụng Jinja2 để điền vào một file template.

Lưu ý rằng bạn cần cài đặt Jinja2 để sử dụng from_template. Bạn có thể thực hiện bằng pip install Jinja2.

card_data = ModelCardData(language='en', license='mit', library_name='keras')
card = ModelCard.from_template(
    card_data,
    model_id='my-cool-model',
    model_description="this model does this and that",
    developers="Nate Raw",
    repo="https://github.com/huggingface/huggingface_hub",
)
card.save('my_model_card_2.md')
print(card)

Chia sẻ Thẻ Mô hình

Nếu bạn đã xác thực với Hugging Face Hub (bằng cách sử dụng hf auth login hoặc login()), bạn có thể đẩy thẻ lên Hub bằng cách đơn giản là gọi ModelCard.push_to_hub(). Hãy cùng xem cách thực hiện…

Đầu tiên, chúng ta sẽ tạo một kho mới có tên ‘hf-hub-modelcards-pr-test’ dưới namespace của người dùng đã xác thực:

from huggingface_hub import whoami, create_repo

user = whoami()['name']
repo_id = f'{user}/hf-hub-modelcards-pr-test'
url = create_repo(repo_id, exist_ok=True)

Sau đó, chúng ta sẽ tạo một thẻ từ mẫu mặc định (giống với mẫu được định nghĩa trong phần ở trên):

card_data = ModelCardData(language='en', license='mit', library_name='keras')
card = ModelCard.from_template(
    card_data,
    model_id='my-cool-model',
    model_description="this model does this and that",
    developers="Nate Raw",
    repo="https://github.com/huggingface/huggingface_hub",
)

Cuối cùng, chúng ta sẽ đẩy nó lên hub

card.push_to_hub(repo_id)

Bạn có thể xem thẻ kết quả tại đây.

Nếu bạn muốn đẩy thẻ dưới dạng pull request, bạn chỉ cần đặt create_pr=True khi gọi push_to_hub:

card.push_to_hub(repo_id, create_pr=True)

PR được tạo ra từ lệnh này có thể được xem tại đây.

Cập nhật metadata

Trong phần này, chúng ta sẽ tìm hiểu các metadata có trong repo cards và cách cập nhật chúng.

metadata là một bản đồ băm (hoặc ngữ cảnh khóa-giá trị) cung cấp một số thông tin cấp cao về một model, dataset hoặc Space. Thông tin đó có thể bao gồm các chi tiết như pipeline type, model_id hoặc model_description của model. Để biết thêm chi tiết, bạn có thể xem các hướng dẫn này: Model Card, Dataset Card và Spaces Settings. Bây giờ hãy xem một số ví dụ về cách cập nhật các metadata đó.

Hãy bắt đầu với một ví dụ đầu tiên:

>>> from huggingface_hub import metadata_update
>>> metadata_update("username/my-cool-model", {"pipeline_tag": "image-classification"})

Với hai dòng mã này, bạn sẽ cập nhật metadata để đặt một pipeline_tag mới.

Mặc định, bạn không thể cập nhật một khóa đã tồn tại trên thẻ. Nếu bạn muốn làm điều đó, bạn phải truyền overwrite=True một cách rõ ràng:

>>> from huggingface_hub import metadata_update
>>> metadata_update("username/my-cool-model", {"pipeline_tag": "text-generation"}, overwrite=True)

Thường thì bạn sẽ muốn đề xuất một số thay đổi cho một kho mã mà bạn không có quyền ghi. Bạn có thể làm điều đó bằng cách tạo một PR trên kho đó, cho phép các chủ sở hữu xem xét và hợp nhất các đề xuất của bạn.

>>> from huggingface_hub import metadata_update
>>> metadata_update("someone/model", {"pipeline_tag": "text-classification"}, create_pr=True)

Bao gồm kết quả đánh giá

Để bao gồm kết quả đánh giá trong metadata model-index, bạn có thể truyền một EvalResult hoặc một danh sách EvalResult kèm theo các kết quả đánh giá liên quan. Bên trong, hệ thống sẽ tạo model-index khi bạn gọi card.data.to_dict(). Để biết thêm thông tin về cách hoạt động này, bạn có thể xem mục này trong tài liệu Hub.

Lưu ý rằng việc sử dụng hàm này yêu cầu bạn phải bao gồm thuộc tính model_name trong ModelCardData.

card_data = ModelCardData(
    language='en',
    license='mit',
    model_name='my-cool-model',
    eval_results = EvalResult(
        task_type='image-classification',
        dataset_type='beans',
        dataset_name='Beans',
        metric_type='accuracy',
        metric_value=0.7
    )
)

card = ModelCard.from_template(card_data)
print(card.data)

card.data thu được nên có dạng như sau:

language: en
license: mit
model-index:
- name: my-cool-model
  results:
  - task:
      type: image-classification
    dataset:
      name: Beans
      type: beans
    metrics:
    - type: accuracy
      value: 0.7

Nếu bạn có nhiều hơn một kết quả đánh giá muốn chia sẻ, chỉ cần truyền một danh sách EvalResult:

card_data = ModelCardData(
    language='en',
    license='mit',
    model_name='my-cool-model',
    eval_results = [
        EvalResult(
            task_type='image-classification',
            dataset_type='beans',
            dataset_name='Beans',
            metric_type='accuracy',
            metric_value=0.7
        ),
        EvalResult(
            task_type='image-classification',
            dataset_type='beans',
            dataset_name='Beans',
            metric_type='f1',
            metric_value=0.65
        )
    ]
)
card = ModelCard.from_template(card_data)
card.data

Điều này sẽ để lại cho bạn card.data như sau:

language: en
license: mit
model-index:
- name: my-cool-model
  results:
  - task:
      type: image-classification
    dataset:
      name: Beans
      type: beans
    metrics:
    - type: accuracy
      value: 0.7
    - type: f1
      value: 0.65
Update on GitHub

←Bộ nhớ đệm Quản lý Space của bạn→