این راهنما قرارداد سازگاری بین کامپایلر XLA:GPU که یک فایل اجرایی سریالی تولید می‌کند و زمان اجرایی که آن را بارگذاری می‌کند، تعریف می‌کند و به شما می‌گوید که چگونه بدون نقض آن قرارداد، تغییری ایجاد کنید. برای آشنایی با کامپایل AOT و نحوه ساختاردهی و بارگذاری یک مصنوع، به کامپایل پیش از زمان XLA:GPU مراجعه کنید.
این قرارداد منحصراً برای بک‌اند XLA:GPU ( GpuExecutableProto ) اعمال می‌شود. فایل‌های اجرایی CPU و TPU AOT از مکانیسم‌های سریال‌سازی متفاوتی استفاده می‌کنند و خارج از محدوده هستند.
پنجره‌های سازگاری {#سازگاری}
XLA:GPU دو پنجره سازگاری ارائه می‌دهد:
- سازگاری رو به عقب (۶ ماه): یک محیط اجرایی که شامل تغییر شما است، باید هر مصنوع منتشر شده توسط کامپایلرها را در ۶ ماه گذشته، با معانی یکسان، بارگذاری و اجرا کند. این امر امکان بارگذاری مدل‌هایی را که مدتی پیش کامپایل شده‌اند، در یک محیط اجرایی به‌روز شده فراهم می‌کند.
- سازگاری رو به جلو (۲ هفته): کامپایلری که شامل تغییر شما است، نباید هیچ ساختار سریال‌سازی را منتشر کند که زمان اجرای آن تا ۲ هفته قدیمی‌تر نتواند آن را از حالت سریال خارج کند یا به اشتباه تفسیر کند. این امر امکان بارگذاری مدل‌های کامپایل شده با جدیدترین کامپایلر را در سرورهای استنتاج قدیمی‌تر و با مدت زمان اجرای طولانی در طول استقرارهای چرخشی فراهم می‌کند.
هر پیام و فیلد پروتو که به صورت انتقالی از GpuExecutableProto قابل دسترسی باشد، بخشی از این قرارداد است.
اولویت‌بندی تغییرات: آیا تغییر من ایمن است؟ {#ترجیح_بندی_تغییر}
برای تعیین اینکه آیا تغییر شما نیاز به اجرای مرحله‌ای دارد یا خیر، این توالی تصمیم‌گیری را دنبال کنید:
آیا تغییر شما شامل موارد زیر می‌شود؟
- یک پروتو که از
GpuExecutableProtoقابل دسترسی است -
ToProto/FromProto - کدهای اجرایی HLO یا نمونه‌های اولیه HLO که می‌توانند در یک فایل اجرایی GPU قرار گیرند
- نام‌ها یا معانی نمادهای هسته ثبت‌شده، فراخوانی‌های سفارشی یا کنترل‌کننده‌های FFI
- thunk زمان بارگذاری، خواندن‌های زمان اجرا را علامت‌گذاری یا ارسال می‌کند.
- معناشناسی اجرای thunk های موجود
خیر: این تغییر داخلی کامپایلر است (مثلاً بهینه‌سازی‌ها، منطق فیوژن، بازنویسی‌های کدژن) یا یک اصلاح‌کننده زمان اجرا کاملاً داخلی با رفتار بدون تغییر برای thunkهای موجود. نصب مستقیم آن ایمن است.
بله: به مرحله ۲ بروید.
- یک پروتو که از
آیا این تغییر، نحوه‌ی تفسیر مصنوعات موجود توسط زمان اجرا (اجرای thunkهای موجود، پاس‌های زمان بارگذاری، پیش‌فرض‌های پرچم‌های خواندن زمان اجرا) را تغییر می‌دهد؟
بله: فقط در صورتی مجاز است که برای هر مصنوع منتشر شده در ۶ ماه گذشته صحیح باشد؛ اگر معنای معنایی تغییر کرد، به جای آن یک فیلد یا پرچم جدید معرفی کنید.
خیر: به مرحله ۳ بروید.
آیا این تغییر، شاخه‌ی پشتیبانِ نوع thunk، فیلد proto یا deserialization موجود را حذف می‌کند؟
بله: سازگاری معکوس را نقض می‌کند، مگر اینکه انتشار کامپایلر حداقل ۶ ماه پیش متوقف شده باشد. نسخه پشتیبان deserialization را تا پایان دوره ۶ ماهه نگه دارید و تگ‌ها و نام‌های اولیه حذف شده را به عنوان
reservedعلامت‌گذاری کنید.خیر: به مرحله ۴ بروید.
آیا این تغییر، یک نوع thunk جدید، یک فیلد proto جدید که برای صحت لازم است، یا یک کد عملیاتی HLO جدید در مصنوع سریالی شده منتشر می‌کند؟
بله: اگر بلافاصله منتشر شود، سازگاری رو به جلو را نقض می‌کند. انتشار مرحله‌ای را دنبال کنید.
خیر: به مرحله ۵ بروید.
آیا این تغییر، یک نماد هسته ثبت‌شده، فراخوانی سفارشی یا نام کنترل‌کننده FFI را تغییر نام می‌دهد یا حذف می‌کند؟
بله: نقض سازگاری با نسخه‌های قبلی است. ثبت‌های سازگار با نسخه‌های قبلی را با نام‌های قدیمی حداقل به مدت ۶ ماه حفظ کنید.
خیر: به مرحله ۶ بروید.
آیا این تغییر یک فیلد پروتو اختیاری اضافه می‌کند که زمان‌های اجرای قدیمی‌تر بتوانند بدون رگرسیون‌های درستی، آن را با خیال راحت نادیده بگیرند؟
بله: اجرای برنامه بی‌خطر است، مشروط بر اینکه فیلدهای اولیه‌ی تنظیم نشده، معانی قدیمی زمان اجرا را حفظ کنند.
خیر: تغییر را دوباره طراحی کنید تا سازگاری رو به جلو و عقب حفظ شود.
ایمن در مقابل شکستن تغییرات
| تغییر | حکم | تأثیر سازگاری | روش ایمن |
|---|---|---|---|
| بهینه‌سازی کامپایلر پس، ادغام یا کدژن (طرح یکسان) | امن | هیچکدام | مستقیماً به زمین فرود بیایید. |
| اصلاح‌کننده زمان اجرا در حافظه با رفتار بدون تغییر برای thunkهای موجود (حافظه‌های پنهان، مالکیت بافر) | امن | هیچکدام | مستقیماً با تست‌های واحد فرود بیایید. |
بازسازی ToProto / FromProto با بایت‌های سریالیزه شده یکسان | امن | هیچکدام | مستقیماً فرود بیایید؛ شامل تست‌های رفت و برگشت نیز می‌شود. |
| فیلد اولیه جدیدی اضافه کنید که پیش‌فرضِ بدون تنظیم آن، رفتار قدیمی را حفظ می‌کند. | امن | هیچکدام | مطمئن شوید که FromProto حالت تنظیم نشده (unset) را به طور تمیز مدیریت می‌کند. |
| فیلد پروتو جدید مورد نیاز برای صحت زمان اجرا را اضافه کنید | شکستن | سازگاری رو به جلو | عرضه مرحله‌ای (ابتدا پشتیبانی از زمان اجرا). |
| نوع thunk جدید، یکی از انواع آن یا مقدار شمارشی را منتشر می‌کند. | شکستن | سازگاری رو به جلو | راه‌اندازی مرحله‌ای (ابتدا runtime thunk را اضافه کنید). |
| کد اجرایی جدید HLO را در ماژول سریالی شده منتشر کنید | شکستن | سازگاری رو به جلو | انتشار مرحله‌ای؛ انتشار گیت تا زمان اتمام پنجره زمان اجرا. |
حذف نوع thunk، فیلد proto یا شاخه FromProto | شکستن | سازگاری با نسخه‌های قبلی | ۶ ماه پس از توقف انتشار صبر کنید؛ برچسب‌های رزرو. |
| تغییر شماره فیلد موجود یا نوع داده پروتو | شکستن | سازگاری رو به جلو و رو به عقب | هرگز برچسب‌های فیلد موجود را تغییر ندهید؛ یک برچسب جدید اختصاص دهید. |
| تغییر معنای معنایی یک فیلد موجود | شکستن | سازگاری رو به جلو و رو به عقب | یک فیلد جدید که نشان‌دهنده‌ی رفتار جدید است، معرفی کنید. |
| تغییر نام یا حذف نماد هسته ثبت شده یا کنترل کننده FFI | شکستن | سازگاری با نسخه‌های قبلی | ثبت نام مستعار را تحت نام اصلی به مدت ۶ ماه حفظ کنید. |
| تغییر مسیر thunk زمان بارگذاری یا تغییر وضعیت پیش‌فرض پرچم خواندن زمان اجرا | بستگی دارد | سازگاری با نسخه‌های قبلی | فقط در صورتی مجاز است که برای هر مصنوع منتشر شده در 6 ماه گذشته صحیح باشد. |
انتشار مرحله‌ای برای شکستن تغییرات {#انتشار_مرحله‌ای}
هنگام معرفی یک ساختار سریال‌سازی جدید، آن را در سه مرحله اجرا کنید تا هر دو پنجره سازگاری برآورده شوند:
- پشتیبانی از زمان اجرا. منطق deserialization و اجرا را به زمان اجرا اضافه کنید. اگر انتشار کامپایلر در همان PR گنجانده شده است، انتشار را به طور پیش‌فرض در پشت یک پرچم آزمایشی غیرفعال نگه دارید. سپس حداقل ۲ هفته از ادغام این تغییر صبر کنید تا زمان اجرای به‌روز شده در محیط‌های استقرار منتشر شود.
- انتشار کامپایلر. انتشار کامپایلر را به طور پیش‌فرض فعال کنید (یا مقدار پیش‌فرض پرچم ویژگی را برعکس کنید). سپس نسخه پشتیبان deserialization قدیمی را حداقل به مدت ۶ ماه در زمان اجرا نگه دارید، که از این مرحله (زمانی که کامپایلر انتشار فرم قدیمی را متوقف کرد) شمارش می‌شود، نه از مرحله ۱.
- پاکسازی. مسیر deserialization قدیمی را حذف کنید و شماره‌های proto tag و نام فیلدهای منسوخ شده را به عنوان
reservedعلامت‌گذاری کنید.
مراحل ۱ و ۲ می‌توانند دو درخواست pull باشند (دومی پس از ۲ هفته از ارسال درخواست اول ارسال می‌شود) یا یک درخواست PR واحد که در آن انتشار به طور پیش‌فرض در پشت یک پرچم غیرفعال است و در ادامه برگردانده می‌شود.
حذف نظرات و مثال‌ها
هر گونه سازگاری جایگزین در زمان اجرا باید تاریخ انقضای خود را مستند کند:
// Backward-compatibility fallback for legacy AOT-compiled kernels without
// an explicit CollectiveKernelSpec.
// Can be removed in <month year> (6 months backward compatibility window).
نمونه‌هایی از انتشار عمومی OpenXLA:
- PR #49046 : ابتدا تخصیص جریان اختصاصی در زمان اجرا معرفی شد و انتشار به طور پیش‌فرض در طول پنجره‌ی انتشار غیرفعال نگه داشته شد.
- PR #46865 : پشتیبانی از thunk زمان اجرا برای
CollectiveReduceاضافه شد، با محافظت از انتشار کامپایلر در پشت یک پرچم آزمایشی.
نوشتن کد زمان اجرا برای فایل‌های اجرایی deserialized
هنگام پیاده‌سازی thunkهای زمان اجرا و روال‌های deserialization:
- بدون انواع فقط کامپایلر: thunk های زمان اجرا نباید به ساختارهای داده کامپایلر مانند
HloInstruction*یاBufferAssignmentوابسته باشند. - اعتبارسنجی مرزهای غیر سریالی‌شده: همیشه قبل از شاخص‌گذاری، شاخص‌های تخصیص بافر، آفست‌های برش و شناسه‌های جریان را در برابر مرزهای تخصیص اعتبارسنجی کنید.
- بارهای داده تکراری نباشند: یک بار داده بزرگ مشابه (مثلاً ثابت‌ها) را بیش از یک بار در مصنوع ذخیره نکنید؛ این کار حافظه زمان بارگذاری را چند برابر می‌کند.
- تخصیص‌های اولیه‌ی محافظت: زمان‌های اجرای سرویس تحت محدودیت‌های سختگیرانه‌ی حافظه عمل می‌کنند. از تخصیص‌های هیپ بی‌قید و شرط در طول مقداردهی اولیه‌ی
FromProtoیا thunk خودداری کنید.
آزمایش
تمام تغییرات سریال‌سازی باید توسط تست‌های خودکار پوشش داده شوند:
- تست‌های واحد رفت و برگشت: صحت سریال‌سازی و حذف سریال‌سازی را از طریق تست‌های
ToProtoوFromProtoتأیید کنید (بهThunkProtoDeserializationTestمراجعه کنید). - تست‌های سازگاری طلایی AOT: تست‌های سازگاری سرتاسری در
xla/tests/aot_compatibility/gpu(مانندcollective_ops_aot_test.cc) قرار دارند و در مقابل فایل‌های اجرایی طلایی سریالی شده درexecutables/<target>/v<N>/اجرا می‌شوند. - آزمایش تمام نسخه‌های تاریخی: به‌طور پیش‌فرض، آزمایش‌های طلایی در برابر نسخه‌های مرزی (قدیمی‌ترین و جدیدترین) اعتبارسنجی می‌شوند. در محیط آزمایش خود،
XLA_AOT_TEST_ALL_VERSIONS=1را تنظیم کنید تا در برابر تمام نسخه‌های طلایی تاریخی اجرا شود.