TensorFlow API दस्तावेज़ीकरण में योगदान करें

परीक्षण योग्य डॉकस्ट्रिंग्स

TensorFlow Python docstrings में कोड स्निपेट का परीक्षण करने के लिए DocTest का उपयोग करता है। स्निपेट निष्पादन योग्य पायथन कोड होना चाहिए। परीक्षण सक्षम करने के लिए, पंक्ति को >>> (तीन बाएँ-कोण कोष्ठक) के साथ जोड़ें। उदाहरण के लिए, यहां array_ops.py स्रोत फ़ाइल में tf.concat फ़ंक्शन का एक अंश दिया गया है:

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>

संदर्भ दस्तावेज़ गुणवत्ता का आकलन करने के लिए, TensorFlow 2 API डॉक्स सलाह का उदाहरण अनुभाग देखें। (ध्यान रखें कि इस शीट पर टास्क ट्रैकर अब उपयोग में नहीं है।)

DocTest के साथ कोड को परीक्षण योग्य बनाएं

वर्तमान में, कई डॉकस्ट्रिंग्स कोड की पहचान करने के लिए बैकटिक्स (```) का उपयोग करते हैं। कोड को DocTest के साथ परीक्षण योग्य बनाने के लिए:

  • बैकटिक्स (```) हटाएं और प्रत्येक पंक्ति के सामने बाएं-ब्रैकेट (>>>) का उपयोग करें। निरंतर पंक्तियों के सामने (...) का प्रयोग करें।
  • Tensorflow.org पर ठीक से प्रस्तुत करने के लिए डॉकटेस्ट स्निपेट को मार्कडाउन टेक्स्ट से अलग करने के लिए एक नई पंक्ति जोड़ें।

अनुकूलन

TensorFlow अंतर्निहित सैद्धांतिक तर्क के लिए कुछ अनुकूलन का उपयोग करता है:

  • यह फ़्लोट मानों की तुलना पाठ के रूप में नहीं करता है: फ़्लोट मानों को पाठ से निकाला जाता है और उदार atol और rtol सहनशीलता के साथ allclose उपयोग करके तुलना की जाती है। यह अनुमति देता है:
    • स्पष्ट दस्तावेज़ - लेखकों को सभी दशमलव स्थानों को शामिल करने की आवश्यकता नहीं है।
    • अधिक मजबूत परीक्षण - अंतर्निहित कार्यान्वयन में संख्यात्मक परिवर्तन के कारण कभी भी सिद्धांत विफल नहीं होना चाहिए।
  • यह केवल आउटपुट की जाँच करता है यदि लेखक किसी पंक्ति के लिए आउटपुट शामिल करता है। यह स्पष्ट दस्तावेज़ों की अनुमति देता है क्योंकि लेखकों को आमतौर पर उन्हें मुद्रित होने से रोकने के लिए अप्रासंगिक मध्यवर्ती मानों को पकड़ने की आवश्यकता नहीं होती है।

डॉकस्ट्रिंग विचार

  • कुल मिलाकर : डॉक्टेस्ट का लक्ष्य दस्तावेज़ीकरण प्रदान करना है, और पुष्टि करना है कि दस्तावेज़ीकरण काम करता है। यह इकाई-परीक्षण से भिन्न है. इसलिए:
    • उदाहरण सरल रखें.
    • लंबे या जटिल आउटपुट से बचें.
    • यदि संभव हो तो गोल संख्याओं का प्रयोग करें।
  • आउटपुट स्वरूप : स्निपेट का आउटपुट सीधे उस कोड के नीचे होना चाहिए जो आउटपुट उत्पन्न कर रहा है। साथ ही, डॉकस्ट्रिंग में आउटपुट कोड निष्पादित होने के बाद आउटपुट के बिल्कुल बराबर होना चाहिए। उपरोक्त उदाहरण देखें. इसके अलावा, DocTest दस्तावेज़ में इस भाग को देखें। यदि आउटपुट 80 लाइन की सीमा से अधिक है, तो आप अतिरिक्त आउटपुट को नई लाइन पर रख सकते हैं और DocTest इसे पहचान लेगा। उदाहरण के लिए, नीचे मल्टी-लाइन ब्लॉक देखें।
  • ग्लोबल्स : `tf` , np और os मॉड्यूल हमेशा TensorFlow के DocTest में उपलब्ध होते हैं।

  • प्रतीकों का उपयोग करें : DocTest में आप सीधे उसी फ़ाइल में परिभाषित प्रतीकों तक पहुंच सकते हैं। ऐसे प्रतीक का उपयोग करने के लिए जो वर्तमान फ़ाइल में परिभाषित नहीं है, कृपया xxx के बजाय TensorFlow के सार्वजनिक API tf.xxx का उपयोग करें। जैसा कि आप नीचे दिए गए उदाहरण में देख सकते हैं, `random.normal` `tf.random.normal` के माध्यम से एक्सेस किया जाता है। ऐसा इसलिए है क्योंकि NewLayer में `random.normal` दिखाई नहीं देता है।

    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=...>
  """

  • फ़्लोटिंग पॉइंट मान : TensorFlow सिद्धांत परिणाम स्ट्रिंग्स से फ़्लोट मान निकालता है, और उचित सहनशीलता ( atol=1e-6 , rtol=1e-6 ) के साथ np.allclose का उपयोग करके तुलना करता है। इस तरह से लेखकों को संख्यात्मक मुद्दों के कारण विफलताओं का कारण बनने वाले अत्यधिक सटीक डॉकस्ट्रिंग्स के बारे में चिंता करने की आवश्यकता नहीं है। बस अपेक्षित मान चिपकाएँ।

  • गैर-नियतात्मक आउटपुट : अनिश्चित भागों के लिए इलिप्सिस( ... ) का उपयोग करें और DocTest उस सबस्ट्रिंग को अनदेखा कर देगा।

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

  • मल्टी-लाइन ब्लॉक : डॉकटेस्ट सिंगल और मल्टी-लाइन स्टेटमेंट के बीच अंतर को लेकर सख्त है। नीचे (...) के उपयोग पर ध्यान दें:

    if x > 0:
  print("X is positive")
model.compile(
  loss="mse",
  optimizer="adam")

  • अपवाद : उठाए गए अपवाद को छोड़कर अपवाद विवरण को अनदेखा कर दिया जाता है। अधिक जानकारी के लिए इसे देखें.

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

tf-doctest की प्रोजेक्ट-स्थानीय प्रति का उपयोग करें।

TensorFlow में कुछ API किसी बाहरी प्रोजेक्ट से आते हैं:

यदि आप किसी बाहरी प्रोजेक्ट पर काम कर रहे हैं, या किसी बाहरी प्रोजेक्ट में रखे गए TensorFlow API पर काम कर रहे हैं, तो ये निर्देश तब तक काम नहीं करेंगे जब तक कि उस प्रोजेक्ट के पास tf_doctest की अपनी स्थानीय प्रतिलिपि न हो, और आप TensorFlow के बजाय उस प्रतिलिपि का उपयोग करें।

उदाहरण के लिए: tf_estimator_doctest.py ।

अपनी स्थानीय मशीन पर परीक्षण करें

स्थानीय स्तर पर डॉकस्ट्रिंग में कोड का परीक्षण करने के दो तरीके हैं:

  • यदि आप केवल किसी वर्ग/फ़ंक्शन/विधि के डॉकस्ट्रिंग को बदल रहे हैं, तो आप उस फ़ाइल के पथ को tf_doctest.py पर पास करके इसका परीक्षण कर सकते हैं। उदाहरण के लिए:

    python tf_doctest.py --file=<file_path>

    यह इसे TensorFlow के आपके इंस्टॉल किए गए संस्करण का उपयोग करके चलाएगा। यह सुनिश्चित करने के लिए कि आप वही कोड चला रहे हैं जिसका आप परीक्षण कर रहे हैं:

    • एक अद्यतन टीएफ-नाइटली pip install -U tf-nightly उपयोग करें
    • अपने पुल अनुरोध को TensorFlow की मास्टर शाखा से हाल ही में किए गए पुल पर पुनः आधार दें।

  • यदि आप किसी क्लास/फ़ंक्शन/विधि का कोड और डॉकस्ट्रिंग बदल रहे हैं, तो आपको स्रोत से TensorFlow बनाने की आवश्यकता होगी। एक बार जब आप स्रोत से निर्माण के लिए तैयार हो जाते हैं, तो आप परीक्षण चला सकते हैं:

    bazel run //tensorflow/tools/docs:tf_doctest

    या

    bazel run //tensorflow/tools/docs:tf_doctest -- --module=ops.array_ops

    --module tensorflow.python से संबंधित है।