Escrever documentação

Para contribuir para tfhub.dev, a documentação no formato Markdown deve ser fornecida. Para obter uma visão geral completa do processo de contribuição de modelos paratfhub.dev, consulte o guia de modelo de contribuição .

Tipos de documentação Markdown

Existem 3 tipos de documentação Markdown usados ​​em tfhub.dev:

• Publisher Markdown - informações sobre um editor ( consulte a sintaxe markdown )
• Model Markdown - informações sobre um modelo específico e como usá-lo ( consulte a sintaxe markdown )
• Collection Markdown - contém informações sobre uma coleção de modelos definida pelo editor ( consulte a sintaxe de markdown )

organização de conteúdo

A seguinte organização de conteúdo é necessária ao contribuir para o repositório TensorFlow Hub GitHub :

• cada diretório do editor está no diretório assets/docs
• cada diretório do editor contém models opcionais e diretórios collections
• cada modelo deve ter seu próprio diretório em assets/docs/<publisher_name>/models
• cada coleção deve ter seu próprio diretório em assets/docs/<publisher_name>/collections

As remarcações do editor não têm versão, enquanto os modelos podem ter versões diferentes. Cada versão do modelo requer um arquivo Markdown separado com o nome da versão que ele descreve (ou seja, 1.md, 2). As coleções são versionadas, mas apenas uma única versão (1) é suportada.

Todas as versões de modelo para um determinado modelo devem estar localizadas no diretório do modelo.

Abaixo está uma ilustração de como o conteúdo do Markdown é organizado:

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

Formato de remarcação do editor

A documentação do publicador é declarada no mesmo tipo de arquivo markdown que os modelos, com pequenas diferenças sintáticas.

O local correto para o arquivo publicador no repositório TensorFlow Hub é: tfhub.dev/assets/docs /<publisher_id>/<publisher_id.md>

Consulte o exemplo mínimo de documentação do editor para o editor "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.

O exemplo acima especifica o ID do editor, o nome do editor, o caminho para o ícone a ser usado e uma documentação de markdown de formato livre mais longa. Observe que o ID do editor deve conter apenas letras minúsculas, dígitos e hífens.

Diretriz de nome do editor

Seu nome de editor pode ser seu nome de usuário do GitHub ou o nome da organização do GitHub que você gerencia.

Formato de marcação da página do modelo

A documentação do modelo é um arquivo Markdown com alguma sintaxe complementar. Veja o exemplo abaixo para um exemplo mínimo ou um arquivo Markdown de exemplo mais realista .

Exemplo de documentação

Uma documentação de modelo de alta qualidade contém trechos de código, informações sobre como o modelo foi treinado e uso pretendido. Você também deve usar as propriedades de metadados específicas do modelo explicadas abaixo para que os usuários possam encontrar seus modelos em tfhub.dev mais rapidamente.

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

Modelar implantações e agrupar implantações

tfhub.dev permite publicar implementações TF.js, TFLite e Coral de um SavedModel do TensorFlow.

A primeira linha do arquivo Markdown deve especificar o tipo do formato:

• # Module publisher/model/version para SavedModels
• # Tfjs publisher/model/version para implantações TF.js
• # Lite publisher/model/version para implantações Lite
• # Coral publisher/model/version para implementações Coral

É uma boa ideia que esses diferentes formatos do mesmo modelo conceitual apareçam na mesma página de modelo em tfhub.dev. Para associar uma determinada implantação de TF.js, TFLite ou Coral a um modelo TensorFlow SavedModel, especifique a tag parent-model:

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

Às vezes, você pode querer publicar uma ou mais implantações sem um TensorFlow SavedModel. Nesse caso, você precisará criar um modelo Placeholder e especificar seu identificador na tag parent-model . O markdown de marcador de posição é idêntico ao Markdown de modelo do TensorFlow, exceto que a primeira linha é: # Placeholder publisher/model/version e não requer a propriedade asset-path .

Propriedades de metadados específicas do Model Markdown

Os arquivos Markdown podem conter propriedades de metadados. Eles são usados ​​para fornecer filtros e tags para ajudar os usuários a encontrar seu modelo. Os atributos de metadados são incluídos como comentários Markdown após a breve descrição do arquivo Markdown, por exemplo

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

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

As seguintes propriedades de metadados são suportadas:

• format : para modelos do TensorFlow: o formato TensorFlow Hub do modelo. Os valores válidos são hub quando o modelo foi exportado por meio do formato de hub legado TF1 ou saved_model_2 quando o modelo foi exportado por meio de um TF2 Saved Model .
• asset-path : o caminho remoto legível para os ativos de modelo reais a serem carregados, como um bucket do Google Cloud Storage. O URL deve ser obtido pelo arquivo robots.txt (por esse motivo, "https://github.com/. /releases/download/. " não é suportado, pois é proibido por https://github .com/robots.txt ). Veja abaixo mais informações sobre o tipo de arquivo e o conteúdo esperados.
• parent-model : Para modelos TF.js/TFLite/Coral: identificador do SavedModel/Placeholder que o acompanha
• fine-tunable : Booleano, se o modelo pode ser ajustado pelo usuário.
• task : o domínio do problema, por exemplo, "incorporação de texto". Todos os valores com suporte são definidos em task.yaml .
• dataset : o conjunto de dados no qual o modelo foi treinado, por exemplo, "wikipedia". Todos os valores compatíveis são definidos em dataset.yaml .
• network-architecture : a arquitetura de rede na qual o modelo é baseado, por exemplo, "mobilenet-v3". Todos os valores com suporte são definidos em network_architecture.yaml .
• language : o código de idioma do idioma em que um modelo de texto foi treinado, por exemplo, "en". Todos os valores com suporte são definidos em language.yaml .
• license : A licença que se aplica ao modelo, por exemplo, "mit". A licença assumida padrão para um modelo publicado é Apache 2.0 License . Todos os valores com suporte são definidos em license.yaml . Observe que a licença custom exigirá consideração especial caso a caso.
• colab : URL HTTPS para um notebook que demonstra como o modelo pode ser usado ou treinado ( exemplo para bigbigan-resnet50 ). Deve levar a colab.research.google.com . Observe que os notebooks Jupyter hospedados no GitHub podem ser acessados ​​por meio de <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 para um site que demonstra como o modelo TF.js pode ser usado ( exemplo para posenet ).
• interactive-visualizer : nome do visualizador que deve ser incorporado na página do modelo, por exemplo, "visão". A exibição de um visualizador permite que os usuários explorem as previsões do modelo interativamente. Todos os valores com suporte são definidos em Interactive_visualizer.yaml .

Os tipos de documentação do Markdown oferecem suporte a diferentes propriedades de metadados obrigatórias e opcionais:

Conteúdo de recurso específico do modelo

Dependendo do tipo de modelo, são esperados os seguintes tipos de arquivo e conteúdo:

• SavedModel: um arquivo tar.gz contendo conteúdo como este:

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: um arquivo tar.gz contendo conteúdo como este:

tf_js_model.tar.gz
├── group*
├── *.json
├── *.txt
└── *.pb

• TFLite: um arquivo .tflite
• Coral: um arquivo .tflite

Para arquivos tar.gz: supondo que seus arquivos de modelo estejam no diretório my_model (por exemplo, my_model/saved_model.pb para SavedModels ou my_model/model.json para modelos TF.js), você pode criar um arquivo tar.gz válido usando a ferramenta tar via cd my_model && tar -czvf ../model.tar.gz * .

Geralmente, todos os arquivos e diretórios (sejam compactados ou não) devem começar com um caractere de palavra, por exemplo, pontos não são prefixos válidos de nomes de arquivos/diretórios.

Formato de marcação de página de coleção

As coleções são um recurso de tfhub.dev que permite aos editores agrupar modelos relacionados para melhorar a experiência de pesquisa do usuário.

Veja a lista de todas as coleções emtfhub.dev.

O local correto para o arquivo de coleção no repositório github.com/tensorflow/tfhub.dev é assets/docs / publisher_name> /collections/ <collection_name> / 1 .md

Aqui está um exemplo mínimo que iria para assets/docs/ vtab /collections/ benchmark / 1 .md. Observe que o nome da coleção na primeira linha não inclui as collections/ parte que estão incluídas no caminho do arquivo.

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

O exemplo especifica o nome da coleção, uma descrição curta de uma frase, metadados do domínio do problema e documentação de remarcação de formato livre.