3. GPU 준비: 머신 대여, 환경 설치, 모델 다운로드¶
이 장부터 비용이 발생합니다. 머신을 켜기 전에 1~2장을 모두 읽었는지, 그리고 로컬에서 업로드 번들을 준비했는지 확인하십시오.
이 장 한눈에 보기
- 이 장에서 하는 일: RTX 4090 클라우드 호스트를 시작합니다.
nvidia-smi를 읽는 법을 익힙니다. 프로젝트를 업로드합니다. 학습용 Python 환경을 구축합니다. ModelScope에서 8 GB 베이스 모델을 다운로드하고 검증합니다. JupyterLab에서 올바른 커널을 선택합니다 - 준비할 것: GPU 플랫폼 계정과 잔액, 로컬 컴퓨터에서
python3 tools/build_gpu_zip.py로 만든llm-lora-tutorial-gpu.zip(코드, 데이터, 토크나이저만 포함, 몇 MB) - 완료하면 얻는 것:
.venv-train환경이 자체 점검을 통과하고,models/qwen3-4b/가 검증을 통과하며, Notebook이 LoRA · Python 3.11 커널로 열려 있습니다 - 대략적인 소요 시간: 30~60분이며, 대부분 의존성 설치와 가중치 다운로드에 쓰입니다
이 장의 다섯 단계와 각 단계가 해결하는 문제는 다음과 같습니다.
| 단계 | 해결하는 문제 | 건너뛰면 생기는 일 |
|---|---|---|
| 3.1 머신 선택 | VRAM에 4비트 베이스 모델과 학습 중간 결과가 들어가야 하고, 디스크에 환경, 베이스 모델, 병합 모델이 들어가야 합니다 | 학습 중 OOM이 나거나, 병합 도중에 디스크가 가득 찹니다 |
3.2 nvidia-smi 읽기 |
GPU, 드라이버 버전, 여유 VRAM을 확인합니다 | 나중에 설치하는 PyTorch가 드라이버와 호환되지 않아 "CUDA를 사용할 수 없음" 오류가 날 수 있습니다 |
| 3.3 업로드 + 환경 구축 | 버전이 고정된 라이브러리로 프로젝트 전용 환경을 만들고 Jupyter 커널로 등록합니다 | 이미지에 기본 포함된 구버전 라이브러리를 쓰게 되어 코드 동작이 튜토리얼과 맞지 않습니다 |
| 3.4 베이스 모델 다운로드 | 이 튜토리얼과 바이트 단위로 동일한 모델 가중치를 받습니다 | 버전이 다르면 답변과 수치가 모두 달라집니다. 샤드가 빠져 있으면 로드할 때가 되어서야 오류가 납니다 |
| 3.5 Notebook 열기 | 올바른 커널을 선택합니다 | Notebook이 시스템 Python에서 실행되어 import가 실패하거나 잘못된 버전을 씁니다 |
3.1 GPU 호스트와 파일¶
어디서 빌릴까: Zhichuan Cloud¶
이 책의 모든 GPU 작업은 Zhichuan Cloud (gpuhome.cc)에서 수행했습니다. 초보자에게는 그냥 이곳을 쓰는 것을 권합니다. 주된 이유는 저렴하고 바로 시작하기 쉽기 때문입니다.
| 항목 | Zhichuan Cloud의 경우 |
|---|---|
| 가격 | RTX 4090D(24 GB) 종량제 ¥1.25/시간, 1일 ¥29, 1주 ¥200, 1개월 ¥800(2026-10-11 기준 페이지 가격이며, 주문 시점 가격이 기준입니다). 이 책의 메인 경로는 약 2~3시간이 걸리므로 3~4위안 정도면 충분합니다 |
| 신규 사용자 혜택 | 첫 충전을 ¥1 이상 하면 ¥5 바우처를 받으며, 메인 경로를 한 번 돌리기에 대략 충분합니다 |
| GPU 모델 | RTX 3090 / 4090 / 4090D / 4090 Lite / 5090, A100, L40S 등, 1~8 GPU, 여러 지역 |
| 이미지 | 이 책에서 사용하는 PyTorch 기본 이미지 2.7.1-CUDA12.6-Py3.11-Ubuntu22가 있습니다 |
| 사용 방법 | 인스턴스 페이지에서 JupyterLab, SSH, VSCode를 클릭 한 번으로 열 수 있고, 50 GB 데이터 디스크가 딸려 있습니다 |
선택 방법: GPU 모델은 RTX 4090, 4090D, 4090 Lite 중 아무것이나 고르면 됩니다. 모두 VRAM이 24 GB이며, 이 책의 명령은 하나도 바꿀 필요가 없습니다(4090D는 중국 내수용 버전으로, 연산 성능은 4090보다 약간 낮고 VRAM은 같습니다). 이미지는 PyTorch → 2.7.1-CUDA12.6-Py3.11-Ubuntu22를 고릅니다. 과금 방식은 종량제를 고르고, 다 쓰면 머신을 끄십시오.
직접 해 보며 얻은 교훈 두 가지입니다. 머신을 켠 뒤 가장 먼저 처리하십시오.
- 프로젝트는 데이터 디스크에 두십시오. 인스턴스의 홈 디렉터리
/root는 30 GB 시스템 디스크에 있습니다. 학습 환경을 설치하고 8 GB 모델을 내려받은 뒤 vLLM까지 설치하면 가득 찹니다.df -h로 약 50 GB짜리 디스크를 찾아(저자의 인스턴스에서는/root/rivermind-data에 마운트되어 있습니다) 프로젝트를 그곳에 압축 해제하십시오. - PyTorch 공식 인덱스에 접속하지 못할 수 있습니다. 3.3절과 5.4절 모두 중국 내 미러를 쓰는 대체 명령을 제공합니다.
가입 링크: https://gpuhome.cc/auth/register?code=zt4f01m0. 가입할 때 초대 코드 zt4f01m0를 입력하면 신규 사용자 바우처를 받을 수 있습니다. 이것은 저자의 추천 링크로, 여러분이 첫 충전을 하면 저자도 플랫폼 바우처를 받습니다. 바우처는 플랫폼이 수동으로 지급하므로, 조건을 충족하면 고객센터에 연락해 받으십시오. 유효 기간은 3개월입니다.
이번에 사용한 호스트 구성¶
이 장은 이미 선택하고 시작한 RTX 4090 클라우드 호스트를 기준으로 진행합니다. 아래 구성은 2026-09-29에 저장한 시작 화면 스크린숏에서 가져온 것이며, 로그인한 뒤에도 실제 장치와 환경을 확인해야 합니다.
| 항목 | 이번 선택 | 주의할 점 |
|---|---|---|
| GPU | RTX 4090 1장, VRAM 24 GB | 이 튜토리얼은 단일 GPU를 사용합니다. 4장은 기본적으로 1 에폭 전체(약 72스텝)를 실행합니다 |
| CPU / 호스트 RAM | 15코어 / 100 GB | 튜토리얼이 권장하는 호스트 RAM 32 GB와, 이후 CPU 병합에 권장하는 64 GB를 충족합니다 |
| 시스템 디스크 | 30 GB SSD | 프로젝트, 학습 환경, 모델은 가능한 한 데이터 디스크에 둡니다 |
| 데이터 디스크 | 50 GB SSD, 스크린숏에서는 확장 미사용 | 전체 워크플로를 하려면 100 GB로 확장할 것을 권합니다. 다운로드 전에 실제 여유 공간을 확인하십시오 |
| 기본 이미지 | 2.7.1-CUDA12.6-Py3.11-Ubuntu22 |
Ubuntu 22, Python 3.11, PyTorch 2.7.1 / CUDA 12.6 사전 설치 |
| 과금 방식 | 종량제 | 한 세션의 실험을 마치면 플랫폼 규칙에 따라 유휴 인스턴스를 중지하고 스토리지 요금을 확인하십시오 |
아래 그림은 이번 실행에서 확인한 GPU와 이미지 구성입니다.
이미지는 골랐으니, 이제 그 안에 프로젝트 전용 학습 환경을 만듭니다. 이미지에는 PyTorch 2.7.1이 사전 설치되어 있지만, 이 튜토리얼의 코드와 의존성은 PyTorch 2.8.0으로 고정되어 있습니다. 다음 절에서 .venv-train을 만들고 2.8.0 + cu126을 설치하며, 이미지의 원래 환경은 건드리지 않습니다. 공식 설치 명령은 PyTorch 2.8.0에 있습니다.
머신은 켜졌지만, 이 호스트의 드라이버, 의존성, 학습 VRAM, 실행 시간은 아직 검증하지 않았습니다. 이 장에서는 환경, 다운로드, 커널을 준비하고, 4장에서 Notebook으로 베이스 모델을 살펴본 뒤 LoRA 파라미터를 업데이트합니다.
다른 GPU를 고를 때¶
아래 표는 표준 데스크톱 카드를 기준으로 하며, Qwen3 4B, 4비트 QLoRA, 최대 4096 토큰, 한 번에 샘플 1개라는 구성을 계획하는 데 쓰기 위한 것입니다. 실제 사용량과 실행 시간은 여전히 직접 측정해야 합니다. 대여할 때는 전체 모델명, GPU당 VRAM, GPU 전용 여부를 확인하십시오.
| GPU 모델 | GPU당 VRAM | 권장 사항 |
|---|---|---|
| RTX 4090 | 24 GB GDDR6X | 이번에 사용한 모델입니다. 아래 cu126 명령을 그대로 쓰십시오 |
| RTX 3090 | 24 GB GDDR6X | 이미 가지고 있거나 실제 대여료가 더 저렴하다면 좋은 선택입니다. cu126을 사용합니다 |
| RTX 5090 | 32 GB GDDR7 | VRAM 여유가 더 큽니다. PyTorch를 설치할 때 인덱스 URL 끝의 cu126을 cu128로 바꾸십시오 |
5090은 Blackwell 아키텍처를 사용하므로 이를 지원하는 호스트 드라이버가 필요합니다. bitsandbytes 0.48.2 지원 표에 따르면 CUDA 12.8 빌드에 필요한 sm120이 포함되어 있습니다. 5090을 쓴다면 아래 점검 스크립트의 CUDA 버전 단언도 12.6에서 12.8로 바꾸십시오. 이번에는 4090을 쓰므로 다음 절의 명령을 그대로 실행하면 됩니다.
3.2 먼저 nvidia-smi 읽기: 드라이버, CUDA, VRAM¶
GPU 호스트에 로그인한 뒤 가장 먼저 할 일은 nvidia-smi를 실행하는 것입니다. 출력은 대략 다음과 같습니다.
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 560.35.03 Driver Version: 560.35.03 CUDA Version: 12.6 |
|-----------------------------------------+------------------------+----------------------+
| GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. |
|=========================================+========================+======================|
| 0 NVIDIA GeForce RTX 4090 Off | 00000000:01:00.0 Off | Off |
| 30% 35C P8 20W / 450W | 0MiB / 24564MiB | 0% Default |
+-----------------------------------------+------------------------+----------------------+
| Processes: |
| GPU GI CI PID Type Process name GPU Memory |
|=========================================================================================|
| No running processes found |
+-----------------------------------------------------------------------------------------+
| 필드 | 의미 | 신경 써야 할 점 |
|---|---|---|
Driver Version |
커널 드라이버 버전으로, 플랫폼 이미지가 정하며 일반 사용자는 바꿀 수 없습니다 | 아래 CUDA 상한을 결정합니다 |
CUDA Version |
이 드라이버가 지원하는 최고 CUDA 버전이며, 설치된 CUDA가 아닙니다 | PyTorch의 cu126은 이 값이 12.6 이상이어야 하고, vLLM 0.21의 cu129는 12.9 이상이어야 합니다 |
Memory-Usage |
사용 중 / 전체 VRAM | 학습 전에는 0에 가까워야 합니다. 학습 중에는 얼마까지 오르는지 보십시오. vLLM을 시작하기 전에 학습 커널이 VRAM을 해제했는지 확인하십시오 |
GPU-Util |
GPU 연산 사용률 | 학습과 부하 테스트 중에는 꽤 높게 유지되어야 합니다. 오랫동안 0이라면 프로그램이 CPU에서 막혀 있거나 대기 중이라는 뜻입니다 |
Processes |
VRAM을 점유한 프로세스 | 깜빡하고 종료하지 않은 Jupyter 커널을 찾는 데 씁니다 |
드라이버, CUDA, PyTorch의 관계: 드라이버는 운영체제에 설치되며 GPU에 묶여 있습니다. CUDA는 NVIDIA의 연산 라이브러리이며, PyTorch wheel이 필요한 사본을 함께 담고 있습니다(torch==2.8.0의 cu126 접미사는 "CUDA 12.6 런타임 내장"이라는 뜻입니다). 그러므로 CUDA 툴킷을 직접 설치할 필요가 없습니다. 유일한 제약은 드라이버가 지원하는 버전이 wheel에 내장된 버전보다 낮으면 안 된다는 것입니다. 이미지 이름의 CUDA12.6은 사전 설치된 툴킷을 가리키며 드라이버 상한과는 별개입니다. nvidia-smi를 기준으로 판단하십시오.
비유하자면 드라이버는 OS 커널 버전, CUDA 런타임은 앱이 함께 번들하는 의존성, nvidia-smi는 top과 free -h를 합친 것과 같습니다.
VRAM과 호스트 RAM은 서로 독립된 두 메모리입니다. 모델 가중치, 학습 중간 결과, KV 캐시는 모두 VRAM에 있어야 하며, 호스트의 100 GB RAM은 데이터 중계와 CPU에서의 병합에만 쓰입니다. VRAM이 부족하면 CUDA out of memory 오류가 나며, 해결책은 사용량을 줄이는 것(양자화, 더 짧은 샘플, 더 낮은 동시성)이지 호스트 RAM을 늘리는 것이 아닙니다.
3.3 프로젝트 업로드와 학습 커널 준비¶
업로드 번들 llm-lora-tutorial-gpu.zip을 플랫폼의 파일 업로드 기능으로 GPU 데이터 디스크에 올립니다. 이 번들은 로컬 프로젝트 루트에서 아래 명령으로 생성하며, Notebook, 코드, 데이터가 바뀔 때마다 다시 생성하십시오. 번들 안의 토크나이저는 로컬 models/qwen3-4b/에서 가져오므로, 처음 패키징하기 전에 2.8절에 따라 lab.download --tokenizer-only를 한 번 실행해야 합니다.
패키징 스크립트는 실행 출력이 남아 있는 Notebook을 거부하므로, 업로드하는 것은 항상 깨끗한 사본입니다. 업로드한 뒤 업로드 위치에서 터미널을 열고 압축을 풉니다.
이후의 모든 GPU 명령은 이 프로젝트 디렉터리에서 실행합니다. Notebook은 실제 절대 경로를 출력합니다. notebooks/ 안에 프로젝트를 한 겹 더 압축 해제하지 마십시오. 이미 이전 버전의 프로젝트가 있다면 새 버전은 다른 디렉터리에 압축 해제하고, 기존 runs/와 모델 다운로드 디렉터리는 그대로 두십시오. 학습 결과를 직접 덮어쓰지 마십시오.
업로드 번들에 들어 있는 것¶
압축 시 약 4 MB, 해제 시 약 17 MB이며, 모두 31개 파일입니다. "GPU에서 학습과 배포에 필요하지만 온라인에서 내려받을 수 없거나 이 튜토리얼과 정확히 일치해야 하는 것"만 들어 있습니다(목록의 설명은 중국어이며, 거기서 언급하는 장에서 각 파일을 설명합니다).
llm-lora-tutorial/
├── GPU_UPLOAD_README.md GPU 上的操作速查：建环境 → 下权重 → 打开 Notebook
├── notebooks/01_gpu_train.ipynb 训练主入口，第 4 章逐格执行
├── data/
│ ├── dataset.json 唯一的数据文件：事实卡 + train/val/test 对话（第 2 章）
│ └── README.md 数据逐字段说明
├── lab/ Notebook 和命令行共用的 Python 代码
│ ├── common.py 拼提示词、生成训练样本和掩码（第 2.5 节）
│ ├── data.py 读入并校验 dataset.json、按回答拆样本
│ ├── download.py 下载并校验基座权重（第 3.4 节）
│ ├── download-lock.json 12 个模型文件的大小和 SHA-256，下载后逐个核对
│ ├── training.py、train.py 训练器配置与命令行训练（第 4.6 节、第 6 章）
│ ├── prepare.py、audit.py 命令行快照与 Token 检查（第 4.6 节、第 6 章）
│ ├── infer.py、evaluate.py A/B/C 对照推理与盲评（第 6 章）
│ └── merge.py 命令行合并 adapter（第 5.1 节）
├── models/qwen3-4b/ 基座的“说明部分”，没有权重
│ ├── config.json 等配置 模型结构、默认生成参数
│ ├── tokenizer.json、vocab.json、merges.txt、tokenizer_config.json 分词器和聊天模板
│ ├── model.safetensors.index.json 权重分片索引（分片本身还没下载）
│ ├── model-lock.json 本教程固定的模型版本号
│ └── LICENSE、README.md 模型许可证与模型卡
├── requirements-train.txt 训练依赖（Transformers、PEFT、TRL、bitsandbytes 等，版本固定）
├── requirements-download.txt 下载依赖（ModelScope；备用镜像用的 huggingface_hub 随 Transformers 安装）
├── requirements-notebook.txt Jupyter 内核与画 loss 曲线的依赖
├── requirements-data.txt 数据检查依赖
└── pyproject.toml 项目元数据
요약하면 이렇습니다. GPU_UPLOAD_README.md는 GPU 작업 빠른 참조입니다. notebooks/01_gpu_train.ipynb는 학습의 메인 진입점입니다(4장). data/에는 단 하나의 데이터셋 파일과 필드 설명서가 있습니다. lab/은 Notebook과 CLI가 공유하는 Python 코드입니다(common.py의 프롬프트 조립과 마스크, download.py의 다운로드와 검증, download-lock.json에 담긴 모델 파일 12개의 크기와 SHA-256, 그리고 CLI용 학습, 스냅숏, 추론, 평가, 병합 스크립트). models/qwen3-4b/는 가중치를 제외한 베이스 모델의 "설명 부분"입니다(설정, 토크나이저와 채팅 템플릿, 샤드 인덱스, 고정 버전, 라이선스와 모델 카드). requirements-*.txt 파일들은 학습, 다운로드, 노트북, 데이터 점검용 의존성을 고정합니다.
| 번들에 없는 것 | 이유 | 어디서 오는가 |
|---|---|---|
8 GB 가중치 샤드 model-0000X-of-00003.safetensors |
너무 커서 업로드가 느립니다. GPU 호스트는 중국 내 미러에서 더 빠르게 내려받습니다 | 3.4절에서 GPU에서 다운로드하고 download-lock.json으로 검증합니다 |
| PyTorch와 기타 의존성 자체 | GPU와 CUDA 버전에 묶여 있으므로 GPU 호스트에서 설치해야 합니다 | 아래 pip 명령이 requirements-*.txt에 따라 설치합니다 |
학습 결과 runs/, 스냅숏 data/processed/ |
GPU에서 생성되는 산출물입니다 | 4장의 학습과 4.6절의 스냅숏 생성 시 만들어집니다 |
자동화 테스트 tests/, 전자책 소스 |
GPU에서는 쓰지 않습니다 | 전체 프로젝트 또는 전자책의 "소스 다운로드" 페이지(8.1절) |
토크나이저를 포함하는 것은 GPU 호스트가 가중치를 내려받기 전에 모델 버전을 확인할 수 있게 하기 위해서이며, 그러면 다운로드 시에는 가중치 샤드 3개만 채우면 됩니다. Notebook은 data/dataset.json을 직접 읽으므로 lab.prepare를 먼저 실행할 필요가 없습니다. 50 GB 데이터 디스크에는 학습 환경, 원본 가중치, 병합 가중치, 추론 환경이 동시에 들어가야 하므로, 전체 배포까지 하려면 100 GB로 확장할 것을 권합니다.
GPU 터미널에서 프로젝트 환경을 구축합니다.
python3.11 -m venv .venv-train
.venv-train/bin/python -m pip install --upgrade pip
.venv-train/bin/python -m pip install torch==2.8.0 --index-url https://download.pytorch.org/whl/cu126
.venv-train/bin/python -m pip install -r requirements-train.txt -r requirements-download.txt -r requirements-notebook.txt
.venv-train/bin/python -m pip check
.venv-train/bin/python -m ipykernel install --user --name lora-train --display-name "LoRA · Python 3.11"
학습에는 버전이 고정된 Torch/Transformers/TRL/PEFT를 사용합니다. ModelScope는 다운로드에만 쓰이고, ipykernel은 플랫폼의 Jupyter가 이 환경을 쓸 수 있게 해 줍니다. 튜토리얼의 이전 버전에 따라 이미 .venv-train을 만들었다면 재사용할 수 있습니다. 새로 추가된 의존성을 설치하고 커널을 등록하면 됩니다. 일반 Python 패키지 인덱스가 느리다면 플랫폼이 제공하는 PyPI 미러를 써도 됩니다. 모델 다운로드 소스와 pip 패키지 소스는 서로 별개입니다.
download.pytorch.org에 접속할 수 없을 때(Network is unreachable이 나거나 재시도가 끝없이 반복될 때): 세 번째 명령은 --index-url로 다운로드 주소를 임시로 PyTorch 공식 인덱스로 바꾸는데, 중국 내 호스트는 여기에 접속하지 못하는 경우가 많습니다. 일반 PyPI 미러(칭화, 알리바바 등)로만 바꿔서는 해결되지 않습니다. 이들 미러에는 PyPI의 기본 torch 2.8.0(CUDA 12.8 내장)만 있는데, 아래 자체 점검은 12.6을 요구하기 때문입니다. 대신 같은 2.8.0+cu126 패키지가 있는 Alibaba Cloud의 PyTorch 미러를 사용하십시오.
.venv-train/bin/python -m pip install 'torch==2.8.0+cu126' -f https://mirrors.aliyun.com/pytorch-wheels/cu126/
-f는 pip에게 torch 본체만 그 페이지에서 찾으라고 지시할 뿐이며, nvidia-*, triton 같은 torch의 의존성은 여전히 설정된 PyPI 소스에서 받습니다. 버전을 2.8.0+cu126으로 적으면 pip가 PyPI의 cu128 빌드를 설치하는 것을 막을 수 있습니다. 설치가 끝나면 위의 네 번째 명령(requirements-*.txt)부터 이어서 실행하십시오. 나머지 단계는 같습니다. PyPI 소스를 영구적으로 고정하려면 .venv-train/bin/python -m pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple을 실행하고, pip config list로 현재 설정을 확인하십시오.
.venv-train/bin/python - <<'CHECK'
import sys, torch, transformers, trl, peft, bitsandbytes
print("Python:", sys.executable)
print("Torch / CUDA:", torch.__version__, torch.version.cuda)
assert torch.__version__.split("+")[0] == "2.8.0"
assert torch.version.cuda == "12.6"
assert torch.cuda.is_available() and torch.cuda.is_bf16_supported()
print("GPU:", torch.cuda.get_device_name(0))
print("依赖:", transformers.__version__, trl.__version__, peft.__version__, bitsandbytes.__version__)
CHECK
이 점검을 통과한 뒤에만 계속 진행하십시오(依赖 줄에는 의존성 버전이 출력됩니다). CUDA를 사용할 수 없다면 커널, 드라이버, wheel을 먼저 확인하십시오. 이미지에 사전 설치된 Torch 2.7.1은 이 프로젝트의 환경을 대신할 수 없습니다. 커널 등록 방법은 IPython 공식 문서를 따릅니다.
3.4 중국 내 GPU 호스트에서 전체 가중치 다운로드¶
기본적으로 알리바바의 ModelScope를 사용하며, 저장소는 Qwen/Qwen3-4B-Instruct-2507입니다. ModelScope에는 자체 SDK가 있으며, HF_ENDPOINT를 ModelScope 홈페이지로 지정하는 방식이 아닙니다.
--tokenizer-only를 붙이지 마십시오. 이 명령은 업로드 번들의 model-lock.json과 이미 검증된 토크나이저를 유지한 채, 빠진 가중치 샤드 3개를 채웁니다. 네트워크가 끊기면 같은 명령을 다시 실행하십시오. .cache와 버전 잠금이 유지되므로 데이터를 다시 준비할 필요가 없습니다.
download.py는 download-lock.json에 따라 원격 파일 크기와 SHA-256을 확인한 다음, 실제로 내려받은 내용을 확인합니다. ModelScope는 master에서 파일을 가져오지만, 여기서 고정한 Hugging Face 리비전과 바이트 단위로 동일해야 합니다. 저장소 내용이 바뀌었다면 중단하므로 버전이 섞이는 일이 없습니다. 목록에 있는 12개 파일의 메타데이터는 양쪽 소스에서 모두 확인했으며, 가중치 파일 3개의 합계는 약 8.0 GB(10진 기준)입니다.
다운로드한 뒤에는 오프라인 점검만 따로 실행할 수 있습니다.
“校验通过：12 个文件；完整模型权重已就绪”(“검증 통과: 파일 12개, 전체 모델 가중치 준비 완료”)가 출력되고 명령이 정상 종료된 경우에만 학습으로 넘어가십시오. 디렉터리에는 다음이 있어야 합니다.
models/qwen3-4b/
├── model-lock.json
├── config.json
├── tokenizer.json
├── tokenizer_config.json
├── model.safetensors.index.json
├── model-00001-of-00003.safetensors
├── model-00002-of-00003.safetensors
└── model-00003-of-00003.safetensors
다른 설정, 어휘, 라이선스 파일도 남겨 두십시오. model-lock.json과 가중치 인덱스만 보이거나, 로그에 Returning existing local_dir라고 나온다고 해서 가중치가 다운로드되었다는 뜻은 아닙니다. 현재 다운로더는 이런 불완전한 결과를 거부합니다.
대안: 중국 내 Hugging Face 미러로 다운로드¶
ModelScope에 접속할 수 없다면 hf-mirror.com을 명시적으로 선택할 수 있습니다.
.venv-train/bin/python -m lab.download --source hf-mirror --output models/qwen3-4b
.venv-train/bin/python -m lab.download --check-only --output models/qwen3-4b
코드가 미러 주소를 Hugging Face SDK에 명시적으로 넘기므로, 설치된 패키지의 소스 코드를 고치거나 전역 환경 변수를 영구적으로 바꿀 필요가 없으며, 같은 버전 잠금과 파일 검증을 그대로 사용합니다. 이 미러는 독립된 서드파티 서비스로, Alibaba Cloud 공식 ModelScope가 아닙니다. 접속 가능 여부는 GPU 호스트의 네트워크에 달려 있습니다. Hugging Face 다운로드 API를 기반으로 합니다.
개발 머신에서는 ModelScope의 설정/토크나이저 다운로드를 테스트해 검증을 통과했고, 큰 가중치 파일 3개도 몇 바이트만 받는 다운로드 테스트를 통과했습니다. 이 GPU 호스트에서는 아직 8 GB 전체 가중치를 다운로드하지 않았습니다. 최종적으로는 호스트에서의 전체 검증 결과를 기준으로 삼습니다.
| 증상 | 대처 방법 |
|---|---|
huggingface.co / Network is unreachable |
--source modelscope를 명시하거나, 대안인 --source hf-mirror를 쓰십시오 |
| 가중치 샤드 누락 | 같은 디렉터리에서 --tokenizer-only 없이 전체 다운로드를 다시 실행하십시오 |
| 로컬 파일 해시 불일치 | 보고된 파일을 옆으로 옮겨 백업한 뒤, 버전 잠금은 유지한 채 다시 다운로드하십시오. 점검을 건너뛰지 마십시오 |
| 원격 파일이 고정 버전과 다름 | 그 소스 사용을 중단하고 다른 소스에서 고정된 내용을 받아 보십시오. 해시를 고쳐서 통과시키지 마십시오 |
No space left on device |
프로젝트가 있는 파티션을 확인하고 확장하거나 데이터 디스크로 옮기십시오. 백업하지 않은 실험 결과는 지우지 마십시오 |
3.5 Notebook을 열고 학습 시작하기¶
JupyterLab에서 01_gpu_train.en.ipynb를 열고 LoRA · Python 3.11 커널을 선택합니다. 보이지 않으면 Jupyter를 새로 고치십시오. 이미지에 딸린 일반 Python 3 커널을 고르지 마십시오.
Jupyter를 처음 쓴다면 다음만 알면 됩니다.
| 동작 | 방법 |
|---|---|
| 현재 셀 실행 | 코드 셀을 클릭하고 Shift+Enter를 누릅니다. 실행 후 포커스가 다음 셀로 넘어갑니다 |
| 실행 중인지 확인 | 코드 셀 왼쪽의 [*]는 실행 중이라는 뜻이고, [3] 같은 숫자는 세 번째 실행으로 완료되었다는 뜻입니다 |
| 출력 보기 | 출력은 코드 셀 바로 아래에 나타납니다. 긴 출력은 접히므로 왼쪽 파란 막대를 클릭해 펼치십시오 |
| 커널 변경 | 메뉴 Kernel → Change Kernel. 현재 커널 이름은 오른쪽 위에 표시됩니다 |
| 처음부터 다시 | Kernel → Restart Kernel은 메모리의 모든 변수를 지웁니다. 디스크의 파일은 영향을 받지 않습니다 |
| VRAM 해제 | Kernel → Shutdown Kernel. 브라우저 탭을 닫는다고 해제되지는 않습니다 |
Notebook은 직관적인 Python 학습 코드를 사용합니다. 각 코드 셀 아래에는 세 부분, 즉 무엇을 하는지, 왜 하는지, 실행 후 무엇을 보게 되는지가 있습니다. 세 번째 부분에는 예상 출력과 각 숫자의 의미가 적혀 있으며, 실제 값은 약간 다를 수 있습니다. 1번 셀은 ROOT와 RUN_DIR를 설정하며, 결과는 기본적으로 runs/science-001/에 저장됩니다. 프로젝트나 notebooks 디렉터리에서 열면 경로를 자동으로 감지하고, 그 밖의 위치에서 열었다면 ROOT를 직접 채우십시오.
다음으로 4장에 따라 셀 단위로 학습합니다. 베이스 모델의 답변도 Notebook에 포함되어 있으므로 예전 A/B 명령을 따로 실행할 필요가 없습니다.