Viết tài liệu

Để đóng góp cho hub.tensorflow.google.cn, bạn phải cung cấp tài liệu ở định dạng Markdown. Để biết tổng quan đầy đủ về quy trình đóng góp mô hình vào hub.tensorflow.google.cnhãy xem hướng dẫn đóng góp mô hình .

Các loại tài liệu Markdown

Có 3 loại tài liệu Markdown được sử dụng trong hub.tensorflow.google.cn:

  • Nhà xuất bản Markdown - thông tin về một nhà xuất bản ( xem cú pháp đánh dấu)
  • Mô hình Markdown - thông tin về một mô hình cụ thể và cách sử dụng nó ( xem cú pháp đánh dấu)
  • Đánh dấu bộ sưu tập - chứa thông tin về bộ sưu tập mô hình do nhà xuất bản xác định ( xem cú pháp đánh dấu )

Tổ chức nội dung

Tổ chức nội dung sau là bắt buộc khi đóng góp vào kho lưu trữ TensorFlow Hub GitHub :

  • mỗi thư mục nhà xuất bản nằm trong thư mục nội dung assets/docs
  • mỗi thư mục nhà xuất bản chứa models tùy chọn và thư mục collections
  • mỗi mô hình phải có thư mục riêng của nó trong assets/docs/<publisher_name>/models
  • mỗi bộ sưu tập phải có một thư mục riêng trong phần assets/docs/<publisher_name>/collections

Đánh dấu nhà xuất bản không được phiên bản, trong khi các mô hình có thể có các phiên bản khác nhau. Mỗi phiên bản mô hình yêu cầu một tệp Markdown riêng biệt được đặt tên theo phiên bản mà nó mô tả (tức là 1.md, 2). Bộ sưu tập được tạo phiên bản nhưng chỉ một phiên bản duy nhất (1) được hỗ trợ.

Tất cả các phiên bản mô hình cho một mô hình nhất định phải được đặt trong thư mục mô hình.

Dưới đây là minh họa về cách tổ chức nội dung Markdown:

assets/docs
├── <publisher_name_a>
│   ├── <publisher_name_a>.md  -> Documentation of the publisher.
│   └── models
│       └── <model_name>       -> Model name with slashes encoded as sub-path.
│           ├── 1.md           -> Documentation of the model version 1.
│           └── 2.md           -> Documentation of the model version 2.
├── <publisher_name_b>
│   ├── <publisher_name_b>.md  -> Documentation of the publisher.
│   ├── models
│   │   └── ...
│   └── collections
│       └── <collection_name>
│           └── 1.md           -> Documentation for the collection.
├── <publisher_name_c>
│   └── ...
└── ...

Định dạng đánh dấu nhà xuất bản

Tài liệu dành cho nhà xuất bản được khai báo dưới dạng tệp đánh dấu giống như các mô hình, với sự khác biệt nhỏ về cú pháp.

Vị trí chính xác cho tệp nhà xuất bản trên kho lưu trữ TensorFlow Hub là: hub.tensorflow.google.cn/ asset / docs / <publisher_id> / <publisher_id.md>

Xem ví dụ về tài liệu dành cho nhà xuất bản tối thiểu cho nhà xuất bản "vtab":

# Publisher vtab
Visual Task Adaptation Benchmark

[![Icon URL]](https://storage.googleapis.com/vtab/vtab_logo_120.png)

## VTAB
The Visual Task Adaptation Benchmark (VTAB) is a diverse, realistic and
challenging benchmark to evaluate image representations.

Ví dụ trên chỉ định id nhà xuất bản, tên nhà xuất bản, đường dẫn đến biểu tượng để sử dụng và tài liệu đánh dấu dạng tự do dài hơn. Lưu ý rằng id nhà xuất bản chỉ nên chứa các chữ cái thường, chữ số và dấu gạch nối.

Hướng dẫn về tên nhà xuất bản

Tên nhà xuất bản của bạn có thể là tên người dùng GitHub của bạn hoặc tên của tổ chức GitHub mà bạn quản lý.

Định dạng đánh dấu trang mô hình

Tài liệu mô hình là một tệp Markdown với một số cú pháp bổ trợ. Xem ví dụ bên dưới để biết ví dụ tối thiểu hoặc tệp Markdown ví dụ thực tế hơn .

Tài liệu ví dụ

Tài liệu về mô hình chất lượng cao chứa các đoạn mã, thông tin về cách mô hình được đào tạo và mục đích sử dụng. Bạn cũng nên sử dụng các thuộc tính siêu dữ liệu dành riêng cho mô hình được giải thích bên dưới để người dùng có thể tìm thấy mô hình của bạn trên hub.tensorflow.google.cn nhanh hơn.

# Module google/text-embedding-model/1

Simple one sentence description.

<!-- asset-path: https://path/to/text-embedding-model/model.tar.gz -->
<!-- task: text-embedding -->
<!-- fine-tunable: true -->
<!-- format: saved_model_2 -->

## Overview

Here we give more information about the model including how it was trained,
expected use cases, and code snippets demonstrating how to use the model:

```
Code snippet demonstrating use (e.g. for a TF model using the tensorflow_hub library)

import tensorflow_hub as hub

model = hub.KerasLayer(<model name>)
inputs = ...
output = model(inputs)
```

Triển khai mô hình và nhóm các triển khai lại với nhau

hub.tensorflow.google.cn cho phép xuất bản triển khai TF.js, TFLite và Coral của TensorFlow SavedModel.

Dòng đầu tiên của tệp Markdown phải chỉ định loại định dạng:

  • # Module publisher/model/version cho SavedModels
  • # Tfjs publisher/model/version Tfjs cho việc triển khai TF.js
  • # Lite publisher/model/version Lite để triển khai Lite
  • # Coral publisher/model/version Coral để triển khai Coral

Bạn nên để các định dạng khác nhau này của cùng một mô hình khái niệm hiển thị trên cùng một trang mô hình trên hub.tensorflow.google.cn. Để liên kết triển khai TF.js, TFLite hoặc Coral nhất định với mô hình TensorFlow SavedModel, hãy chỉ định thẻ mô hình mẹ:

<!-- parent-model: publisher/model/version -->

Đôi khi bạn có thể muốn xuất bản một hoặc nhiều triển khai mà không có TensorFlow SavedModel. Trong trường hợp đó, bạn sẽ cần tạo mô hình Trình giữ chỗ và chỉ định phần xử lý của nó trong thẻ parent-model . Trình giữ chỗ Markdown giống với Markdown mô hình TensorFlow, ngoại trừ dòng đầu tiên là: # Placeholder publisher/model/version và không yêu cầu thuộc asset-path .

Thuộc tính siêu dữ liệu cụ thể của Model Markdown

Các tệp Markdown có thể chứa các thuộc tính siêu dữ liệu. Chúng được sử dụng để cung cấp các bộ lọc và thẻ để giúp người dùng tìm thấy mô hình của bạn. Các thuộc tính siêu dữ liệu được bao gồm dưới dạng nhận xét Markdown sau phần mô tả ngắn về tệp Markdown, ví dụ:

# Module google/universal-sentence-encoder/1
Encoder of greater-than-word length text trained on a variety of data.

<!-- task: text-embedding -->
...

Các thuộc tính siêu dữ liệu sau được hỗ trợ:

  • format : Đối với mô hình TensorFlow: định dạng TensorFlow Hub của mô hình. Giá trị hợp lệ là hub khi mô hình được xuất qua định dạng trung tâm TF1 cũ hoặc saved_model_2 khi mô hình được xuất qua Mô hình đã lưu TF2 .
  • asset-path : đường dẫn từ xa có thể đọc được trên toàn thế giới đến nội dung mô hình thực tế để tải lên, chẳng hạn như tới nhóm Google Cloud Storage. URL phải được cho phép tìm nạp từ tệp robots.txt (vì lý do này, "https://github.com/. / Release / download /. " Không được hỗ trợ vì nó bị cấm bởi https: // github .com / robots.txt ). Xem bên dưới để biết thêm thông tin về loại tệp dự kiến ​​và nội dung.
  • parent-model : Đối với mô hình TF.js / TFLite / Coral: xử lý SavedModel / Trình giữ chỗ đi kèm
  • fine-tunable : Boolean, liệu người dùng có thể tinh chỉnh mô hình hay không.
  • task : miền sự cố, ví dụ: "text-embedding". Tất cả các giá trị được hỗ trợ được xác định trong task.yaml .
  • dataset : tập dữ liệu mà mô hình đã được đào tạo, ví dụ: "wikipedia". Tất cả các giá trị được hỗ trợ được xác định trong dataset.yaml .
  • network-architecture mạng: kiến ​​trúc mạng mà mô hình dựa trên, ví dụ: "mobilenet-v3". Tất cả các giá trị được hỗ trợ được xác định trong network_architecture.yaml .
  • language : mã ngôn ngữ của ngôn ngữ mà mô hình văn bản đã được đào tạo, ví dụ: "en". Tất cả các giá trị được hỗ trợ được xác định trong language.yaml .
  • license : Giấy phép áp dụng cho mô hình, ví dụ: "mit". Giấy phép giả định mặc định cho mô hình đã xuất bản là Giấy phép Apache 2.0 . Tất cả các giá trị được hỗ trợ được xác định trong license.yaml . Lưu ý rằng giấy phép custom sẽ yêu cầu xem xét đặc biệt theo từng trường hợp.
  • colab : URL HTTPS tới một sổ ghi chép minh họa cách mô hình có thể được sử dụng hoặc đào tạo ( ví dụ cho bigbigan-resnet50 ). Phải dẫn đến colab.research.google.com . Lưu ý rằng bạn có thể truy cập sổ ghi chép Jupyter được lưu trữ trên GitHub qua <a href="https://colab.research.google.com/github/ORGANIZATION/PROJECT/">https://colab.research.google.com/github/ORGANIZATION/PROJECT/</a> blob/master/.../my_notebook.ipynb .
  • demo : URL HTTPS đến một trang web trình bày cách sử dụng mô hình TF.js ( ví dụ cho posenet ).
  • interactive-visualizer : tên của trình hiển thị sẽ được nhúng trên trang mô hình, ví dụ: "tầm nhìn". Hiển thị trình hiển thị cho phép người dùng khám phá các dự đoán của mô hình một cách tương tác. Tất cả các giá trị được hỗ trợ được xác định trong tương tác_visualizer.yaml .

Các loại tài liệu Markdown hỗ trợ các thuộc tính siêu dữ liệu tùy chọn và bắt buộc khác nhau:

Loại hình Yêu cầu Không bắt buộc
Nhà xuất bản
Bộ sưu tập nhiệm vụ tập dữ liệu, ngôn ngữ, kiến ​​trúc mạng
Trình giữ chỗ nhiệm vụ tập dữ liệu, có thể tinh chỉnh, trình hiển thị tương tác, ngôn ngữ, giấy phép, kiến ​​trúc mạng
SavedModel đường dẫn nội dung, tác vụ, có thể tinh chỉnh, định dạng colab, tập dữ liệu, trình hiển thị tương tác, ngôn ngữ, giấy phép, kiến ​​trúc mạng
Tfjs đường dẫn nội dung, mô hình gốc colab, demo, tương tác-visualizer
Lite đường dẫn nội dung, mô hình gốc colab, trình hiển thị tương tác
San hô đường dẫn nội dung, mô hình gốc colab, trình hiển thị tương tác

Nội dung nội dung dành riêng cho mô hình

Tùy thuộc vào loại mô hình, các loại tệp và nội dung sau được mong đợi:

  • SavedModel: một kho lưu trữ tar.gz chứa nội dung như sau:
saved_model.tar.gz
├── assets/            # Optional.
├── assets.extra/      # Optional.
├── variables/
│     ├── variables.data-?????-of-?????
│     └──  variables.index
├── saved_model.pb
├── keras_metadata.pb  # Optional, only required for Keras models.
└── tfhub_module.pb    # Optional, only required for TF1 models.
  • TF.js: một kho lưu trữ tar.gz chứa nội dung như sau:
tf_js_model.tar.gz
├── group*
├── *.json
├── *.txt
└── *.pb
  • TFLite: một tệp .tflite
  • Coral: một tệp .tflite

Đối với tệp lưu trữ tar.gz: giả sử tệp mô hình của bạn nằm trong thư mục my_model (ví dụ: my_model/saved_model.pb cho SavedModels hoặc my_model/model.json cho mô hình TF.js), bạn có thể tạo tệp lưu trữ tar.gz hợp lệ bằng công cụ tar thông qua cd my_model && tar -czvf ../model.tar.gz * .

Nói chung, tất cả các tệp và thư mục (dù nén hay không nén) phải bắt đầu bằng một ký tự từ, vì vậy, ví dụ: dấu chấm không phải là tiền tố hợp lệ của tên tệp / thư mục.

Định dạng đánh dấu trang bộ sưu tập

Bộ sưu tập là một tính năng của hub.tensorflow.google.cn cho phép nhà xuất bản nhóm các mô hình có liên quan lại với nhau để cải thiện trải nghiệm tìm kiếm của người dùng.

Xem danh sách tất cả các bộ sưu tập trênhub.tensorflow.google.cn.

Vị trí chính xác cho tệp bộ sưu tập trong kho lưu trữ github.com/tensorflow/hub.tensorflow.google.cn là asset / docs / publisher_name> / collection / <collection_name> / 1 .md

Dưới đây là một ví dụ tối thiểu về tài sản / docs / vtab / collection / benchmark / 1 .md. Lưu ý rằng tên của bộ sưu tập trong dòng đầu tiên không bao gồm collections/ phần được bao gồm trong đường dẫn tệp.

# Collection vtab/benchmark/1
Collection of visual representations that have been evaluated on the VTAB
benchmark.

<!-- task: image-feature-vector -->

## Overview
This is the list of visual representations in TensorFlow Hub that have been
evaluated on VTAB. Results can be seen in
[google-research.github.io/task_adaptation/](https://google-research.github.io/task_adaptation/)

#### Models
|                   |
|-------------------|
| [vtab/sup-100/1](https://hub.tensorflow.google.cn/vtab/sup-100/1)   |
| [vtab/rotation/1](https://hub.tensorflow.google.cn/vtab/rotation/1) |
|------------------------------------------------------|

Ví dụ chỉ định tên của bộ sưu tập, mô tả ngắn một câu, siêu dữ liệu miền sự cố và tài liệu đánh dấu dạng tự do.