כתוב תיעוד

קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

כדי לתרום ל- 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 . ה-placeholder Markdown זהה ל-Markdown של מודל TensorFlow, אלא שהשורה הראשונה היא: # 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 Saved Model .
  • asset-path : הנתיב המרוחק הניתן לקריאה בעולם לנכסי הדגם האמיתיים להעלאה, כגון לדלי של Google Cloud Storage. יש לאפשר את שליפת כתובת האתר על ידי קובץ robots.txt (מסיבה זו, "https://github.com/. /releases/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 License . כל הערכים הנתמכים מוגדרים ב- licence.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 : שם הוויזואליזר שאמור להיות מוטבע בדף הדגם, למשל "vision". הצגת מכשיר חזותי מאפשרת למשתמשים לחקור את התחזיות של המודל באופן אינטראקטיבי. כל הערכים הנתמכים מוגדרים ב- interactive_visualizer.yaml .

סוגי התיעוד של Markdown תומכים במאפייני מטא נתונים נדרשים ואופציונליים שונים:

סוּג נדרש אופציונאלי
מוֹצִיא לָאוֹר
אוסף מְשִׁימָה מערך נתונים, שפה, ארכיטקטורת רשת
מציין מקום מְשִׁימָה מערך נתונים, ניתן לכוונון עדין, אינטראקטיבי-חזותי, שפה, רישיון, ארכיטקטורת רשת
SavedModel asset-path, task, fine-tunable, format colab, מערך נתונים, אינטראקטיבי-חזותי, שפה, רישיון, ארכיטקטורת רשת
Tfjs נכס-נתיב, אב-מודל colab, הדגמה, אינטראקטיבי-חזותי
לייט נכס-נתיב, אב-מודל 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
  • קורל: קובץ 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 הוא assets/docs / publisher_name> /collections/ <collection_name> / 1 .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) |
|------------------------------------------------------|

הדוגמה מציינת את שם האוסף, תיאור קצר של משפט אחד, מטא נתונים של תחום בעיה ותיעוד סימון בפורמט חופשי.