مستندات را بنویسید

برای مشارکت در tfhub.dev، باید اسنادی در قالب Markdown ارائه شود. برای یک نمای کلی از روند ارائه مدل‌ها بهtfhub.dev، به راهنمای مدل مشارکت مراجعه کنید.

انواع اسناد Markdown

3 نوع سند Markdown در tfhub.devاستفاده می شود:

سازماندهی محتوا

سازماندهی محتوای زیر هنگام مشارکت در مخزن TensorFlow Hub GitHub مورد نیاز است:

  • هر دایرکتوری ناشر در فهرست assets/docs است
  • هر فهرست ناشر شامل models اختیاری و دایرکتوری های collections است
  • هر مدل باید دایرکتوری خود را تحت assets/docs/<publisher_name>/models داشته باشد
  • هر مجموعه باید دایرکتوری خود را تحت assets/docs/<publisher_name>/collections داشته باشد.

نشانه‌گذاری‌های ناشر بدون نسخه هستند، در حالی که مدل‌ها می‌توانند نسخه‌های متفاوتی داشته باشند. هر نسخه مدل نیاز به یک فایل Markdown جداگانه دارد که به نام نسخه ای که توضیح می دهد (یعنی 1.md، 2) نامگذاری شده است. مجموعه ها نسخه بندی شده اند اما تنها یک نسخه (1) پشتیبانی می شود.

تمام نسخه های مدل برای یک مدل معین باید در فهرست راهنمای مدل قرار گیرند.

در زیر تصویری از نحوه سازماندهی محتوای 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>
│   └── ...
└── ...

قالب نشانه گذاری ناشر

اسناد ناشر در همان نوع فایل‌های نشانه‌گذاری مدل‌ها، با تفاوت‌های نحوی جزئی، اعلام می‌شوند.

مکان صحیح فایل ناشر در مخزن TensorFlow Hub این است: tfhub.dev/assets/docs /<publisher_id>/<publisher_id.md>

نمونه حداقل مستندات ناشر را برای ناشر "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.

مثال بالا شناسه ناشر، نام ناشر، مسیر آیکون مورد استفاده و مستندات علامت گذاری با فرم آزاد طولانی تر را مشخص می کند. توجه داشته باشید که شناسه ناشر فقط باید دارای حروف کوچک، ارقام و خط فاصله باشد.

راهنمای نام ناشر

نام ناشر شما می تواند نام کاربری GitHub یا نام سازمان GitHub باشد که مدیریت می کنید.

قالب علامت گذاری صفحه مدل

مستندات مدل یک فایل Markdown با برخی دستورات افزودنی است. مثال زیر را برای نمونه حداقل یا یک مثال واقعی تر از فایل Markdown ببینید.

نمونه مستندات

مستندات مدل با کیفیت بالا حاوی قطعات کد، اطلاعات نحوه آموزش مدل و استفاده مورد نظر است. همچنین باید از ویژگی‌های فراداده مخصوص مدل که در زیر توضیح داده شده است استفاده کنید تا کاربران بتوانند مدل‌های شما را در tfhub.dev سریع‌تر پیدا کنند.

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

استقرار مدل و گروه بندی استقرار با هم

tfhub.dev امکان انتشار TF.js، TFLite و Coral را از TensorFlow SavedModel می دهد.

خط اول فایل Markdown باید نوع قالب را مشخص کند:

  • # Module publisher/model/version برای SavedModels
  • # Tfjs publisher/model/version برای استقرار TF.js
  • # Lite publisher/model/version برای استقرار Lite
  • # Coral publisher/model/version برای استقرار مرجانی

این ایده خوبی است که این قالب‌های مختلف از یک مدل مفهومی در یک صفحه مدل در tfhub.devنشان داده شوند. برای مرتبط کردن یک استقرار TF.js، TFLite یا Coral به یک مدل TensorFlow SavedModel، تگ والد-مدل را مشخص کنید:

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

گاهی اوقات ممکن است بخواهید یک یا چند استقرار را بدون TensorFlow SavedModel منتشر کنید. در این صورت، باید یک مدل Placeholder ایجاد کنید و دسته آن را در تگ parent-model مشخص کنید. مکان‌نما Markdown با مدل TensorFlow Markdown یکسان است، با این تفاوت که خط اول عبارت است از: # Placeholder publisher/model/version و به ویژگی asset-path نیاز ندارد.

ویژگی های فراداده خاص Markdown را مدل کنید

فایل‌های Markdown می‌توانند حاوی ویژگی‌های ابرداده باشند. اینها برای ارائه فیلترها و برچسب ها برای کمک به کاربران برای یافتن مدل شما استفاده می شوند. ویژگی های فراداده به عنوان نظرات Markdown پس از توضیحات کوتاه فایل Markdown گنجانده شده است، به عنوان مثال

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

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

ویژگی های ابرداده زیر پشتیبانی می شوند:

  • format : برای مدل های TensorFlow: قالب TensorFlow Hub مدل. مقادیر hub زمانی که مدل از طریق فرمت هاب قدیمی TF1 صادر شده باشد، یا زمانی که مدل از طریق یک مدل ذخیره شده TF2 صادر شده است saved_model_2 .
  • asset-path : مسیر راه دور قابل خواندن جهان به دارایی‌های مدل واقعی برای آپلود، مانند سطل فضای ذخیره‌سازی Google Cloud. URL باید توسط فایل robots.txt واکشی شود (به همین دلیل، "https://github.com/. /releases/download/. " پشتیبانی نمی شود، زیرا https://github ممنوع شده است. .com/robots.txt ). برای اطلاعات بیشتر در مورد نوع فایل مورد انتظار و محتوای زیر را ببینید.
  • parent-model : برای مدل‌های TF.js/TFLite/Coral: دسته SavedModel/Placeholder همراه
  • fine-tunable : Boolean، اینکه آیا مدل می تواند توسط کاربر تنظیم شود یا خیر.
  • task : دامنه مشکل، به عنوان مثال "جاسازی متن". همه مقادیر پشتیبانی شده در task.yaml تعریف شده اند.
  • dataset : مجموعه داده ای که مدل روی آن آموزش داده شده است، به عنوان مثال "ویکی پدیا". همه مقادیر پشتیبانی شده در dataset.yaml تعریف شده اند.
  • network-architecture : معماری شبکه ای که مدل مبتنی بر آن است، به عنوان مثال "mobilenet-v3". همه مقادیر پشتیبانی شده در network_architecture.yaml تعریف شده اند.
  • language : کد زبان زبانی که یک مدل متنی روی آن آموزش داده شده است، به عنوان مثال "en". همه مقادیر پشتیبانی شده در language.yaml تعریف شده اند.
  • license : مجوزی که برای مدل اعمال می شود، به عنوان مثال "mit". مجوز پیش فرض فرض شده برای یک مدل منتشر شده مجوز Apache 2.0 است. همه مقادیر پشتیبانی شده در License.yaml تعریف شده اند. توجه داشته باشید که مجوز custom مورد به مورد به بررسی خاصی نیاز دارد.
  • colab : نشانی وب HTTPS به یک نوت بوک که نحوه استفاده یا آموزش مدل را نشان می دهد ( مثال برای bigbigan-resnet50 ). باید به colab.research.google.com منتهی شود. توجه داشته باشید که از طریق <a href="https://colab.research.google.com/github/ORGANIZATION/PROJECT/">https://colab.research.google.com/github/ORGANIZATION/PROJECT/</a> blob/master/.../my_notebook.ipynb می‌توانید به نوت‌بوک‌های Jupyter میزبانی شده در GitHub دسترسی داشته باشید. <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 : نشانی وب HTTPS به وب‌سایتی که نحوه استفاده از مدل TF.js را نشان می‌دهد ( مثلاً برای posenet ).
  • interactive-visualizer : نام ویژوالایزر که باید در صفحه مدل تعبیه شود، به عنوان مثال "Vision". نمایش یک ویژوالایزر به کاربران اجازه می دهد تا پیش بینی های مدل را به صورت تعاملی بررسی کنند. همه مقادیر پشتیبانی شده در interactive_visualizer.yaml تعریف شده اند.

انواع اسناد Markdown از ویژگی های مختلف فراداده مورد نیاز و اختیاری پشتیبانی می کنند:

تایپ کنید ضروری اختیاری
ناشر
مجموعه وظیفه مجموعه داده، زبان، معماری شبکه
جای جای وظیفه مجموعه داده، تنظیم دقیق، تعاملی-بصری، زبان، مجوز، معماری شبکه
SavedModel مسیر دارایی، وظیفه، قابل تنظیم، قالب colab، مجموعه داده، تعاملی-ویژوالایزر، زبان، مجوز، شبکه-معماری
Tfjs مسیر دارایی، مدل والد colab، نسخه ی نمایشی، تعاملی-Visualizer
ساده مسیر دارایی، مدل والد colab، تعاملی-بصری
مرجان مسیر دارایی، مدل والد colab، تعاملی-بصری

محتوای دارایی خاص مدل

بسته به نوع مدل، انواع فایل و محتویات زیر مورد انتظار است:

  • SavedModel: یک بایگانی tar.gz حاوی مطالبی مانند:
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: یک بایگانی tar.gz حاوی محتوایی مانند:
tf_js_model.tar.gz
├── group*
├── *.json
├── *.txt
└── *.pb
  • TFLite: یک فایل tflite
  • Coral: یک فایل tflite

برای بایگانی‌های tar.gz: با فرض اینکه فایل‌های مدل شما در دایرکتوری my_model هستند (مثلا my_model/saved_model.pb برای SavedModels یا my_model/model.json برای مدل‌های TF.js)، می‌توانید با استفاده از ابزار tar یک بایگانی معتبر tar.gz ایجاد کنید. از طریق cd my_model && tar -czvf ../model.tar.gz * .

به طور کلی، همه فایل‌ها و فهرست‌ها (چه فشرده یا غیرفشرده) باید با یک کاراکتر کلمه شروع شوند، به‌طور مثال، نقطه‌ها پیشوند معتبر نام فایل/دایرکتوری‌ها نیستند.

قالب نشانه گذاری صفحه مجموعه

مجموعه‌ها یکی از ویژگی‌های tfhub.dev هستند که به ناشران امکان می‌دهد مدل‌های مرتبط را با هم ترکیب کنند تا تجربه جستجوی کاربر را بهبود بخشند.

فهرست همه مجموعه‌ها را درtfhub.devببینید.

مکان صحیح فایل مجموعه در مخزن github.com/tensorflow/tfhub.dev assets /docs / publisher_name> /collections_name/> < collection است. .md

در اینجا یک نمونه حداقلی وجود دارد که به assets/docs/ vtab /collections/ benchmark / 1.md می‌رود. توجه داشته باشید که نام مجموعه در سطر اول شامل collections/ قسمتی که در مسیر فایل موجود است نمی باشد.

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

این مثال نام مجموعه، شرح کوتاه یک جمله ای، فراداده دامنه مشکل و مستندات علامت گذاری فرم آزاد را مشخص می کند.