8. 개발자 참고: 자동화 테스트와 코드 맵¶
실습만 하고 코드를 바꾸지 않는 독자는 이 장을 건너뛰어도 됩니다. 데이터 처리, 학습 코드, 또는 튜토리얼 자체를 바꾸려면 먼저 이 장을 읽으십시오. 이 프로젝트는 자동화 테스트로 "문서에 적힌 것"과 "코드가 실제로 하는 것"을 묶어 둡니다.
8.1 자동화 테스트¶
데이터 처리나 학습 코드를 바꾼 뒤에는 CPU 환경에서 회귀 테스트를 실행합니다. 이 환경에는 PyTorch, TRL, PEFT가 들어 있어, 무작위로 초기화한 아주 작은 모델로 학습 메커니즘을 검증합니다. 2장의 데이터 실습만 한다면 건너뛰어도 됩니다.
python3.11 -m venv .venv-cpu
source .venv-cpu/bin/activate
python -m pip install -r requirements-cpu.txt
python -m pytest -q
테스트에는 tests/를 포함한 프로젝트 전체 소스가 필요합니다. 3장의 경량화된 GPU 업로드 번들에는 개발자 테스트가 들어 있지 않습니다. 전체 프로젝트에서는 .venv-train으로도 테스트를 실행할 수 있습니다. 작은 모델 테스트에는 가중치를 내려받을 필요가 없습니다.
| 계층 | 테스트/명령 | 증명하는 것 |
|---|---|---|
| 데이터 | test_data.py, test_prepare.py, test_bundle.py, test_notebook.py |
단일 파일 로딩, 초안 게이트, 그룹 및 이후 턴 격리, 비어 있지 않은 타깃, 스냅숏 호환성 |
| 템플릿 | test_render.py, lab.audit |
타깃 범위, 토큰 경계, EOS, 길이 초과, 실제 collator의 패딩 |
| 작은 모델 학습 | test_training.py, test_notebook.py |
CLI 학습 구성 요소와 노트북의 실제 코드가 LoRA를 업데이트, 저장, 재로드, 병합할 수 있음 |
| 평가 | test_eval.py |
짝 맞추기, 누락된 점수, 무승부, 대화 단위 클러스터 통계 |
| 문서와 코드 | test_tutorial.py, test_book.py |
튜토리얼 명령을 실제 CLI가 받아들이고, 배포 예시와 부록이 소스와 일치하며, 페이지와 다운로드 번들이 동작함 |
| API 예시 | test_tutorial.py |
책의 호출 예시를 직접 실행해 모델 이름, 주소, 파라미터, 멀티턴 이력 전달을 확인 |
| 다운로드 | test_download.py |
모든 다운로드 소스가 같은 리비전을 사용하고, 누락되거나 손상된 가중치는 거부됨 |
| GPU 모델 | 4장과 5장의 명령 | 실제 QLoRA 학습/재개, 어댑터와 병합 결과물 |
| vLLM 통합 | /health, /v1/models, 5장의 Python 예시, vllm bench serve |
실제 서비스를 호출할 수 있고, 싱글턴/멀티턴/스트리밍 호출과 동시 부하 테스트가 완료됨 |
API 예시 테스트는 임시 로컬 HTTP 서버를 사용하므로 vLLM 추론의 증거가 될 수 없습니다. GPU와 서비스 점검은 각각의 환경에서 실행하며, 실행하지 않은 항목은 todo에서 체크하지 않은 채로 둡니다.
다음 완료 증거를 보관하십시오. 원본/확장 데이터와 검토 기록, 토큰 보고서와 테스트 출력, 모델 SHA, 의존성, 드라이버, 학습 설정, 체크포인트, 어댑터, 재개 단계, A/B/C 원본 출력과 점수, 병합 매니페스트, 추론 환경 버전, API 응답.
8.2 코드 읽기 지도와 설계 근거¶
메인 경로는 노트북부터 읽고, 보조 모듈은 역할별로 찾아보십시오.
| 튜토리얼 위치 | 대응 코드 | 목적 |
|---|---|---|
| 2.8절, 3장 | download.py, download-lock.json | 고정된 리비전을 내려받고 무결성 확인 |
| 2장 | dataset.json, data.py, prepare.py, common.py | 팩트와 대화 검증, 프롬프트 구성, 토큰화된 샘플 생성 |
| 2장, 6장 | audit.py | 실제 collator의 감독 범위와 패딩 확인 |
| 4장 | 01_gpu_train.en.ipynb | 1 epoch 학습, loss 곡선, 산출물 점검, 재로드 후 답변, 병합 |
| 4.6절, 6장, 부록 | train.py, training.py | 명령줄 학습, 정식 파라미터 비교, 체크포인트 재개 |
| 6장 | infer.py, evaluate.py | A/B/C 추론, 블라인드 평가 통계, 후보 고정 |
| 5장 | merge.py, 노트북의 마지막 두 섹션 | 독립 내보내기, vLLM 배포와 어댑터 마운트, API 호출, 부하 테스트 |
노트북은 학습의 세부 사항을 보여 주고, CLI는 반복 실험과 재개를 위해 남겨 두었으며, 진입점마다 담당하는 장이 있습니다. API 예시는 HTTP나 OpenAI SDK를 직접 호출하고, 부하 테스트는 vLLM에 내장된 vllm bench serve를 사용하므로 별도의 클라이언트는 유지하지 않습니다.
| 결정 | 이유와 출처 |
|---|---|
| 텍스트 전용 4B로 고정 | 같은 기본 모델에서 실험을 비교; Qwen 모델 카드 |
| 명시적인 completion mask | 감독 범위를 점검할 수 있음; TRL 0.24 |
| NF4+LoRA | 단일 GPU에서 소수의 파라미터만 학습; PEFT 양자화 |
| 별도의 추론 환경 | 의존성이 서로 덮어쓰는 것을 방지; vLLM GPU 설치 |
| 사실과 표현을 분리해 학습 | 이 프로젝트의 실험 설계이며, 개선 효과는 비교로 검증 |
팩트 카드에는 과학 출처 링크가 기록되어 있습니다. 검토할 때는 각 주장, 적용 조건, 각 비유의 한계를 하나씩 확인하고, 특히 아직 pending으로 표시된 출처에 주의하십시오. 웹 페이지에 접속할 수 있다고 해서 그 페이지가 생성된 모든 대화를 뒷받침하는 것은 아닙니다.