FlyLeague

공개된 초파리 시각 신경회로 모델이 눈으로 본 것을 처리하고, 그 신경 활동만 보고 움직이는 가상 초파리 10마리가 5대5 풋살을 배우는 2D 다중 에이전트 강화학습 시뮬레이터다.

T10 최종 체크포인트로 기록한 5v5 경기(Q-20MATCH 1경기, 42.0초 시점). 오른쪽 패널은 선택한 선수의 행동, 신경 판독값 108개, 수용체 721개의 휘도다.

무엇을, 왜 만드는가

FlyVis는 초파리 시각계의 커넥톰(connectome, 뉴런 간 연결 지도)을 제약으로 학습된 공개 신경회로 모델이다(뉴런 45,669개, 세포유형 65종, 수용체 위치 721개). FlyLeague는 이 회로를 행동 경로 한가운데에 둔다.

경기 상태 → 선수별 자기중심 광선투사(흑백 휘도) → FlyVis(가중치 고정) → 세포유형 판독 → 정책(actor) → 이동·회전·킥

정책은 공이나 상대의 좌표를 받지 않는다. 볼 수 있는 것은 신경 판독값과 자기 몸 감각(고유감각)뿐이다. 그래서 신경 출력을 끊거나 특정 세포유형을 억제하면 경기력이 실제로 달라지는지 같은 질문을 같은 시드·같은 상대로 비교해 볼 수 있다.

핵심 특징

• 자체 배치 풋살 엔진: Torch 텐서 연산으로 여러 경기를 한 번에 병렬 처리한다. 1인 연습, 1v1, 2v2, 3v3, 5v5를 지원하고, 벽 반사, 득점 후 킥오프 재배치, 골키퍼 역할 입력이 있다.
• 신경 경로 강제: actor 입력은 FlyVis v2 판독값 108개와 고유감각 8개다. 전역 상태는 학습 전용 중앙 critic만 본다. 좌표 정책은 디버깅 기준선으로만 쓰고 신경 효과 주장에는 쓰지 않는다.
• 회로 조작 평가: 정상, 신경 출력 차단(output_block), T4/T5 세포유형 억제(silence_types), 같은 수의 무작위 뉴런 억제(silence_control) 4조건을 고정 시드와 진영 교대로 비교한다.
• MAPPO 학습: 공유 actor와 중앙 critic을 쓰는 자체 PPO 구현이다. single → 1v1 → 2v2 → 3v3 → 5v5 커리큘럼, 과거 정책 자기대전 풀, 정확한 재개용 체크포인트를 갖췄다.
• 재현 가능한 기록과 관전: NPZ+JSON 리플레이를 오프라인 브라우저 뷰어로 본다. CPU 라이브 경기를 시작·일시정지·재개·정지·초기화하며 볼 수도 있다.
• GPU 학습 환경: AMD Radeon RX 9070 XT에서 ROCm on WSL Docker 이미지로 학습했다. CPU만으로도 설치, 테스트, 경기, 평가, 뷰어를 쓸 수 있다.

현재 결과 (T10 최종 캠페인)

사전등록한 프로토콜 하나로 학습 캠페인 1회를 돌렸다. 자세한 수치와 한계는 최종 결과에 있다.

• 학습 경로 완주: single → 1v1 → 3v3 → 5v5 커리큘럼을 실제 GPU 경험으로 학습해 총 약 18.0M env-step을 마쳤다. 다만 네 단계 모두 성능 기준을 넘지 못했고, 사전등록 규칙에 따라 예산 소진으로 다음 단계로 넘어갔다(budget_forced).
• Q-20MATCH PASS: 최종 5v5 체크포인트로 10개체 전원이 신경 경로로 행동하는 120초 경기를 20회 연속 오류 없이 마쳤다(신경 에이전트 결정 240,200회).
• 신경 경로 의존성 확인: 5v5에서 규칙 기반 팀을 상대로 신경 출력을 차단하면 평균 득실차(GD)가 -8.66, T4/T5 억제 시 -19.76 떨어졌다(같은 수 무작위 뉴런 억제는 -2.34). 정책이 실제로 신경 판독값에 기대어 움직인다는 뜻이다. 두 억제 조건은 각각 정상과 비교했으며, 유형−대조 직접 CI를 사전등록하지 않아 세포유형 특이 효과는 확립하지 못했다.
• 경기력은 아직 낮다: 규칙 기반 팀 상대 평균 GD는 3v3 -1.20, 5v5 -1.22로 진다. 무작위 초기 정책 대비 개선(3v3 +0.26 [-0.28, +0.80], 5v5 +0.54 [-0.20, +1.28])은 95% 신뢰구간이 0을 포함해 유의하지 않다.

소프트웨어 완성, 장시간 안정성, 학습된 경기력은 별개의 결론이다. 이 프로젝트는 앞의 둘을 보였고, 세 번째는 아직 보이지 못했다.

5분 체험 (CPU)

Windows PowerShell, Python 3.12 기준이다. 규칙 기반 5v5 경기를 한 번 녹화하고 브라우저로 본다. FlyVis 모델 다운로드는 필요 없다.

python -m pip install uv
git clone https://git.2ex.dev/hanyul/FlyLeague.git
cd FlyLeague
python -m uv venv --python 3.12 .venv
python -m uv pip install --python .venv/Scripts/python.exe -e ".[sim,neuro,dev,viewer]"
.venv/Scripts/python.exe scripts/run_headless.py --episodes 1 --team-size 5 --record runs/quickstart
.venv/Scripts/python.exe scripts/view_replay.py runs/quickstart.npz --port 8791

run_headless.py는 120초짜리 경기 한 번을 돌리고 episodes=1 ... errors=0 형식의 요약을 출력한다. 리플레이는 runs/quickstart.npz와 옆의 runs/quickstart.json으로 저장된다. 뷰어를 띄운 뒤 http://127.0.0.1:8791 을 열어 재생·프레임 이동·속도 변경을 하고, 선수를 클릭해 행동을 본다. 포트를 지정하지 않으면 8765를 쓴다. 끝내려면 Ctrl+C를 누른다.

이 녹화는 규칙 기반 선수라 신경 채널이 없다. 위 그림처럼 시야와 신경 활동까지 보려면 사용 설명서의 정책 리플레이 기록을 따른다.

문서 지도

목적	문서
설치(Windows CPU), FlyVis 모델 확보·검증	docs/install.md
GPU 환경(RX 9070 XT, ROCm on WSL Docker)	docs/docker-rocm.md
경기, 학습·재개, 평가, 리플레이, 라이브 경기, HTTP API	docs/user-guide.md
시스템 구조, 데이터 계약, 설계 결정	docs/architecture.md
감각 모델(광선투사, 휘도 코드, 판독 v2)	docs/sensory-model.md
신경 모델(FlyVis 래퍼, 무결성, 조작 훅)	docs/neuro-model.md
학습(MAPPO, 커리큘럼, 자기대전, 체크포인트)	docs/training.md
요구사항 ↔ 구현 ↔ 테스트 ↔ 증거	docs/traceability.md
라이선스·제3자 고지	docs/third-party.md
결과: P0 GPU 가능성 점검	docs/results/p0-gpu.md
결과: 정확도·처리량(T7, T8)	docs/results/throughput.md
결과: 중간 신경 경로 실험(T6)	docs/results/midterm.md
결과: CPU 중간 검증(T9)	docs/results/t9-verification.md
결과: 최종 커리큘럼·평가·Q-20MATCH(T10)	docs/results/final.md
결과: 라이브 뷰어 응답 시간(T11)	docs/results/live-viewer.md
기여자·코딩 에이전트 안내	AGENTS.md

상태와 한계

• 학습 캠페인은 한 번뿐이다. 신뢰구간은 초기 조건 불확실성만 반영하며, 독립 학습 시드 반복은 하지 않았다.
• 규칙 기반 팀을 이기지 못한다. 학습 성과는 결과 문서의 측정값 그대로 읽어야 한다.
• 시각 장면(흑백 휘도 코드, 원기둥 선수, 골대 식별 휘도)은 인공 가정이다. 실제 초파리 광학이나 조명을 재현하지 않는다.
• GPU 경로는 RX 9070 XT + Docker Desktop(WSL2) 한 구성에서만 검증했다. Windows 네이티브 실행은 CPU 전용이다.
• 브라우저 수동 조작 검수, 5v5 실신경 라이브 지연, 배포는 수행하지 않았다.

라이선스와 출처

FlyVis 1.2.0(TuragaLab) 사전학습 모델은 저장소에 포함하지 않는다. 설치 시 공식 다운로더로 받아 data/manifest.json의 해시로 검증한다. 제3자 구성요소와 고지는 docs/third-party.md에 정리돼 있다. 풋살 엔진은 자체 Torch 구현이며 VMAS 코드를 복사하거나 런타임에 쓰지 않는다.