طراحی کتابخانه

Tokamax برای استانداردسازی و ساده‌سازی مسیرهای معمول توسعه‌دهنده در زمینه تألیف، بهینه‌سازی، نگهداری، و استفاده تولیدی از هسته طراحی شده است. این کار را ازطریق کلاس‌های بنیادی و زیرساخت مشترکی انجام می‌دهد که همه اپراتورها در کتابخانه از آن ارث می‌برند و در چارچوبی با ساختار مناسب پیاده‌سازی می‌کنند.

لایه‌های اپراتور

Tokamax Base Class

tokamax.Op کلاس پایه‌ای Tokamax است که به‌عنوان پایه برای هر اپراتور در کتابخانه عمل می‌کند. وقتی هر اپراتور مشتق‌شده‌ای فراخوانده می‌شود، این لایه به‌طور خودکار عملکرد زیر را مدیریت می‌کند:

  • اتصال آرگومان: قبل‌از اجرای هرگونه محاسبات، کلاس پایه آرگومان‌های فراخواننده را به یک نمایش متعارف واحد نرمال‌سازی و اعتبارسنجی می‌کند تا ذخیره‌سازی موقت، اکتشافی، و اجرای هسته همگی بتوانند به‌طور یکنواخت درباره حجم کاری (ازطریق شیء BoundArguments) استدلال کنند، صرف‌نظر از اینکه ورودی‌ها چگونه منتقل شده‌اند (op.bind() را ببینید).
  • اعتبارسنجی دستگاه: برای تشخیص زودهنگام عدم تطابق سخت‌افزار، اپراتور پشتیبانی دستگاه را دربرابر شتاب‌دهنده هدف قبل‌از اجرا تأیید می‌کند، درحالی‌که همچنان اجازه می‌دهد این بررسی هنگام کامپایل متقابل از میزبان CPU دور زده شود (به op.supported_on()، bypass_device_check=True، و config.cross_compile(True) مراجعه کنید).
  • Batching Capture: Because the best kernel configuration (Config) often depends on the full batched problem size rather than a single slice, the base class captures surrounding batch dimensions when an operator is vectorized (jax.vmap) so that heuristics and autotuning caches can optimize for the true workload shape (see op._capture_batched_args()).
  • Config Resolution: To provide strong performance out of the box without requiring manual tuning, the base class resolves kernel hyperparameters automatically whenever the caller does not supply them -- reusing previously autotuned settings in a disk-based autotuning cache if available, or falling back to built-in heuristics (see BoundArguments.default_config).
  • StableHLO Metadata Serialization: To make compiled programs introspectable for offline profiling and automated tuning, the base class embeds operator metadata into the lowered graph so downstream tools can reconstruct which operators ran and with what inputs (shapes, types, etc.) directly from a compiled module or performance profile (see _tokamax_metadata()).
  • اجرای پیش‌رو و VJP سفارشی: چون هسته‌های سخت‌افزاری تخصصی اغلب نمی‌توانند به‌طور کارآمد توسط تفکیک خودکار استاندارد تفکیک شوند، کلاس پایه اجرای پیش‌رو و پس‌رو را به‌عنوان یک جفت هماهنگ می‌کند و به گذر پیش‌رو اجازه می‌دهد مقادیر میانی را مستقیماً به یک هسته پس‌رو سفارشی درطول محاسبه گرادیان منتقل کند (به op._fwd() مراجعه کنید) و به jax.custom_vjp فراخوانی کند.

کلاس پایه مختص عملیات

هر خانواده عملگر کلاس پایه خودش را تعریف می‌کند که از کلاس عملگر بنیادی ارث‌بری می‌کند و قراردادی را که بین همه پس‌بخش‌ها مشترک است ایجاد می‌کند (برای مثال، RaggedDot را ببینید):

  • پیاده‌سازی مرجع: هر کلاس پایه عملگر یک پیاده‌سازی مرجع JAX خالص و قابل‌حمل از مشخصات کامل ریاضی ارائه می‌دهد، ازجمله گرادیان‌ها درصورت لزوم. این به‌عنوان واقعیت عینی برای آزمایش‌های درستی عددی عمل می‌کند و تضمین می‌کند که در هر سخت‌افزاری یک جایگزین فعال وجود دارد (به RaggedDot._fwd() مراجعه کنید).
  • اتصال متعارف: چون کاربران می‌توانند یک عملیات ریاضی را به روش‌های مختلفی بیان کنند (مثلاً با ارسال شکل‌های مختلف ماسک، تنظیمات دقت، یا مشخصات ابعاد)، کلاس پایه اپراتور ورودی‌ها را نرمال‌سازی می‌کند و سازگاری شکل و نوع را ازقبل بررسی می‌کند تا باطن‌های سخت‌افزاری مجزا فقط نیاز به مدیریت یک قالب ورودی واحد و قابل‌پیش‌بینی داشته باشند (به RaggedDot.bind() مراجعه کنید).

کلاس‌های پیاده‌سازی Op

این کلاس‌ها پیاده‌سازی‌های هسته مختص سخت‌افزار را ارائه می‌دهند و می‌توانند مستقیماً توسط کاربران نمونه‌سازی و فراخوانی شوند. هر پیاده‌سازی از کلاس پایه خاص اپراتور خود ارث‌بری می‌کند و رفتار خاص پسین را ارائه می‌دهد (برای مثال، PallasMosaicTpuRaggedDot را ببینید):

  • عملکرد اصلی: این جایی است که اجرای هسته سخت‌افزاری واقعی تعریف می‌شود، معمولاً بااستفاده از زبان هسته مانند Pallas. وقتی عملیاتی به گذر عقب‌گرد تخصصی نیاز دارد، هسته گرادیان معمولاً به‌عنوان پیاده‌سازی اپراتور درجه یک خودش مدل‌سازی می‌شود تا بتوان آن را به‌طور مستقل پیکربندی، تنظیم، و آزمایش کرد. اگرچه کد هسته پایین‌ترین سطح اغلب برای مدولار بودن در یک فایل کمکی جداگانه فاکتور می‌شود، این کلاس به‌عنوان رابط اصلی برای فراخوانی آن هسته عمل می‌کند (به PallasMosaicTpuRaggedDot._fwd() مراجعه کنید).
  • پیکربندی: چون هسته‌های سخت‌افزاری اغلب دکمه‌های عملکردی را نشان می‌دهند (مانند اندازه‌های کاشی، مراحل خط لوله، یا استراتژی‌های بافر حافظه)، هر پس‌زمینه یک ساختار پیکربندی اختصاصی تعریف می‌کند که به کاربران یا ابزارهای خودکار اجازه می‌دهد نحوه تقسیم‌بندی، کامپایل، و اجرای هسته را کنترل کنند (به Config مراجعه کنید).
  • اکتشافی: همه حجم‌های کاری ازقبل به‌طور خودکار تنظیم نشده‌اند، بنابراین هر پشت‌افزار اکتشافی‌های داخلی ارائه می‌دهد که پارامترهای تنظیم پیش‌فرض معقولی را براساس ابعاد مسئله، انواع داده، و مشخصات شتاب‌دهنده انتخاب می‌کنند (به _get_heuristics_config() مراجعه کنید).
  • فضای جستجوی تنظیم خودکار: برای حجم‌های کاری که عملکرد اوج اهمیت دارد، هر پس‌زمینه یک فضای جستجوی تنظیم خودکار از ترکیب‌های پارامتر معتبر برای یک شکل مسئله معین تعریف می‌کند، که به تنظیم‌کننده خودکار اجازه می‌دهد تا نامزدها را محک بزند و سریع‌ترین پیکربندی را کشف کند (به _get_autotuning_configs() مراجعه کنید).
  • اعتبارسنجی مختص پیاده‌سازی: هسته‌های سخت‌افزاری اغلب الزامات سخت‌گیرانه‌تری نسبت به عملیات ریاضی عمومی دارند، مانند قوانین تراز ابعاد یا پشتیبانی محدود از نوع داده. هر پیاده‌سازی این محدودیت‌ها را اعتبارسنجی می‌کند و زمانی که حجم کاری قابل‌مدیریت نباشد، سیگنال می‌دهد، و به توزیع‌کنندگان سطح بالاتر اجازه می‌دهد تا به‌طور مناسب به یک پسوند دیگر بازگردند (ببینید PallasMosaicTpuRaggedDot._fwd()).

High-Level API

اکثر اپراتورها چندین باطن دارند—مانند یک پیاده‌سازی مرجع قابل حمل در کنار یک یا چند هسته خاص سخت‌افزار—و یک نقطه ورود آشنا و سطح بالا (مثلاً یک تابع استاندارد jax.lax) را ارائه می‌دهند. این لایه طراحی شده است تا به کاربران یک رابط کاربری ساده و آماده ارائه دهد که به‌طور خودکار بهترین پسوند پشتیبانی‌شده را برای سخت‌افزار و شکل‌های ورودی آن‌ها انتخاب می‌کند، درحالی‌که همچنان به آن‌ها اجازه می‌دهد درصورت تمایل، پیاده‌سازی خاصی را درخواست کنند (به tokamax.ragged_dot() مراجعه کنید).

ArgSpecs

حفظ کاتالوگ مشترک از شکل‌های مهم حجم کاری برای آزمایش و بهینه‌سازی هسته‌ها به‌طور مداوم در سراسر پس‌بک‌ها ضروری است. Tokamax این شکل‌های تولید و محک نماینده را به‌عنوان مشخصات حجم کاری که در همه پیاده‌سازی‌های یک اپراتور هم‌رسانی می‌شود ضبط می‌کند. این کار به آزمایش‌های ادغام مداوم، محک‌های رگرسیون، و خطوط لوله تنظیم خودکار یک منبع واحد حقیقت می‌دهد که می‌توان آن را براساس برچسب‌ها برای گردش‌های کاری مختلف فیلتر کرد (به ArgSpecs برای ragged_dot مراجعه کنید).

ساختار مخزن

کد پیاده‌سازی داخلی در درخت منبع خصوصی قرار دارد (به tokamax/_src مراجعه کنید)، درحالی‌که نمادهای عمومی برای اپراتورها، تنظیم خودکار، محک‌زنی، و پیکربندی ازطریق ماژول‌های سطح بالا دوباره صادر می‌شوند (به tokamax/__init__.py مراجعه کنید).

در هر فهرست راهنمای اپراتور (به tokamax/_src/ops مراجعه کنید)، فایل‌ها از قرارداد نام‌گذاری ثابتی پیروی می‌کنند که در اینجا بااستفاده از نقطه ناهموار نشان داده شده است:

  • میانای برنامه‌سازی کاربردی سطح بالا: نقطه ورودی عملکردی عمومی و منطق ارسال باطن را تعریف می‌کند (api.py را ببینید).
  • کلاس پایه مختص عملیات: پیاده‌سازی مرجع قابل‌حمل را تعریف می‌کند (به base.py مراجعه کنید).
  • پیاده‌سازی‌های پس‌نهایی: کلاس‌های اپراتور، پیکربندی‌ها، اکتشافی‌ها، و فضاهای تنظیم خودکار مختص سخت‌افزار را تعریف می‌کند (به pallas_mosaic_tpu.py مراجعه کنید).
  • هسته‌های سطح پایین: پیاده‌سازی‌های هسته مستقل و کمک‌کننده‌های سطح پایین مشترک را به واحدهای همراه جدا می‌کند (به pallas_mosaic_tpu_kernel.py مراجعه کنید).
  • مشخصات حجم کاری: شکل‌های ورودی متعارف را برای آزمایش، محک‌زنی، و تنظیم خودکار فهرست‌بندی می‌کند (به arg_specs.py مراجعه کنید).
  • مجموعه‌های آزمون: بررسی‌های درستی پارامتری‌شده مشترک را در کنار مجموعه‌های آزمون هر پس‌رانه تعریف می‌کند (test_base.py را ببینید).

عملیات‌های موجود در فهرست experimental از ساختار مشابهی پیروی می‌کنند، اما ممکن است در میانای برنامه‌سازی کاربردی عمومی نمایش داده نشوند. این عملیات‌ها برای تکرار و کاوش سریع درنظر گرفته شده‌اند و ممکن است به‌طور مکرر و قابل‌توجهی تغییر کنند، و معمولاً انتظارات کمتری درخصوص نگهداری و پشتیبانی مداوم دارند.

Which Layer Should Users Call

انتخاب نقطه ورود اساساً موازنه‌ای بین راحتی و کنترل است. اکثر کاربران باید با فراخوانی اپراتورها ازطریق میانای برنامه‌سازی کاربردی تابعی سطح بالا شروع کنند که میانایی با سبک آشنا ارائه می‌دهد و به‌طور خودکار پیاده‌سازی پسای مناسبی را انتخاب می‌کند. وقتی انتخاب قطعی باطن لازم باشد، کاربران می‌توانند انتخاب پیاده‌سازی صریحی را به تابع سطح بالا منتقل کنند و درعین‌حال همان شناسه ارتباط را حفظ کنند. برای کنترل حداکثری، کاربران می‌توانند یک کلاس پیاده‌سازی اپراتور خاص را مستقیماً برای سفارشی‌سازی فراپارامترهای هسته (مانند اندازه‌های کاشی) نمونه‌سازی کنند و آرگومان‌های مختص پس‌بخش را ارسال کنند.

فراخوانی مستقیم توابع هسته سطح پایین بدون عبور از کلاس پیاده‌سازی اپراتور توصیه نمی‌شود. انجام این کار زیرساخت‌های ضروری را دور می‌زند—ازجمله تنظیم خودکار، اعتبارسنجی و متعارف‌سازی ورودی، و سریال‌سازی فراداده—بدون اینکه صرفه‌جویی معناداری در سربار ارائه دهد، زیرا پوشاننده‌های عملگر به‌طور عمدی سبک هستند. برای مثال، درصورت نبود فراپارامترهای تنظیم‌شده خودکار مناسب، کاربران احتمالاً عملکردی به‌طور قابل‌توجهی غیربهینه خواهند دید.

موضوعات پیشرفته

Operator Fusion

عملگرهای Fusible Pallas TPU از ادغام پیش‌گفتارها و پس‌گفتارهای JAX اطراف مستقیماً در هسته ازطریق @tokamax.ops.op_fusion.fuse پشتیبانی می‌کنند. برای نمونه‌های استفاده و دستورالعمل‌های مربوط به نوشتن هسته‌های سازگار با ادغام و زیرکلاس‌های Op، به راهنمای ادغام اپراتور مراجعه کنید.

سریال‌سازی

هسته‌ها را می‌توان به StableHLO سریال‌سازی کرد. فراخوانی‌های هسته فراخوانی‌های سفارشی JAX هستند که به‌طور پیش‌فرض در jax.export ممنوع هستند، و برای اینکه همه هسته‌های Tokamax صادر شوند، tokamax.DISABLE_JAX_EXPORT_CHECKS باید استفاده شود:

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 را ارائه می‌دهد: سازگاری با نسخه قدیمی ۶ ماهه.

کامپایل متقاطع و صادر کردن CPU

هسته‌های 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),
      ...,
  )