اكتب الوثائق

للمساهمة في tfhub.dev، يجب تقديم وثائق بتنسيق Markdown. للحصول على نظرة عامة كاملة حول عملية مساهمة النماذج فيtfhub.dev، راجع المساهمة بدليل نموذج .

أنواع وثائق Markdown

هناك ثلاثة أنواع من وثائق Markdown المستخدمة في tfhub.dev:

• Publisher Markdown - معلومات حول الناشر ( انظر بناء الجملة Markdown )
• Model Markdown - معلومات حول نموذج معين وكيفية استخدامه ( انظر بناء الجملة markdown )
• Collection Markdown - يحتوي على معلومات حول مجموعة من النماذج التي يحددها الناشر ( انظر بناء جملة markdown )

تنظيم المحتوى

يلزم تنظيم المحتوى التالي عند المساهمة في مستودع GitHub TensorFlow Hub :

• يوجد كل دليل ناشر في دليل 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>
│   └── ...
└── ...

تنسيق تخفيض الناشر

يتم الإعلان عن وثائق الناشر في نفس النوع من ملفات markdown مثل النماذج ، مع اختلافات نحوية طفيفة.

الموقع الصحيح لملف الناشر في TensorFlow Hub repo هو: tfhub.dev/ أصول / مستندات / <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. في هذه الحالة ، ستحتاج إلى إنشاء نموذج عنصر نائب وتحديد مقبضه في علامة 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 القديم أو saved_model_2 عندما تم تصدير النموذج عبر نموذج TF2 محفوظ .
• asset-path : المسار البعيد المقروء عالميًا إلى أصول النموذج الفعلية المراد تحميلها ، مثل حاوية Google Cloud Storage. يجب السماح بجلب عنوان URL من ملف robots.txt (لهذا السبب ، "https://github.com/. / release / download /. " غير مدعوم لأنه ممنوع بواسطة https: // github .com / robots.txt ). انظر أدناه للحصول على مزيد من المعلومات حول نوع الملف المتوقع والمحتوى.
• parent-model : لنماذج TF.js / TFLite / Coral: مقبض الموديل SavedModel / Placeholder المصاحب
• fine-tunable : منطقي ، ما إذا كان يمكن للمستخدم ضبط النموذج.
• task : مجال المشكلة ، على سبيل المثال "تضمين النص". يتم تحديد جميع القيم المدعومة في Task.yaml .
• dataset : مجموعة البيانات التي تم تدريب النموذج عليها ، على سبيل المثال "ويكيبيديا". يتم تحديد جميع القيم المدعومة في dataset.yaml .
• network-architecture : بنية الشبكة التي يعتمد عليها النموذج ، على سبيل المثال "mobilenet-v3". يتم تحديد جميع القيم المدعومة في network_architecture.yaml .
• language : رمز اللغة للغة التي تم تدريب نموذج النص عليها ، على سبيل المثال "en". يتم تحديد جميع القيم المدعومة في language.yaml .
• license : الترخيص الذي ينطبق على النموذج ، على سبيل المثال "MIT". الترخيص الافتراضي المفترض للنموذج المنشور هو ترخيص Apache 2.0 . يتم تحديد جميع القيم المدعومة في ترخيص. yaml . لاحظ أن الترخيص custom سيتطلب اعتبارات خاصة لكل حالة على حدة.
• colab : عنوان URL لـ HTTPS لجهاز كمبيوتر محمول يوضح كيفية استخدام النموذج أو تدريبه (على سبيل المثال bigbigan-resnet50 ). يجب أن يؤدي إلى colab.research.google.com . لاحظ أنه يمكن الوصول إلى دفاتر 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 : عنوان URL لـ HTTPS لموقع ويب يوضح كيفية استخدام نموذج TF.js ( مثال لـ posenet ).
• interactive-visualizer : اسم المتخيل الذي يجب تضمينه في صفحة النموذج ، على سبيل المثال "الرؤية". يتيح عرض متخيل للمستخدمين استكشاف تنبؤات النموذج بشكل تفاعلي. يتم تحديد جميع القيم المدعومة في Interactive_visualizer.yaml .

تدعم أنواع وثائق Markdown خصائص البيانات الوصفية المختلفة المطلوبة والاختيارية:

محتوى الأصول الخاص بالنموذج

بناءً على نوع النموذج ، من المتوقع أن تكون أنواع الملفات والمحتويات التالية:

• 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
• كورال: ملف tflite

بالنسبة لأرشيفات tar.gz: بافتراض أن ملفات النموذج موجودة في الدليل my_model (على سبيل المثال ، my_model/saved_model.pb لـ SavedModels أو my_model/model.json لنماذج TF.js) ، يمكنك إنشاء أرشيف tar.gz صالح باستخدام أداة tar عبر cd my_model && tar -czvf ../model.tar.gz * .

بشكل عام ، يجب أن تبدأ جميع الملفات والمجلدات (سواء كانت مضغوطة أو غير مضغوطة) بحرف كلمة ، على سبيل المثال ، النقاط ليست بادئة صالحة لأسماء / أدلة الملفات.

تنسيق تخفيض صفحة المجموعة

المجموعات هي إحدى ميزات tfhub.dev التي تمكن الناشرين من تجميع النماذج ذات الصلة معًا لتحسين تجربة بحث المستخدم.

راجع قائمة كل المجموعات علىtfhub.dev.

الموقع الصحيح لملف المجموعة في المستودع github.com/tensorflow/tfhub.dev هو الأصول / docs / publisher_name> / collections / <collection_name> / 1 .md

في ما يلي مثال بسيط يمكن أن يدخل في الأصول / 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) |
|------------------------------------------------------|

يحدد المثال اسم المجموعة ، ووصفًا قصيرًا لجملة واحدة ، وبيانات وصفية لمجال المشكلة ، ووثائق تخفيض السعر الحر.