Ta strona została przetłumaczona przez Cloud Translation API.

Weź udział w dokumentacji interfejsu API TensorFlow

Testowalne dokumenty

TensorFlow używa DocTest do testowania fragmentów kodu w dokumentach Pythona. Fragment musi być wykonywalnym kodem Pythona. Aby umożliwić testowanie, dodaj wiersz >>> (trzy lewe nawiasy ostrokątne). Na przykład oto fragment funkcji tf.concat w pliku źródłowym array_ops.py :

def concat(values, axis, name="concat"):
  """Concatenates tensors along one dimension.
  ...

  >>> t1 = [[1, 2, 3], [4, 5, 6]]
  >>> t2 = [[7, 8, 9], [10, 11, 12]]
  >>> concat([t1, t2], 0)
  <tf.Tensor: shape=(4, 3), dtype=int32, numpy=
  array([[ 1,  2,  3],
         [ 4,  5,  6],
         [ 7,  8,  9],
         [10, 11, 12]], dtype=int32)>

  <... more description or code snippets ...>

  Args:
    values: A list of `tf.Tensor` objects or a single `tf.Tensor`.
    axis: 0-D `int32` `Tensor`.  Dimension along which to concatenate. Must be
      in the range `[-rank(values), rank(values))`. As in Python, indexing for
      axis is 0-based. Positive axis in the rage of `[0, rank(values))` refers
      to `axis`-th dimension. And negative axis refers to `axis +
      rank(values)`-th dimension.
    name: A name for the operation (optional).

    Returns:
      A `tf.Tensor` resulting from concatenation of the input tensors.
  """

  <code here>

Aby ocenić jakość dokumentacji referencyjnej, zobacz przykładową sekcję porady dotyczącej dokumentów API TensorFlow 2 . (Pamiętaj, że moduł śledzenia zadań na tym arkuszu nie jest już używany.)

Spraw, aby kod był testowalny za pomocą DocTest

Obecnie wiele dokumentów używa znaczników wstecznych (```) do identyfikacji kodu. Aby kod można było testować za pomocą DocTest:

Usuń tylne znaczniki (```) i użyj lewych nawiasów (>>>) przed każdą linią. Użyj (...) przed liniami ciągłymi.
Dodaj znak nowej linii, aby oddzielić fragmenty DocTest od tekstu Markdown, aby poprawnie renderować na tensorflow.org.

Dostosowania

TensorFlow wykorzystuje kilka dostosowań wbudowanej logiki doctest:

Nie porównuje wartości zmiennoprzecinkowych jako tekstu: Wartości zmiennoprzecinkowe są wyodrębniane z tekstu i porównywane przy użyciu allclose z liberalnymi tolerancjami atol i rtol . Pozwala to na:
- Przejrzystsza dokumentacja — autorzy nie muszą podawać wszystkich miejsc po przecinku.
- Bardziej niezawodne testy — zmiany numeryczne w podstawowej implementacji nigdy nie powinny powodować niepowodzenia dokumentu.
Sprawdza dane wyjściowe tylko wtedy, gdy autor umieścił dane wyjściowe dla wiersza. Pozwala to na uzyskanie jaśniejszych dokumentów, ponieważ autorzy zwykle nie muszą przechwytywać nieistotnych wartości pośrednich, aby zapobiec ich wydrukowaniu.

Uwagi dotyczące dokumentacji

Ogólnie : celem doctest jest dostarczenie dokumentacji i potwierdzenie, że dokumentacja działa. Różni się to od testów jednostkowych. Więc:
- Staraj się, aby przykłady były proste.
- Unikaj długich lub skomplikowanych wyników.
- Jeśli to możliwe, używaj okrągłych liczb.
Format wyjściowy : dane wyjściowe fragmentu muszą znajdować się bezpośrednio pod kodem generującym dane wyjściowe. Ponadto wynik w dokumencie musi być dokładnie równy wynikowi po wykonaniu kodu. Zobacz powyższy przykład. Sprawdź także tę część w dokumentacji DocTest. Jeśli wynik przekracza limit 80 linii, możesz umieścić dodatkowe wyjście w nowej linii, a DocTest to rozpozna. Zobacz na przykład bloki wieloliniowe poniżej.
Globals : Moduły `tf` , np i os są zawsze dostępne w DocTest TensorFlow.
Użyj symboli : W DocTest możesz uzyskać bezpośredni dostęp do symboli zdefiniowanych w tym samym pliku. Aby użyć symbolu, który nie jest zdefiniowany w bieżącym pliku, użyj publicznego interfejsu API TensorFlow tf.xxx zamiast xxx . Jak widać w poniższym przykładzie, dostęp do `random.normal` można uzyskać poprzez `tf.random.normal` . Dzieje się tak, ponieważ `random.normal` nie jest widoczne w NewLayer .
```
def NewLayer():
  """This layer does cool stuff.

  Example usage:

  >>> x = tf.random.normal((1, 28, 28, 3))
  >>> new_layer = NewLayer(x)
  >>> new_layer
  <tf.Tensor: shape=(1, 14, 14, 3), dtype=int32, numpy=...>
  """
```
Wartości zmiennoprzecinkowe : dokument TensorFlow wyodrębnia wartości zmiennoprzecinkowe z ciągów wynikowych i porównuje przy użyciu np.allclose z rozsądnymi tolerancjami ( atol=1e-6 , rtol=1e-6 ). W ten sposób autorzy nie muszą się martwić, że zbyt precyzyjne ciągi dokumentów będą powodować awarie z powodu problemów numerycznych. Po prostu wklej oczekiwaną wartość.

Dane wyjściowe niedeterministyczne : użyj wielokropka( ... ) dla niepewnych części, a DocTest zignoruje ten podciąg.

x = tf.random.normal((1,))
print(x)
    <tf.Tensor: shape=(1,), dtype=float32, numpy=..., dtype=float32)>

Bloki wielowierszowe : DocTest ściśle określa różnicę między instrukcją jednowierszową a instrukcją wielowierszową. Zwróć uwagę na użycie (...) poniżej:
```
if x > 0:
  print("X is positive")
model.compile(
  loss="mse",
  optimizer="adam")
    
```

Wyjątki : szczegóły wyjątku są ignorowane, z wyjątkiem zgłoszonego wyjątku. Zobacz to , aby uzyskać więcej szczegółów.

np_var = np.array([1, 2])
tf.keras.backend.is_keras_tensor(np_var)
    Traceback (most recent call last):

    ValueError: Unexpectedly found an instance of type `<class 'numpy.ndarray'>`.

Użyj lokalnej kopii projektu tf-doctest.

Niektóre interfejsy API w TensorFlow pochodzą z projektu zewnętrznego:

tf.estimator (z tensorflow_estimator )
tf.summary tablica tensorowa )
tf.keras.preprocessing (z keras-preprocessing )

Jeśli pracujesz nad projektem zewnętrznym lub nad interfejsami API TensorFlow znajdującymi się w projekcie zewnętrznym, te instrukcje nie będą działać, chyba że projekt ten ma własną lokalną kopię tf_doctest i użyjesz tej kopii zamiast TensorFlow.

Na przykład: tf_estimator_doctest.py .

Przetestuj na komputerze lokalnym

Istnieją dwa sposoby lokalnego testowania kodu w dokumencie:

Jeśli zmieniasz tylko dokument klasy/funkcji/metody, możesz to przetestować, przekazując ścieżkę tego pliku do tf_doctest.py . Na przykład:
```
python tf_doctest.py --file=<file_path>
```
Spowoduje to uruchomienie go przy użyciu zainstalowanej wersji TensorFlow. Aby mieć pewność, że używasz tego samego kodu, który testujesz:
- Użyj aktualnej instalacji pip tf-nightly pip install -U tf-nightly
- Oprzyj swoje żądanie ściągnięcia na ostatnim pobraniu z głównej gałęzi TensorFlow .
Jeśli zmieniasz kod i dokumentację klasy/funkcji/metody, będziesz musiał zbudować TensorFlow ze źródła . Po skonfigurowaniu kompilacji ze źródła możesz uruchomić testy:
```
bazel run //tensorflow/tools/docs:tf_doctest
```
Lub
```
bazel run //tensorflow/tools/docs:tf_doctest -- --module=ops.array_ops
```
Opcja --module jest zależna od tensorflow.python .