android_kata

KataGo (v1.18.2, tf3-b11c768 transformer network, aka "t11b")를 Android에서 LiteRT와 ExecuTorch로 추론하도록 포팅하는 프로젝트.

범위: 모델 변환 파이프라인 + Android 추론 엔진 통합 (게임 UI/전체 앱은 범위 밖).

구조

katago/               git submodule, upstream lightvector/KataGo @ v1.18.2 (변환 소스/레퍼런스 오라클)
tools/model_export/    .bin.gz(+raw checkpoint) → ONNX/TFLite/ExecuTorch 변환 스크립트
android/               Android Gradle 프로젝트 (engine-native, engine, engine-test)
docs/                  결정 기록(ADR), 벤치마크 결과

진행 상황 및 계획

전체 마일스톤(M0~M4)과 조사 근거는 docs/decisions/0001-model-and-pipeline.md 참고.

• M0: katago submodule 고정(v1.18.2), 저장소 스켈레톤
• M0: tf3-b11c768 가중치(.bin.gz + raw checkpoint) 확보 (tools/model_export/fetch_model.sh)
• M0: raw checkpoint 아키텍처 검증 (tools/model_export/verify_checkpoint.py, config 전 항목 b11c768h12nbt3tflrs-fson-silu와 일치 확인)
• M0: KataGo ONNX 백엔드 빌드 (protobuf 설치 후 완료, 빌드 이슈 2건 해결 — docs/decisions/0001-model-and-pipeline.md "M1 오라클 확보 결과" 참고)
• M1: 공식 dumponnx 오라클 확보 + ONNX 백엔드로 runnnevalcanarytests 재통과(CUDA 빌드와는 독립된 경로) 완료. 실기기 덤프값을 오라클/PyTorch와 직접 diff해본 결과 실제 버그 발견: .pte 변환 스크립트가 SWA 평균 가중치가 아니라 원본(비-SWA) 가중치를 쓰고 있었음(공식 .bin.gz는 SWA 가중치 사용). 수정 후 오라클과 ~1e-6 수준 (FP32 오차 수준)으로 일치 확인, 실기기(ExecuTorch Android 런타임) 재검증까지 완료 — docs/decisions/0001-model-and-pipeline.md "'값' 비교 및 발견한 버그" 참고
• M2: LiteRT / ExecuTorch 변환 스파이크 및 백엔드 결정 — ExecuTorch는 raw checkpoint → torch.export → .pte 변환 및 eager 대비 수치 일치 확인 성공. LiteRT(litert-torch, 구 ai-edge-torch)는 트랜스포머 블록 4개 이상에서 컨버터 버그로 추정되는 tfl.batch_matmul 랭크 오류로 막혀 보류. ExecuTorch를 M3 1차(유일) 백엔드로 확정 (docs/decisions/0002-litert-vs-executorch.md)
• M3: Android 통합 (docs/decisions/0003-android-integration.md) — engine-native (NDK로 katago의 board/rules/boardhistory/nninputs.cpp 재사용 + JNI), engine (KataGoNet/ExecuTorchEngine/Mcts 기본 PUCT), engine-test(인스트루먼트 테스트) 스캐폴딩 완료, 전체 모듈 빌드(assembleDebug/assembleDebugAndroidTest) 성공. 실기기(SM-X730, Tailscale로 무선 ADB 연결)에서 connectedAndroidTest 전부 통과 — JNI 재사용 로직, ExecuTorch .pte 로드/추론, Mcts 탐색 루프까지 end-to-end 검증 완료. SWA 가중치 버그 수정(위 M1 참고) 후 최종 .pte로 실기기 재검증도 완료
• M4: 검증 및 벤치마크 정리 (docs/benchmarks.md) — XNNPACK 델리게이트 적용 (to_edge_transform_and_lower(partitioner=[XnnpackPartitioner()])), 오라클과의 수치 일치 유지, 실기기 지연시간 5~5.6배 개선(evaluate_producesExpectedShapes 4.27s→0.854s, mcts_picksALegalMove 60.9s→10.9s). Vulkan(GPU)은 시도 안 함 — 공식 executorch-android AAR에 Vulkan 백엔드가 아예 안 들어있어(XNNPACK만 컴파일됨) 쓰려면 ExecuTorch를 소스에서 직접 빌드해야 하는데, 투자 대비 효과가 불확실해 이번 범위에서 제외하기로 확정(2026-09-05, 사용자 확인). XNNPACK을 최종 가속 백엔드로 채택

서브모듈 받기

git submodule update --init --recursive

Android 빌드

android/는 Android SDK cmake 패키지 대신 시스템 cmake + ninja를 쓰도록 구성돼 있다 (자세한 배경은 docs/decisions/0003-android-integration.md). 필요한 것:

• Android SDK (ANDROID_HOME), NDK (side-by-side로 설치, 어떤 버전이든 android/engine-native/build.gradle.kts가 특정 버전을 강제하진 않음)
• cmake, ninja (시스템 패키지든 uv tool install ninja로 받은 것이든 PATH에 있으면 됨)
• android/local.properties(gitignore됨)에 sdk.dir=<SDK 경로>와 cmake.dir=<cmake가 있는 디렉토리> 설정

cd android
./gradlew assembleDebug assembleDebugAndroidTest