TensorFlow API ডকুমেন্টেশনে অবদান রাখুন

পরীক্ষাযোগ্য ডকস্ট্রিং

Python ডকস্ট্রিং-এ কোড স্নিপেট পরীক্ষা করার জন্য TensorFlow ডকটেস্ট ব্যবহার করে। স্নিপেটটি অবশ্যই এক্সিকিউটেবল পাইথন কোড হতে হবে। টেস্টিং সক্ষম করতে, >>> (তিনটি বাম-কোণ বন্ধনী) দিয়ে লাইনটি প্রিপেন্ড করুন। উদাহরণস্বরূপ, এখানে 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 ডক্স পরামর্শের উদাহরণ বিভাগটি দেখুন। (সচেতন থাকুন যে এই শীটে টাস্ক ট্র্যাকার আর ব্যবহার করা হচ্ছে না।)

কোডটি ডকটেস্ট দিয়ে পরীক্ষাযোগ্য করুন

বর্তমানে, অনেক ডকস্ট্রিং কোড শনাক্ত করতে ব্যাকটিক্স (```) ব্যবহার করে। ডকটেস্টের সাথে কোডটি পরীক্ষাযোগ্য করতে:

  • ব্যাকটিক্স (```) সরান এবং প্রতিটি লাইনের সামনে বাম-বন্ধনী (>>>) ব্যবহার করুন। ক্রমাগত লাইনের সামনে (...) ব্যবহার করুন।
  • tensorflow.org-এ সঠিকভাবে রেন্ডার করতে Markdown পাঠ্য থেকে DocTest স্নিপেটগুলিকে আলাদা করতে একটি নতুন লাইন যোগ করুন।

কাস্টমাইজেশন

TensorFlow বিল্টইন ডক্টেস্ট লজিকের জন্য কয়েকটি কাস্টমাইজেশন ব্যবহার করে:

  • এটি ফ্লোট মানগুলিকে পাঠ্য হিসাবে তুলনা করে না: ফ্লোট মানগুলি পাঠ্য থেকে বের করা হয় এবং লিবারেল atol এবং rtol সহনশীলতার সাথে allclose ব্যবহার করে তুলনা করা হয়। এটি অনুমতি দেয়:
    • পরিষ্কার ডক্স - লেখকদের সমস্ত দশমিক স্থান অন্তর্ভুক্ত করার প্রয়োজন নেই।
    • আরও শক্তিশালী পরীক্ষা - অন্তর্নিহিত বাস্তবায়নে সংখ্যাগত পরিবর্তনগুলি কখনই ডক্টেস্টকে ব্যর্থ হওয়ার কারণ হওয়া উচিত নয়।
  • এটি শুধুমাত্র আউটপুট পরীক্ষা করে যদি লেখক একটি লাইনের জন্য আউটপুট অন্তর্ভুক্ত করে। এটি পরিষ্কার ডক্সের জন্য অনুমতি দেয় কারণ লেখকদের সাধারণত অপ্রাসঙ্গিক মধ্যবর্তী মানগুলিকে মুদ্রিত হওয়া থেকে আটকাতে হয় না।

ডকস্ট্রিং বিবেচনা

  • সামগ্রিক : ডকটেস্টের লক্ষ্য হল ডকুমেন্টেশন প্রদান করা এবং নিশ্চিত করা যে ডকুমেন্টেশন কাজ করে। এটি ইউনিট-পরীক্ষা থেকে আলাদা। তাই:
    • উদাহরণ সহজ রাখুন।
    • দীর্ঘ বা জটিল আউটপুট এড়িয়ে চলুন.
    • সম্ভব হলে বৃত্তাকার সংখ্যা ব্যবহার করুন।
  • আউটপুট বিন্যাস : স্নিপেটের আউটপুট সরাসরি কোডের নীচে থাকা দরকার যা আউটপুট তৈরি করছে। এছাড়াও, ডকস্ট্রিং-এর আউটপুটটি কোডটি কার্যকর করার পরে আউটপুটটির ঠিক সমান হতে হবে। উপরের উদাহরণ দেখুন। এছাড়াও, ডকটেস্ট ডকুমেন্টেশনে এই অংশটি দেখুন। যদি আউটপুট 80 লাইনের সীমা অতিক্রম করে, আপনি নতুন লাইনে অতিরিক্ত আউটপুট রাখতে পারেন এবং ডকটেস্ট এটি চিনবে। উদাহরণস্বরূপ, নীচে মাল্টি-লাইন ব্লক দেখুন।
  • গ্লোবাল : TensorFlow এর DocTest-এ `tf` , np এবং os মডিউল সবসময় পাওয়া যায়।
  • প্রতীক ব্যবহার করুন : ডকটেস্টে আপনি একই ফাইলে সংজ্ঞায়িত প্রতীকগুলি সরাসরি অ্যাক্সেস করতে পারেন। বর্তমান ফাইলে সংজ্ঞায়িত নয় এমন একটি প্রতীক ব্যবহার করতে, অনুগ্রহ করে 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 ডক্টেস্ট ফলাফলের স্ট্রিংগুলি থেকে ফ্লোট মান বের করে এবং np.allclose ব্যবহার করে যুক্তিসঙ্গত সহনশীলতার সাথে তুলনা করে ( atol=1e-6 , rtol=1e-6 )। এইভাবে লেখকদের অত্যধিক সুনির্দিষ্ট ডকস্ট্রিংগুলি নিয়ে চিন্তা করার দরকার নেই যা সংখ্যাগত সমস্যার কারণে ব্যর্থতার কারণ হয়। শুধু প্রত্যাশিত মান পেস্ট করুন.

  • নন-ডিটারমিনিস্টিক আউটপুট : অনিশ্চিত অংশগুলির জন্য ellipsis( ... ) ব্যবহার করুন এবং 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 এর মাস্টার ব্রাঞ্চ থেকে সাম্প্রতিক টানে আপনার পুল অনুরোধ রিবেস করুন।
  • আপনি যদি কোনো ক্লাস/ফাংশন/পদ্ধতির কোড এবং ডকস্ট্রিং পরিবর্তন করেন, তাহলে আপনাকে উৎস থেকে টেনসরফ্লো তৈরি করতে হবে। একবার আপনি উৎস থেকে তৈরি করার জন্য সেটআপ হয়ে গেলে, আপনি পরীক্ষা চালাতে পারেন:

    bazel run //tensorflow/tools/docs:tf_doctest
    

    বা

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

    --module tensorflow.python এর সাথে আপেক্ষিক।