Escrever documentação

Para contribuir com 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 para tfhub.devconsulte o guia para contribuir com um modelo .

Tipos de documentação do Markdown

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

Organização de conteúdo

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

  • 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 são versionadas, 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 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 de modelos.

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 editor é declarada no mesmo tipo de arquivos de remarcação que os modelos, com pequenas diferenças sintáticas.

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

Consulte o exemplo de documentação mínima 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 de página de 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 .

Documentação de exemplo

Uma documentação de modelo de alta qualidade contém trechos de código, informações sobre como o modelo foi treinado e o 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)
```

Implantações de modelo e agrupamento de implantações

tfhub.dev permite publicar implantações de 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 do módulo para SavedModels
  • # Tfjs publisher/model/version de Tfjs para implantações de TF.js
  • # Lite publisher/model/version Lite para implantações Lite
  • # Coral publisher/model/version Coral para implantaçõ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 SavedModel do TensorFlow, especifique a tag do modelo pai:

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

Às vezes, você pode querer publicar uma ou mais implantações sem um SavedModel do TensorFlow. Nesse caso, você precisará criar um modelo Placeholder e especificar seu identificador na tag parent-model . O marcador Markdown é idêntico ao Markdown do modelo 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 compatíveis:

  • format : para modelos do TensorFlow: o formato do TensorFlow Hub do modelo. Os valores válidos são hub quando o modelo foi exportado por meio do formato de hub TF1 legado ou saved_model_2 quando o modelo foi exportado por meio de um modelo salvo do TF2 .
  • asset-path : o caminho remoto legível para todos os recursos do modelo real para upload, como um bucket do Google Cloud Storage. O URL deve ter permissão para ser buscado 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 : Boolean, se o modelo pode ser ajustado pelo usuário.
  • task : o domínio do problema, por exemplo, "incorporação de texto". Todos os valores suportados são definidos em task.yaml .
  • conjunto de dataset : o conjunto de dados em que 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 se baseia, por exemplo, "mobilenet-v3". Todos os valores suportados 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 suportados são definidos em language.yaml .
  • license : A licença que se aplica ao modelo, por exemplo, "mit". A licença padrão assumida para um modelo publicado é a Licença Apache 2.0 . Todos os valores suportados 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 de forma interativa. Todos os valores suportados são definidos em interativo_visualizer.yaml .

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

Modelo Requeridos Opcional
Editor
Coleção tarefa conjunto de dados, idioma, arquitetura de rede
Espaço reservado tarefa conjunto de dados, ajuste fino, visualizador interativo, idioma, licença, arquitetura de rede
Modelo salvo caminho de ativos, tarefa, ajuste fino, formato colab, conjunto de dados, visualizador interativo, idioma, licença, arquitetura de rede
Tfjs caminho do ativo, modelo pai colab, demo, visualizador interativo
Leve caminho do ativo, modelo pai colab, visualizador interativo
Coral caminho do ativo, modelo pai colab, visualizador interativo

Conteúdo do recurso específico do modelo

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

  • SavedModel: um arquivo tar.gz contendo conteúdo assim:
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 assim:
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 (comprimidos ou descomprimidos) 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 remarcação de página de coleção

As coleções são um recurso do tfhub.dev que permite que os editores agrupem 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 entraria em assets/docs/ vtab /collections/ benchmark / 1 .md. Observe que o nome da coleção na primeira linha não inclui a parte collections/ que está incluída 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 de domínio do problema e documentação de markdown de formato livre.