Attend the Women in ML Symposium on December 7 Register now

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

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Docstrings có thể kiểm tra

TensorFlow sử dụng DocTest để kiểm tra các đoạn mã trong Python docstrings. Đoạn mã phải là mã Python có thể thực thi. Để kích hoạt thử nghiệm, hãy thêm dòng trước >>> (ba dấu ngoặc nhọn bên trái). Ví dụ: đây là một đ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ụ về lời khuyên của Tài liệu API TensorFlow 2 . (Lưu ý rằng Task Tracker 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 với DocTest

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

  • Bỏ dấu gạch ngược (`` `) và sử dụng dấu ngoặc trái (>>>) ở phía trước mỗi dòng. Sử dụng (...) trước các dòng tiếp tục.
  • Thêm một dòng mới để tách các đoạn DocTest khỏi văn bản Markdown để 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 của tài liệu tích hợp:

  • 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à so sánh bằng cách sử dụng allclose với dung sai atolrtol 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 - Các thay đổi bằng số trong quá trình triển khai cơ bản sẽ không bao giờ khiến học thuyết 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 các tài liệu rõ ràng hơn vì các 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.

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

  • Nhìn chung : Mục tiêu của học thuyết 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 kiểm thử đơn vị. Vì thế:
    • Giữ các ví dụ đơn giản.
    • Tránh các đầ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 docstring phải chính xác bằng giá trị đầ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 thêm đầu ra trên dòng mới và DocTest sẽ nhận ra nó. Ví dụ, hãy xem các khối nhiều dòng bên dưới.
  • Globals : Các mô-đun `tf` , npos 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 vào 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 của TensorFlow tf.xxx 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 `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 chấm động : Học thuyết TensorFlow trích xuất các giá trị float từ các 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, các tác giả không cần phải lo lắng về các chuỗi docstrings quá chính xác gây ra lỗi do các vấn đề 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 chấm lửng ( ... ) 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 nghiêm ngặt về sự khác biệt giữa câu lệnh đơn và câu lệnh nhiều dòng. Lưu ý cách sử dụng (...) dưới đây:

    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 điều 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 tf-doctest dự án cục bộ.

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

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 được đặt trong một dự án bên ngoài, 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 riêng nó là 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 docstring 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 đó đến tf_doctest.py . Ví dụ:

    python tf_doctest.py --file=<file_path>
    

    Điều này sẽ chạy nó bằng cách sử dụng phiên bản TensorFlow đã cài đặt của bạn. Để đảm bảo rằng bạn đang chạy cùng một mã mà bạn đang thử nghiệm:

    • Sử dụng cài đặt tf-nightly pip install -U tf-nightly
    • Căn cứ yêu cầu kéo của bạn vào một lần 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 / chức năng / phương thức, thì bạn sẽ cần phải xây dựng TensorFlow từ nguồn . Khi bạn đã thiết lập để xây dựng từ nguồn, bạn có thể chạy các bài kiểm tra:

    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 .