ms-swift 零基礎學習教材從推理到 LoRA 微調與部署適合剛開始學習 AI 和編程的。你不需要一次看懂全部內容也不需要死記參數。第一次只完成“第 0 關 → 第 1 關 → 第 2 關”成功后再學習自定義數據和參數調節。本文依據 2026 年 8 月 24 日可見的 ms-swift 4.x 官方文檔整理。框架、模型和依賴會更新若命令失效請以文末官方文檔為準。0. 先知道自己在做什么0.1 一句話認識 ms-swiftms-swift 是 ModelScope 社區提供的大模型訓練、微調、推理、評測、量化和部署工具。你可以把大語言模型想象成一名已經讀過很多書的學生推理inference向這名學生提問讓它回答。監督微調SFT拿“問題—標準答案”練習冊繼續教它。LoRA不重寫整本大腦只訓練一小組“外掛筆記”花費更少顯存。部署deploy把模型變成一個可以由其他程序訪問的服務。量化quantization降低數字精度讓模型更小、更省顯存代價可能是少量能力損失。checkpoint訓練過程中的存檔點類似游戲存檔。ms-swift 的包名是ms-swift但安裝后使用的命令是swift。它和 Apple 的 Swift 編程語言不是一回事。0.2 這份教材的學習路線準備 Python 環境 ↓ 用原始模型聊天推理 ↓ 準備少量 JSONL 教學數據 ↓ 用 LoRA 做 SFT 微調 ↓ 加載 LoRA 檢查效果 ↓ 部署成 OpenAI 兼容接口0.3 先接受三個現實大模型很吃硬件。普通電腦能學習命令和運行小模型但訓練較大模型通常需要 NVIDIA GPU 或云 GPU。第一次成功比第一次完美重要。先用小模型、少量數據、1 個 epoch 跑通全流程。微調不是給模型灌入百科知識的萬能辦法。想讓模型準確查詢大量、經常變化的資料很多時候 RAG檢索增強生成比微調更合適。1. 硬件與系統先選適合你的路線路線 ANVIDIA GPU最適合訓練推薦 Linux NVIDIA GPU。先檢查nvidia-smi如果能看到顯卡名稱、顯存和 CUDA 信息說明驅動基本可用。顯存越大能使用的模型、序列長度和批量越大。大致理解模型規模0.6B約為 6 億參數4B約為 40 億參數。參數越多通常資源需求越大。實際顯存還受精度、序列長度、優化器、注意力實現等影響不能只靠參數量精確計算。路線 BApple 芯片 Mac適合入門推理和小實驗PyTorch 可使用 MPS但 CUDA、flash_attn、vLLM 和部分量化/訓練功能是 NVIDIA 路線不能照搬。建議先用較小模型做swift infer訓練時從極小模型、短序列和很少數據開始遇到算子不支持或內存不足時轉到 NVIDIA 云 GPU不要設置CUDA_VISIBLE_DEVICES。路線 C只有 CPU適合理解流程可以安裝、查看幫助、處理數據也可能運行很小的模型但速度通常很慢不建議把 CPU 當作正式訓練設備。安全提醒租云 GPU 會產生費用。設置預算和自動關機訓練結束后停止實例。不要把平臺 Token、API Key 寫進公開代碼或提交到 Git。2. 創建干凈的 Python 環境官方 4.x 主線要求 Python 至少 3.10官方當前推薦 Python 3.12。下面二選一。2.1 使用 Condaconda create-nms-swift-studypython3.12-yconda activate ms-swift-study python--version以后每次打開新終端都先執行conda activate ms-swift-study2.2 使用 uv在一個專門的練習文件夾內執行mkdirms-swift-studycdms-swift-study uv venv--python3.12source.venv/bin/activateWindows PowerShell 激活命令是.venv\Scripts\Activate.ps1如果沒有uv可先按 uv 官方說明安裝也可以使用上一節 Conda 路線。3. 安裝 ms-swift 并做體檢3.1 常規安裝python-mpipinstall-Ums-swift如果正在使用 uv 創建的環境也可按官方推薦uv pipinstall-Ums-swift --torch-backendauto不要一開始安裝全部可選依賴。需要評測、DeepSpeed、vLLM 時再安裝對應組件可以減少沖突。3.2 檢查是否成功swift--helpswift sft--helppython-cimport torch; print(PyTorch:, torch.__version__); print(CUDA可用:, torch.cuda.is_available()); print(MPS可用:, torch.backends.mps.is_available() if hasattr(torch.backends, mps) else False)看到swift的幫助文字就說明命令已安裝。再記錄環境方便排錯python--versionpython-mpip show ms-swift torch transformers3.3 下載來源ms-swift 默認從 ModelScope 下載模型和數據集。若要從 Hugging Face 下載在命令后增加--use_hftrue第一次運行會下載模型可能需要較多時間和磁盤。--model既可以是 Hub 上的模型 ID也可以是已經下載好的本地模型目錄。4. 第 1 關先讓原始模型回答問題第一次請選小模型。下面以Qwen/Qwen3-0.6B為學習示例若官方支持列表或模型頁面發生變化請換成當前受支持的小型指令模型。NVIDIA 單卡CUDA_VISIBLE_DEVICES0swift infer\--modelQwen/Qwen3-0.6B\--infer_backendtransformers\--streamtrue\--temperature0\--max_new_tokens256Mac 或 CPU去掉第一行環境變量swift infer\--modelQwen/Qwen3-0.6B\--infer_backendtransformers\--streamtrue\--temperature0\--max_new_tokens256進入交互模式后輸入請用高中生能理解的語言解釋什么是神經網絡。常用交互命令clear清空對話歷史reset-system重置系統提示詞和歷史multi-line進入多行輸入模式以#結束single-line回到單行模式quit或exit退出。參數解釋--model模型 ID 或本地目錄--infer_backend transformers使用兼容性最好的 Transformers 推理后端--stream true像打字一樣逐步輸出--temperature 0回答更穩定--max_new_tokens 256最多生成 256 個新 token不等于 256 個漢字。如果這一步失敗先不要訓練。把推理環境解決好再繼續。可選瀏覽器聊天界面swift app\--modelQwen/Qwen3-0.6B\--infer_backendtransformers\--streamtrue\--max_new_tokens256完整訓練 Web UI 可啟動swift web-ui命令行更適合學習參數和復現因此本教材以命令行為主。5. 第 2 關認識訓練數據5.1 SFT 數據在教什么每條數據都像一道帶標準答案的題{messages:[{role:user,content:11等于幾},{role:assistant,content:11等于2。}]}user用戶說的話assistant希望模型學習的答案system可選規定身份、風格或規則。5.2 創建data/train.jsonlJSONL 的規則是一行一個完整 JSON 對象不是在最外層套一個大數組。{messages:[{role:system,content:你是一名耐心的高中數學助教分步驟回答。},{role:user,content:什么是一元二次方程},{role:assistant,content:只含一個未知數并且未知數的最高次數是2的整式方程叫作一元二次方程。一般形式是 ax2bxc0其中 a≠0。}]} {messages:[{role:system,content:你是一名耐心的高中數學助教分步驟回答。},{role:user,content:如何解方程 x2-5x60},{role:assistant,content:第1步因式分解x2-5x6(x-2)(x-3)。第2步令每個因式為0x-20或x-30。因此 x2 或 x3。}]} {messages:[{role:system,content:你是一名耐心的高中數學助教分步驟回答。},{role:user,content:判別式有什么用},{role:assistant,content:對 ax2bxc0判別式 Δb2-4ac。Δ0 時有兩個不相等實根Δ0 時有兩個相等實根Δ0 時沒有實根。}]}真實訓練不要只用 3 條這是檢查格式的最小樣例。高質量的幾十至幾百條數據比大量錯誤、矛盾、機械重復的數據更值得嘗試。5.3 數據檢查清單每一行能單獨通過 JSON 解析使用 UTF-8 編碼messages存在且是列表對話角色順序合理最后有要學習的assistant答案答案正確、清晰、風格一致不含密碼、身份證號、私人聊天等敏感信息訓練集和測試問題不要完全重復。快速檢查 JSONLpython-cimport json; pdata/train.jsonl; rows[json.loads(x) for x in open(p, encodingutf-8) if x.strip()]; print(有效行數:, len(rows)); print(rows[0])ms-swift 也能自動識別常見的query/response、Alpaca、ShareGPT 格式但初學階段建議統一使用官方標準messages格式。6. 第 3 關第一次 LoRA 微調先做“冒煙測試”目標只是驗證整個流程能跑通不追求模型立刻變強。6.1 NVIDIA GPU 入門命令CUDA_VISIBLE_DEVICES0swift sft\--modelQwen/Qwen3-0.6B\--tuner_typelora\--datasetdata/train.jsonl\--split_dataset_ratio0.1\--torch_dtypebfloat16\--num_train_epochs1\--per_device_train_batch_size1\--per_device_eval_batch_size1\--gradient_accumulation_steps8\--learning_rate1e-4\--lora_rank8\--lora_alpha32\--lora_dropout0.05\--target_modulesall-linear\--max_length512\--warmup_ratio0.05\--logging_steps1\--eval_steps10\--save_steps10\--save_total_limit2\--output_diroutput/qwen3-0_6b-math-lora如果顯卡不支持 BF16把--torch_dtypebfloat16換成--torch_dtypefloat166.2 極小數據的注意事項只有 3 條數據時--split_dataset_ratio 0.1可能無法得到有意義的驗證集。冒煙測試可以暫時改為--split_dataset_ratio0并刪除--per_device_eval_batch_size、--eval_steps。正式實驗建議準備足夠數據或用獨立文件--datasetdata/train.jsonl\--val_datasetdata/val.jsonl驗證集用來檢查模型是否只會背訓練題。它不參與參數更新。6.3 訓練結束后去哪里找結果output/qwen3-0_6b-math-lora下通常會出現一次運行目錄和若干checkpoint-數字目錄。日志會打印實際路徑。LoRA checkpoint 主要保存“增量適配器”不是一份完整基礎模型。不要隨便移動其中的args.json等文件ms-swift 推理時會用它們恢復訓練配置。7. 第 4 關加載訓練結果并比較把下面路徑換成你的真實 checkpointswift infer\--adaptersoutput/qwen3-0_6b-math-lora/vx-xxx/checkpoint-xxx\--infer_backendtransformers\--streamtrue\--temperature0\--max_new_tokens256--adapters指向 LoRA checkpoint。因為目錄里有args.json通常不用重復寫--model。若不想自動加載保存的參數可顯式設置--load_args false但初學時不建議。請用完全相同的問題比較原始基礎模型微調后的模型訓練集中沒出現過、但類型相似的問題。不要只憑“感覺不錯”判斷。準備固定測試題并記錄正確性、格式、是否啰嗦、是否編造、響應速度。8. 最常用參數意思、影響和建議8.1 模型與數據參數作用入門建議--modelHub 模型 ID 或本地模型目錄先選 0.5B1.5B 量級的小模型跑通--use_hf true改用 Hugging Face 下載默認 ModelScope 可用時不必加--dataset一個或多個訓練數據集 ID/路徑自定義數據優先用 JSONL--val_dataset獨立驗證集正式實驗推薦使用--split_dataset_ratio從訓練集切出驗證集的比例官方當前默認 0可從0.05或0.1開始--dataset_num_proc數據預處理進程數小數據用 1大文本數據可逐漸增加--columns把自定義列名映射到標準列名標準messages格式不需要--system命令行提供系統提示詞數據里的 system 優先級更高Hub 數據集還支持--dataset數據集ID:子集#采樣數例如#500表示采樣 500 條適合冒煙測試。多個數據集可在--dataset后依次寫多個值。8.2 訓練規模與顯存參數作用調大后通常怎樣--max_length單條樣本編碼后的最大 token 數能容納長文本但顯存和計算量明顯增加--per_device_train_batch_size每張卡一次放幾條樣本吞吐可能提高但更吃顯存--gradient_accumulation_steps累積多少次小批量再更新少占峰值顯存但每次更新等待更久--gradient_checkpointing用額外計算換顯存更省顯存但訓練變慢實際默認行為依模型/版本檢查--torch_dtype權重和計算精度BF16 通常更穩定硬件必須支持SFT 中常用的有效總 batch size總 batch size 每卡 batch size × 梯度累積步數 × GPU 數量例1 × 8 × 1 8。顯存不足時通常先保持每卡 batch 為 1再用梯度累積獲得更大的有效 batch。8.3 學習過程參數作用入門建議--num_train_epochs完整學習訓練集幾遍先 1再比較 23防止過擬合--learning_rate每次更新參數的步幅LoRA 常從1e-4起全參官方默認更低1e-5--warmup_ratio前多少比例逐漸升高學習率0.030.1示例用0.05--weight_decay對過大權重的懲罰不理解時先用默認值--lr_scheduler_type學習率如何隨訓練變化默認cosine通常可先保留--seed隨機種子固定后更方便復現實驗學習率過大loss 可能劇烈震蕩、出現 NaN 或能力被破壞過小則幾乎學不到。一次只改變一個關鍵參數并記錄結果。8.4 LoRA 參數參數作用入門建議--tuner_type lora啟用 LoRA 微調初學首選--target_modules all-linear給模型中的線性層掛 LoRA官方常用通用設置--lora_rankLoRA 容量官方當前默認 8先用 8復雜任務可試 16/32但更吃顯存--lora_alphaLoRA 更新的縮放系數rank8 時先用 16 或 32官方示例用 32--lora_dropoutLoRA 分支隨機丟棄比例當前默認 0.05小數據可保留 0.05別隨意大改--lora_bias是否訓練 bias先用默認none不要把rank理解成“越大越好”。rank 太大意味著更多可訓練參數、更多顯存也可能讓小數據更容易過擬合。8.5 日志、驗證與保存參數作用入門建議--logging_steps每隔多少 step 打印日志小實驗 15大實驗可更大--eval_steps每隔多少 step 驗證應與總 step 數匹配--save_steps每隔多少 step 保存小實驗 1050--save_total_limit最多保留幾個 checkpoint23避免磁盤被占滿--output_dir輸出目錄每個實驗使用不同名字--report_to記錄到 TensorBoard/WB 等當前官方默認 TensorBoard如果總訓練只有 8 step卻設置save_steps100中途當然不會出現第 100 步存檔。先觀察日志中的總 step 數。8.6 推理生成參數參數作用常見選擇--temperature隨機程度事實/數學用 00.2創作用 0.7 左右再觀察--top_p只在累計概率較高的候選中采樣常與 temperature 配合不必同時亂調--max_new_tokens最多生成多少新 token128、256、512 起步--stream true流式顯示聊天時推薦--infer_backend推理后端初學用transformersmax_length多用于限制輸入/訓練樣本長度max_new_tokens限制新生成內容長度。兩者不要混淆。9. 顯存不足CUDA out of memory怎么處理按照這個順序每改一項就重試降低--max_length例如2048 → 1024 → 512把--per_device_train_batch_size設為 1適當增加--gradient_accumulation_steps保持有效 batch換更小的模型使用 LoRA不要全參數訓練確認沒有其他程序占用 GPU用nvidia-smi查看在理解兼容性后再學習 QLoRA、DeepSpeed、FlashAttention、序列打包。不要把幾十個優化開關一次全打開否則失敗時很難知道是哪一個造成的。10. 用 YAML 管理參數比超長命令更清楚創建configs/sft_lora.yamlmodel:Qwen/Qwen3-0.6Btuner_type:loradataset:-data/train.jsonlsplit_dataset_ratio:0.1torch_dtype:bfloat16num_train_epochs:1per_device_train_batch_size:1per_device_eval_batch_size:1gradient_accumulation_steps:8learning_rate:0.0001warmup_ratio:0.05max_length:512lora_rank:8lora_alpha:32lora_dropout:0.05target_modules:-all-linearlogging_steps:1eval_steps:10save_steps:10save_total_limit:2output_dir:output/qwen3-0_6b-math-lora運行swift sft configs/sft_lora.yaml還可以臨時覆蓋一個值swift sft configs/sft_lora.yaml--num_train_epochs2好習慣每個實驗復制一份配置文件名寫清變化如sft_rank16.yaml并記錄結果。11. 部署成一個 API11.1 兼容性優先的部署swift deploy\--adaptersoutput/qwen3-0_6b-math-lora/vx-xxx/checkpoint-xxx\--infer_backendtransformers\--served_model_namemath-helper\--host127.0.0.1\--port8000\--temperature0\--max_new_tokens256這里使用127.0.0.1只允許本機訪問比直接開放到局域網或公網更安全。若需要對外提供服務應設置鑒權、防火墻、限流和日志脫敏。11.2 用 curl 調用另開一個終端curlhttp://127.0.0.1:8000/v1/chat/completions\-HContent-Type: application/json\-d{ model: math-helper, messages: [ {role: user, content: 請分步驟解方程 x2-7x120} ], max_tokens: 256, temperature: 0 }服務端參數--max_new_tokens和 OpenAI 兼容請求中的max_tokens都在限制生成長度具體請求值可以比服務端上限更小。11.3 vLLM 是什么時候學的vLLM 能提高吞吐適合 NVIDIA GPU 部署但要額外安裝并且對 CUDA、PyTorch、模型和量化方式有兼容要求。初學先用transformers流程穩定后再按官方版本表安裝 vLLM 并設置--infer_backendvllmQLoRA 適配器不能直接按所有 vLLM LoRA 場景處理請以當前官方推理后端兼容表為準。12. 合并、導出與發布LoRA 可在推理時單獨加載也可以與基礎模型合并。官方當前支持在推理時用--merge_lora true或通過導出流程處理。合并會生成體積更大的完整權重需要額外磁盤和內存。發布到 ModelScope 的官方命令形式swiftexport\--adaptersoutput/qwen3-0_6b-math-lora/vx-xxx/checkpoint-xxx\--push_to_hubtrue\--hub_model_id你的模型ID\--hub_token你的Token\--use_hffalse安全做法不要把真實 Token 保存進.md、腳本或 Git 歷史。先檢查基礎模型許可證、數據許可證和隱私要求再決定是否公開。13. 進階地圖現在只需認識名字全參數 SFT訓練所有參數資源和數據要求更高。QLoRA量化基礎模型后訓練 LoRA進一步省顯存但兼容性更復雜。DPO/KTO/GRPO 等偏好學習或強化學習不是零基礎第一課。DeepSpeed/FSDP/Megatron多卡或大規模訓練技術。vLLM/SGLang/LMDeploy推理加速后端各自兼容性不同。AWQ/GPTQ/BNB/FP8不同量化方法。EvalScope模型評測工具。多模態微調數據還包含images、videos、audios等字段資源需求更大。推薦順序LoRA SFT → 可靠評測 → 部署 → QLoRA/量化 → 多卡訓練 → 偏好或強化學習。14. 常見報錯排查swift: command not found可能沒激活正確環境或包裝到了另一個 Pythonwhichpythonwhichswift python-mpip show ms-swiftWindows 使用where python where swift模型或數據下載失敗檢查網絡和磁盤空間確認模型 ID 拼寫ModelScope 不通時嘗試--use_hf true反之亦然私有/受限模型需要先在對應平臺授權和登錄不要重復中斷大文件下載。CUDA out of memory按第 9 章的順序縮小訓練配置并用nvidia-smi查看占用。BF16 不支持或出現 NaN換成--torch_dtype float16或使用支持 BF16 的 GPU。若仍出現 NaN再檢查學習率、數據異常和依賴版本。數據被丟棄或提示格式錯誤先用 23 條數據測試并增加--stricttrue它會讓錯誤樣本直接報錯便于找到壞行。檢查 JSON、角色順序、空答案和超長樣本。默認truncation_strategydelete時超過max_length的訓練樣本可能被刪除。訓練沒有明顯效果數據太少或答案質量低訓練問題與測試問題差別太大學習率太低或訓練步數太少模型太小任務超過其能力只測試了訓練原題誤把背誦當泛化生成參數不同比較不公平。訓練后能力變差數據單一、錯誤或相互矛盾學習率過大epoch 太多導致過擬合訓練模板或模型類型不匹配沒有保留通用能力相關的數據。15. 怎樣做一次像樣的小實驗準備一張實驗記錄表實驗模型數據量max_lengthranklrepoch驗證結果備注baseline原始模型0----記錄 20 道題基線exp01Qwen 小模型10051281e-41待填寫首次 LoRAexp02同上10051285e-51待填寫只改 lr科學實驗的核心是固定一組測試題每次只改一個主要變量保存配置、日志和 checkpoint同時記錄成功與失敗不用訓練集原題冒充測試集成績。15.1 loss 怎么看loss 是模型答案與標準答案差距的數學度量。通常訓練 loss 下降說明正在擬合數據但它不是最終成績訓練 loss 下降、驗證效果也提高通常是好現象訓練 loss 繼續下降、驗證效果變差可能過擬合loss 不動檢查數據、可訓練參數、學習率loss 突然 NaN檢查精度、學習率、異常數據和依賴。不要比較不同數據、不同模板下 loss 的絕對數值后直接下結論。16. 一周入門計劃第 1 天終端與環境學會cd、ls、pwd創建 Python 環境成功運行swift --help。第 2 天模型推理跑通一個小模型理解 model、token、temperature、max_new_tokens。第 3 天數據手寫 10 條 JSONL用 Python 檢查解析區分訓練集與驗證集。第 4 天LoRA用 1050 條數據跑冒煙測試找到 checkpoint看懂 loss 和 step。第 5 天比較準備 20 個固定問題比較原始模型和微調模型記錄失敗案例。第 6 天參數實驗只改變 epoch 或 learning_rate使用 YAML 保存配置比較實驗結果。第 7 天部署啟動本地 API用 curl 調用寫一頁學習總結。17. 最小速查表# 安裝python-mpipinstall-Ums-swift# 看幫助這是查當前版本參數最可靠的方法之一swift--helpswift sft--helpswift infer--helpswift deploy--help# 原始模型推理swift infer--modelQwen/Qwen3-0.6B--infer_backendtransformers# LoRA 微調swift sft\--modelQwen/Qwen3-0.6B\--tuner_typelora\--datasetdata/train.jsonl\--max_length512\--per_device_train_batch_size1\--gradient_accumulation_steps8\--learning_rate1e-4\--lora_rank8\--lora_alpha32\--target_modulesall-linear\--num_train_epochs1\--output_diroutput/my-first-lora# LoRA 推理替換真實路徑swift infer--adaptersoutput/.../checkpoint-...--temperature0# 本地部署替換真實路徑swift deploy\--adaptersoutput/.../checkpoint-...\--infer_backendtransformers\--host127.0.0.1\--port800018. 官方資料與繼續學習優先看官方資料因為命令和默認值會變化ms-swift GitHub 與官方 READMEms-swift 中文文檔首頁安裝說明快速開始命令行參數自定義數據集預訓練與微調推理與部署支持的模型與數據集官方 examples 目錄遇到問題時提問要附上操作系統、GPU 型號與顯存、python --version、pip show ms-swift torch transformers、完整命令、報錯最后 50 行、最小數據樣例。不要附 Token 或隱私數據。結語學習 AI 不是智力競賽而是把大問題拆成小問題、不斷得到反饋的過程。你第一次的目標只有四個swift --help能運行小模型能回答一句話3 條 JSONL 能被正確讀取LoRA 冒煙測試能生成 checkpoint。做到這四點你已經完成了一個真實的大模型微調閉環。接下來不是“我會不會”而只是“我準備把哪一步練得更熟”。 ms-swift零基礎學習教材
ms-swift 零基礎學習教材從推理到 LoRA 微調與部署適合剛開始學習 AI 和編程的。你不需要一次看懂全部內容也不需要死記參數。第一次只完成“第 0 關 → 第 1 關 → 第 2 關”成功后再學習自定義數據和參數調節。本文依據 2026 年 8 月 24 日可見的 ms-swift 4.x 官方文檔整理。框架、模型和依賴會更新若命令失效請以文末官方文檔為準。0. 先知道自己在做什么0.1 一句話認識 ms-swiftms-swift 是 ModelScope 社區提供的大模型訓練、微調、推理、評測、量化和部署工具。你可以把大語言模型想象成一名已經讀過很多書的學生推理inference向這名學生提問讓它回答。監督微調SFT拿“問題—標準答案”練習冊繼續教它。LoRA不重寫整本大腦只訓練一小組“外掛筆記”花費更少顯存。部署deploy把模型變成一個可以由其他程序訪問的服務。量化quantization降低數字精度讓模型更小、更省顯存代價可能是少量能力損失。checkpoint訓練過程中的存檔點類似游戲存檔。ms-swift 的包名是ms-swift但安裝后使用的命令是swift。它和 Apple 的 Swift 編程語言不是一回事。0.2 這份教材的學習路線準備 Python 環境 ↓ 用原始模型聊天推理 ↓ 準備少量 JSONL 教學數據 ↓ 用 LoRA 做 SFT 微調 ↓ 加載 LoRA 檢查效果 ↓ 部署成 OpenAI 兼容接口0.3 先接受三個現實大模型很吃硬件。普通電腦能學習命令和運行小模型但訓練較大模型通常需要 NVIDIA GPU 或云 GPU。第一次成功比第一次完美重要。先用小模型、少量數據、1 個 epoch 跑通全流程。微調不是給模型灌入百科知識的萬能辦法。想讓模型準確查詢大量、經常變化的資料很多時候 RAG檢索增強生成比微調更合適。1. 硬件與系統先選適合你的路線路線 ANVIDIA GPU最適合訓練推薦 Linux NVIDIA GPU。先檢查nvidia-smi如果能看到顯卡名稱、顯存和 CUDA 信息說明驅動基本可用。顯存越大能使用的模型、序列長度和批量越大。大致理解模型規模0.6B約為 6 億參數4B約為 40 億參數。參數越多通常資源需求越大。實際顯存還受精度、序列長度、優化器、注意力實現等影響不能只靠參數量精確計算。路線 BApple 芯片 Mac適合入門推理和小實驗PyTorch 可使用 MPS但 CUDA、flash_attn、vLLM 和部分量化/訓練功能是 NVIDIA 路線不能照搬。建議先用較小模型做swift infer訓練時從極小模型、短序列和很少數據開始遇到算子不支持或內存不足時轉到 NVIDIA 云 GPU不要設置CUDA_VISIBLE_DEVICES。路線 C只有 CPU適合理解流程可以安裝、查看幫助、處理數據也可能運行很小的模型但速度通常很慢不建議把 CPU 當作正式訓練設備。安全提醒租云 GPU 會產生費用。設置預算和自動關機訓練結束后停止實例。不要把平臺 Token、API Key 寫進公開代碼或提交到 Git。2. 創建干凈的 Python 環境官方 4.x 主線要求 Python 至少 3.10官方當前推薦 Python 3.12。下面二選一。2.1 使用 Condaconda create-nms-swift-studypython3.12-yconda activate ms-swift-study python--version以后每次打開新終端都先執行conda activate ms-swift-study2.2 使用 uv在一個專門的練習文件夾內執行mkdirms-swift-studycdms-swift-study uv venv--python3.12source.venv/bin/activateWindows PowerShell 激活命令是.venv\Scripts\Activate.ps1如果沒有uv可先按 uv 官方說明安裝也可以使用上一節 Conda 路線。3. 安裝 ms-swift 并做體檢3.1 常規安裝python-mpipinstall-Ums-swift如果正在使用 uv 創建的環境也可按官方推薦uv pipinstall-Ums-swift --torch-backendauto不要一開始安裝全部可選依賴。需要評測、DeepSpeed、vLLM 時再安裝對應組件可以減少沖突。3.2 檢查是否成功swift--helpswift sft--helppython-cimport torch; print(PyTorch:, torch.__version__); print(CUDA可用:, torch.cuda.is_available()); print(MPS可用:, torch.backends.mps.is_available() if hasattr(torch.backends, mps) else False)看到swift的幫助文字就說明命令已安裝。再記錄環境方便排錯python--versionpython-mpip show ms-swift torch transformers3.3 下載來源ms-swift 默認從 ModelScope 下載模型和數據集。若要從 Hugging Face 下載在命令后增加--use_hftrue第一次運行會下載模型可能需要較多時間和磁盤。--model既可以是 Hub 上的模型 ID也可以是已經下載好的本地模型目錄。4. 第 1 關先讓原始模型回答問題第一次請選小模型。下面以Qwen/Qwen3-0.6B為學習示例若官方支持列表或模型頁面發生變化請換成當前受支持的小型指令模型。NVIDIA 單卡CUDA_VISIBLE_DEVICES0swift infer\--modelQwen/Qwen3-0.6B\--infer_backendtransformers\--streamtrue\--temperature0\--max_new_tokens256Mac 或 CPU去掉第一行環境變量swift infer\--modelQwen/Qwen3-0.6B\--infer_backendtransformers\--streamtrue\--temperature0\--max_new_tokens256進入交互模式后輸入請用高中生能理解的語言解釋什么是神經網絡。常用交互命令clear清空對話歷史reset-system重置系統提示詞和歷史multi-line進入多行輸入模式以#結束single-line回到單行模式quit或exit退出。參數解釋--model模型 ID 或本地目錄--infer_backend transformers使用兼容性最好的 Transformers 推理后端--stream true像打字一樣逐步輸出--temperature 0回答更穩定--max_new_tokens 256最多生成 256 個新 token不等于 256 個漢字。如果這一步失敗先不要訓練。把推理環境解決好再繼續。可選瀏覽器聊天界面swift app\--modelQwen/Qwen3-0.6B\--infer_backendtransformers\--streamtrue\--max_new_tokens256完整訓練 Web UI 可啟動swift web-ui命令行更適合學習參數和復現因此本教材以命令行為主。5. 第 2 關認識訓練數據5.1 SFT 數據在教什么每條數據都像一道帶標準答案的題{messages:[{role:user,content:11等于幾},{role:assistant,content:11等于2。}]}user用戶說的話assistant希望模型學習的答案system可選規定身份、風格或規則。5.2 創建data/train.jsonlJSONL 的規則是一行一個完整 JSON 對象不是在最外層套一個大數組。{messages:[{role:system,content:你是一名耐心的高中數學助教分步驟回答。},{role:user,content:什么是一元二次方程},{role:assistant,content:只含一個未知數并且未知數的最高次數是2的整式方程叫作一元二次方程。一般形式是 ax2bxc0其中 a≠0。}]} {messages:[{role:system,content:你是一名耐心的高中數學助教分步驟回答。},{role:user,content:如何解方程 x2-5x60},{role:assistant,content:第1步因式分解x2-5x6(x-2)(x-3)。第2步令每個因式為0x-20或x-30。因此 x2 或 x3。}]} {messages:[{role:system,content:你是一名耐心的高中數學助教分步驟回答。},{role:user,content:判別式有什么用},{role:assistant,content:對 ax2bxc0判別式 Δb2-4ac。Δ0 時有兩個不相等實根Δ0 時有兩個相等實根Δ0 時沒有實根。}]}真實訓練不要只用 3 條這是檢查格式的最小樣例。高質量的幾十至幾百條數據比大量錯誤、矛盾、機械重復的數據更值得嘗試。5.3 數據檢查清單每一行能單獨通過 JSON 解析使用 UTF-8 編碼messages存在且是列表對話角色順序合理最后有要學習的assistant答案答案正確、清晰、風格一致不含密碼、身份證號、私人聊天等敏感信息訓練集和測試問題不要完全重復。快速檢查 JSONLpython-cimport json; pdata/train.jsonl; rows[json.loads(x) for x in open(p, encodingutf-8) if x.strip()]; print(有效行數:, len(rows)); print(rows[0])ms-swift 也能自動識別常見的query/response、Alpaca、ShareGPT 格式但初學階段建議統一使用官方標準messages格式。6. 第 3 關第一次 LoRA 微調先做“冒煙測試”目標只是驗證整個流程能跑通不追求模型立刻變強。6.1 NVIDIA GPU 入門命令CUDA_VISIBLE_DEVICES0swift sft\--modelQwen/Qwen3-0.6B\--tuner_typelora\--datasetdata/train.jsonl\--split_dataset_ratio0.1\--torch_dtypebfloat16\--num_train_epochs1\--per_device_train_batch_size1\--per_device_eval_batch_size1\--gradient_accumulation_steps8\--learning_rate1e-4\--lora_rank8\--lora_alpha32\--lora_dropout0.05\--target_modulesall-linear\--max_length512\--warmup_ratio0.05\--logging_steps1\--eval_steps10\--save_steps10\--save_total_limit2\--output_diroutput/qwen3-0_6b-math-lora如果顯卡不支持 BF16把--torch_dtypebfloat16換成--torch_dtypefloat166.2 極小數據的注意事項只有 3 條數據時--split_dataset_ratio 0.1可能無法得到有意義的驗證集。冒煙測試可以暫時改為--split_dataset_ratio0并刪除--per_device_eval_batch_size、--eval_steps。正式實驗建議準備足夠數據或用獨立文件--datasetdata/train.jsonl\--val_datasetdata/val.jsonl驗證集用來檢查模型是否只會背訓練題。它不參與參數更新。6.3 訓練結束后去哪里找結果output/qwen3-0_6b-math-lora下通常會出現一次運行目錄和若干checkpoint-數字目錄。日志會打印實際路徑。LoRA checkpoint 主要保存“增量適配器”不是一份完整基礎模型。不要隨便移動其中的args.json等文件ms-swift 推理時會用它們恢復訓練配置。7. 第 4 關加載訓練結果并比較把下面路徑換成你的真實 checkpointswift infer\--adaptersoutput/qwen3-0_6b-math-lora/vx-xxx/checkpoint-xxx\--infer_backendtransformers\--streamtrue\--temperature0\--max_new_tokens256--adapters指向 LoRA checkpoint。因為目錄里有args.json通常不用重復寫--model。若不想自動加載保存的參數可顯式設置--load_args false但初學時不建議。請用完全相同的問題比較原始基礎模型微調后的模型訓練集中沒出現過、但類型相似的問題。不要只憑“感覺不錯”判斷。準備固定測試題并記錄正確性、格式、是否啰嗦、是否編造、響應速度。8. 最常用參數意思、影響和建議8.1 模型與數據參數作用入門建議--modelHub 模型 ID 或本地模型目錄先選 0.5B1.5B 量級的小模型跑通--use_hf true改用 Hugging Face 下載默認 ModelScope 可用時不必加--dataset一個或多個訓練數據集 ID/路徑自定義數據優先用 JSONL--val_dataset獨立驗證集正式實驗推薦使用--split_dataset_ratio從訓練集切出驗證集的比例官方當前默認 0可從0.05或0.1開始--dataset_num_proc數據預處理進程數小數據用 1大文本數據可逐漸增加--columns把自定義列名映射到標準列名標準messages格式不需要--system命令行提供系統提示詞數據里的 system 優先級更高Hub 數據集還支持--dataset數據集ID:子集#采樣數例如#500表示采樣 500 條適合冒煙測試。多個數據集可在--dataset后依次寫多個值。8.2 訓練規模與顯存參數作用調大后通常怎樣--max_length單條樣本編碼后的最大 token 數能容納長文本但顯存和計算量明顯增加--per_device_train_batch_size每張卡一次放幾條樣本吞吐可能提高但更吃顯存--gradient_accumulation_steps累積多少次小批量再更新少占峰值顯存但每次更新等待更久--gradient_checkpointing用額外計算換顯存更省顯存但訓練變慢實際默認行為依模型/版本檢查--torch_dtype權重和計算精度BF16 通常更穩定硬件必須支持SFT 中常用的有效總 batch size總 batch size 每卡 batch size × 梯度累積步數 × GPU 數量例1 × 8 × 1 8。顯存不足時通常先保持每卡 batch 為 1再用梯度累積獲得更大的有效 batch。8.3 學習過程參數作用入門建議--num_train_epochs完整學習訓練集幾遍先 1再比較 23防止過擬合--learning_rate每次更新參數的步幅LoRA 常從1e-4起全參官方默認更低1e-5--warmup_ratio前多少比例逐漸升高學習率0.030.1示例用0.05--weight_decay對過大權重的懲罰不理解時先用默認值--lr_scheduler_type學習率如何隨訓練變化默認cosine通常可先保留--seed隨機種子固定后更方便復現實驗學習率過大loss 可能劇烈震蕩、出現 NaN 或能力被破壞過小則幾乎學不到。一次只改變一個關鍵參數并記錄結果。8.4 LoRA 參數參數作用入門建議--tuner_type lora啟用 LoRA 微調初學首選--target_modules all-linear給模型中的線性層掛 LoRA官方常用通用設置--lora_rankLoRA 容量官方當前默認 8先用 8復雜任務可試 16/32但更吃顯存--lora_alphaLoRA 更新的縮放系數rank8 時先用 16 或 32官方示例用 32--lora_dropoutLoRA 分支隨機丟棄比例當前默認 0.05小數據可保留 0.05別隨意大改--lora_bias是否訓練 bias先用默認none不要把rank理解成“越大越好”。rank 太大意味著更多可訓練參數、更多顯存也可能讓小數據更容易過擬合。8.5 日志、驗證與保存參數作用入門建議--logging_steps每隔多少 step 打印日志小實驗 15大實驗可更大--eval_steps每隔多少 step 驗證應與總 step 數匹配--save_steps每隔多少 step 保存小實驗 1050--save_total_limit最多保留幾個 checkpoint23避免磁盤被占滿--output_dir輸出目錄每個實驗使用不同名字--report_to記錄到 TensorBoard/WB 等當前官方默認 TensorBoard如果總訓練只有 8 step卻設置save_steps100中途當然不會出現第 100 步存檔。先觀察日志中的總 step 數。8.6 推理生成參數參數作用常見選擇--temperature隨機程度事實/數學用 00.2創作用 0.7 左右再觀察--top_p只在累計概率較高的候選中采樣常與 temperature 配合不必同時亂調--max_new_tokens最多生成多少新 token128、256、512 起步--stream true流式顯示聊天時推薦--infer_backend推理后端初學用transformersmax_length多用于限制輸入/訓練樣本長度max_new_tokens限制新生成內容長度。兩者不要混淆。9. 顯存不足CUDA out of memory怎么處理按照這個順序每改一項就重試降低--max_length例如2048 → 1024 → 512把--per_device_train_batch_size設為 1適當增加--gradient_accumulation_steps保持有效 batch換更小的模型使用 LoRA不要全參數訓練確認沒有其他程序占用 GPU用nvidia-smi查看在理解兼容性后再學習 QLoRA、DeepSpeed、FlashAttention、序列打包。不要把幾十個優化開關一次全打開否則失敗時很難知道是哪一個造成的。10. 用 YAML 管理參數比超長命令更清楚創建configs/sft_lora.yamlmodel:Qwen/Qwen3-0.6Btuner_type:loradataset:-data/train.jsonlsplit_dataset_ratio:0.1torch_dtype:bfloat16num_train_epochs:1per_device_train_batch_size:1per_device_eval_batch_size:1gradient_accumulation_steps:8learning_rate:0.0001warmup_ratio:0.05max_length:512lora_rank:8lora_alpha:32lora_dropout:0.05target_modules:-all-linearlogging_steps:1eval_steps:10save_steps:10save_total_limit:2output_dir:output/qwen3-0_6b-math-lora運行swift sft configs/sft_lora.yaml還可以臨時覆蓋一個值swift sft configs/sft_lora.yaml--num_train_epochs2好習慣每個實驗復制一份配置文件名寫清變化如sft_rank16.yaml并記錄結果。11. 部署成一個 API11.1 兼容性優先的部署swift deploy\--adaptersoutput/qwen3-0_6b-math-lora/vx-xxx/checkpoint-xxx\--infer_backendtransformers\--served_model_namemath-helper\--host127.0.0.1\--port8000\--temperature0\--max_new_tokens256這里使用127.0.0.1只允許本機訪問比直接開放到局域網或公網更安全。若需要對外提供服務應設置鑒權、防火墻、限流和日志脫敏。11.2 用 curl 調用另開一個終端curlhttp://127.0.0.1:8000/v1/chat/completions\-HContent-Type: application/json\-d{ model: math-helper, messages: [ {role: user, content: 請分步驟解方程 x2-7x120} ], max_tokens: 256, temperature: 0 }服務端參數--max_new_tokens和 OpenAI 兼容請求中的max_tokens都在限制生成長度具體請求值可以比服務端上限更小。11.3 vLLM 是什么時候學的vLLM 能提高吞吐適合 NVIDIA GPU 部署但要額外安裝并且對 CUDA、PyTorch、模型和量化方式有兼容要求。初學先用transformers流程穩定后再按官方版本表安裝 vLLM 并設置--infer_backendvllmQLoRA 適配器不能直接按所有 vLLM LoRA 場景處理請以當前官方推理后端兼容表為準。12. 合并、導出與發布LoRA 可在推理時單獨加載也可以與基礎模型合并。官方當前支持在推理時用--merge_lora true或通過導出流程處理。合并會生成體積更大的完整權重需要額外磁盤和內存。發布到 ModelScope 的官方命令形式swiftexport\--adaptersoutput/qwen3-0_6b-math-lora/vx-xxx/checkpoint-xxx\--push_to_hubtrue\--hub_model_id你的模型ID\--hub_token你的Token\--use_hffalse安全做法不要把真實 Token 保存進.md、腳本或 Git 歷史。先檢查基礎模型許可證、數據許可證和隱私要求再決定是否公開。13. 進階地圖現在只需認識名字全參數 SFT訓練所有參數資源和數據要求更高。QLoRA量化基礎模型后訓練 LoRA進一步省顯存但兼容性更復雜。DPO/KTO/GRPO 等偏好學習或強化學習不是零基礎第一課。DeepSpeed/FSDP/Megatron多卡或大規模訓練技術。vLLM/SGLang/LMDeploy推理加速后端各自兼容性不同。AWQ/GPTQ/BNB/FP8不同量化方法。EvalScope模型評測工具。多模態微調數據還包含images、videos、audios等字段資源需求更大。推薦順序LoRA SFT → 可靠評測 → 部署 → QLoRA/量化 → 多卡訓練 → 偏好或強化學習。14. 常見報錯排查swift: command not found可能沒激活正確環境或包裝到了另一個 Pythonwhichpythonwhichswift python-mpip show ms-swiftWindows 使用where python where swift模型或數據下載失敗檢查網絡和磁盤空間確認模型 ID 拼寫ModelScope 不通時嘗試--use_hf true反之亦然私有/受限模型需要先在對應平臺授權和登錄不要重復中斷大文件下載。CUDA out of memory按第 9 章的順序縮小訓練配置并用nvidia-smi查看占用。BF16 不支持或出現 NaN換成--torch_dtype float16或使用支持 BF16 的 GPU。若仍出現 NaN再檢查學習率、數據異常和依賴版本。數據被丟棄或提示格式錯誤先用 23 條數據測試并增加--stricttrue它會讓錯誤樣本直接報錯便于找到壞行。檢查 JSON、角色順序、空答案和超長樣本。默認truncation_strategydelete時超過max_length的訓練樣本可能被刪除。訓練沒有明顯效果數據太少或答案質量低訓練問題與測試問題差別太大學習率太低或訓練步數太少模型太小任務超過其能力只測試了訓練原題誤把背誦當泛化生成參數不同比較不公平。訓練后能力變差數據單一、錯誤或相互矛盾學習率過大epoch 太多導致過擬合訓練模板或模型類型不匹配沒有保留通用能力相關的數據。15. 怎樣做一次像樣的小實驗準備一張實驗記錄表實驗模型數據量max_lengthranklrepoch驗證結果備注baseline原始模型0----記錄 20 道題基線exp01Qwen 小模型10051281e-41待填寫首次 LoRAexp02同上10051285e-51待填寫只改 lr科學實驗的核心是固定一組測試題每次只改一個主要變量保存配置、日志和 checkpoint同時記錄成功與失敗不用訓練集原題冒充測試集成績。15.1 loss 怎么看loss 是模型答案與標準答案差距的數學度量。通常訓練 loss 下降說明正在擬合數據但它不是最終成績訓練 loss 下降、驗證效果也提高通常是好現象訓練 loss 繼續下降、驗證效果變差可能過擬合loss 不動檢查數據、可訓練參數、學習率loss 突然 NaN檢查精度、學習率、異常數據和依賴。不要比較不同數據、不同模板下 loss 的絕對數值后直接下結論。16. 一周入門計劃第 1 天終端與環境學會cd、ls、pwd創建 Python 環境成功運行swift --help。第 2 天模型推理跑通一個小模型理解 model、token、temperature、max_new_tokens。第 3 天數據手寫 10 條 JSONL用 Python 檢查解析區分訓練集與驗證集。第 4 天LoRA用 1050 條數據跑冒煙測試找到 checkpoint看懂 loss 和 step。第 5 天比較準備 20 個固定問題比較原始模型和微調模型記錄失敗案例。第 6 天參數實驗只改變 epoch 或 learning_rate使用 YAML 保存配置比較實驗結果。第 7 天部署啟動本地 API用 curl 調用寫一頁學習總結。17. 最小速查表# 安裝python-mpipinstall-Ums-swift# 看幫助這是查當前版本參數最可靠的方法之一swift--helpswift sft--helpswift infer--helpswift deploy--help# 原始模型推理swift infer--modelQwen/Qwen3-0.6B--infer_backendtransformers# LoRA 微調swift sft\--modelQwen/Qwen3-0.6B\--tuner_typelora\--datasetdata/train.jsonl\--max_length512\--per_device_train_batch_size1\--gradient_accumulation_steps8\--learning_rate1e-4\--lora_rank8\--lora_alpha32\--target_modulesall-linear\--num_train_epochs1\--output_diroutput/my-first-lora# LoRA 推理替換真實路徑swift infer--adaptersoutput/.../checkpoint-...--temperature0# 本地部署替換真實路徑swift deploy\--adaptersoutput/.../checkpoint-...\--infer_backendtransformers\--host127.0.0.1\--port800018. 官方資料與繼續學習優先看官方資料因為命令和默認值會變化ms-swift GitHub 與官方 READMEms-swift 中文文檔首頁安裝說明快速開始命令行參數自定義數據集預訓練與微調推理與部署支持的模型與數據集官方 examples 目錄遇到問題時提問要附上操作系統、GPU 型號與顯存、python --version、pip show ms-swift torch transformers、完整命令、報錯最后 50 行、最小數據樣例。不要附 Token 或隱私數據。結語學習 AI 不是智力競賽而是把大問題拆成小問題、不斷得到反饋的過程。你第一次的目標只有四個swift --help能運行小模型能回答一句話3 條 JSONL 能被正確讀取LoRA 冒煙測試能生成 checkpoint。做到這四點你已經完成了一個真實的大模型微調閉環。接下來不是“我會不會”而只是“我準備把哪一步練得更熟”。