Qwen/Qwen3-VL-4B-Instruct의 HuggingFaceM4/DocumentVQA 벤치마크 개선을 위한 자율 연구 루프

이 저장소는 에이전트 기반 학습(agentic training research)을 위해 설계되었습니다. 즉, 벤치마크와 평가기는 고정된 상태를 유지하고, 에이전트가 train.py를 반복적으로 수정하여 학습을 실행하고, 전체 검증 분할(full validation split)에서 결과를 측정하며, 실제 개선분만 보존합니다. 이 프로젝트는 karpathy/autoresearch에서 영감을 받았지만, 재현 가능한 계약(reproducible contract)을 가진 구체적인 공개 VLM 벤치마크에 초점을 맞추었습니다.

이 프로젝트가 연구, 평가(evals), 또는 에이전트 워크플로우에 유용하다면 저장소에 별표를 눌러주세요.

이 저장소에는 이전에 분리되었던 두 개의 코드베이스가 서로 다른 브랜치로 포함되어 있습니다:

브랜치별 명령어는 각 브랜치의 README를 사용하세요. main에서는 진입점(entrypoint)이 ./run_experiment.sh이며, mlx에서는 uv run python run_experiment.py입니다.

• 고정된 벤치마크: 전체 공식 DocVQA의 train, validation, 및 test 분할
• 고정된 평가기: 검증 점수는 항상 저장소 평가기에 의해 계산됩니다.
• 변경 가능한 표면(mutable surface): 에이전트는 train.py를 수정하도록 기대됩니다.
• 재현 가능한 루프: 준비(prepare) -> 학습(train) -> 평가(evaluate) -> 보존 또는 폐기 -> 반복
• 공개 벤치마크 마인드셋: 개선은 목표 지점을 옮기는 것이 아니라 더 나은 학습 결정에서 나와야 합니다.

prepare.py 데이터셋 + 모델 스냅샷 다운로드
|
train.py 수정 가능한 학습 코드 (에이전트가 이 부분을 수정함)
... 

유일한 목표는 전체 공식 검증 분할(full official validation split)에서 평균 ANLS로 정의되는 val_score를 최대화하는 것입니다.

유용한 후속 명령어:

uv run python analysis.py
uv run python submit_test.py

train.py: 수정 가능한 학습 코드
evaluate.py: 고정된 평가기
run_experiment.sh: main에서 한 번의 명령어로 학습 -> 평가 파이프라인 실행
...

전체 실험 프로토콜은 program.md에 있습니다. 실질적인 시작 프롬프트는 다음과 같습니다:

Read the entire repository, especially README.md and program.md. You may read all files for context, but only edit train.py. Run `uv run autoresearch-qwen doctor --json`, record a `--base-only` validation baseline, then start the autoresearch loop. Parse `artifacts/last_result.json` after each run and keep only changes that improve val_score.

artifacts/last_result.json: 최신 학습/평가 결과 페이로드(payload)를 저장합니다.
analysis.py: 누적된 결과를 바탕으로 실험 진행 상황을 플로팅합니다.
submit_test.py: 블라인드 DocVQA 테스트에 대한 예측값을 내보냅니다.

split: 제출물 묶음(submission bundle)을 업로드하기 전에 로컬에서 유효성을 검사합니다.

이슈 및 풀 리퀘스트는 특히 다음 항목들에 대해 환영합니다:

• 벤치마크 계약(benchmark contract)을 존중하는 더 강력한 학습 레시피
• 더 나은 실험 도구와 재현성(reproducibility)
• 더 명확한 문서화 및 온보딩
• 전용 브랜치에 속해야 하는 하드웨어별 개선 사항

벤치마크 계약 자체를 변경하고 싶다면, 먼저 이슈를 열어 그 근거가 명시되도록 해야 합니다.

• karpathy/autoresearch: 원래의 자율 연구 루프 프레임워크
• Qwen: 기반 비전-언어 모델(vision-language model)
• Hugging Face M4: 공개 DocVQA 데이터셋 릴리스