Tulis dokumentasi

Untuk berkontribusi ke l10n- tfhub.dev l10n, dokumentasi dalam format penurunan harga harus disediakan. Untuk ikhtisar lengkap tentang proses kontribusi model ke l10n- tfhub.dev l10nlihat panduan model kontribusi .

Jenis dokumentasi penurunan harga

Ada 3 jenis dokumentasi penurunan harga yang digunakan di l10n- tfhub.dev l10n:

Organisasi konten

Organisasi konten berikut diperlukan saat berkontribusi ke repositori TensorFlow Hub GitHub :

  • setiap direktori penerbit ada di direktori assets/docs
  • setiap direktori penerbit berisi models opsional dan direktori collections
  • setiap model harus memiliki direktori sendiri di bawah assets/docs/<publisher_name>/models
  • setiap koleksi harus memiliki direktori sendiri di bawah assets/docs/<publisher_name>/collections

Penurunan harga penerbit tidak berversi, sedangkan model dapat memiliki versi yang berbeda. Setiap versi model memerlukan file penurunan harga terpisah yang dinamai menurut versi yang dijelaskannya (yaitu 1.md, 2). Koleksi berversi tetapi hanya satu versi (1) yang didukung.

Semua versi model untuk model tertentu harus ditempatkan di direktori model.

Di bawah ini adalah ilustrasi tentang bagaimana konten Markdown diatur:

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>
│   └── ...
└── ...

Format penurunan harga penerbit

Dokumentasi penerbit dideklarasikan dalam jenis file penurunan harga yang sama dengan model, dengan sedikit perbedaan sintaksis.

Lokasi yang benar untuk file penerbit di repo TensorFlow Hub adalah: l10n-tfhub.dev l10n/assets/docs /<publisher_id>/<publisher_id.md>

Lihat contoh dokumentasi penerbit minimal untuk penerbit "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.

Contoh di atas menentukan id penerbit, nama penerbit, jalur ke ikon yang akan digunakan, dan dokumentasi penurunan harga bentuk bebas yang lebih panjang. Perhatikan bahwa id penerbit hanya boleh berisi huruf kecil, angka, dan tanda hubung.

Pedoman nama penerbit

Nama penerbit Anda dapat berupa nama pengguna GitHub Anda atau nama organisasi GitHub yang Anda kelola.

Format penurunan harga halaman model

Dokumentasi model adalah file penurunan harga dengan beberapa sintaks tambahan. Lihat contoh di bawah untuk contoh minimal atau contoh file Markdown yang lebih realistis .

Contoh dokumentasi

Dokumentasi model berkualitas tinggi berisi cuplikan kode, informasi bagaimana model dilatih dan penggunaan yang dimaksudkan. Anda juga harus menggunakan properti metadata khusus model yang dijelaskan di bawah sehingga pengguna dapat menemukan model Anda di l10n- tfhub.dev l10n lebih cepat.

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

Penerapan model dan pengelompokan penerapan bersama

l10n-tfhub.dev l10n memungkinkan penerbitan penerapan TF.js, TFLite, dan Coral dari TensorFlow SavedModel.

Baris pertama dari file penurunan harga harus menentukan jenis format:

  • # Module publisher/model/version modul untuk SavedModels
  • # Tfjs publisher/model/version Tfjs untuk penerapan TF.js
  • # Lite publisher/model/version Lite untuk penerapan Lite
  • # Coral publisher/model/version Coral untuk penerapan Coral

Sebaiknya format yang berbeda dari model konseptual yang sama ini ditampilkan pada halaman model yang sama di l10n- tfhub.dev l10n. Untuk mengaitkan penerapan TF.js, TFLite, atau Coral tertentu ke model TensorFlow SavedModel, tentukan tag model induk:

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

Terkadang Anda mungkin ingin memublikasikan satu atau beberapa penerapan tanpa TensorFlow SavedModel. Dalam hal ini, Anda harus membuat model Placeholder dan menentukan pegangannya di tag parent-model . Penurunan harga placeholder identik dengan penurunan harga model TensorFlow, kecuali bahwa baris pertama adalah: # Placeholder publisher/model/version placeholder dan tidak memerlukan properti asset-path aset.

Model properti metadata khusus penurunan harga

File penurunan harga dapat berisi properti metadata. Ini digunakan untuk menyediakan filter dan tag untuk membantu pengguna menemukan model Anda. Atribut metadata disertakan sebagai komentar penurunan harga setelah deskripsi singkat dari file penurunan harga, mis

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

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

Properti metadata berikut ini didukung:

  • format : Untuk model TensorFlow: format TensorFlow Hub dari model. Nilai yang valid adalah hub saat model diekspor melalui format hub TF1 lawas atau saved_model_2 saat model diekspor melalui Model Tersimpan TF2 .
  • asset-path : jalur jarak jauh yang dapat dibaca dunia ke aset model aktual yang akan diupload, seperti ke keranjang Google Cloud Storage. URL harus diizinkan untuk diambil oleh file robots.txt (untuk alasan ini, "https://github.com/. /releases/download/. " tidak didukung karena dilarang oleh https://github .com/robots.txt ). Lihat di bawah untuk informasi lebih lanjut tentang jenis dan konten file yang diharapkan.
  • parent-model : Untuk model TF.js/TFLite/Coral: pegangan SavedModel/Placeholder yang menyertainya
  • fine-tunable : Boolean, apakah model dapat disetel dengan baik oleh pengguna.
  • task : domain masalah, misalnya "penyematan teks". Semua nilai yang didukung didefinisikan dalam task.yaml .
  • dataset : kumpulan data tempat model dilatih, misalnya "wikipedia". Semua nilai yang didukung ditentukan dalam dataset.yaml .
  • network-architecture : arsitektur jaringan yang menjadi dasar model, misalnya "mobilenet-v3". Semua nilai yang didukung didefinisikan dalam network_architecture.yaml .
  • language : kode bahasa dari bahasa tempat model teks dilatih, misalnya "en". Semua nilai yang didukung didefinisikan dalam language.yaml .
  • license : Lisensi yang berlaku untuk model, misalnya "mit". Lisensi default yang diasumsikan untuk model yang diterbitkan adalah Lisensi Apache 2.0 . Semua nilai yang didukung didefinisikan dalam license.yaml . Perhatikan bahwa lisensi custom akan memerlukan pertimbangan khusus kasus per kasus.
  • colab : URL HTTPS ke notebook yang menunjukkan bagaimana model dapat digunakan atau dilatih ( contoh untuk bigbigan-resnet50 ). Harus mengarah ke colab.research.google.com . Perhatikan bahwa notebook Jupyter yang dihosting di GitHub dapat diakses melalui <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 ke situs web yang menunjukkan bagaimana model TF.js dapat digunakan ( contoh untuk posenet ).
  • interactive-visualizer : nama visualizer yang harus disematkan pada halaman model, misalnya "vision". Menampilkan visualizer memungkinkan pengguna menjelajahi prediksi model secara interaktif. Semua nilai yang didukung didefinisikan dalam interactive_visualizer.yaml .

Jenis dokumentasi penurunan harga mendukung berbagai properti metadata wajib dan opsional:

Jenis Yg dibutuhkan Opsional
Penerbit
Koleksi tugas kumpulan data, bahasa, arsitektur jaringan
Tempat penampung tugas dataset, fine-tunable, visualisator interaktif, bahasa, lisensi, arsitektur jaringan
Model Tersimpan jalur aset, tugas, dapat disesuaikan dengan baik, format colab, kumpulan data, visualisator interaktif, bahasa, lisensi, arsitektur jaringan
Tfjs jalur aset, model induk colab, demo, visualisator interaktif
ringan jalur aset, model induk colab, visualisator interaktif
Karang jalur aset, model induk colab, visualisator interaktif

Konten aset khusus model

Bergantung pada tipe model, tipe file dan konten berikut diharapkan:

  • SavedModel: arsip tar.gz yang berisi konten seperti:
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: arsip tar.gz yang berisi konten seperti:
tf_js_model.tar.gz
├── group*
├── *.json
├── *.txt
└── *.pb
  • TFLite: file .tflite
  • Karang: file .tflite

Untuk arsip tar.gz: dengan asumsi file model Anda berada di direktori my_model (mis my_model/saved_model.pb untuk SavedModels atau my_model/model.json untuk model TF.js), Anda dapat membuat arsip tar.gz yang valid menggunakan alat tar melalui cd my_model && tar -czvf ../model.tar.gz * .

Umumnya, semua file dan direktori (apakah terkompresi atau tidak terkompresi) harus dimulai dengan karakter kata jadi misalnya titik bukan awalan nama file/direktori yang valid.

Format penurunan harga halaman koleksi

Koleksi adalah fitur l10n- tfhub.dev l10n yang memungkinkan penerbit menggabungkan model terkait untuk meningkatkan pengalaman penelusuran pengguna.

Lihat daftar semua koleksi di l10n-tfhub.dev l10n.

Lokasi yang benar untuk file koleksi di repositori github.com/tensorflow/ l10ntfhub.dev l10n adalah assets/docs / publisher_name> /collections/ <collection_name> / 1 .md

Berikut adalah contoh minimal yang akan masuk ke assets/docs/ vtab /collections/ benchmark / 1 .md. Perhatikan bahwa nama koleksi di baris pertama tidak termasuk collections/ bagian yang termasuk dalam jalur file.

# 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://tfhub.dev/vtab/sup-100/1)   |
| [vtab/rotation/1](https://tfhub.dev/vtab/rotation/1) |
|------------------------------------------------------|

Contoh menentukan nama koleksi, deskripsi singkat satu kalimat, metadata domain masalah, dan dokumentasi penurunan harga bentuk bebas.