লাইব্রেরি ডিজাইন

কার্নেল অথরিং, অপ্টিমাইজেশন, রক্ষণাবেক্ষণ এবং প্রোডাকশন ব্যবহারের ক্ষেত্রে সাধারণ ডেভেলপার জার্নিকে স্ট্যান্ডার্ডাইজ এবং সহজ করার জন্য Tokamax ডিজাইন করা হয়েছে। এটি ফাউন্ডেশনাল ক্লাস এবং শেয়ার্ড ইনফ্রাস্ট্রাকচারের মাধ্যমে এটি করে যা লাইব্রেরির সমস্ত অপারেটর উত্তরাধিকার সূত্রে পায় এবং একটি সুগঠিত ফ্রেমওয়ার্কের মধ্যে প্রয়োগ করে।

অপারেটর লেয়ার

Tokamax Base Class

tokamax.Op হল Tokamax-এর ফাউন্ডেশনাল ক্লাস, যা লাইব্রেরির প্রতিটি অপারেটরের জন্য বেস হিসেবে কাজ করে। কোনও ডিরাইভড অপারেটরকে কল করা হলে, এই লেয়ার অটোমেটিক নিম্নলিখিত কার্যকারিতা ম্যানেজ করে:

  • আর্গুমেন্ট বাইন্ডিং: কোনও কম্পিউটেশন রান করার আগে, বেস ক্লাস কলারের আর্গুমেন্টকে একটি ক্যানোনিক্যাল রিপ্রেজেন্টেশনে নরমালাইজ ও যাচাই করে যাতে ক্যাশিং, হিউরিস্টিক ও কার্নেল এক্সিকিউশন, ইনপুট কীভাবে পাস করা হয়েছে তা নির্বিশেষে ওয়ার্কলোড সম্পর্কে (একটি BoundArguments অবজেক্টের মাধ্যমে) যুক্তি দিতে পারে ( op.bind() দেখুন)।
  • ডিভাইস যাচাইকরণ: হার্ডওয়্যার সংক্রান্ত অমিল আগেভাগে ধরতে, অপারেটর টার্গেট অ্যাক্সিলারেটরের সাথে ডিভাইসের সামঞ্জস্য যাচাই করে, তবে CPU হোস্ট থেকে ক্রস-কম্পাইল করার সময় এই যাচাইকরণ বাইপাস করার অনুমতি দেয় (দেখুন op.supported_on(), bypass_device_check=True, এবং config.cross_compile(True))।
  • ব্যাচিং ক্যাপচার: কারণ সেরা কার্নেল কনফিগারেশন (Config) প্রায়ই একটি স্লাইসের পরিবর্তে সম্পূর্ণ ব্যাচ করা সমস্যার সাইজের উপর নির্ভর করে, তাই অপারেটর ভেক্টরাইজ করা হলে (jax.vmap) বেস ক্লাস আশেপাশের ব্যাচ ডাইমেনশন ক্যাপচার করে যাতে হিউরিস্টিক এবং অটোটিউনিং ক্যাশে আসল ওয়ার্কলোড শেপের জন্য অপ্টিমাইজ করতে পারে (op._capture_batched_args() দেখুন)।
  • কনফিগারেশন রেজোলিউশন: ম্যানুয়াল টিউনিংয়ের প্রয়োজন ছাড়াই বক্সের বাইরে শক্তিশালী পারফর্ম্যান্স প্রদান করতে, কলার হাইপারপ্যারামিটার প্রদান না করলে, বেস ক্লাস কার্নেল হাইপারপ্যারামিটার অটোমেটিক সমাধান করে -- ডিস্ক-ভিত্তিক অটোটউনিং ক্যাশেতে আগে থেকে অটোটউন করা সেটিংস উপলভ্য থাকলে তা আবার ব্যবহার করে অথবা বিল্ট-ইন হিউরিস্টিক্সে ফিরে যায় (BoundArguments.default_config দেখুন)।
  • StableHLO মেটাডেটা সিরিয়ালাইজেশন: অফলাইন প্রোফাইলিং ও অটোমেটেড টিউনিংয়ের জন্য কম্পাইল করা প্রোগ্রাম ইন্ট্রোস্পেক্টেবল করতে, বেস ক্লাস লোয়ার্ড গ্রাফে অপারেটর মেটাডেটা এম্বেড করে যাতে ডাউনস্ট্রিম টুল কোন অপারেটর রান করেছে এবং কোন ইনপুট (শেপ, ধরন ইত্যাদি) সহ রান করেছে তা সরাসরি কম্পাইল করা মডিউল বা পারফর্ম্যান্স প্রোফাইল (_tokamax_metadata() দেখুন) থেকে পুনর্নির্মাণ করতে পারে।
  • ফরওয়ার্ড এক্সিকিউশন ও কাস্টম VJP: বিশেষ হার্ডওয়্যার কার্নেল সাধারণত স্ট্যান্ডার্ড অটোমেটিক ডিফারেন্সিয়েশন দ্বারা দক্ষতার সাথে ডিফারেন্সিয়েট করা যায় না, তাই বেস ক্লাস ফরওয়ার্ড ও ব্যাকওয়ার্ড এক্সিকিউশনকে একটি পেয়ার হিসেবে কোঅর্ডিনেট করে, যার ফলে গ্রেডিয়েন্ট কম্পিউটেশনের সময় ফরওয়ার্ড পাস ইন্টারমিডিয়েট ভ্যালু সরাসরি কাস্টম ব্যাকওয়ার্ড কার্নেলে পাস করতে পারে (দেখুন op._fwd()) এবং jax.custom_vjp-এ কল করে।

Op-নির্দিষ্ট মূল ক্লাস

প্রতিটি অপারেটর ফ্যামিলি তার নিজস্ব মূল ক্লাসকে সংজ্ঞায়িত করে যা ফাউন্ডেশনাল অপারেটর ক্লাস থেকে ইনহেরিট করে এবং সমস্ত ব্যাকএন্ড জুড়ে শেয়ার করা চুক্তি স্থাপন করে (উদাহরণস্বরূপ, RaggedDot দেখুন):

  • রেফারেন্স ইমপ্লিমেন্টেশন: প্রতিটি অপারেটর বেস ক্লাস সম্পূর্ণ গাণিতিক স্পেসিফিকেশনের একটি পোর্টেবল, বিশুদ্ধ-JAX রেফারেন্স ইমপ্লিমেন্টেশন প্রদান করে, প্রযোজ্য হলে গ্রেডিয়েন্ট সহ। এটি সংখ্যাগত নির্ভুলতা পরীক্ষার জন্য বাস্তবিক সত্য হিসেবে কাজ করে এবং যেকোনও হার্ডওয়্যারে একটি কার্যকরী ফলব্যাক নিশ্চিত করে (দেখুন RaggedDot._fwd())।
  • ক্যানোনিকাল বাইন্ডিং: ব্যবহারকারীরা একই গাণিতিক অপারেশন একাধিক উপায়ে প্রকাশ করতে পারেন—যেমন, বিভিন্ন ধরনের মাস্ক, প্রিসিশন সেটিংস বা ডাইমেনশন স্পেসিফিকেশন পাস করা—অপারেটর বেস ক্লাস ইনপুটকে নরমালাইজ করে এবং শেপ ও টাইপ কম্প্যাটিবিলিটি আগে থেকে চেক করে যাতে স্বতন্ত্র হার্ডওয়্যার ব্যাকএন্ডকে শুধুমাত্র একটি, অনুমানযোগ্য ইনপুট ফর্ম্যাট (দেখুন RaggedDot.bind()) ম্যানেজ করতে হয়।

Op ইমপ্লিমেন্টেশন ক্লাস

এই ক্লাসগুলি হার্ডওয়্যার-নির্দিষ্ট কার্নেল বাস্তবায়ন প্রদান করে এবং হতে পারে ব্যবহারকারীদের দ্বারা সরাসরি ইনস্ট্যান্ট করা এবং আহ্বান করা হয়েছে। প্রতিটি ইমপ্লিমেন্টেশন তার অপারেটর-নির্দিষ্ট মূল ক্লাস থেকে উত্তরাধিকার সূত্রে প্রাপ্ত হয় এবং ব্যাকএন্ড-নির্দিষ্ট আচরণ প্রদান করে (উদাহরণস্বরূপ, PallasMosaicTpuRaggedDot দেখুন):

  • মূল কার্যকারিতা: এখানে প্রকৃত হার্ডওয়্যার কার্নেল এক্সিকিউশন সংজ্ঞায়িত করা হয়, সাধারণত Pallas-এর মতো কার্নেল ভাষা ব্যবহার করে। যখন কোনও অপারেশনের জন্য বিশেষ ব্যাকওয়ার্ড পাসের প্রয়োজন হয়, তখন গ্রেডিয়েন্ট কার্নেলকে সাধারণত নিজস্ব ফার্স্ট-ক্লাস অপারেটর ইমপ্লিমেন্টেশন হিসেবে মডেল করা হয় যাতে এটি স্বাধীনভাবে কনফিগার, টিউন ও পরীক্ষা করা যায়। যদিও সর্বনিম্ন-লেভেল কার্নেল কোড প্রায়ই মডিউলারিটির জন্য আলাদা সহায়ক ফাইলে ফ্যাক্টর করা হয়, এই ক্লাস সেই কার্নেলকে ইনভোক করার জন্য প্রাথমিক ইন্টারফেস হিসেবে কাজ করে (দেখুন PallasMosaicTpuRaggedDot._fwd())।
  • কনফিগারেশন: যেহেতু হার্ডওয়্যার কার্নেল প্রায়শই পারফর্ম্যান্স নব প্রকাশ করে—যেমন টাইল সাইজ, পাইপলাইন স্টেজ বা মেমরি বাফারিং স্ট্র্যাটেজি, প্রতিটি ব্যাকএন্ড একটি ডেডিকেটেড কনফিগারেশন স্ট্রাকচার সংজ্ঞায়িত করে যা ব্যবহারকারী বা অটোমেটেড টুলকে কার্নেল কীভাবে পার্টিশন, কম্পাইল এবং এক্সিকিউট করা হয় তা নিয়ন্ত্রণ করতে দেয় (দেখুন Config)।
  • হিউরিস্টিক: প্রতিটি ওয়ার্কলোড আগে থেকে অটোটিউন করা হয় না, তাই প্রতিটি ব্যাকএন্ড বিল্ট-ইন হিউরিস্টিক প্রদান করে যা সমস্যার মাত্রা, ডেটার ধরন এবং অ্যাক্সিলারেটর স্পেসিফিকেশনের উপর ভিত্তি করে যুক্তিসঙ্গত ডিফল্ট টিউনিং প্যারামিটার বেছে নেয় (দেখুন _get_heuristics_config())।
  • অটোটিউনিং সার্চ স্পেস: যেসব ওয়ার্কলোডের ক্ষেত্রে সর্বোচ্চ পারফর্ম্যান্স গুরুত্বপূর্ণ, সেগুলির জন্য প্রতিটি ব্যাকএন্ড কোনও নির্দিষ্ট সমস্যার আকারের জন্য সঠিক প্যারামিটার কম্বিনেশনের অটোটিউনিং সার্চ স্পেস নির্ধারণ করে, যার ফলে অটোটিউনার ক্যান্ডিডেটদের বেঞ্চমার্ক করতে এবং সবচেয়ে দ্রুত কনফিগারেশন খুঁজে পেতে পারে (_get_autotuning_configs() দেখুন)।
  • প্রয়োগ-নির্দিষ্ট যাচাইকরণ: হার্ডওয়্যার কার্নেলে প্রায়শই সাধারণ গাণিতিক অপারেশনের চেয়ে কঠোর প্রয়োজনীয়তা থাকে, যেমন ডাইমেনশন অ্যালাইনমেন্ট নিয়ম বা সীমিত ডেটা টাইপ সাপোর্ট। প্রতিটি ইমপ্লিমেন্টেশন এইসব সীমাবদ্ধতা যাচাই করে এবং কোনও ওয়ার্কলোড সামলানো না গেলে সিগন্যাল দেয়, যার ফলে উচ্চ-লেভেলের ডিসপ্যাচার অন্য ব্যাকএন্ডে সুন্দরভাবে ফলব্যাক করতে পারে (দেখুন PallasMosaicTpuRaggedDot._fwd())।

High-Level API

Most operators have multiple backends—such as a portable reference implementation alongside one or more hardware-specific kernels—and expose a single familiar, high-level entry point (e.g., a standard jax.lax function). এই লেয়ারটি ব্যবহারকারীদের একটি সহজ, ড্রপ-ইন ইন্টারফেস দেওয়ার জন্য ডিজাইন করা হয়েছে যা অটোমেটিক তাদের হার্ডওয়্যার এবং ইনপুট আকারের জন্য সবচেয়ে ভালো সমর্থিত ব্যাকএন্ড বেছে নেয়, তবে এখনও তাদের ইচ্ছা হলে একটি নির্দিষ্ট বাস্তবায়নের অনুরোধ করতে দেয় (tokamax.ragged_dot() দেখুন)।

ArgSpecs

ব্যাকএন্ড জুড়ে কার্নেল পরীক্ষা এবং অপ্টিমাইজ করার জন্য গুরুত্বপূর্ণ ওয়ার্কলোড শেপের একটি শেয়ার্ড ক্যাটালগ বজায় রাখা প্রয়োজন। Tokamax এই প্রতিনিধিত্বমূলক প্রোডাকশন এবং বেঞ্চমার্ক শেপগুলিকে ওয়ার্কলোড স্পেসিফিকেশন হিসাবে ক্যাপচার করে যা অপারেটরের সমস্ত বাস্তবায়ন জুড়ে শেয়ার করা হয়। এটি কন্টিনিউয়াস ইন্টিগ্রেশন টেস্ট, রিগ্রেশন বেঞ্চমার্ক এবং অটোটিউনিং পাইপলাইনকে single source of truth প্রদান করে যা বিভিন্ন ওয়ার্কফ্লোর জন্য ট্যাগ দ্বারা ফিল্টার করা যেতে পারে (ragged_dot-এর জন্য ArgSpecs দেখুন)।

রিপোজিটরি স্ট্রাকচার

ইন্টার্নাল ইমপ্লিমেন্টেশন কোড প্রাইভেট সোর্স ট্রির (দেখুন tokamax/_src) অধীনে থাকে, যদিও অপারেটর, অটোটউনিং, বেঞ্চমার্কিং ও কনফিগারেশনের জন্য পাবলিক সিম্বল টপ-লেভেল মডিউলের (দেখুন tokamax/__init__.py) মাধ্যমে আবার এক্সপোর্ট করা হয়।

প্রতিটি অপারেটর ডিরেক্টরির (দেখুন tokamax/_src/ops) মধ্যে, ফাইলগুলি একটি সামঞ্জস্যপূর্ণ নামকরণের নিয়ম অনুসরণ করে, যা এখানে র‍্যাগড ডট ব্যবহার করে দেখানো হয়েছে:

  • হাই-লেভেল API: সর্বজনীন ফাংশনাল এন্ট্রি পয়েন্ট ও ব্যাকএন্ড ডিসপ্যাচ লজিক (দেখুন api.py) নির্ধারণ করে।
  • Op-নির্দিষ্ট বেস ক্লাস: পোর্টেবল রেফারেন্স ইমপ্লিমেন্টেশনকে সংজ্ঞায়িত করে (দেখুন base.py)।
  • ব্যাকএন্ড ইমপ্লিমেন্টেশন: হার্ডওয়্যার-নির্দিষ্ট অপারেটর ক্লাস, কনফিগারেশন, হিউরিস্টিক ও অটোটিউনিং স্পেস (pallas_mosaic_tpu.py দেখুন) সংজ্ঞায়িত করে।
  • লো-লেভেল কার্নেল: স্বতন্ত্র কার্নেল ইমপ্লিমেন্টেশন এবং শেয়ার করা লো-লেভেল হেল্পারকে কম্প্যানিয়ন মডিউলে আলাদা করে (pallas_mosaic_tpu_kernel.py দেখুন)।
  • ওয়ার্কলোড স্পেসিফিকেশন: টেস্টিং, বেঞ্চমার্কিং ও অটোটউনিংয়ের জন্য ক্যানোনিকাল ইনপুট শেপের ক্যাটালগ (arg_specs.py দেখুন)।
  • টেস্ট স্যুট: প্রতিটি ব্যাকএন্ড টেস্ট স্যুটের পাশাপাশি শেয়ার করা প্যারামিটারাইজড সঠিকতা চেক করার পদ্ধতি নির্ধারণ করে (দেখুন test_base.py)।

experimental ডিরেক্টরির মধ্যে থাকা Ops একই ধরনের স্ট্রাকচার অনুসরণ করে, তবে পাবলিক API-তে প্রকাশ নাও হতে পারে। এইসব অপারেশন দ্রুত ইটারেশন ও এক্সপ্লোরেশনের জন্য তৈরি করা হয়েছে এবং এগুলি ঘন ঘন ও উল্লেখযোগ্যভাবে পরিবর্তিত হতে পারে। সাধারণত এগুলির ক্ষেত্রে চলমান রক্ষণাবেক্ষণ ও সহায়তার প্রত্যাশা কম থাকে।

ব্যবহারকারীদের কোন লেয়ার কল করা উচিত

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

অপারেটর ইমপ্লিমেন্টেশন ক্লাসের মাধ্যমে না গিয়ে সরাসরি লো-লেভেল কার্নেল ফাংশন কল করার সাজেশন দেওয়া হয় না। এটি করলে, অটোটিউনিং, ইনপুট যাচাইকরণ ও ক্যানোনিকালাইজেশন এবং মেটাডেটা সিরিয়ালাইজেশন সহ প্রয়োজনীয় ইনফ্রাস্ট্রাকচার বাইপাস করা হয়। এর ফলে, কোনও অর্থপূর্ণ ওভারহেড সেভিংস হয় না, কারণ অপারেটর র‍্যাপার ইচ্ছাকৃতভাবে হালকা করা হয়। যেমন, উপযুক্ত অটোটিউনড হাইপারপ্যারামিটার না থাকলে, ব্যবহারকারীরা সম্ভবত উল্লেখযোগ্যভাবে সাবঅপ্টিমাল পারফর্ম্যান্স দেখতে পাবেন।

উন্নত বিষয়

Operator Fusion

ফিউজিবল প্যালাস TPU অপারেটর @tokamax.ops.op_fusion.fuse-এর মাধ্যমে কার্নেলে সরাসরি আশেপাশের JAX প্রোলগ এবং এপিলগ ফিউজ করতে সাহায্য করে। ব্যবহারের উদাহরণ এবং ফিউশন-মানানসই কার্নেল ও Op সাবক্লাস তৈরি করার নির্দেশাবলীর জন্য Operator Fusion গাইড দেখুন।

সিরিয়াল অনুযায়ী সাজানো

কার্নেল StableHLO-তে সিরিয়ালাইজ করা যেতে পারে। কার্নেল কল হল JAX কাস্টম কল, যা সাধারণত jax.export-এ নিষিদ্ধ, যার জন্য tokamax.DISABLE_JAX_EXPORT_CHECKS ব্যবহার করতে হয় যাতে সব Tokamax কার্নেল এক্সপোর্ট করা যায়:

from jax import export

f_grad_exported = export.export(f_grad, disabled_checks=tokamax.DISABLE_JAX_EXPORT_CHECKS)(
    jax.ShapeDtypeStruct(x.shape, x.dtype),
    jax.ShapeDtypeStruct(scale.shape, scale.dtype),
)

মনে রাখবেন, Tokamax কার্নেলের সাথে সিরিয়ালাইজ করা ফাংশন স্ট্যান্ডার্ড StableHLO-এর ডিভাইস-ইন্ডিপেন্ডেন্স হারায়। Tokamax দুটি সিরিয়ালাইজেশন গ্যারেন্টি দেয়:

  1. নির্দিষ্ট ডিভাইসে সিরিয়ালাইজ করা ডিসিরিয়ালাইজড ফাংশনটি যে ডিভাইসের জন্য সিরিয়ালাইজ করা হয়েছে সেটিতেই রান করবে বলে গ্যারান্টি দেওয়া হবে।
  2. Tokamax, JAX-এর মতোই কম্প্যাটিবিলিটি গ্যারান্টি দেয়: ৬ মাসের ব্যাকওয়ার্ড কম্প্যাটিবিলিটি।

ক্রস-কম্পাইলেশন এবং সিপিইউ এক্সপোর্ট

Tokamax কার্নেল CPU হোস্টে এক্সপোর্ট বা ক্রস-কম্পাইল করা যেতে পারে:

  • স্পষ্টভাবে ইমপ্লিমেন্টেশন বেছে নেওয়া (যেমন implementation="mosaic_tpu_v2") অটোমেটিক হোস্ট ডিভাইস যাচাইকরণ বাইপাস করে।
  • বিকল্প হিসেবে, tokamax.config.cross_compile(True) ব্যবহার করে বিশ্বব্যাপী ক্রস-কম্পাইলেশন চালু করুন:
with tokamax.config.cross_compile(True):
  f_exported = export.export(
      f, disabled_checks=tokamax.DISABLE_JAX_EXPORT_CHECKS
  )(
      jax.ShapeDtypeStruct(x.shape, x.dtype),
      ...,
  )