Guida allo stile del codice TensorFlow

Stile pitone

Segui la guida allo stile Python PEP 8 , tranne per il fatto che TensorFlow utilizza 2 spazi anziché 4. Conformati alla guida allo stile Python di Google e utilizza pylint per verificare le modifiche apportate a Python.

pilinto

Per installare pylint :

$ pip install pylint

Per controllare un file con pylint dalla directory root del codice sorgente di TensorFlow: 

$ pylint --rcfile=tensorflow/tools/ci_build/pylintrc tensorflow/python/keras/losses.py

Versioni Python supportate

Per le versioni Python supportate, consulta la guida all'installazione di TensorFlow.

Consulta lo stato delle build continue di TensorFlow per le build ufficiali e supportate dalla community.

Stile di codifica C++

Le modifiche al codice C++ di TensorFlow devono essere conformi alla Guida allo stile di Google C++ e ai dettagli di stile specifici di TensorFlow . Usa clang-format per controllare le modifiche C/C++.

Per installare su Ubuntu 16+, esegui:

$ apt-get install -y clang-format

Puoi controllare il formato di un file C/C++ con quanto segue: 

$ clang-format <my_cc_file> --style=google > /tmp/my_cc_file.cc
$ diff <my_cc_file> /tmp/my_cc_file.cc

Altre lingue

Convenzioni TensorFlow e usi speciali

Operazioni Python

Un'operazione TensorFlow è una funzione che, dati i tensori di input, restituisce tensori di output (o aggiunge un'operazione a un grafico durante la creazione di grafici).

  • Il primo argomento dovrebbe essere tensori, seguito dai parametri Python di base. L'ultimo argomento è name con il valore predefinito None .
  • Gli argomenti tensoriali dovrebbero essere un singolo tensore o un iterabile di tensori. Cioè, un "Tensore o elenco di Tensori" è troppo ampio. Vedi assert_proper_iterable .
  • Le operazioni che accettano tensori come argomenti dovrebbero chiamare convert_to_tensor per convertire input non tensori in tensori se utilizzano operazioni C++. Si noti che gli argomenti sono ancora descritti come un oggetto Tensor di un dtype specifico nella documentazione.
  • Ogni operazione Python dovrebbe avere un name_scope . Come visto di seguito, passa il nome dell'operazione come una stringa.
  • Le operazioni dovrebbero contenere un commento Python completo con dichiarazioni Args e Returns che spieghino sia il tipo che il significato di ciascun valore. Eventuali forme, dtype o ranghi dovrebbero essere specificati nella descrizione. Vedi i dettagli della documentazione.
  • Per una maggiore usabilità, includi un esempio di utilizzo con input/output dell'operazione nella sezione Esempio.
  • Evitare di fare un uso esplicito di tf.Tensor.eval o tf.Session.run . Ad esempio, per scrivere la logica che dipende dal valore Tensor, utilizzare il flusso di controllo TensorFlow. In alternativa, limitare l'esecuzione dell'operazione solo quando è abilitata l'esecuzione entusiasta ( tf.executing_eagerly() ).

Esempio:

def my_op(tensor_in, other_tensor_in, my_param, other_param=0.5,
          output_collections=(), name=None):
  """My operation that adds two tensors with given coefficients.

  Args:
    tensor_in: `Tensor`, input tensor.
    other_tensor_in: `Tensor`, same shape as `tensor_in`, other input tensor.
    my_param: `float`, coefficient for `tensor_in`.
    other_param: `float`, coefficient for `other_tensor_in`.
    output_collections: `tuple` of `string`s, name of the collection to
                        collect result of this op.
    name: `string`, name of the operation.

  Returns:
    `Tensor` of same shape as `tensor_in`, sum of input values with coefficients.

  Example:
    >>> my_op([1., 2.], [3., 4.], my_param=0.5, other_param=0.6,
              output_collections=['MY_OPS'], name='add_t1t2')
    [2.3, 3.4]
  """
  with tf.name_scope(name or "my_op"):
    tensor_in = tf.convert_to_tensor(tensor_in)
    other_tensor_in = tf.convert_to_tensor(other_tensor_in)
    result = my_param * tensor_in + other_param * other_tensor_in
    tf.add_to_collection(output_collections, result)
    return result

Utilizzo:

output = my_op(t1, t2, my_param=0.5, other_param=0.6,
               output_collections=['MY_OPS'], name='add_t1t2')