এইচএলও আইসোলেশন ব্যবহারকারী নির্দেশিকা

এই ডকুমেন্টটিতে HLO আইসোলেশন এপিআই এবং সিএলআই কীভাবে ইনস্টল ও ব্যবহার করতে হয় তা ব্যাখ্যা করা হয়েছে। HLO আইসোলেশন টুলিং ডেভেলপার এবং গবেষকদের কম্পাইল করা HLO মডিউলগুলিতে সাংখ্যিক অমিল এবং স্থিতিশীলতার সমস্যাগুলি শনাক্ত করতে, যাচাই করতে এবং ডিবাগ করতে সহায়তা করে।

ইনস্টলেশন

আপনি স্ট্যান্ডার্ড OpenXLA/TensorFlow বিল্ড মেকানিজম (Bazel) অথবা বাইনারি ডিস্ট্রিবিউশনের মাধ্যমে HLO আইসোলেশন কম্পোনেন্টগুলো ব্যবহার করতে পারেন।

উৎস এবং বেজেল সেটআপ

সোর্স থেকে কম্পাইলার এবং টুলস স্ট্যাক তৈরি করার সময়, নিম্নলিখিত লাইব্রেরিগুলি অন্তর্ভুক্ত করুন বা সেগুলির উপর নির্ভর করুন:

  • এপিআই টার্গেট: //third_party/tensorflow/compiler/xla/tools/hlo_isolation:hlo_isolation_api
  • CLI টার্গেট: //third_party/tensorflow/compiler/xla/tools/hlo_isolation:hlo_isolation_test

স্বতন্ত্র CLI টুলটি তৈরি করতে:

bazel build -c opt //third_party/tensorflow/compiler/xla/tools/hlo_isolation:hlo_isolation_test

কমান্ড-লাইন ইন্টারফেস (CLI)

hlo_isolation_test CLI আপনাকে সরাসরি টার্মিনাল থেকে কম্পাইল করা HLO মডিউলগুলোর সাংখ্যিক অমিল এবং স্থিতিশীলতা পরীক্ষা আলাদা করে চালানোর সুযোগ দেয়। এটি বিভিন্ন পরিবেশে (যেমন, TPU বনাম Defused TPU / CPU / Interpreter) এক্সিকিউশনের ফলাফল তুলনা করে।

পতাকা রেফারেন্স

CLI নিম্নলিখিত ফ্ল্যাগগুলো সমর্থন করে:

  • --hlo_file : লোড করার জন্য ইনপুট .hlo বা .pbtxt ফাইলের পাথ। এটি টেক্সট বা প্রোটো ফরম্যাটে হতে পারে (আবশ্যক)।
  • --test_platform : মূল পরীক্ষাটি চালানোর জন্য লক্ষ্য প্ল্যাটফর্ম (যেমন, cpu , gpu , tpu )। ডিফল্ট হিসেবে cpu ব্যবহৃত হয়।
  • --reference_platform : বেসলাইন তুলনার জন্য রেফারেন্স প্ল্যাটফর্ম (যেমন, interpreter )। এটি খালি থাকলে, রেফারেন্স তুলনা নিষ্ক্রিয় থাকবে।
  • --filter_by_name : মডিউলের নাম মেলানোর জন্য রেগুলার এক্সপ্রেশন। শুধুমাত্র মিলে যাওয়া মডিউলগুলোই চালানো হবে। ডিফল্ট মান হলো .* ।
  • --skip_by_name : মডিউলের নাম মেলানোর জন্য রেগুলার এক্সপ্রেশন। মিলে যাওয়া মডিউলগুলো এড়িয়ে যাওয়া হবে।
  • --filter_by_opcode : ইনস্ট্রাকশন অপকোড মেলানোর জন্য রেগুলার এক্সপ্রেশন। শুধুমাত্র সেইসব মডিউলই চালানো হবে যেগুলিতে অন্তত একটি মিলে যাওয়া অপকোড রয়েছে। ডিফল্ট মান হলো .* ।
  • --skip_by_opcode : ইনস্ট্রাকশন অপকোড মেলানোর জন্য রেগুলার এক্সপ্রেশন। যে মডিউলগুলিতে কোনো মিলে যাওয়া অপকোড থাকবে, সেগুলি বাদ দেওয়া হবে।
  • --abs_error_bound : তুলনার জন্য ব্যবহৃত পরম ত্রুটির সীমা। ডিফল্ট মান 0.01 ।
  • --rel_error_bound : তুলনার জন্য ব্যবহৃত আপেক্ষিক ত্রুটির সীমা। ডিফল্ট মান 0.1 ।
  • --run_hlo_passes : সাবমডিউলগুলিতে স্ট্যান্ডার্ড HLO পাস চালানো হবে কিনা তা নির্ধারণ করার জন্য বুলিয়ান ফ্ল্যাগ। ডিফল্ট মান false ।
  • --shard_index : চালানোর জন্য নির্দিষ্ট শার্ড ইনডেক্স (শূন্য-ভিত্তিক)। ডিফল্ট মান -1 (অক্ষম)।
  • --num_shards : মোট শার্ড সংখ্যা। ডিফল্ট মান 1 ।

মৌলিক আহ্বান 

./hlo_isolation_test \
  --hlo_file=/path/to/failing_fusion.hlo \
  --test_platform=gpu \
  --reference_platform=interpreter

ফলাফল এবং আর্টিফ্যাক্ট ডাম্প

আইসোলেশন টেস্টিং চলাকালীন কোনো সাবমডিউলে সাংখ্যিক অমিল বা অন্য কোনো ত্রুটি দেখা দিলে, টুলটি আরও নিবিড় পর্যবেক্ষণের জন্য স্বয়ংক্রিয়ভাবে ডিবাগ আর্টিফ্যাক্টগুলোকে ডিস্কে সিরিয়ালাইজ করে।

ডাম্পের বিষয়বস্তু

সংখ্যাগত অমিল হলে, টুলটি নিম্নলিখিত ডিবাগ আর্টিফ্যাক্টগুলো লিখে থাকে:

  1. ইন্টারেক্টিভ এইচটিএমএল অমিল রিপোর্ট ( failed-module-<module_name>.html )।
  2. ব্যর্থ HLO সাবমডিউলের টেক্সট ( failed-module-<module_name>.txt )।
  3. প্রত্যাশিত আউটপুট লিটারেল ( failed-<module_name>-expected.txt )।
  4. প্রকৃত আউটপুট লিটারেল ( failed-<module_name>-actual.txt )।
  5. অমিল উপাদানগুলির সারাংশ ( failed-<module_name>-mismatches.txt )।

ইন্টারেক্টিভ এইচটিএমএল গ্রাফ ইউআই

আইসোলেশন টেস্টিং চলাকালীন সাংখ্যিক অমিল শনাক্ত হলে, প্রতিটি অমিলের জন্য একটি ইন্টারেক্টিভ HTML রিপোর্ট ( failed-module-<module_name>.html ) তৈরি করা হয়। এটি HLO গ্রাফ রেন্ডার করে এবং অ্যানোটেশন ও টুলটিপের মাধ্যমে অমিল নির্দেশাবলীকে হাইলাইট করে ব্যর্থ HLO মডিউলটির একটি গ্রাফিক্যাল চিত্র প্রদান করে, যা বিস্তারিত সাংখ্যিক অমিলের পরিসংখ্যান (প্রকৃত ও প্রত্যাশিত মান, আপেক্ষিক ও পরম ত্রুটির সীমা এবং এলিমেন্ট অমিলের শতাংশ সহ) প্রদর্শন করে।

HLO আইসোলেশন ইন্টারেক্টিভ HTML গ্রাফ UI

উপরে: সাংখ্যিক অমিলযুক্ত একটি ফিউশনের উদাহরণ এইচটিএমএল আউটপুট।

ডাম্প টার্গেট লোকেশন

  • পরীক্ষার পরিবেশ: যদি bazel test মাধ্যমে অথবা TEST_UNDECLARED_OUTPUTS_DIR এনভায়রনমেন্ট ভেরিয়েবল নির্ধারণ করা কোনো পরিবেশে এটি চালানো হয়, তাহলে ফলাফলগুলি সরাসরি সেই ডিরেক্টরিতে উপরে উল্লিখিত সঠিক ফাইলের নামগুলিতে রাখা হয় (যেমন, failed-<module_name>-expected.txt )।
  • স্ট্যান্ডার্ড/ম্যানুয়াল রান: কমান্ড লাইনের মাধ্যমে ম্যানুয়ালি চালানো হলে, আর্টিফ্যাক্টগুলো অপারেটিং সিস্টেমের টেম্পোরারি ডিরেক্টরিতে (যেমন, /tmp ) লেখা হয় এবং ফাইলের নামকরণের একই সমন্বিত নিয়ম (যেমন, /tmp/failed-<module_name>-expected.txt -expected.txt) বজায় রাখা হয়।

C++ ইন্টিগ্রেশন এবং এপিআই

যেসব ডেভেলপার কাস্টম কম্পাইলার পাস, টেস্টিং রিগ বা অটোমেটেড পাইপলাইন তৈরি করেন, তাদের জন্য C++ API আইসোলেশন টেস্ট ইন্টিগ্রেট করার একটি সরাসরি উপায় প্রদান করে।

সরাসরি এপিআই ব্যবহার করে

কোর এপিআই মডিউল চালানোর এবং কাঠামোগত প্রতিবেদন আনার জন্য কার্যকরী ইন্টারফেস প্রদান করে:

#include "third_party/tensorflow/compiler/xla/tools/hlo_isolation/hlo_isolation_api.h"

xla::hlo_isolation::PipelineIsolationOptions options;
options.module_options.abs_error_bound = 0.01;
options.module_options.rel_error_bound = 0.1;
// Filter specific opcodes programmatically
options.filter_by_opcode = "exponential";

absl::StatusOr<std::vector<xla::HloIsolationTestResult>> results =
    xla::hlo_isolation::RunIsolationPipeline(
        input_hlo_module,
        &my_test_runner,
        &my_reference_runner,
        options);

টেস্ট মিক্সিন ব্যবহার করে

GoogleTest C++ টেস্ট স্যুট লেখার সময়, বিল্ট-ইন অ্যাসারশন হ্যান্ডলিংয়ের জন্য আপনি HloIsolationTestMixin থেকে ইনহেরিট করতে পারেন। বেস ক্লাসটিতে অবশ্যই একটি টেস্ট রানার এবং একটি রেফারেন্স রানার উভয়ই থাকতে হবে (যেমন, HloPjRtInterpreterReferenceMixin এর মাধ্যমে):

#include "third_party/tensorflow/compiler/xla/tests/hlo_pjrt_interpreter_reference_mixin.h"
#include "third_party/tensorflow/compiler/xla/tools/hlo_isolation/hlo_isolation_test_base.h"

class MyCustomPassIsolationTest : public xla::hlo_isolation::HloIsolationTestMixin<
    xla::HloPjRtInterpreterReferenceMixin<xla::HloPjRtTestBase>> {};

TEST_F(MyCustomPassIsolationTest, ChecksMyFusionSanity) {
  RunAndVerifyIsolationTest(my_failing_module);
}

শার্ডেড এক্সিকিউশন (কে৮এস/স্লার্ম)

বড় মডিউল বা ভারী টেস্ট ম্যাট্রিক্সের জন্য, আপনি শার্ডিং ফ্ল্যাগ ব্যবহার করে একাধিক ডিভাইস ক্লাস্টারে (যেমন গুগল কুবারনেটিস ইঞ্জিন বা স্লার্ম) এক্সিকিউশন ভাগ করে দিতে পারেন। প্রতিটি shard_index সুনির্দিষ্টভাবে বিভক্ত সাবমডিউলগুলোর একটি বিচ্ছিন্ন উপসেট চালায়। এটি পুনরাবৃত্তিযোগ্য ডিস্ট্রিবিউটেড ভেরিফিকেশন এবং ব্যর্থ পার্টিশনগুলোর নির্দিষ্ট লক্ষ্য নিয়ে পুনরায় চালানোর সুযোগ করে দেয়।

উদাহরণ: কুবারনেটিস জব

প্রতিটি টেস্ট শার্ডকে completionMode: Indexed ব্যবহার করে একটি পৃথক Kubernetes pod হিসেবে এক্সিকিউট করা হয়। JOB_COMPLETION_INDEX টি সরাসরি CLI-এর --shard_index ফ্ল্যাগে পাস করা হয়।

apiVersion: batch/v1
kind: Job
metadata:
  name: hlo-isolation-job
spec:
  completions: 50
  parallelism: 50
  completionMode: Indexed
  template:
    spec:
      containers:
      - name: test-runner
        image: gcr.io/my-project/hlo-isolation-tools:latest
        command: ["/bin/sh", "-c"]
        args:
        - |
          ./hlo_isolation_test \
            --num_shards=50 \
            --shard_index=$JOB_COMPLETION_INDEX \
            --hlo_file=/data/path/to/hlo.hlo
        volumeMounts:
        - name: hlo-data-volume
          mountPath: /data
      volumes:
      - name: hlo-data-volume
        csi:
          driver: gcsfuse.csi.storage.gke.io
          volumeAttributes:
            bucketName: my-xla-debug-bucket

মূল সক্ষমতা

  • বহনযোগ্যতা: অভ্যন্তরীণ টেস্ট র‍্যাপারগুলোকে স্বতন্ত্র এপিআই থেকে বিচ্ছিন্ন করে, ফলে স্থানীয়ভাবে এইচএলও অমিল ডিবাগ করা সহজ হয়।
  • সূক্ষ্মতা: বিশাল আকারের HLO ডাম্প নিয়ে কাজ করার সময়, সূক্ষ্ম অপকোড এবং নাম ফিল্টারিং ডিবাগিং প্রক্রিয়াকে উন্নত করে।
  • ইন্টারেক্টিভ ভিজ্যুয়ালাইজেশন: দ্রুত মূল কারণ নির্ণয়ের জন্য গ্রাফ ভিজ্যুয়ালাইজেশন এবং প্রতিটি নির্দেশনার জন্য সাংখ্যিক অমিল টীকা সহ ইন্টারেক্টিভ এইচটিএমএল রিপোর্ট প্রদান করে।
  • সম্প্রসারণযোগ্যতা: কাস্টম রানার এক্সিকিউশন কলব্যাক এবং ডেটা ইনজেক্টর ( make_fake_arguments_fn ) উন্নত যাচাইকরণ ওয়ার্কফ্লোর জন্য সম্পূর্ণ কাস্টমাইজেশনের সুযোগ দেয়।