라이브러리 설계

Tokamax는 커널 작성, 최적화, 유지관리, 프로덕션 사용과 관련된 일반적인 개발자 여정을 표준화하고 간소화하도록 설계되었습니다. 이는 라이브러리의 모든 연산자가 잘 구조화된 프레임워크 내에서 상속하고 구현하는 기본 클래스와 공유 인프라를 통해 이루어집니다.

연산자 레이어

Tokamax 기본 클래스

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 호출 참조).

작업별 기본 클래스

모든 연산자 계열은 기본 연산자 클래스에서 상속되는 자체 기본 클래스를 정의하고 모든 백엔드에서 공유되는 계약을 설정합니다(예: RaggedDot 참조).

  • 참조 구현: 각 연산자 기본 클래스는 해당하는 경우 경사를 포함하여 전체 수학 사양의 이식 가능한 순수 JAX 참조 구현을 제공합니다. 이는 수치 정확성 테스트의 정답 역할을 하며 모든 하드웨어에서 작동하는 대체 기능을 보장합니다(RaggedDot._fwd() 참고).
  • 표준 바인딩: 사용자는 다양한 형태의 마스크, 정밀도 설정 또는 차원 사양을 전달하는 등 여러 가지 방법으로 동일한 수학 연산을 표현할 수 있으므로 연산자 기본 클래스는 입력을 정규화하고 형태 및 유형 호환성을 사전에 확인하여 개별 하드웨어 백엔드가 예측 가능한 단일 입력 형식만 처리하면 됩니다(RaggedDot.bind() 참고).

작업 구현 클래스

이러한 클래스는 하드웨어별 커널 구현을 제공하며 사용자가 직접 인스턴스화하고 호출할 수 있습니다. 각 구현은 연산자별 기본 클래스에서 상속되며 백엔드별 동작을 제공합니다(예: PallasMosaicTpuRaggedDot 참고).

  • 핵심 기능: 실제 하드웨어 커널 실행이 정의되는 곳으로, 일반적으로 Pallas와 같은 커널 언어를 사용합니다. 작업에 특수한 역방향 패스가 필요한 경우, 경사 커널은 일반적으로 독립적으로 구성, 조정, 테스트할 수 있도록 자체 일급 연산자 구현으로 모델링됩니다. 최하위 수준 커널 코드는 모듈성을 위해 별도의 도우미 파일로 분리되는 경우가 많지만, 이 클래스는 해당 커널을 호출하는 기본 인터페이스 역할을 합니다(PallasMosaicTpuRaggedDot._fwd() 참고).
  • 구성: 하드웨어 커널은 타일 크기, 파이프라인 단계, 메모리 버퍼링 전략과 같은 성능 노브를 노출하는 경우가 많으므로 각 백엔드는 사용자 또는 자동화 도구가 커널의 파티션 나누기, 컴파일, 실행 방식을 제어할 수 있는 전용 구성 구조를 정의합니다(Config 참고).
  • 휴리스틱: 모든 워크로드가 사전에 자동 조정되는 것은 아니므로 각 백엔드는 문제 차원, 데이터 유형, 가속기 사양에 따라 합리적인 기본 조정 매개변수를 선택하는 기본 제공 휴리스틱을 제공합니다(_get_heuristics_config() 참조).
  • 자동 조정 검색 공간: 최고 성능이 중요한 워크로드의 경우 각 백엔드는 지정된 문제 형태에 대해 유효한 매개변수 조합의 자동 조정 검색 공간을 정의하여 자동 조정기가 후보를 벤치마킹하고 가장 빠른 구성을 찾을 수 있도록 합니다(_get_autotuning_configs() 참조).
  • 구현별 검증: 하드웨어 커널은 차원 정렬 규칙이나 제한된 데이터 유형 지원과 같은 일반적인 수학 연산보다 더 엄격한 요구사항을 갖는 경우가 많습니다. 각 구현은 이러한 제약 조건을 검증하고 워크로드를 처리할 수 없는 경우 신호를 보내 상위 수준 디스패처가 다른 백엔드로 원활하게 대체할 수 있도록 합니다(PallasMosaicTpuRaggedDot._fwd() 참고).

상위 수준 API

대부분의 연산자에는 하나 이상의 하드웨어별 커널과 함께 이식 가능한 참조 구현과 같은 여러 백엔드가 있으며, 친숙한 단일 상위 수준 진입점(예: 표준 jax.lax 함수)을 노출합니다. 이 레이어는 사용자에게 하드웨어 및 입력 형태에 가장 적합한 백엔드를 자동으로 선택하는 간단한 드롭인 인터페이스를 제공하는 동시에 원하는 경우 특정 구현을 요청할 수 있도록 설계되었습니다(tokamax.ragged_dot() 참고).

ArgSpecs

중요한 워크로드 형태의 공유 카탈로그를 유지하는 것은 백엔드 전반에서 커널을 일관되게 테스트하고 최적화하는 데 필수적입니다. Tokamax는 이러한 대표적인 프로덕션 및 벤치마크 형태를 연산자의 모든 구현에서 공유되는 워크로드 사양으로 캡처합니다. 이렇게 하면 지속적 통합 테스트, 회귀 벤치마크, 자동 조정 파이프라인에 다양한 워크플로의 태그로 필터링할 수 있는 단일 정보 소스가 제공됩니다(ragged_dot의 ArgSpecs 참조).

저장소 구조

내부 구현 코드는 비공개 소스 트리(tokamax/_src 참고)에 있으며 연산자, 자동 조정, 벤치마킹, 구성의 공개 기호는 최상위 모듈을 통해 다시 내보내집니다(tokamax/__init__.py 참고).

각 연산자 디렉터리(tokamax/_src/ops 참고) 내에서 파일은 일관된 이름 지정 규칙을 따르며, 여기서는 래기드 도트를 사용하여 설명합니다.

  • 상위 수준 API: 공개 기능 진입점 및 백엔드 전달 로직을 정의합니다(api.py 참고).
  • 작업별 기본 클래스: 이식 가능한 참조 구현을 정의합니다(base.py 참고).
  • 백엔드 구현: 하드웨어별 연산자 클래스, 구성, 휴리스틱, 자동 조정 공간을 정의합니다(pallas_mosaic_tpu.py 참고).
  • 하위 수준 커널: 독립형 커널 구현과 공유 하위 수준 도우미를 컴패니언 모듈로 분리합니다(pallas_mosaic_tpu_kernel.py 참고).
  • 워크로드 사양: 테스트, 벤치마킹, 자동 조정을 위한 표준 입력 형태를 분류합니다(arg_specs.py 참조).
  • 테스트 모음: 백엔드별 테스트 모음과 함께 공유된 매개변수화된 정확성 검사를 정의합니다(test_base.py 참고).

experimental 디렉터리 내의 작업은 유사한 구조를 따르지만 공개 API에 노출되지 않을 수 있습니다. 이러한 작업은 빠른 반복과 탐색을 위한 것으로, 지속적인 유지보수 및 지원에 대한 기대치가 일반적으로 낮으며 자주 크게 변경될 수 있습니다.

사용자가 호출해야 하는 레이어

진입점을 선택하는 것은 기본적으로 편의성과 제어 간의 절충입니다. 대부분의 사용자는 익숙한 스타일의 인터페이스를 제공하고 적합한 백엔드 구현을 자동으로 선택하는 상위 수준 함수형 API를 통해 연산자를 호출하는 것으로 시작해야 합니다. 결정론적 백엔드 선택이 필요한 경우 사용자는 동일한 호출 서명을 유지하면서 명시적인 구현 선택을 상위 수준 함수에 전달할 수 있습니다. 최대한의 제어를 위해 사용자는 특정 연산자 구현 클래스를 직접 인스턴스화하여 타일 크기와 같은 커널 하이퍼파라미터를 맞춤설정하고 백엔드별 인수를 전달할 수 있습니다.

연산자 구현 클래스를 거치지 않고 하위 수준 커널 함수를 직접 호출하는 것은 권장되지 않습니다. 이렇게 하면 자동 조정, 입력 검증 및 표준화, 메타데이터 직렬화를 비롯한 필수 인프라를 우회하게 되며, 연산자 래퍼는 의도적으로 가볍게 설계되었기 때문에 오버헤드를 크게 줄이지 못합니다. 예를 들어 적절한 자동 조정 하이퍼파라미터가 없으면 사용자는 최적의 성능을 얻지 못할 가능성이 높습니다.

고급 주제

연산자 융합

융합 가능한 Pallas TPU 연산자는 @tokamax.ops.op_fusion.fuse를 통해 주변 JAX 프롤로그와 에필로그를 커널에 직접 융합하는 것을 지원합니다. 사용 예시와 퓨전 호환 커널 및 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와 동일한 호환성 보장(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),
      ...,
  )