การออกแบบห้องสมุด

Tokamax ออกแบบมาเพื่อสร้างมาตรฐานและลดความซับซ้อนของเส้นทางทั่วไปของนักพัฒนาซอฟต์แวร์เกี่ยวกับการเขียน การเพิ่มประสิทธิภาพ การบำรุงรักษา และการใช้งานเคอร์เนลในเวอร์ชันที่ใช้งานจริง โดยดำเนินการผ่านคลาสพื้นฐานและโครงสร้างพื้นฐานที่ใช้ร่วมกันซึ่งโอเปอเรเตอร์ทั้งหมดในไลบรารีรับช่วงมาและนำไปใช้ภายในเฟรมเวิร์กที่มีโครงสร้างที่ดี

เลเยอร์โอเปอเรเตอร์

คลาสพื้นฐาน Tokamax

tokamax.Op เป็นคลาสพื้นฐานของ Tokamax ซึ่งทำหน้าที่เป็นฐานสำหรับโอเปอเรเตอร์ทุกตัวในไลบรารี เมื่อมีการเรียกใช้โอเปอเรเตอร์ที่ได้มา เลเยอร์นี้จะจัดการฟังก์ชันการทำงานต่อไปนี้โดยอัตโนมัติ

  • การเชื่อมโยงอาร์กิวเมนต์: ก่อนที่การคำนวณจะทำงาน คลาสพื้นฐานจะปรับอาร์กิวเมนต์ของผู้เรียกให้เป็นมาตรฐานและตรวจสอบความถูกต้องเป็นรูปแบบ Canonical เดียว เพื่อให้การแคช การวิเคราะห์พฤติกรรม และการดำเนินการเคอร์เนลสามารถให้เหตุผลเกี่ยวกับภาระงานได้อย่างสม่ำเสมอ (ผ่านออบเจ็กต์ 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

คลาสพื้นฐานเฉพาะการดำเนินการ

ตระกูลโอเปอเรเตอร์แต่ละตระกูลจะกำหนดคลาสพื้นฐานของตนเองซึ่งรับค่ามาจากคลาสโอเปอเรเตอร์พื้นฐาน และสร้างสัญญาที่ใช้ร่วมกันในแบ็กเอนด์ทั้งหมด (เช่น ดู RaggedDot)

  • การใช้งานอ้างอิง: คลาสพื้นฐานของโอเปอเรเตอร์แต่ละคลาสจะมีการใช้งานอ้างอิง JAX แบบพกพาและบริสุทธิ์ของข้อกำหนดทางคณิตศาสตร์ทั้งหมด รวมถึงการไล่ระดับสีเมื่อเกี่ยวข้อง ซึ่งทำหน้าที่เป็นข้อมูลที่เป็นความจริงสำหรับการทดสอบความถูกต้องของตัวเลข และรับประกันว่าจะมีทางเลือกสำรองที่ใช้งานได้ในฮาร์ดแวร์ทุกประเภท (ดู RaggedDot._fwd())
  • การเชื่อมโยงตามรูปแบบบัญญัติ: เนื่องจากผู้ใช้สามารถแสดงการดำเนินการทางคณิตศาสตร์เดียวกันได้หลายวิธี เช่น การส่งมาสก์ การตั้งค่าความแม่นยำ หรือข้อกำหนดมิติข้อมูลในรูปแบบต่างๆ คลาสพื้นฐานของโอเปอเรเตอร์จะปรับอินพุตให้เป็นมาตรฐานและตรวจสอบความเข้ากันได้ของรูปร่างและประเภทล่วงหน้า เพื่อให้แบ็กเอนด์ฮาร์ดแวร์แต่ละรายการต้องจัดการกับรูปแบบอินพุตเดียวที่คาดการณ์ได้เท่านั้น (ดู RaggedDot.bind())

คลาสการติดตั้งใช้งาน Op

คลาสเหล่านี้ให้การใช้งานเคอร์เนลเฉพาะฮาร์ดแวร์ และผู้ใช้สามารถสร้างอินสแตนซ์และเรียกใช้ได้โดยตรง การใช้งานแต่ละรายการจะรับค่ามาจากคลาสพื้นฐานเฉพาะโอเปอเรเตอร์และให้ลักษณะการทำงานเฉพาะแบ็กเอนด์ (เช่น ดู PallasMosaicTpuRaggedDot)

  • ฟังก์ชันหลัก: ส่วนนี้เป็นที่ที่กำหนดการดำเนินการเคอร์เนลฮาร์ดแวร์จริง โดยปกติจะใช้ภาษาเคอร์เนล เช่น Pallas เมื่อการดำเนินการต้องใช้การส่งผ่านย้อนกลับแบบเฉพาะ โดยปกติแล้วเคอร์เนลการไล่ระดับสีจะได้รับการจำลองเป็นการใช้งานโอเปอเรเตอร์ชั้นหนึ่งของตัวเอง เพื่อให้สามารถกำหนดค่า ปรับแต่ง และทดสอบได้อย่างอิสระ แม้ว่าโค้ดเคอร์เนลระดับต่ำสุดมักจะแยกออกเป็นไฟล์ตัวช่วยแยกต่างหากเพื่อความเป็นโมดูล แต่คลาสนี้ทำหน้าที่เป็นอินเทอร์เฟซหลักสำหรับการเรียกใช้เคอร์เนลนั้น (ดู PallasMosaicTpuRaggedDot._fwd())
  • การกำหนดค่า: เนื่องจากเคอร์เนลฮาร์ดแวร์มักจะแสดงปุ่มควบคุมประสิทธิภาพ เช่น ขนาดไทล์ ขั้นตอนไปป์ไลน์ หรือกลยุทธ์การบัฟเฟอร์หน่วยความจำ แบ็กเอนด์แต่ละรายการจึงกำหนดโครงสร้างการกำหนดค่าเฉพาะที่ช่วยให้ผู้ใช้หรือเครื่องมืออัตโนมัติควบคุมวิธีแบ่งพาร์ติชัน คอมไพล์ และเรียกใช้เคอร์เนลได้ (ดู Config)
  • การเรียนรู้จากประสบการณ์: ไม่ใช่ว่าภาระงานทุกรายการจะได้รับการปรับแต่งอัตโนมัติล่วงหน้า ดังนั้นแบ็กเอนด์แต่ละรายการจึงมีการเรียนรู้จากประสบการณ์ในตัวซึ่งจะเลือกพารามิเตอร์การปรับแต่งเริ่มต้นที่เหมาะสมตามมิติข้อมูลของปัญหา ประเภทข้อมูล และข้อกำหนดของตัวเร่ง (ดู _get_heuristics_config())
  • พื้นที่ค้นหาการปรับแต่งอัตโนมัติ: สำหรับภาระงานที่ประสิทธิภาพสูงสุดเป็นสิ่งสำคัญ แบ็กเอนด์แต่ละรายการจะกำหนดพื้นที่ค้นหาการปรับแต่งอัตโนมัติของการรวมพารามิเตอร์ที่ถูกต้องสำหรับรูปร่างปัญหาที่กำหนด ซึ่งช่วยให้เครื่องมือปรับแต่งอัตโนมัติสามารถเปรียบเทียบผู้สมัครและค้นหาการกำหนดค่าที่เร็วที่สุดได้ (ดู _get_autotuning_configs())
  • การตรวจสอบความถูกต้องเฉพาะการใช้งาน: เคอร์เนลฮาร์ดแวร์มักมีข้อกำหนดที่เข้มงวดกว่าการดำเนินการทางคณิตศาสตร์ทั่วไป เช่น กฎการจัดแนวขนาดหรือการรองรับประเภทข้อมูลที่จำกัด การติดตั้งใช้งานแต่ละรายการจะตรวจสอบข้อจำกัดและสัญญาณเหล่านี้เมื่อไม่สามารถจัดการภาระงานได้ ซึ่งช่วยให้ผู้จัดส่งระดับสูงสามารถกลับไปใช้แบ็กเอนด์อื่นได้อย่างราบรื่น (ดู PallasMosaicTpuRaggedDot._fwd())

API ระดับสูง

โอเปอเรเตอร์ส่วนใหญ่มีแบ็กเอนด์หลายรายการ เช่น การติดตั้งใช้งานอ้างอิงแบบพกพาควบคู่ไปกับเคอร์เนลเฉพาะฮาร์ดแวร์อย่างน้อย 1 รายการ และแสดงจุดแรกเข้าในระดับสูงที่คุ้นเคยเพียงจุดเดียว (เช่น ฟังก์ชัน jax.lax มาตรฐาน) เลเยอร์นี้ออกแบบมาเพื่อให้ผู้ใช้มีอินเทอร์เฟซแบบ Drop-in ที่เรียบง่าย ซึ่งจะเลือกแบ็กเอนด์ที่รองรับที่ดีที่สุดสำหรับฮาร์ดแวร์และรูปร่างอินพุตโดยอัตโนมัติ ขณะเดียวกันก็ยังคงอนุญาตให้ผู้ใช้ขอการใช้งานที่เฉพาะเจาะจงได้เมื่อต้องการ (ดู tokamax.ragged_dot())

ArgSpecs

การดูแลรักษาแคตตาล็อกที่ใช้ร่วมกันของรูปแบบภาระงานที่สำคัญเป็นสิ่งจำเป็นสำหรับการทดสอบและเพิ่มประสิทธิภาพเคอร์เนลอย่างสม่ำเสมอในแบ็กเอนด์ต่างๆ Tokamax จะบันทึกรูปร่างการผลิตและรูปร่างการเปรียบเทียบที่เป็นตัวแทนเหล่านี้เป็นข้อกำหนดภาระงานที่แชร์ในการใช้งานทั้งหมดของผู้ให้บริการ ซึ่งจะทำให้การทดสอบการรวมอย่างต่อเนื่อง การเปรียบเทียบการถดถอย และไปป์ไลน์การปรับแต่งอัตโนมัติมีแหล่งข้อมูลที่เชื่อถือได้เพียงแหล่งเดียว (SSOT) ซึ่งกรองตามแท็กสำหรับเวิร์กโฟลว์ต่างๆ ได้ (ดู ArgSpecs สำหรับ ragged_dot)

โครงสร้างที่เก็บ

โค้ดการติดตั้งใช้งานภายในจะอยู่ในโครงสร้างซอร์สโค้ดส่วนตัว (ดู tokamax/_src) ส่วนสัญลักษณ์สาธารณะสำหรับโอเปอเรเตอร์ การปรับแต่งอัตโนมัติ การเปรียบเทียบ และการกำหนดค่าจะส่งออกอีกครั้งผ่านโมดูลระดับบนสุด (ดู tokamax/__init__.py)

ภายในไดเรกทอรีของผู้ให้บริการแต่ละราย (ดู tokamax/_src/ops) ไฟล์จะเป็นไปตามรูปแบบการตั้งชื่อที่สอดคล้องกัน ดังที่แสดงไว้ที่นี่โดยใช้ Ragged Dot

  • API ระดับสูง: กำหนดจุดแรกเข้าของฟังก์ชันสาธารณะและตรรกะการส่งแบ็กเอนด์ (ดู api.py)
  • คลาสพื้นฐานเฉพาะการดำเนินการ: กำหนดการติดตั้งใช้งานอ้างอิงแบบพกพา (ดู base.py)
  • การติดตั้งใช้งานแบ็กเอนด์: กำหนดคลาสโอเปอเรเตอร์ การกำหนดค่า การวิเคราะห์พฤติกรรม และพื้นที่การปรับแต่งอัตโนมัติเฉพาะฮาร์ดแวร์ (ดู pallas_mosaic_tpu.py)
  • Low-Level Kernels: แยกการติดตั้งใช้งานเคอร์เนลแบบสแตนด์อโลนและตัวช่วยระดับต่ำที่ใช้ร่วมกันออกเป็นโมดูลที่ใช้ร่วมกัน (ดู pallas_mosaic_tpu_kernel.py)
  • ข้อกำหนดของภาระงาน: แคตตาล็อกรูปแบบอินพุตตามรูปแบบบัญญัติสำหรับการทดสอบ การเปรียบเทียบ และการปรับแต่งอัตโนมัติ (ดู arg_specs.py)
  • ชุดโปรแกรมทดสอบ: กำหนดการตรวจสอบความถูกต้องที่กำหนดพารามิเตอร์ที่ใช้ร่วมกันควบคู่ไปกับชุดโปรแกรมทดสอบต่อแบ็กเอนด์ (ดู test_base.py)

การดำเนินการภายในไดเรกทอรี experimental จะเป็นไปตามโครงสร้างที่คล้ายกัน แต่อาจไม่แสดงใน API สาธารณะ การดำเนินการเหล่านี้มีไว้สำหรับการทำซ้ำและการสำรวจอย่างรวดเร็ว และอาจมีการเปลี่ยนแปลงบ่อยครั้งและมีนัยสำคัญ โดยทั่วไปแล้วจะมีความคาดหวังต่ำกว่าเกี่ยวกับการบำรุงรักษาและการสนับสนุนอย่างต่อเนื่อง

ผู้ใช้ควรเรียกใช้เลเยอร์ใด

การเลือกจุดแรกเข้าเป็นเรื่องของการแลกเปลี่ยนระหว่างความสะดวกและการควบคุม ผู้ใช้ส่วนใหญ่ควรเริ่มต้นด้วยการเรียกโอเปอเรเตอร์ผ่าน API ฟังก์ชันระดับสูง ซึ่งมีอินเทอร์เฟซสไตล์ที่คุ้นเคยและเลือกการติดตั้งใช้งานแบ็กเอนด์ที่เหมาะสมโดยอัตโนมัติ เมื่อจำเป็นต้องเลือกแบ็กเอนด์เชิงกำหนด ผู้ใช้สามารถส่งตัวเลือกการใช้งานที่ชัดเจนไปยังฟังก์ชันระดับสูงได้โดยยังคงใช้ลายเซ็นการเรียกเดียวกัน เพื่อให้ควบคุมได้สูงสุด ผู้ใช้สามารถสร้างอินสแตนซ์คลาสการติดตั้งใช้งานโอเปอเรเตอร์ที่เฉพาะเจาะจงได้โดยตรงเพื่อปรับแต่งไฮเปอร์พารามิเตอร์ของเคอร์เนล เช่น ขนาดไทล์ และส่งอาร์กิวเมนต์เฉพาะแบ็กเอนด์

เราไม่แนะนำให้เรียกใช้ฟังก์ชันเคอร์เนลระดับต่ำโดยตรงโดยไม่ผ่านคลาสการใช้งานโอเปอเรเตอร์ การทำเช่นนี้จะข้ามโครงสร้างพื้นฐานที่สำคัญ ซึ่งรวมถึงการปรับแต่งอัตโนมัติ การตรวจสอบอินพุตและการแปลงเป็นรูปแบบมาตรฐาน และการจัดรูปแบบข้อมูลเมตาเป็นอนุกรม โดยไม่ได้ช่วยประหยัดค่าใช้จ่ายเพิ่มเติมที่มีนัยสำคัญ เนื่องจาก Wrapper ของโอเปอเรเตอร์ได้รับการออกแบบมาให้มีน้ำหนักเบาโดยเจตนา ตัวอย่างเช่น หากไม่มีไฮเปอร์พารามิเตอร์ที่ปรับแต่งอัตโนมัติอย่างเหมาะสม ผู้ใช้ก็อาจเห็นประสิทธิภาพที่ต่ำกว่ามาตรฐานอย่างมาก

หัวข้อขั้นสูง

การรวมโอเปอเรเตอร์

โอเปอเรเตอร์ TPU ของ Fusible Pallas รองรับการรวมบทนำและบทส่งท้าย JAX โดยรอบเข้ากับเคอร์เนลโดยตรงผ่าน @tokamax.ops.op_fusion.fuse ดูตัวอย่างการใช้งานและวิธีการเขียนเคอร์เนลและคลาสย่อย 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 มีการรับประกันการจัดลำดับ 2 รายการดังนี้

  1. ฟังก์ชันที่ผ่านการดีซีเรียลไลซ์ซึ่งผ่านการซีเรียลไลซ์ในอุปกรณ์ที่เฉพาะเจาะจงจะได้รับการรับประกันว่าจะทำงานในอุปกรณ์ที่ผ่านการซีเรียลไลซ์มาอย่างแน่นอน
  2. Tokamax ให้การรับประกันความเข้ากันได้เช่นเดียวกับ JAX ซึ่งก็คือความเข้ากันได้แบบย้อนหลัง 6 เดือน

การคอมไพล์แบบข้ามระบบและการส่งออก 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),
      ...,
  )