분산 머신러닝 학습·추론 코드를 망가뜨리지 않고 고치기

## 먼저 코드를 읽고 공유 구성이나 API를 바꾸기 전에 확인받기 편집하기 전에 관련 구현, 인접한 패턴, 구성 계약 및 테스트를 읽으십시오. 프로젝트의 환경 관리자, 포매터, 린터 및 pre-commit 도구 모음을 사용하고 훅을 우회하지 마십시오. 자격 증명, 머신 경로, 서비스 엔드포인트 또는 클러스터 토폴로지를 절대 하드코딩하지 마십시오. 스케줄러 설정을 추측하거나 문제 해결의 지름길로 가속기 드라이버와 런타임 스택을 다시 구축하지 마십시오. 다음 작업을 수행하기 전에 결정을 받으십시오. - 공유 구성 구조 변경 - 종속성 추가 - 런처 또는 스케줄러 동작 변경 - 공개 API 삭제, 이름 변경 또는 호환되지 않는 방식으로 변경 필요한 하드웨어나 클러스터 접근 권한이 없다면 어떤 통합 검사를 건너뛰었으며 그 이유가 무엇인지 명시하십시오. 검증되지 않은 분산 환경 가정을 코드로 옮기지 마십시오. 하위 시스템에 따라 작업을 분류하십시오. 하위 시스템에는 학습 엔진, 추론 엔진, 알고리즘, 런처, 스케줄러, 데이터셋, 보상, 워크플로 및 분산 디버깅이 있습니다. 프로젝트에 전문 구현 가이드나 도메인 검토 절차가 있다면 이를 사용하십시오. ## 하위 시스템별 역할을 나누고 데이터에 가중치 버전 붙이기 오케스트레이션, 롤아웃 생성, 학습, 추론, 인프라, 모델 적응, 보상, 데이터셋 및 여러 영역에 걸친 유틸리티를 서로 다른 책임으로 유지하십시오. 트레이너는 루프, 데이터 로딩 및 워크플로를 조정합니다. 롤아웃 워크플로는 비동기 에피소드 생성을 정의합니다. 추론 엔진은 출력을 생성하고 가중치 업데이트를 수신하며, 학습 엔진은 롤아웃 텐서를 입력으로 받아 업데이트를 계산하고 새로운 가중치 버전을 게시합니다. 비동기 시스템에서는 생성된 데이터와 업데이트에 명시적인 가중치 버전 메타데이터를 첨부하십시오. 모델 버전이 서로 맞지 않는다는 사실이 드러나지 않은 상태에서 학습하거나 평가하지 마십시오. 표준 추적기를 통해 메트릭을 내보내고, 구성된 출력 루트 아래에 아티팩트를 영구 저장하며, 체크포인트에는 정식 저장 및 복구 경로를 사용하십시오. 관찰 가능성과 복구는 실행 계약의 일부입니다. 깊은 상속보다 합성과 위임을 우선하십시오. 엔진, 워크플로 및 모델 어댑터를 독립적으로 테스트할 수 있도록 확장 경계를 충분히 작게 유지하십시오. ## 디바이스-호스트 동기화를 피해 빠른 가속기 코드 쓰기 담당 모듈의 기존 명명, 타입 지정 및 로깅 규칙을 따르십시오. 명시적인 타입 힌트와 import를 사용하고 와일드카드 import는 절대 사용하지 마십시오. 무거운 선택적 종속성은 이를 필요로 하는 함수 또는 코드 경로 내부에 두십시오. 직접 출력하는 대신 프로젝트 로거를 사용하십시오. 동시 출력의 출처를 계속 식별할 수 있도록 로그 레코드에 구성 요소와 분산 rank 컨텍스트를 포함하십시오. 가속기 핫 패스에서는 다음을 지키십시오. - 로깅을 위해 스칼라 값이나 목록 값을 추출하는 것과 같은 디바이스-호스트 동기화를 피하십시오. - Python에서 개별 요소를 반복 처리하지 말고 텐서 연산을 일괄 처리하십시오. - 디바이스와 데이터 타입을 명시적으로 설정하십시오. - 경계에서 예상 텐서 형태를 assertion으로 검증하십시오. 롤아웃 워크플로가 차단되지 않도록 유지하십시오. 비동기 엔진 호출과 파일 작업을 await하고, 비동기 에피소드 경로에 동기식 I/O를 도입하지 마십시오. 새 기능을 구현할 때는 가장 가까운 정상 작동 모듈의 패턴을 따르고, 집중된 테스트를 추가하며, 관련 없는 리팩터링을 피하십시오. ## 호환성을 지키며 구성 필드와 공개 API 바꾸기 구성 필드는 필수 필드, 일반적인 선택 필드, 드문 선택 필드, 내부 필드 순으로 배치하십시오. 초기화 시 잘못된 값이나 위반된 제약 조건을 명시하는 명확한 예외를 사용해 검증하십시오. 공개 필드에는 안전한 기본값을 제공하십시오. 제거하기 전에 사용 중단으로 표시하고 기존 필드 타입을 변경하지 마십시오. 공개 구성 클래스는 제약 조건과 허용되는 값을 문서화해야 합니다. 유한한 명령줄 선택지는 자유 형식 문자열이 아닌 제한된 타입으로 표현하십시오. 병렬 구조를 새로 만들지 말고 정식 구성 데이터 클래스를 재사용하십시오. 공유 구성, 런처, 스케줄러 및 공개 API 이름을 영향이 큰 영역으로 취급하십시오. 변경 설명에 호환성 영향을 명시하고 파괴적이거나 호환되지 않는 편집을 하기 전에 승인을 받으십시오. 현재 계약만으로 올바른 동작을 결정할 수 없다면 기본값을 임의로 만들지 말고, 범위가 명확한 후속 작업 마커를 남기고 해결되지 않은 제약 조건을 보고하십시오. ## 모든 rank에서 프로세스 그룹과 집합 통신을 일치시키기 import 시점에 전역 프로세스 그룹을 절대 생성하지 마십시오. 의도한 프로세스 그룹을 명시적으로 전달하고, 그룹 구성원 여부가 중요할 때는 해당 그룹을 기준으로 rank를 조회하십시오. 디바이스 메시 차원을 선언된 병렬 처리 모델과 일치시키십시오. 해당하는 경우 데이터 샤딩, 텐서, 컨텍스트, 전문가 및 전문가 텐서 축을 포함하십시오. 집합 통신 연산은 전역 계약입니다. - 참여하는 모든 rank는 동일한 all-reduce를 동일한 순서로 호출해야 합니다. - 합계와 평균 중에서 선택하는 경우처럼 축소 연산을 신중하게 선택하십시오. - 브로드캐스트에는 명시적인 소스 rank를 지정해야 합니다. - 배리어는 진단 도구이며 일상적인 동기화 전략이 아닙니다. 멈춤 현상은 집합 통신 연산 순서가 서로 일치하지 않는지 확인하여 진단하십시오. 잘못된 결과는 축소 의미 체계와 가중치 버전을 확인하여 진단하십시오. 메모리 부족 오류는 모델 기능을 축소하기 전에 샤딩, 텐서 배치 및 디바이스 소유권을 확인하여 진단하십시오. 상세한 분산 실행, 통신 라이브러리 및 동기식 시작 진단 기능은 표적 디버깅에만 사용하고, 문제를 이해한 뒤에는 제거하거나 비활성화하십시오. ## 분산 코드를 테스트하고 건너뛴 테스트를 풀 리퀘스트에 적기 동작, 조건 및 예상 결과를 나타내도록 테스트 이름을 지정하고 준비, 실행, 검증 구조로 작성하십시오. 기본 CI가 올바른 테스트 모음을 선택할 수 있도록 느린 테스트, 비동기 테스트, 가속기 테스트 및 분산 테스트를 표시하십시오. 사용할 수 없는 가속기 또는 다중 노드 테스트는 명시적인 이유와 함께 적절히 건너뛰십시오. 단위 수준의 분산 동작에는 프레임워크의 모의 프로세스 그룹을 사용하십시오. 테스트에서 검증하려는 의미 체계를 가진 심층 샤딩이나 분산 텐서 내부 구현은 모킹하지 마십시오. 명시적인 상대 및 절대 허용 오차로 텐서를 비교하십시오. 관리되는 임시 경로와 범위가 제한된 monkeypatch를 우선하십시오. 먼저 범위가 좁은 단위 테스트 모음을 실행한 다음, 하드웨어가 허용하는 경우 직접 영향을 받는 가속기 또는 분산 테스트 모음을 실행하십시오. 제출하기 전에 전체 포매팅 및 pre-commit 도구 모음을 실행하십시오. 정식 생성기를 통해 명령줄 참조 문서를 생성하십시오. 필요한 정적 설정과 패키징을 수행하는 프로젝트 래퍼를 통해 릴리스 문서를 빌드하고, 프로젝트 단계를 누락하는 하위 수준의 문서 명령은 사용하지 마십시오. 풀 리퀘스트에 문제, 위험 영역, 정확한 테스트 명령, 건너뛴 테스트 모음과 그 이유 및 하드웨어 제한을 명시하십시오. 관례에 맞는 명령형 커밋 제목을 사용하고 검토 전에 작업 중 커밋을 제거하십시오.