Trang này được dịch bởi Cloud Translation API.

Đóng góp vào tài liệu API TensorFlow

Chuỗi tài liệu có thể kiểm tra

TensorFlow sử dụng DocTest để kiểm tra các đoạn mã trong chuỗi tài liệu Python. Đoạn mã phải là mã Python có thể thực thi được. Để kích hoạt tính năng kiểm tra, hãy thêm >>> (ba dấu ngoặc nhọn bên trái) vào trước dòng này. Ví dụ: đây là đoạn trích từ hàm tf.concat trong tệp nguồn 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>

Để đánh giá chất lượng tài liệu tham khảo, hãy xem phần ví dụ trong lời khuyên về Tài liệu API TensorFlow 2 . (Xin lưu ý rằng Trình theo dõi tác vụ trên trang tính này không còn được sử dụng nữa.)

Làm cho mã có thể kiểm tra được bằng DocTest

Hiện tại, nhiều tài liệu sử dụng dấu backticks (```) để xác định mã. Để làm cho mã có thể kiểm tra được bằng DocTest:

Xóa dấu backticks (```) và sử dụng dấu ngoặc trái (>>>) trước mỗi dòng. Sử dụng (...) trước các dòng tiếp theo.
Thêm một dòng mới để tách các đoạn DocTest khỏi văn bản Markdown nhằm hiển thị chính xác trên tensorflow.org.

Tùy chỉnh

TensorFlow sử dụng một số tùy chỉnh đối với logic doctest dựng sẵn:

Nó không so sánh các giá trị float dưới dạng văn bản: Các giá trị float được trích xuất từ văn bản và được so sánh bằng cách sử dụng allclose với dung sai atol và rtol tự do . Điều này cho phép:
- Tài liệu rõ ràng hơn - Tác giả không cần bao gồm tất cả các vị trí thập phân.
- Các thử nghiệm mạnh mẽ hơn - Những thay đổi về mặt số học trong quá trình triển khai cơ bản sẽ không bao giờ khiến doctest bị lỗi.
Nó chỉ kiểm tra đầu ra nếu tác giả bao gồm đầu ra cho một dòng. Điều này cho phép tài liệu rõ ràng hơn vì tác giả thường không cần nắm bắt các giá trị trung gian không liên quan để ngăn chúng được in ra.

Cân nhắc về chuỗi tài liệu

Nhìn chung : Mục tiêu của doctest là cung cấp tài liệu và xác nhận rằng tài liệu đó hoạt động. Điều này khác với thử nghiệm đơn vị. Vì thế:
- Giữ các ví dụ đơn giản.
- Tránh kết quả đầu ra dài hoặc phức tạp.
- Sử dụng số tròn nếu có thể.
Định dạng đầu ra : Đầu ra của đoạn mã cần phải nằm ngay bên dưới mã tạo ra đầu ra. Ngoài ra, đầu ra trong chuỗi tài liệu phải chính xác bằng kết quả đầu ra sau khi mã được thực thi. Xem ví dụ trên. Ngoài ra, hãy xem phần này trong tài liệu DocTest. Nếu đầu ra vượt quá giới hạn 80 dòng, bạn có thể đặt đầu ra bổ sung trên dòng mới và DocTest sẽ nhận ra nó. Ví dụ: xem các khối nhiều dòng bên dưới.
Globals : Các mô-đun `tf` , np và os luôn có sẵn trong DocTest của TensorFlow.
Sử dụng các ký hiệu : Trong DocTest bạn có thể truy cập trực tiếp các ký hiệu được xác định trong cùng một tệp. Để sử dụng ký hiệu không được xác định trong tệp hiện tại, vui lòng sử dụng API công khai tf.xxx của TensorFlow thay vì xxx . Như bạn có thể thấy trong ví dụ bên dưới, `random.normal` được truy cập thông qua `tf.random.normal` . Điều này là do `random.normal` không hiển thị trong 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=...>
  """
```
Giá trị dấu phẩy động : Doctest TensorFlow trích xuất các giá trị float từ chuỗi kết quả và so sánh bằng cách sử dụng np.allclose với dung sai hợp lý ( atol=1e-6 , rtol=1e-6 ). Bằng cách này, tác giả không cần phải lo lắng về việc các chuỗi tài liệu quá chính xác sẽ gây ra lỗi do các vấn đề về số. Đơn giản chỉ cần dán vào giá trị mong đợi.
Đầu ra không xác định : Sử dụng dấu ba chấm( ... ) cho các phần không chắc chắn và DocTest sẽ bỏ qua chuỗi con đó.
```
x = tf.random.normal((1,))
print(x)
    <tf.Tensor: shape=(1,), dtype=float32, numpy=..., dtype=float32)>
    
```
Khối nhiều dòng : DocTest rất nghiêm ngặt về sự khác biệt giữa câu lệnh một dòng và câu lệnh nhiều dòng. Lưu ý cách sử dụng (...) bên dưới:
```
if x > 0:
  print("X is positive")
model.compile(
  loss="mse",
  optimizer="adam")
    
```

Ngoại lệ : Chi tiết ngoại lệ bị bỏ qua ngoại trừ Ngoại lệ được nêu ra. Xem cái này để biết thêm chi tiết.

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'>`.

Sử dụng bản sao cục bộ của dự án tf-doctest.

Một số API trong TensorFlow đến từ một dự án bên ngoài:

tf.estimator (từ tensorflow_estimator )
tf.summary tensorboard )
tf.keras.preprocessing (từ keras-preprocessing )

Nếu bạn đang làm việc trên một dự án bên ngoài hoặc trên các API TensorFlow nằm trong một dự án bên ngoài thì các hướng dẫn này sẽ không hoạt động trừ khi dự án đó có bản sao cục bộ của tf_doctest và bạn sử dụng bản sao đó thay vì của TensorFlow.

Ví dụ: tf_estimator_doctest.py .

Kiểm tra trên máy cục bộ của bạn

Có hai cách để kiểm tra mã trong chuỗi tài liệu cục bộ:

Nếu bạn chỉ thay đổi chuỗi tài liệu của một lớp/hàm/phương thức thì bạn có thể kiểm tra nó bằng cách chuyển đường dẫn của tệp đó tới tf_doctest.py . Ví dụ:
```
python tf_doctest.py --file=<file_path>
```
Thao tác này sẽ chạy nó bằng phiên bản TensorFlow đã cài đặt của bạn. Để chắc chắn rằng bạn đang chạy cùng một mã mà bạn đang kiểm tra:
- Sử dụng bản cập nhật tf-nightly pip install -U tf-nightly
- Chuyển lại yêu cầu kéo của bạn thành yêu cầu kéo gần đây từ nhánh chính của TensorFlow .
Nếu bạn đang thay đổi mã và chuỗi tài liệu của một lớp/hàm/phương thức thì bạn sẽ cần xây dựng TensorFlow từ nguồn . Sau khi thiết lập để xây dựng từ nguồn, bạn có thể chạy thử nghiệm:
```
bazel run //tensorflow/tools/docs:tf_doctest
```
hoặc
```
bazel run //tensorflow/tools/docs:tf_doctest -- --module=ops.array_ops
```
--module có liên quan đến tensorflow.python .