المساهمة في وثائق TensorFlow API

مستندات قابلة للاختبار

يستخدم TensorFlow DocTest لاختبار مقتطفات التعليمات البرمجية في مستندات Python. يجب أن يكون المقتطف كود بايثون قابلاً للتنفيذ. لتمكين الاختبار، ألحق السطر بـ >>> (ثلاثة أقواس في الزاوية اليسرى). على سبيل المثال، إليك مقتطف من الدالة tf.concat في الملف المصدر 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>

لتقييم جودة الوثائق المرجعية، راجع قسم الأمثلة في نصيحة TensorFlow 2 API Docs . (كن على علم بأن أداة تعقب المهام الموجودة في هذه الورقة لم تعد قيد الاستخدام.)

اجعل الكود قابلاً للاختبار باستخدام DocTest

حاليًا، تستخدم العديد من سلاسل المستندات العلامات الخلفية (```) لتحديد التعليمات البرمجية. لجعل الكود قابلاً للاختبار باستخدام DocTest:

  • قم بإزالة العلامات الخلفية (```) واستخدم الأقواس اليسرى (>>>) أمام كل سطر. استخدم (...) أمام الخطوط المستمرة.
  • أضف سطرًا جديدًا لفصل مقتطفات DocTest عن نص Markdown لعرضه بشكل صحيح على Tensorflow.org.

التخصيصات

يستخدم TensorFlow بعض التخصيصات لمنطق doctest المدمج:

  • لا تقارن القيم العائمة كنص: يتم استخراج القيم العائمة من النص ومقارنتها باستخدام allclose مع تسامحات atol و rtol الليبرالية . هذا يسمح :
    • مستندات أكثر وضوحًا - لا يحتاج المؤلفون إلى تضمين جميع المنازل العشرية.
    • اختبارات أكثر قوة - لا ينبغي أبدًا أن تتسبب التغييرات العددية في التنفيذ الأساسي في فشل اختبار الوثيقة.
  • إنه يتحقق فقط من الإخراج إذا قام المؤلف بتضمين مخرجات للخط. يتيح ذلك الحصول على مستندات أكثر وضوحًا لأن المؤلفين عادةً لا يحتاجون إلى التقاط قيم وسيطة غير ذات صلة لمنع طباعتها.

اعتبارات مستندية

  • بشكل عام : الهدف من doctest هو توفير التوثيق والتأكد من عمل التوثيق. وهذا يختلف عن اختبار الوحدة. لذا:
    • أبقِ الأمثلة بسيطة.
    • تجنب النواتج الطويلة أو المعقدة.
    • استخدم الأرقام المستديرة إن أمكن.
  • تنسيق الإخراج : يجب أن يكون إخراج المقتطف مباشرة أسفل الكود الذي ينشئ الإخراج. أيضًا، يجب أن يكون الإخراج في سلسلة المستندات مساويًا تمامًا لما سيكون عليه الإخراج بعد تنفيذ التعليمات البرمجية. انظر المثال أعلاه. راجع أيضًا هذا الجزء في وثائق DocTest. إذا تجاوز الإخراج حد الـ 80 سطرًا، فيمكنك وضع الإخراج الإضافي على السطر الجديد وسيتعرف عليه DocTest. على سبيل المثال، راجع الكتل متعددة الأسطر أدناه.
  • Globals : الوحدات النمطية `tf` و np و os متاحة دائمًا في TensorFlow's DocTest.

  • استخدام الرموز : في DocTest يمكنك الوصول مباشرة إلى الرموز المحددة في نفس الملف. لاستخدام رمز غير محدد في الملف الحالي، يرجى استخدام tf.xxx API العامة لـ TensorFlow بدلاً من xxx . كما ترون في المثال أدناه، يتم الوصول إلى `random.normal` عبر `tf.random.normal` . وذلك لأن `random.normal` غير مرئي في 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=...>
  """

  • قيم النقطة العائمة : يستخرج اختبار TensorFlow القيم العائمة من سلاسل النتائج، ويقارنها باستخدام np.allclose مع التفاوتات المعقولة ( atol=1e-6 , rtol=1e-6 ). بهذه الطريقة لا يحتاج المؤلفون إلى القلق بشأن سلاسل المستندات الدقيقة للغاية التي تسبب الفشل بسبب مشكلات رقمية. ما عليك سوى لصق القيمة المتوقعة.

  • الإخراج غير الحتمي : استخدم علامة القطع ( ... ) للأجزاء غير المؤكدة وسيتجاهل DocTest تلك السلسلة الفرعية.

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

  • كتل متعددة الأسطر : DocTest صارم بشأن الفرق بين عبارة مفردة ومتعددة الأسطر. لاحظ استخدام (...) أدناه:

    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 من مشروع خارجي:

إذا كنت تعمل على مشروع خارجي، أو على واجهات برمجة تطبيقات TensorFlow الموجودة في مشروع خارجي، فلن تعمل هذه التعليمات إلا إذا كان لهذا المشروع نسخته المحلية الخاصة من tf_doctest ، واستخدمت تلك النسخة بدلاً من نسخة TensorFlow.

على سبيل المثال: tf_estimator_doctest.py .

اختبار على جهازك المحلي

هناك طريقتان لاختبار الكود الموجود في سلسلة المستندات محليًا:

  • إذا كنت تقوم فقط بتغيير مستند فئة/وظيفة/طريقة، فيمكنك اختباره عن طريق تمرير مسار هذا الملف إلى tf_doctest.py . على سبيل المثال:

    python tf_doctest.py --file=<file_path>

    سيؤدي هذا إلى تشغيله باستخدام الإصدار المثبت من TensorFlow. للتأكد من أنك تقوم بتشغيل نفس الكود الذي تختبره:

    • استخدم تثبيت tf-nightly 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 .