Hub documentation

Thẻ mô hình

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Thẻ mô hình

Model Cards là gì?

Model cards là các tệp đi kèm với mô hình và cung cấp thông tin hữu ích. Về bản chất, model cards là các tệp Markdown đơn giản với thêm các metadata. Model cards rất quan trọng cho khả năng tìm kiếm, tái lập và chia sẻ! Bạn có thể tìm thấy model card dưới dạng tệp README.md trong bất kỳ repo mô hình nào.

Thẻ mô tả mô hình nên mô tả:

mô hình
các mục đích sử dụng dự kiến & các hạn chế tiềm ẩn, bao gồm các thiên kiến và các cân nhắc đạo đức như được mô tả chi tiết trong Mitchell, 2018
các tham số huấn luyện và thông tin thực nghiệm (bạn có thể nhúng hoặc liên kết đến một nền tảng theo dõi thực nghiệm để tham khảo)
các bộ dữ liệu nào đã được sử dụng để huấn luyện mô hình của bạn
kết quả đánh giá của mô hình

Mẫu thẻ mô hình có sẵn tại đây.

Cách điền từng phần của model card được mô tả trong the Annotated Model Card.

Model Cards trên Hub có hai phần chính, với thông tin có sự trùng lặp:

Thông tin mô tả
Mô tả văn bản

Metadata thẻ mô hình

Một kho mô hình sẽ hiển thị README.md của nó dưới dạng thẻ mô hình. Thẻ mô hình là một tệp Markdown, có một phần YAML ở đầu chứa các siêu dữ liệu về mô hình.

Metadata bạn thêm vào model card hỗ trợ việc tìm kiếm và sử dụng mô hình của bạn dễ dàng hơn. Ví dụ:

Cho phép người dùng lọc các mô hình tại https://huggingface.co/models.
Hiển thị giấy phép của mô hình.
Việc thêm các bộ dữ liệu vào metadata sẽ chèn một thông báo có nội dung Datasets used to train: vào trang mô hình của bạn và liên kết đến các bộ dữ liệu liên quan, nếu chúng có sẵn trên Hub.

Các định danh tập dữ liệu và ngôn ngữ là những định danh được liệt kê trên các trang Datasets và Languages.

Thêm metadata vào thẻ mô hình của bạn

Có một số cách khác nhau để thêm metadata vào model card của bạn, bao gồm:

Sử dụng giao diện người dùng metadata
Chỉnh sửa trực tiếp phần YAML của tệp README.md
Thông qua thư viện Python huggingface_hub, xem tài liệu để biết thêm chi tiết.

Nhiều thư viện có tích hợp Hub sẽ tự động thêm metadata vào model card khi bạn tải lên một model.

Sử dụng giao diện người dùng metadata

Bạn có thể thêm metadata vào model card của mình bằng cách sử dụng metadata UI. Để truy cập metadata UI, hãy chuyển đến trang model và nhấp vào nút Edit model card ở góc trên bên phải của model card. Thao tác này sẽ mở một trình soạn thảo hiển thị tệp README.md của model card, cùng với một UI để chỉnh sửa metadata.

Giao diện này cho phép bạn thêm các metadata chính vào model card của mình và nhiều trường sẽ tự động hoàn thành dựa trên thông tin bạn cung cấp. Sử dụng giao diện là cách dễ nhất để thêm metadata vào model card, nhưng nó không hỗ trợ tất cả các trường metadata. Nếu bạn muốn thêm metadata không được giao diện hỗ trợ, bạn có thể chỉnh sửa trực tiếp phần YAML của tệp README.md.

Chỉnh sửa phần YAML của tệp README.md

Bạn cũng có thể chỉnh sửa trực tiếp phần YAML của tệp README.md. Nếu thẻ mô hình chưa có phần YAML, bạn có thể thêm một phần bằng cách thêm ba --- ở đầu tệp, sau đó bao gồm tất cả các metadata liên quan, và đóng phần bằng một nhóm --- khác như ví dụ bên dưới:

---
language: 
  - "List of ISO 639-1 code for your language"
  - lang1
  - lang2
thumbnail: "url to a thumbnail used in social sharing"
tags:
- tag1
- tag2
license: "any valid license identifier"
datasets:
- dataset1
- dataset2
base_model: "base model Hub identifier"
---

Bạn có thể tìm thấy thông số kỹ thuật chi tiết về metadata của model card tại đây.

Chỉ định một thư viện

Bạn có thể chỉ định các thư viện được hỗ trợ trong phần metadata của model card. Tìm hiểu thêm về các thư viện được hỗ trợ của chúng tôi tại đây. Thư viện sẽ được chỉ định theo thứ tự ưu tiên sau:

Việc chỉ định library_name trong thẻ mô hình (được khuyến nghị nếu mô hình của bạn không phải là mô hình transformers). Thông tin này có thể được thêm vào qua giao diện người dùng metadata hoặc trực tiếp trong phần YAML của thẻ mô hình:

library_name: flair

Có một thẻ mang tên của thư viện được hỗ trợ

tags:
- flair

Nếu không được chỉ định, Hub sẽ cố gắng tự động phát hiện loại thư viện. Tuy nhiên, cách tiếp cận này không được khuyến khích, và người tạo kho nên sử dụng library_name tường minh càng nhiều càng tốt.

Bằng cách kiểm tra sự hiện diện của các tệp như *.nemo hoặc *.mlmodel, Hub có thể xác định xem một mô hình có đến từ NeMo hay CoreML hay không.
Trước đây, nếu không phát hiện được gì và có tệp config.json, thư viện được mặc định là transformers. Đối với các kho mô hình được tạo sau tháng 8 năm 2024, điều này không còn đúng nữa, vì vậy bạn cần đặt library_name: transformers một cách tường minh.

Chỉ định một mô hình cơ sở

Nếu mô hình của bạn là một phiên bản fine-tune, adapter, hoặc phiên bản lượng tử hóa của một mô hình cơ sở, bạn có thể chỉ định mô hình cơ sở trong phần metadata của model card. Thông tin này cũng có thể được sử dụng để chỉ ra nếu mô hình của bạn là một bản merge của nhiều mô hình hiện có. Do đó, trường base_model có thể là một model ID duy nhất, hoặc một danh sách gồm một hoặc nhiều base_models (được chỉ định bằng Hub identifiers của chúng).

base_model: HuggingFaceH4/zephyr-7b-beta

Metadata này sẽ được sử dụng để hiển thị mô hình cơ sở trên trang mô hình. Người dùng cũng có thể sử dụng thông tin này để lọc các mô hình theo mô hình cơ sở hoặc tìm các mô hình được phát triển từ một mô hình cơ sở cụ thể:

Đối với một mô hình đã tinh chỉnh:

Đối với một adapter (LoRA, PEFT, v.v.):

Đối với phiên bản lượng tử hóa của một mô hình khác:

Đối với việc hợp nhất hai hoặc nhiều mô hình:

Trong trường hợp hợp nhất, bạn chỉ định một danh sách gồm hai hoặc nhiều hơn base_models:

base_model:
- Endevor/InfinityRP-v1-7B
- l3utterfly/mistral-7b-v0.1-layla-v4

Hub sẽ suy luận loại quan hệ từ model hiện tại đến model cơ sở ("adapter", "merge", "quantized", "finetune") nhưng bạn cũng có thể đặt nó một cách rõ ràng nếu cần: ví dụ base_model_relation: quantized.

Chỉ định một phiên bản mới

Nếu một phiên bản mới của mô hình của bạn có sẵn trên Hub, bạn có thể chỉ định nó trong trường new_version.

Ví dụ, trên l3utterfly/mistral-7b-v0.1-layla-v3:

new_version: l3utterfly/mistral-7b-v0.1-layla-v4

Metadata này sẽ được sử dụng để hiển thị liên kết đến phiên bản mới nhất của một model trên trang model. Nếu model được liên kết trong new_version cũng có trường new_version, phiên bản mới nhất sẽ luôn được hiển thị.

Chỉ định một tập dữ liệu

Bạn có thể chỉ định các bộ dữ liệu được sử dụng để huấn luyện mô hình của mình trong phần metadata của model card. Các bộ dữ liệu sẽ được hiển thị trên trang mô hình và người dùng sẽ có thể lọc mô hình theo bộ dữ liệu. Bạn nên sử dụng Hub dataset identifier, tức là trùng với tên repo của bộ dữ liệu, làm định danh:

datasets:
- stanfordnlp/imdb
- HuggingFaceFW/fineweb

Chỉ định một bucket

Bạn có thể chỉ định các storage buckets liên kết với model của bạn trong phần metadata của model card. Các bucket sẽ được hiển thị dưới dạng tag trên trang model và các trang bucket liên kết sẽ hiển thị model tương ứng. Bạn nên sử dụng Hub bucket identifier, đây cũng chính là tên repo của bucket:

buckets:
- my-org/my-bucket
- my-org/another-bucket

Chỉ định một tác vụ ( pipeline_tag )

Bạn có thể chỉ định pipeline_tag trong metadata của model card. pipeline_tag cho biết loại tác vụ mà model được thiết kế để thực hiện. Thẻ này sẽ được hiển thị trên trang model và người dùng có thể lọc các model trên Hub theo tác vụ. Thẻ này cũng được dùng để xác định widget nào sẽ được sử dụng cho model và các API nào sẽ được dùng bên trong.

Đối với các mô hình transformers, thẻ pipeline được suy ra tự động từ tệp config.json của mô hình, nhưng bạn có thể ghi đè nó trong metadata của model card nếu cần. Việc chỉnh sửa trường này trong giao diện metadata sẽ đảm bảo rằng thẻ pipeline hợp lệ. Một số thư viện khác có tích hợp Hub cũng sẽ tự động thêm thẻ pipeline vào metadata của model card.

Chỉ định giấy phép

Bạn có thể chỉ định giấy phép trong phần metadata của model card. Giấy phép sẽ được hiển thị trên trang model và người dùng có thể lọc các model theo giấy phép. Khi sử dụng giao diện metadata, bạn sẽ thấy một menu thả xuống chứa các giấy phép phổ biến nhất.

Nếu cần, bạn cũng có thể chỉ định một giấy phép tùy chỉnh bằng cách thêm other làm giá trị giấy phép và chỉ định tên cùng liên kết đến giấy phép trong metadata.

# Example from https://huggingface.co/coqui/XTTS-v1
---
license: other
license_name: coqui-public-model-license
license_link: https://coqui.ai/cpml
---

Nếu giấy phép không có sẵn qua URL, bạn có thể liên kết đến tệp LICENSE được lưu trong kho mô hình.

Kết quả đánh giá

Bạn có thể chỉ định kết quả đánh giá mô hình của mình theo cách có cấu trúc trong metadata của model card. Kết quả sẽ được Hub phân tích và hiển thị trong một widget trên trang mô hình. Dưới đây là một ví dụ về cách nó trông như thế nào đối với mô hình bigcode/starcoder:

Quy cách metadata ban đầu được xây dựng dựa trên quy cách model-index của Papers with code. Điều này cho phép chúng tôi trực tiếp lập chỉ mục kết quả vào các bảng xếp hạng của Papers with code khi phù hợp. Bạn cũng có thể liên kết đến nguồn mà từ đó kết quả đánh giá đã được tính toán.

MỚI: Chúng tôi có định dạng metadata mới, đơn giản hơn cho kết quả đánh giá. Xem chi tiết tại trang tài liệu chuyên biệt.

Dưới đây là một ví dụ một phần về model-index mô tả điểm số của 01-ai/Yi-34B trên benchmark ARC. Kết quả này đến từ Open LLM Leaderboard, được xác định là source:

---
model-index:
  - name: Yi-34B
    results:
      - task:
          type: text-generation
        dataset:
          name: ai2_arc
          type: ai2_arc
        metrics:
          - name: AI2 Reasoning Challenge (25-Shot)
            type: AI2 Reasoning Challenge (25-Shot)
            value: 64.59
        source:
          name: Open LLM Leaderboard
          url: https://huggingface.co/spaces/open-llm-leaderboard/open_llm_leaderboard
---

Để biết thêm chi tiết về cách định dạng dữ liệu này, hãy xem quy định Model Card.

Phát thải CO2

Thẻ mô hình (model card) cũng là nơi tuyệt vời để hiển thị thông tin về tác động CO₂ của mô hình của bạn. Hãy truy cập hướng dẫn theo dõi và báo cáo lượng phát thải CO₂ để tìm hiểu thêm.

Liên kết một bài báo

Nếu thẻ mô hình bao gồm một liên kết đến trang Paper (trên HF hoặc abstract/PDF trên Arxiv), Hugging Face Hub sẽ trích xuất ID arXiv và bao gồm nó trong các thẻ mô hình với định dạng arxiv:<PAPER ID>. Nhấp vào thẻ sẽ cho phép bạn:

Trang Paper
Lọc các mô hình khác trên Hub trích dẫn cùng một bài báo.

Đọc thêm về các trang Paper tại đây.

Văn bản Model Card

Chi tiết về cách điền phần mô tả bằng ngôn ngữ tự nhiên của model card (để có thể in ra, cắt+dán, v.v.) có sẵn trong Annotated Model Card.

Câu hỏi thường gặp

Các thẻ mô hình được xác định như thế nào?

Mỗi trang mô hình liệt kê tất cả các thẻ của mô hình trong phần tiêu đề trang, ngay bên dưới tên mô hình. Các thẻ này chủ yếu được tính toán từ metadata của thẻ mô hình, mặc dù một số được thêm vào tự động, như đã mô tả trong Enabling a Widget.

Tôi có thể thêm các thẻ tùy chỉnh vào mô hình của mình không?

Có, bạn có thể thêm các thẻ tùy chỉnh vào mô hình của mình bằng cách thêm chúng vào trường tags trong metadata của model card. Giao diện metadata sẽ gợi ý một số thẻ phổ biến, nhưng bạn có thể thêm bất kỳ thẻ nào bạn muốn. Ví dụ, bạn có thể chỉ ra rằng mô hình của mình tập trung vào tài chính bằng cách thêm thẻ finance.

Làm thế nào để tôi chỉ ra rằng mô hình của mình không phù hợp với tất cả mọi đối tượng

Bạn có thể thêm thẻ not-for-all-audiences vào metadata của model card. Khi thẻ này có mặt, một thông báo sẽ được hiển thị trên trang model, cho biết model không dành cho mọi đối tượng. Người dùng có thể nhấp vào thông báo này để xem model card.

Làm thế nào để hiển thị các hình ảnh khác nhau cho chế độ tối và chế độ sáng?

Bạn có thể hiển thị các phiên bản khác nhau của một hình ảnh được tối ưu hóa cho từng giao diện. Tính năng này đặc biệt hữu ích cho logo, sơ đồ hoặc ảnh chụp màn hình cần các bảng màu khác nhau để duy trì khả năng hiển thị và tính thẩm mỹ trên cả chế độ sáng và tối. Để sử dụng tính năng này, bạn cần cung cấp cả hai phiên bản của hình ảnh.

Đối với hình ảnh được tải lên qua trình soạn thảo markdown

Khi bạn tải lên một hình ảnh trực tiếp từ trình soạn thảo markdown (dùng kéo-thả), hãy thêm URI fragment #hf-light-mode-only hoặc #hf-dark-mode-only vào cuối URL của hình ảnh để chỉ định chủ đề mà nó nên hiển thị:

Image only displays when viewing in light mode
![Logo](https://cdn-uploads.huggingface.co/production/uploads/logo-light.png#hf-light-mode-only)

Image only displays when viewing in dark mode
![Logo](https://cdn-uploads.huggingface.co/production/uploads/logo-dark.png#hf-dark-mode-only)

Đối với các hình ảnh đã được lưu trữ

Nếu bạn muốn tham chiếu các hình ảnh đã được lưu trữ sẵn mà không cần tải lên lại, hãy sử dụng thẻ HTML <img> với các lớp Tailwind CSS sau để chỉ định chủ đề hiển thị:

// Image only displays when viewing in dark mode
<img class="hidden dark:block" src="https://hf.co/logo-dark.png" alt="Logo" />

// Image only displays when viewing in light mode
<img class="dark:hidden" src="https://hf.co/logo-light.png" alt="Logo" />

Tôi có thể viết LaTeX trong thẻ mô hình của mình không?

Đúng vậy! Hub sử dụng thư viện dàn trang công thức toán học KaTeX để hiển thị các công thức toán học phía máy chủ trước khi phân tích Markdown.

Bạn phải sử dụng các ký tự phân cách sau:

$$ ... $$ cho chế độ hiển thị
\$...\$ cho chế độ inline (không có khoảng trắng giữa các dấu gạch chéo và dấu ngoặc).

Sau đó, bạn sẽ có thể viết: $\LaTeX$ $\mathrm{MSE} = \left(\frac{1}{n}\right)\sum_{i=1}^{n}(y_{i} - x_{i})^{2}$ $E=mc^2$

Update on GitHub

←Trung tâm Mô hình Phát thải Carbon→