AIMAC LOCAL AI · 學習手冊
從硬體理解,到部署與實戰
持續更新的課程筆記

《macOS 地端 AI 完整部署與實戰學習手冊》

以你的 Mac mini 為實驗平台,逐課記錄 Apple Silicon、模型大小與量化,接著一路整理到地端推論、知識庫、Agent 與微調實作。

從第一課開始 建立日期:2026 年 9 月 24 日 · 更新日期:2026 年 10 月 11 日
學習進度
7 / 25 課完成
第一、二、九至十一、十四、十五課已完成;第十四堂已完成圖像與 MiniMax H3 影片生成;第十二、十三課跨工具實測待完成。
實驗平台
Mac mini · M4 Pro
14 核 CPU · 48GB 統一記憶體
文件方式
單一 HTML 文件
課後在同一份手冊中追加內容
COURSE JOURNAL · 01—25

課程記錄

第一至第十四課內容已納入課程記錄;第十四課補上 ComfyUI、MiniMax H3、中文對話、嘴型同步、分段生成、角色連貫性修正與報告版驗收,第十五課保留音訊基礎、Whisper STT、TTS/Voice Cloning、即時語音助理與延遲優化的實作紀錄。

01

Apple Silicon 與統一記憶體

認識 Mac 跑地端 AI 的硬體基礎

這一課先看懂 CPU、GPU 與記憶體的關係,再用自己的 Mac 規格和系統讀值,建立之後挑選、執行模型的基準。

A重點觀念
傳統 CPU 與獨立 GPU

系統 RAM 和顯示卡 VRAM 分開。模型能否放進 VRAM,常是能不能執行的限制;兩者容量不能直接相加當作一池可用記憶體。

Apple Silicon

CPU、GPU 等運算單元可共享統一記憶體。它讓 Mac 能把較大的模型放進同一個記憶體池,但不代表整池都能交給模型。

容量與頻寬

容量像工作桌有多大;頻寬像資料通道有多寬。容量影響可放入的模型與快取,頻寬則會影響讀取權重和生成速度。

觀察系統狀態

Unused RAM 低不一定等於故障。搭配活動監視器的 Memory Pressure、壓縮量與 Swap 變化,才較能了解當下的記憶體狀況。

這台 Mac 的硬體基準

項目實際規格對地端 AI 的意義
機型Mac mini可作為本機模型與服務的實驗平台。
晶片Apple M4 ProApple Silicon,支援以統一記憶體共享運算資料。
CPU14 核(10 Performance + 4 Efficiency)兼顧高效能工作與背景工作。
記憶體48GB Unified Memory可嘗試 7B 至 32B 左右的量化模型;仍須為系統、其他 App 和 KV Cache 留空間。
理解重點:模型可否順暢執行,除了參數量,也要看精度/量化、上下文長度、KV Cache、執行工具,以及當下其他 App 使用了多少記憶體。
B指令

以下指令可在「終端機」查看硬體架構與記憶體狀態。即時數字會隨使用情況改變。

system_profiler SPHardwareDataType
uname -m
sysctl hw.memsize
top -l 1 | grep PhysMem
sysctl vm.swapusage
memory_pressure

重點讀取 Chip、Memory、CPU 核心數、PhysMem、Swap Used 與 memory_pressure 輸出。

判讀方式:把記憶體快照視為某一刻的紀錄。若要判斷現在是否適合載入大型模型,請同時看活動監視器的 Memory Pressure,並觀察 Swap 是否持續增加。
C實際紀錄

以下是使用者在 Mac mini 上提供的讀值,保留原始輸出供日後比較:

記憶體快照
PhysMem: 47G used (2099M wired, 8041M compressor), 175M unused.
Swap 快照
vm.swapusage: total = 6144.00M used = 4448.69M free = 1695.31M (encrypted)

這組數據代表讀取當時 macOS 已使用記憶體壓縮,且 Swap 有約 4.45GB 在用。單次快照不等同目前效能診斷;可在不同工作負載下重新記錄並比較。

D小測驗
Q1|48GB 統一記憶體是否全部都能分配給模型?
答案:不是。macOS、其他 App、模型權重、KV Cache 和執行時暫存都會一起使用這個記憶體池。
Q2|70B 模型是否一定需要 70GB?
答案:不一定。參數量不是位元組數;模型權重大小還取決於 FP16、8-bit、Q4 等儲存精度。除此之外,還要留出快取與系統空間。
Q3|記憶體容量越大,模型輸出一定越快嗎?
答案:不一定。更大的容量能容納較大的模型,生成速度還受記憶體頻寬、晶片、模型結構、量化與上下文等因素影響。
E完成狀態

本課完成:確認 Apple Silicon 與統一記憶體的基本概念,並記錄 Mac mini 的晶片、核心數、記憶體與兩組系統快照。

02

模型大小、參數量與量化

看懂 7B、Q4、GGUF、MLX 與 KV Cache

看到模型名稱時,先拆解參數量與精度,再估算權重大小;接著還要把上下文快取和執行環境算進記憶體預算。

A重點觀念

參數量是模型規模,不是檔案大小

B 是 Billion(十億)。參數是模型中的數值,參數越多通常帶來較大的能力上限,也需要較多空間;實際表現仍受訓練資料、模型設計與任務影響。

7B ≈ 70 億參數 14B ≈ 140 億參數 32B ≈ 320 億參數 70B ≈ 700 億參數

精度與量化:用較少記憶體存放權重

FP16 通常以每個參數約 2 bytes 作快速估算。量化把權重存成較低位元數,降低檔案與記憶體需求,但實際平均大小會受到分組、縮放資料、模型格式等影響。

格式/精度粗略每參數怎麼理解
FP16約 2 bytes權重品質保留較多,記憶體需求高。
8-bit/Q8約 1 byte權重空間大約是 FP16 的一半,常作為較高品質的量化選項。
Q6約 0.75 byte在品質與體積間折衷,實際格式會有額外開銷。
Q5約 0.625 byte較 Q4 保留更多精度,體積也相對較大。
Q4約 0.5 byte常見的省記憶體選擇;模型品質會因模型家族和量化方式而不同。
權重大小粗估(GB)≈ 參數量(B)× 每參數 bytes

例:14B FP16 約 14 × 2 ≈ 28GB;14B 的 4-bit 權重約 14 × 0.5 ≈ 7GB。這是心算估值,不是精確下載量或執行時記憶體需求。

GGUF 與 MLX 是兩個不同層次的東西

項目GGUFMLX
是什麼適合 GGML 執行器載入的模型檔案格式,常見副檔名為 .gguf。Apple Silicon 上的機器學習陣列框架;mlx-lm 是用 MLX 執行與微調語言模型的工具套件。
常見生態llama.cpp、LM Studio,以及採用相容模型的本機工具。MLX、mlx-lm、mlx-vlm 等 Apple Silicon 工具。
挑選時留意確認模型架構和量化版本受到執行器支援。確認模型 repo、權重格式與工具版本相容;MLX 本身不是單一模型檔案格式。
看到 Qwen3-14B-Q4_K_M.gguf 這類名稱時,可先辨認模型家族、參數量、量化標籤與檔案格式。名稱慣例可能因發布者而不同,仍要查看模型頁的說明。

不要漏算 KV Cache

模型讀取上下文時,會保留注意力機制所需的 Key/Value 狀態,避免每生成一個 token 都從頭重算先前內容。這份快取通常會隨上下文長度與並行請求增加,也會受模型架構、精度和執行工具影響。

執行時記憶體 ≈ 模型權重 + KV Cache + 執行暫存 + macOS 與其他 App

因此,模型檔案大小不等於完整執行時用量。長上下文可能大幅增加快取需求,尤其當系統同時開著多個大型 App。

B指令與估算步驟

先用心算篩選,再查看模型發布頁上的實際檔案大小與量化資訊:

權重大小粗估(GB) = 參數量(B) × 每參數 bytes

FP16:每參數約 2 bytes
Q8:  每參數約 1 byte
Q6:  每參數約 0.75 byte
Q5:  每參數約 0.625 byte
Q4:  每參數約 0.5 byte

最後再預留 KV Cache、執行暫存、macOS 與其他 App 的空間。

這是估算規則,不是終端機命令;不同架構與量化方案的實際大小會有差異。

C實際紀錄與 M4 Pro 48GB 建議

下表用模型級距與常見量化作為起步指南。模型大小是粗略範圍;長上下文、多 App 工作流或不同執行器都可能改變實際餘裕。

模型級距起步量化在 48GB 上的建議大致權重空間
7B/8BQ4~Q8輕鬆起步;適合日常聊天與工具測試。Q4 約 4~5GB;Q8 約 7~9GB
14BQ4~Q8適合當作能力與速度的平衡級距。Q4 約 7~10GB;Q8 約 14~17GB
20B~24BQ4~Q6可作為進一步實測的中大型級距;留意長上下文所需快取。Q4 約 11~16GB;Q6 約 16~21GB
30B~32BQ4~Q5很值得測試;載入前確認其他 App 用量,並從較短上下文開始。Q4 約 17~22GB;Q5 約 21~27GB
70BQ4 僅作實驗偏吃緊,不建議當日常主力;Q4 權重本身可能已占掉大部分可用空間。Q4 約 38~45GB
70B FP16不建議單是權重粗估就約 140GB,不適合 48GB 記憶體。約 140GB(未含額外開銷)
挑選原則:先看實際檔案大小,再替 macOS、KV Cache 與其他程式保留餘裕。若目前仍看到第一課記錄中的壓縮與 Swap 使用量,先確認即時記憶體壓力,再進行大模型測試。
D小測驗
Q1|「14B Q4」代表什麼?
答案:約 140 億參數的模型,權重以 4-bit 量化方式儲存;實際檔案大小還會因量化格式及額外資料而變。
Q2|32B FP16 的權重大約多大?
答案:32 × 2 bytes,約 64GB,還沒算 KV Cache、執行暫存與系統用量,因此不適合直接放進 48GB 機器。
Q3|GGUF 和 MLX 是同一類格式嗎?
答案:不是。GGUF 是模型檔案格式;MLX 是 Apple Silicon 的機器學習框架,mlx-lm 則是在 MLX 上執行語言模型的工具。
Q4|模型權重放得下,就能確定長上下文也順暢嗎?
答案:不能。上下文長度會影響 KV Cache;實際用量還包括執行暫存、macOS 和其他 App。
E完成狀態

本課完成:理解參數量與檔案大小的差別,能估算 FP16/Q8/Q6/Q5/Q4 權重大小,辨認 GGUF、MLX 與 KV Cache,並依照 48GB 統一記憶體選擇模型級距。

03

macOS 系統準備與最佳化

建立基準、檢查更新與備份、確認儲存空間和記憶體狀態

開始安裝本機 AI 工具之前,先確認 Mac 的系統版本、可用磁碟空間、備份與目前記憶體狀態。這堂課先做檢查與紀錄;除非有明確需求,不必為了跑模型隨意改動電源或系統設定。

A重點觀念
先留下基準,再做改動

先記下 macOS 版本、磁碟空間、開發工具是否存在,以及記憶體壓力。之後安裝或更新工具時,才比較得出變化來自哪一步。

重大更新前先備份

Apple 建議使用相容的最新 macOS,並在更新前先備份重要資料。Time Machine 是 macOS 內建的備份方式;更新畫面與可用版本會依裝置而異。Apple:更新 macOS · Apple:備份 Mac

模型檔案需要 SSD 空間

模型下載檔、解壓後檔案、快取與其他資料都會占用內建或外接磁碟。磁碟空間與統一記憶體是兩種不同資源;請先看模型實際檔案大小並保留作業餘裕,不把單一數字當成所有模型通用門檻。

Apple Silicon 共用統一記憶體

你的 M4 Pro 沒有一塊可由使用者固定切分的獨立 VRAM。CPU、GPU、macOS 和 App 會依工作負載使用統一記憶體;GPU History 顯示的是活動狀況,不代表 GPU 可用記憶體容量。

用記憶體壓力判讀整體狀況

活動監視器「記憶體」頁面會顯示實體記憶體、已使用記憶體、壓縮記憶體與 Swap Used。記憶體壓力會綜合可用記憶體、Swap、wired memory 與檔案快取等因素;單看「unused 很低」不能判定故障。Apple:查看記憶體使用量 · Apple:判斷是否需要更多記憶體

電源設定按任務調整

Mac mini 可用的「系統設定 › 能源」選項會依 macOS 與機型不同。只有在長時間推論、下載或訓練時才考慮避免自動睡眠;延後睡眠會增加耗電。Apple:更改能源設定

本課判讀原則:看「記憶體壓力」趨勢,並搭配 Swap Used 與正在執行的工作。Swap 是目前或曾經使用交換空間的線索;只憑一張舊快照,不能推定此刻仍然卡頓。
B指令與檢查步驟

以下是 macOS 內建的查詢指令,只讀取資訊,不會安裝套件或更改設定。可逐行貼到「終端機」執行:

sw_vers
uname -m
system_profiler SPHardwareDataType
df -h /
xcode-select -p
pmset -g custom
memory_pressure
sysctl vm.swapusage
tmutil destinationinfo
  • sw_vers:查看 macOS 版本與組建版本;uname -m:確認處理器架構,Apple Silicon 通常顯示 arm64。
  • system_profiler SPHardwareDataType:查看硬體摘要;不要公開序號或硬體 UUID。
  • df -h /:查看系統磁碟容量與剩餘空間。模型若放在外接磁碟,需另行選取該磁碟檢查。
  • xcode-select -p:查看 Command Line Tools 路徑;若尚未安裝而出現錯誤訊息,先記為「未安裝」,本課不需要立即安裝。
  • pmset -g custom:讀取目前電源設定。實際可用選項以「系統設定 › 能源」畫面為準。
  • memory_pressure 與 sysctl vm.swapusage:讀取當下記憶體壓力和 Swap 狀態。也可開啟「活動監視器 › 記憶體」,觀察記憶體壓力圖。
  • tmutil destinationinfo:查看 Time Machine 備份目的地。輸出可能含有磁碟名稱或路徑,請勿把完整輸出貼到公開網頁。
長時間工作才暫時防止閒置睡眠:在終端機執行 caffeinate -i,工作結束後按 Control + C 停止。不要把它設成永久常駐;延後睡眠會增加耗電,也可能影響螢幕關閉或排程管理。
C實際紀錄

硬體與記憶體快照沿用第一課已提供的資料。其他系統讀值尚未在本課取得,因此保留待查欄位;完成檢查後再補入,不以猜測代填。

檢查項目目前紀錄下一步
Mac 型號Mac mini · Apple M4 Pro已知硬體資料
CPU/統一記憶體14 核 CPU(10 個效能核心 + 4 個節能核心)· 48GB Unified Memory已知硬體資料
macOS 版本/組建待查(執行 sw_vers)記錄產品版本與組建版本
處理器架構待查(執行 uname -m)確認為原生 Apple Silicon 環境
系統磁碟剩餘空間待查(執行 df -h /)模型下載前先確認要存放的磁碟
Command Line Tools待查(執行 xcode-select -p)本課只盤點;第四課再處理開發環境
Time Machine是否已備份/目的地:待確認確認最近一次備份;不要公開完整磁碟路徑
能源設定待查(系統設定 › 能源)僅在長時間任務時評估是否需避免睡眠
記憶體壓力/Swap第一課當時快照:PhysMem: 47G used (2099M wired, 8041M compressor), 175M unused;vm.swapusage: total = 6144MB, used = 4448.69MB, free = 1695.31MB這是先前讀值;開始模型工作前重新查看即時壓力
分享紀錄前先檢查:請移除序號、硬體 UUID、帳號名稱、備份磁碟完整路徑與其他個人資料。公開手冊只保留摘要數值即可。
D小測驗
Q1|活動監視器顯示 unused 很低,就代表 RAM 壞了嗎?
答案:不是。macOS 會使用記憶體做快取;請搭配記憶體壓力、壓縮記憶體、Swap 與實際操作是否變慢來判讀。
Q2|M4 Pro 有多少固定專用 VRAM 可以指定給模型?
答案:本機 Apple Silicon 使用統一記憶體,沒有一個可當成獨立顯卡 VRAM 的固定分區供使用者切分;CPU、GPU 與其他工作會共用系統記憶體。
Q3|模型檔案下載得下來,就表示執行時一定放得下嗎?
答案:不一定。磁碟空間和記憶體不同;執行時還需要模型權重、KV Cache、暫存空間與 macOS/其他 App 的記憶體。
Q4|需要一夜執行的任務,怎麼暫時避免閒置睡眠?
答案:可在該任務期間於終端機執行 caffeinate -i,完成後按 Control + C 停止,避免把防睡眠設定長期常駐。
Q5|要公開備份設定畫面或 tmutil 輸出,應注意什麼?
答案:先遮掉磁碟名稱、完整路徑與個人帳號等識別資料,只分享必要摘要。
E完成狀態

完成這課後,應能查看 macOS 版本、磁碟空間、開發工具路徑與記憶體狀態,知道如何確認 Time Machine 備份,並能說明何時暫時避免睡眠。課程內容已補齊;待本機檢查紀錄完成後,再勾選本課完成。

04

終端機與開發環境建置

Terminal/Ghostty、Command Line Tools、Homebrew、Python uv、Node.js 與 Hugging Face CLI

本課建立之後課程會用到的基本工具,並用一個獨立資料夾示範 Python 專案環境。先檢查現況,只安裝需要的項目;終端機操作會照著一行一行執行,避免把多個尚未確認的變更一次做完。

A重點觀念
Terminal 是操作入口

macOS 已內建「終端機」App,可以執行命令列程式。Ghostty 是可選的第三方終端機 App,提供另一種使用介面;本課命令在 Terminal 和 Ghostty 中都相同,不需要為了學習先更換工具。Ghostty 安裝說明

Command Line Tools 不等於完整 Xcode

Apple 的 Command Line Tools 套件包含常見編譯與開發工具,很多情境不必安裝完整 Xcode。若已存在,略過安裝;若命令列要求安裝,再執行 xcode-select --install 並在系統視窗確認。Apple:安裝命令列工具

Homebrew 管理 macOS 工具

Homebrew 是套件管理工具,可安裝與更新命令列程式及部分 Mac App。Apple Silicon 的預設位置是 /opt/homebrew;安裝完成後,依安裝程式顯示的提示設定 shell PATH。Homebrew 要求 macOS 版本符合目前官方支援條件,安裝前先核對。Homebrew:安裝與系統需求

uv 把 Python 專案隔開管理

uv 可建立專案、管理 Python 版本、相依套件和虛擬環境。每個專案有自己的設定與鎖定檔,避免把不同課程的套件混裝到系統 Python。uv 安裝說明 · uv 專案指南

Node.js 只在課程需要時安裝

Node.js 執行 JavaScript,也附 npm 套件管理工具;部分 WebUI 或開發工作會用到。若透過官網下載,選 macOS Apple Silicon 的 LTS 安裝檔。此工具不是執行每個地端模型的必要條件。Node.js 官方下載頁

Hugging Face CLI 可先用暫時執行

新式命令名稱是 hf。如果已安裝 uv,可用 uvx hf --help 暫時執行,不必立刻全域安裝。下載受限制的模型時才需要登入;存取權杖是密碼,不能貼到公開頁面或對話中。Hugging Face CLI 文件

先求可重複,不求工具多:本課的核心是確認 Terminal、Git/開發工具與 uv 可用,並成功建立一個隔離的 Python 專案。Ghostty、Node.js 和 Hugging Face CLI 都可依後續課程需求再加裝。
B指令與建置步驟

1. 打開終端機並認識目前位置

從 Finder 的「應用程式 › 工具程式 › 終端機」開啟 Terminal。先執行查詢指令,確認 Apple Silicon 架構與開發工具狀態:

pwd
uname -m
git --version
xcode-select -p

若 uname -m 顯示 arm64,代表目前 shell 以 Apple Silicon 架構執行。xcode-select -p 顯示 Command Line Tools 或 Xcode 路徑即為已設定;若顯示錯誤,再執行下面這行並依系統對話框安裝:

xcode-select --install

2. 安裝 Homebrew(尚未安裝才做)

先到 Homebrew 官方網站核對目前需求,再使用官方安裝指令。安裝程式會顯示將執行的步驟,讀完提示後再確認;不要從搜尋廣告或陌生網站複製安裝指令。

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

如果安裝完成後出現 brew: command not found,依安裝程式最後列出的 PATH 設定指示處理。Apple Silicon 預設前綴通常為 /opt/homebrew;不要在已存在的 shell 設定中重複加入同一行。確認後執行:

brew --version
brew doctor

brew doctor 用於檢查環境;看到提示時先閱讀說明,不必為了讓輸出全綠就盲目刪除檔案或修改權限。

3. 安裝 uv,建立一個獨立 Python 專案

以下用 Homebrew 安裝 uv。若不想使用 Homebrew,也可參考 uv 官方文件的獨立安裝方式;同一個工具選一種安裝方式即可。

brew install uv
uv --version
uv python install 3.12
mkdir -p ~/ai-lab
cd ~/ai-lab
uv init --python 3.12 macos-local-ai-project
cd macos-local-ai-project
uv run python --version
uv run python -c "print('Python 專案環境可用')"

第一次執行可能會下載 Python,需有網路連線。uv run 會在專案內建立或同步環境;專案相依性記錄在 pyproject.toml 和 uv.lock,通常不必手動啟用虛擬環境。

4. 視需要安裝 Ghostty 或 Node.js

Terminal 已經足夠完成課程。如果想試用 Ghostty,可從官方頁下載簽署的 macOS DMG,或在已安裝 Homebrew 後選擇社群維護的 cask。Node.js 可透過官方下載頁安裝 Apple Silicon 的 LTS 版本;如果改用 Homebrew,則由 Homebrew 管理其版本。

# 以下為選用項目,按需要一行一行執行:
brew install --cask ghostty
brew install node

# 檢查 Node.js 和 npm(安裝 node 後執行)
node --version
npm --version

Ghostty 官方也提供拖放 DMG 安裝方式。brew install node 和從官網下載安裝檔是兩種選擇,不需同時使用。

5. 試用 Hugging Face CLI

已安裝 uv 時,先用暫時環境看說明,不用安裝到全系統:

uvx hf --help

需要下載 gated model 且已取得模型存取權時,再依官方說明登入。CLI 登入可能會保存權杖;只在自己的 Mac 輸入權杖,不要把權杖複製進本手冊、截圖或公開聊天。

安全與清理:複製貼上前讀懂每個安裝命令;本課只有 Homebrew 和 Xcode 工具的安裝器可能要求確認。不要執行網路文章要求的 sudo 或刪除命令。若安裝途中出現錯誤,先保留錯誤訊息摘要和版本,不要反覆重跑安裝器。
C實際紀錄

本課先提供檢查欄位;工具是否已安裝、版本與專案執行結果尚未從這台 Mac 讀取,因此保留待查。若將結果分享至公開手冊,只記版本與成功/失敗摘要,不貼帳號名稱或 Token。

項目紀錄確認方式
目前終端機macOS Terminal 內建;Ghostty:選用/待確認Terminal 執行 echo $SHELL;Ghostty 依 App 是否已安裝記錄
Shell 與架構待查;M4 Pro 預期原生 Apple Siliconecho $SHELL、uname -m
Command Line Tools待查xcode-select -p、git --version
Homebrew待查;Apple Silicon 預設位置通常為 /opt/homebrewbrew --version、brew doctor
uv/Python 專案待查uv --version、uv run python --version
Node.js/npm選用/待查node --version、npm --version
Hugging Face CLI待查;本課用 uvx hf --help 試用確認出現 hf 指令說明;不公開 Token
專案資料夾~/ai-lab/macos-local-ai-project(完成指令後)確認 pyproject.toml 與 uv.lock 存在
D小測驗
Q1|Command Line Tools 和完整 Xcode 是同一個東西嗎?
答案:不是。Command Line Tools 是較精簡的命令列工具套件;若只需要常見編譯器和 Git 等工具,通常不必安裝完整 Xcode。
Q2|Apple Silicon 上 Homebrew 常見的預設安裝位置是?
答案:/opt/homebrew。安裝器結束時會提示 shell PATH 設定,依它提供的步驟操作。
Q3|為什麼把 Python 相依套件放在各自的專案環境?
答案:讓每個專案的套件與版本各自管理,降低不同工具互相衝突,也方便透過專案設定和鎖定檔重建環境。
Q4|Hugging Face CLI 的登入權杖可以貼到公開的課程紀錄嗎?
答案:不可以。存取權杖相當於密碼;只在自己裝置的登入提示中輸入,公開紀錄時不可包含權杖。
Q5|Ghostty 和 Node.js 是跑每個本機模型都必備的嗎?
答案:不是。macOS Terminal 已可執行命令列;Ghostty 是可選終端機,Node.js 只在後續工具或專案需要時安裝。
E完成狀態

完成這課後,應能打開終端機、辨認目前路徑與 Apple Silicon 架構,檢查 Command Line Tools 和 Homebrew,使用 uv 建立一個隔離的 Python 專案,並知道 Node.js、Ghostty 和 Hugging Face CLI 各自何時需要。待實際工具版本和 Python 專案執行結果完成紀錄後,再勾選本課完成。

05

遠端存取與系統監控

用 SSH、螢幕共享與 Tailscale 管理 Mac mini,並讀取主機狀態

本課讓 Mac mini 可以在沒有螢幕、鍵盤和滑鼠接在旁邊時,仍由你的另一台裝置管理。先分清楚「命令列登入」和「遠端看桌面」,再使用私有網路連線,最後練習查看 CPU、記憶體、Swap 與磁碟狀態。設定狀態尚待你在自己的 Mac 上確認,所以本課只提供安全操作步驟與待填紀錄。

A重點觀念
SSH 適合文字命令和檔案傳輸

macOS「遠端登入(Remote Login)」會開啟 SSH/SFTP 服務。從另一台電腦的終端機登入後,可以執行命令列工作;Apple 建議在「只允許這些使用者」中挑選帳號。遠端使用者的「完整磁碟存取權」是額外權限,只有確定需要時才開啟。Apple:允許遠端電腦存取 Mac

螢幕共享適合需要圖形介面的情況

螢幕共享會讓遠端使用者看見並操作 Mac 桌面,適合需要點選 App 或查看視窗時使用。請限定允許連線的使用者;如果只是跑命令或檢查主機,SSH 通常較直接。Apple:開啟或關閉螢幕共享

Tailscale 提供裝置之間的私有連線

在 Mac mini 和你要連入的裝置上安裝 Tailscale,登入同一個 tailnet 並確認裝置已上線。Tailscale 負責建立裝置間的網路路徑;它不會自動替 macOS 開啟 SSH 或螢幕共享,仍需在 Mac mini 啟用對應服務。MagicDNS 可讓你用裝置名稱取代記 IP。Tailscale:macOS 安裝 · MagicDNS · 連接 tailnet 裝置

Headless 主機也要有穩定電源和網路

正式遠端使用前,先在 Mac mini 本機完成帳號、網路與分享服務設定,並從另一台裝置實際測試。Mac mini 關機、睡眠、斷網,或帳號權限變動時,遠端連線可能中斷;先想好如何在本機恢復存取。

遠端監控要看趨勢而非單一數字

活動監視器「記憶體」頁面會顯示記憶體壓力、壓縮記憶體與 Swap Used。可在工作開始前、執行中、結束後各記一次,搭配 CPU 與磁碟資訊,觀察本機模型對主機的實際負載。Apple:查看記憶體使用量

減少對外暴露的服務與帳號

SSH 和螢幕共享只對需要的使用者開放。這份手冊會放在公開 Pages 網站,因此不要填入真實帳號、裝置名稱、tailnet 名稱、IP 位址、密碼或金鑰。一般家用遠端存取可優先使用 Tailscale 私有網路,不要為了方便把路由器的 SSH/VNC 連接埠轉發到公網。

先使用最小權限:Remote Login 選「只允許這些使用者」;完整磁碟存取權先保持關閉,確定某項工作真的需要時再評估。Tailscale 也要確認兩台裝置屬於你預期的 tailnet,並保持帳號與裝置存取清單整潔。
B設定步驟與指令

1. 在 Mac mini 本機確認帳號和基礎狀態

先在 Mac mini 開啟「終端機」,逐行執行以下只讀查詢。whoami 和 hostname 會顯示本機帳號與主機名稱,若把輸出貼到公開手冊前請先移除可識別資料。

whoami
hostname
ssh -V
uptime

2. 只為指定帳號開啟 SSH 遠端登入

在 Mac mini 開啟「系統設定 › 一般 › 共享 › 遠端登入」,打開服務後,在「允許存取」選「只允許這些使用者」,加入自己要用的帳號。先不要勾選「允許遠端使用者完整磁碟存取權」。若不需要 SSH,關閉 Remote Login 即可。

在你的另一台 Mac 安裝並登入 Tailscale,確認 Mac mini 與客戶端都出現在同一個 tailnet 且狀態為線上。若 MagicDNS 已啟用,使用控制台顯示的 Mac mini 裝置名稱;若尚未設定,也可先在同一個可信任區域網路內測試。

從客戶端終端機連線,將範例中的帳號與主機名稱換成你自己的值:

ssh 使用者名稱@Mac-mini的MagicDNS名稱

第一次連線可能會要求確認主機金鑰指紋。先核對目的裝置是自己的 Mac mini,再輸入 yes 繼續;之後輸入該 Mac 帳號密碼。成功後輸入 exit 離開遠端工作階段。

3. 需要桌面時,使用螢幕共享

在 Mac mini 開啟「系統設定 › 一般 › 共享 › 螢幕共享」,只加入需要的使用者。客戶端可用 Spotlight 搜尋「螢幕共享」,或從「應用程式 › 工具程式」開啟 Screen Sharing,再連到 tailnet 中 Mac mini 的名稱。螢幕共享會提供桌面操作能力,完成疑難排解後可關閉。

4. 登入後收集一份主機快照

在 SSH 工作階段中執行以下指令。它們會讀取目前狀態,不會安裝工具或修改設定:

uptime
top -l 1 -n 5
memory_pressure
sysctl vm.swapusage
df -h /

top -l 1 -n 5 是一次取樣後顯示前幾個處理程序,不是持續監控;memory_pressure、Swap 與磁碟數字也都是當下快照。需要圖形介面時,可透過螢幕共享開啟「活動監視器」,查看 CPU、記憶體和網路頁籤。記錄同一個任務前後的數據,比較容易看出模型載入後的影響。

連線方式記住這個組合:客戶端與 Mac mini 都登入 Tailscale + Mac mini 開啟指定的服務 + 帳號獲得最少必要權限。Tailscale 連線成功本身不代表 SSH 或螢幕共享已啟用;遇到連不上時,先在 Mac mini 本機確認服務和允許帳號。
C實際紀錄

目前已知的實驗平台規格沿用第一課。遠端登入、螢幕共享、Tailscale 和現時監控數據尚未由本機實測,因此不填入推測值。若要公開截圖或輸出,先遮蔽帳號、主機名稱、tailnet 名稱、IP 位址及金鑰資訊。

項目紀錄確認方式
實驗主機Mac mini · Apple M4 Pro · 14 核 CPU · 48GB 統一記憶體沿用第一課已記錄規格
macOS 版本待確認;本手冊不保存未核實版本sw_vers
Remote Login/允許帳號待確認;建議只允許指定帳號系統設定 › 一般 › 共享 › 遠端登入
遠端完整磁碟存取權目前狀態待確認;預設先保持關閉Remote Login 資訊設定
螢幕共享/允許帳號待確認;只記設定是否完成,不記私人帳號系統設定 › 一般 › 共享 › 螢幕共享
Tailscale/MagicDNS安裝狀態、裝置名稱與連線結果待確認;名稱留在私人裝置內Tailscale App 與 tailnet 裝置清單
遠端連線測試待實測:SSH 或螢幕共享可成功連線從另一台裝置連到 Mac mini
主機監控快照待實測;第一課的記憶體與 Swap 數字是歷史紀錄,不代表目前狀態uptime、memory_pressure、sysctl vm.swapusage、df -h /
D小測驗
Q1|SSH 和螢幕共享有什麼不同?
答案:SSH 提供終端機命令列登入和 SFTP 檔案傳輸;螢幕共享則能看見並操作遠端桌面。
Q2|兩台 Mac 都裝好 Tailscale,就一定能 SSH 到 Mac mini 嗎?
答案:不一定。Tailscale 建立裝置間的網路連線,Mac mini 還要開啟 Remote Login,且登入帳號必須獲准。
Q3|為什麼 Remote Login 建議選「只允許這些使用者」?
答案:把能嘗試登入的帳號限定在有需要的人,減少不必要的存取範圍;完整磁碟存取權也只在確有需求時才開啟。
Q4|為了外出時連回家裡的 Mac,應該把 SSH 或 VNC 連接埠轉發到公網嗎?
答案:一般家用遠端管理不建議這樣做。先使用 tailnet 私有連線並限制允許的帳號,不要把管理服務直接暴露在公網。
Q5|MagicDNS 有什麼用途?
答案:讓同一個 tailnet 中的裝置可用其名稱互相連線,不必手動記住可能變動的 IP 位址;它不會替 Mac 開啟 SSH 服務。
Q6|為什麼要在模型執行前後都記錄記憶體和 Swap?
答案:前後比較能看見同一個工作對主機資源的變化;單一快照只能代表取樣當時的狀況。
E完成狀態

閱讀並理解本課後可先完成知識部分。要勾選整課完成,還需在自己的 Mac mini 限定遠端登入使用者,從另一台裝置實際測試 SSH 或螢幕共享(建議透過 Tailscale),確認不需要完整磁碟存取權,並成功讀取一次遠端系統快照。本手冊不會代填實際設定或把私人連線識別資料公開。

06

Ollama:命令列模型執行器

安裝、下載與執行模型、本機 API、記憶體與儲存管理

Ollama 把模型下載、啟動和本機 API 整合成一套工具。本課會先安裝 macOS App,再用一個小模型完成第一次對話,接著用 CLI 和 HTTP API 檢查結果。你的 Mac mini 是 M4 Pro、48GB 統一記憶體;實際 macOS 版本、磁碟空間和安裝狀態尚未確認,因此這裡提供可照順序執行的教學與待填紀錄,不代填執行結果。

A重點觀念
Ollama 是執行工具,不是模型本身

Ollama App、CLI 和背景服務負責取得模型、啟動推論及提供本機 API。模型本身仍要另外下載;不同模型名稱、版本標籤和量化會有不同能力、檔案大小與記憶體需求。Ollama:CLI 指令參考

模型檔案放在 SSD,執行時也會用統一記憶體

macOS 預設把模型存在 ~/.ollama/models。下載檔案會占用磁碟;模型載入時還需要記憶體放權重、上下文 KV Cache 和執行暫存,所以「磁碟上放得下」不代表執行時一定有足夠空間。先看可用磁碟並保留餘裕。Ollama FAQ:模型位置與伺服器設定

第一次先用小模型、短上下文

Ollama 官方目前用 Gemma 4 E2B 示範本機第一次執行,下載約 7.2GB;模型庫顯示的實際大小和變體可能更新。對你的 48GB Mac,先用 gemma4:e2b、4K 上下文熟悉流程,再根據可用記憶體逐步試更大的模型。Ollama:快速入門 · Gemma 4 模型與標籤

上下文長度會影響額外記憶體

模型可能標示很大的最大上下文,但不表示 Mac 一開始就適合用到最大值。上下文愈長,KV Cache 通常會占更多記憶體。先從 4096 tokens 開始,確認速度、記憶體壓力和 Swap 後再調整;實際用量也取決於模型和執行設定。Ollama FAQ:上下文視窗設定

本機 CLI 連到本機服務

macOS 上的 Ollama 服務預設監聽 127.0.0.1:11434;同一台 Mac 的 CLI 和程式可呼叫這個位址。除非已理解網路邊界並完成適當保護,先不要把服務改綁到所有網路介面,也不要把 11434 轉發到公網。Ollama FAQ:網路監聽位址

注意選的是本機模型還是雲端模型

使用下載到 Mac 的本機模型時,推論在本機執行;選擇 Ollama Cloud 模型或雲端功能時,資料處理方式不同。第一次練習請選一般本機模型標籤,例如 gemma4:e2b,不要選名稱含 -cloud 的標籤。Ollama FAQ:本機與 Cloud 功能

48GB 的挑選原則:先查看實際模型標籤和下載大小,確認磁碟空間後,以 E2B/小模型和 4K 上下文起步。權重大小之外還要留記憶體給 macOS、其他 App 與 KV Cache;第一課的壓縮記憶體和 Swap 是過去快照,開始測試前要重新看當下狀態。
練習階段建議起點在 M4 Pro 48GB 上的做法
第一次啟動gemma4:e2b先核對官方模型頁的下載大小;從 4096 tokens 上下文開始,測通後記錄回覆與資源用量。
能力與速度比較12B 級本機模型確認模型標籤、量化及下載大小;保持短上下文,與小模型用同一題比較。
較大型實驗26B/31B 級模型先檢查記憶體壓力並關閉不需要的大型 App;若 Swap 持續增加或系統變慢,停止模型並回到較小版本。
70B 級模型暫不作入門選擇48GB 還需容納 macOS、KV Cache 和其他程式;依第二課原則先評估實際量化檔案與可用記憶體。
B安裝、命令與 API 練習

1. 安裝官方 macOS App

先在「終端機」執行 sw_vers 確認 macOS 版本。Ollama 官方目前要求 macOS Sonoma 14 或更新版本,Apple M 系列支援 CPU 與 GPU 加速。從 Ollama 官方 macOS 下載頁下載 DMG,將 Ollama 拖到「應用程式」後開啟。首次啟動時若詢問是否在 /usr/local/bin 建立 CLI 連結,先確認 App 來自官方下載,再依畫面提示處理。Ollama:macOS 系統需求與安裝

先確認 CLI 是否可用;這些命令不會安裝模型:

ollama --version
ollama ls

若顯示找不到 ollama,先檢查 App 是否已放入「應用程式」並完成 CLI 連結提示;重新開啟終端機再試。若服務尚未啟動,先從「應用程式」開啟 Ollama,不要在 App 已執行時另外啟動第二個伺服器程序。

2. 查看模型大小,再下載第一個本機模型

到官方 Gemma 4 模型頁查看標籤、檔案大小與上下文說明。確認磁碟空間足夠後,下載入門模型:

ollama pull gemma4:e2b
ollama ls

ollama pull 下載模型,ollama ls 列出已下載模型。模型資料預設放在 ~/.ollama/models;檔案大時下載可能需要一些時間。此步驟需要網路和數 GB 以上的可用儲存空間。

3. 對話並設較保守的上下文

ollama run gemma4:e2b

進入互動對話後,先將上下文設為 4096,再輸入一個短測試提示:

/set parameter num_ctx 4096
請用繁體中文,以 100 字內解釋什麼是 Apple Silicon 統一記憶體。
/bye

/bye 離開對話。回答完成後回到終端機,記下第一次載入時間、回答是否成功,以及回答期間活動監視器的記憶體壓力。可重複問相同問題,比較不同模型時的差別。

4. 查看載入狀態與釋放記憶體

ollama ps
memory_pressure
sysctl vm.swapusage
df -h /

ollama ps 顯示目前載入的模型;ollama stop gemma4:e2b 可停止該模型並釋放執行時佔用的記憶體。它不會刪除已下載的權重;刪除權重的 ollama rm 會移除本機模型檔案,確認不再需要前不必使用。

ollama stop gemma4:e2b

5. 呼叫本機聊天 API

確保 Ollama App 正在執行,再從同一台 Mac 的終端機送出請求。這個範例設定 stream 為 false,所以回傳完整 JSON,回答位於 message.content:

curl http://127.0.0.1:11434/api/chat   -H "Content-Type: application/json"   -d '{
    "model": "gemma4:e2b",
    "messages": [
      {"role": "user", "content": "請用繁體中文回答:什麼是 KV Cache?"}
    ],
    "stream": false,
    "options": {"num_ctx": 4096},
    "keep_alive": 0
  }'

keep_alive: 0 會在這次回答後立即卸載模型,較適合測試後釋放記憶體;如想短時間內連續提問,可省略這個欄位,Ollama 預設會讓模型暫留記憶體一段時間。localhost 或 127.0.0.1 指向目前這台 Mac,不是公開網站。Ollama:聊天 API · Ollama FAQ:Keep Alive 與記憶體

保留本機範圍:不要把本課 API 改成對所有網路介面監聽、不要設定路由器轉發 11434,也不要將 API 請求中可能含個資或 API 金鑰的內容貼到公開紀錄。下載模型需要網路;本機模型推論則在 Mac 上執行。
C實際紀錄

下表將教學範例和你的實測分開。型號與記憶體規格沿用第一課;Ollama 安裝、macOS 版本、模型下載與效能都尚未在本課實際確認。

項目紀錄確認方式
實驗主機Mac mini · Apple M4 Pro · 14 核 CPU · 48GB 統一記憶體沿用第一課硬體資料
macOS 版本待確認;官方目前要求 Sonoma 14 或更新sw_vers
Ollama App/CLI安裝狀態與版本待確認App 是否在「應用程式」;執行 ollama --version
模型與標籤教學範例為 gemma4:e2b;是否下載待確認ollama ls 與官方模型頁
下載大小與磁碟餘裕待確認;不要把模型頁的約略數字當成本機實測下載前看模型頁;執行 df -h /
上下文設定教學起點 4096 tokens;實際使用待測/set parameter num_ctx 4096
第一次對話/API 回覆待實測;不填入推測速度或答案ollama run 與 curl 請求
載入狀態/CPU、GPU 分配待實測ollama ps;搭配活動監視器觀察
記憶體壓力/Swap待實測;第一課數字為歷史快照模型啟動前後查看 memory_pressure 與 sysctl vm.swapusage
D小測驗
Q1|下載並安裝 Ollama,代表已經有模型可以執行嗎?
答案:不一定。Ollama 是模型執行工具;要先下載某個模型,才有模型權重可以執行。
Q2|模型檔案存在 SSD,為什麼跑起來仍會占用統一記憶體?
答案:SSD 儲存下載檔;執行時還需要記憶體放模型權重、KV Cache 和暫存資料。
Q3|第一次測試,為什麼先用 4096 tokens 上下文?
答案:較短上下文能先確認基本流程並控制額外快取需求;通過後再觀察記憶體和品質,逐步增加。
Q4|ollama ps 和 ollama ls 各在看什麼?
答案:ollama ls 列出已下載模型;ollama ps 顯示目前載入在記憶體中的模型。
Q5|把 API 位址改成 0.0.0.0:11434 有什麼影響?
答案:服務可能接受本機以外的網路連線。初學先保留預設的 loopback 位址,不要對外開放或設定路由器轉發。
Q6|選本機模型與 Ollama Cloud 模型時,資料路徑相同嗎?
答案:不同。本機模型在這台 Mac 執行;雲端模型使用遠端服務,開始提問前要先確認模型標籤與服務類型。
E完成狀態

要勾選本課完成,請確認 Ollama 在支援的 macOS 版本成功啟動,記錄 App/CLI 版本與模型標籤,完成一次小模型對話及一次 /api/chat 本機 API 請求,並比較執行前後記憶體壓力與 Swap。若尚未實際安裝或測試,保持未勾選即可;不要把帳號、金鑰或私人提示內容貼進公開手冊。

07

WebUI:瀏覽器裡的模型工作台

用 Open WebUI 連接 Ollama、整理對話與試用知識庫

WebUI 是透過瀏覽器操作模型的介面,本身不包含 Ollama 模型權重。本課以 Open WebUI 為例,沿用第六課的本機 Ollama;先在同一台 Mac 啟動網頁介面、完成對話,再用非敏感的小文字檔了解知識庫。安裝方式採用本機 Python 工具 uv,實際安裝狀態仍待確認。

A重點觀念
介面和模型執行器是兩件事

Open WebUI 管理瀏覽器聊天、對話和知識庫;Ollama 負責載入模型與推論。停止網頁介面不會刪除已下載的模型。

模型服務要先連通

同一台 Mac 上,本課使用 http://localhost:11434 連到 Ollama。模型清單空白時先確認 Ollama App 有啟動,並用 ollama ls 確認已有本機模型。

Knowledge 使用 RAG,不會訓練權重

知識庫將文件切成片段、建立索引,再依問題找出相關內容交給模型。回答仍應回原始文件核對;Embedding 模型與檔案處理方式依設定而變。官方知識庫說明

本機介面不等於資料一定只在本機

本機 Ollama 推論在 Mac 執行;若選雲端供應端、外部 Embedding、網路搜尋或外掛,提示和文件可能被送往外部服務。初次練習先只接本機模型。

對話和設定會占用儲存空間

指定固定的 DATA_DIR 保存帳號、設定及對話。升級或重建前備份重要資料;停止服務不會清除這個資料目錄。

先從單人、本機、小文件開始

第一個建立的帳號是管理員。先在本機完成連線,再用少量、可公開的文字檔練習文件問答。

本課預設只供這台 Mac 使用:服務綁定 127.0.0.1。不要把頁面公開到網際網路。若改用 Docker,容器連回 Mac 上的 Ollama 需要調整網路監聽設定,請先了解安全影響。
目的功能確認方式
一般對話New Chat,選本機 Ollama 模型模型出現在清單並收到回答
問一份文件在聊天中附加小型文字檔回原文核對答案
重複使用一批文件Workspace → Knowledge確認索引完成及來源片段
備份對話Settings → Data Controls確認匯出位置並妥善保存
B安裝、連線與知識庫練習

1. 確認 uv 和 Ollama 可用

先依第四課確認 uv 已安裝,再開啟 Ollama App 並確認已有本機模型:

uv --version
ollama ls

第一次啟動會透過網路下載 Open WebUI 套件。若找不到 uv,先回第四課完成安裝。

2. 啟動 Open WebUI

建立固定的本機資料目錄,再限制服務只接受本機連線:

mkdir -p "$HOME/.open-webui"
DATA_DIR="$HOME/.open-webui" uvx --python 3.11 open-webui@latest serve --host 127.0.0.1 --port 8080

首次啟動需等套件下載及服務準備完成,保持終端機開啟,再用瀏覽器前往 http://127.0.0.1:8080。若連接埠 8080 已被使用,停止服務後改用其他埠號,並開啟相應網址。

3. 建立帳號、選模型並聊天

初次畫面會提供建立管理帳號。進入新對話後,選取 Ollama 已下載的模型,例如 gemma4:e2b。若模型未出現,到「Settings → Admin → Connections」確認 Ollama 位址為 http://localhost:11434。送出一個短問題,確認收到回答。

4. 試用知識庫

準備不含私人資料的小型文字檔,到「Workspace → Knowledge」建立知識庫並加入檔案。等待處理完成後,問一個答案確實在檔案中的問題,請模型指出依據,並回原文核對。若需要 Embedding 模型,先確認它使用本機或外部服務。

5. 停止服務並保留資料

回到終端機按 Control-C 停止服務。對話與設定留在 ~/.open-webui;用相同命令可重新啟動。要重設或升級前,先備份重要資料。

如果改用 Docker

Open WebUI 官方 Docker 文件提供 host.docker.internal 讓容器連到主機;官方也指出容器連接 Ollama 時,Ollama 需要接受非 loopback 的連線。這可能讓未驗證的 Ollama API 對區網可達,應先了解監聽位址及防火牆,勿轉發到公網。Open WebUI:Ollama 連線 · Ollama FAQ:服務設定

C實際紀錄

下列版本、連線、文件問答與資源數據待你在 Mac mini 上完成後填寫。

項目紀錄確認方式
主機與記憶體Mac mini · M4 Pro · 14 核 CPU · 48GB 統一記憶體沿用第一課資料
macOS/uv版本待確認sw_vers、uv --version
Open WebUI 套件版本待確認啟動訊息或套件資訊
網址與資料目錄教學設定為 127.0.0.1:8080、~/.open-webui;啟動待確認瀏覽器與資料夾
Ollama 模型與連線模型標籤和連線狀態待測模型選單、ollama ls
第一次對話回答狀態待測用一題短問題確認
Knowledge 文件問答檔案、Embedding 提供者和回答待測非敏感練習檔,對照原文
記憶體/Swap待測;第一課數值是歷史快照活動監視器、memory_pressure、sysctl vm.swapusage
D小測驗
Q1|Open WebUI 會提供可執行的模型權重嗎?
答案:不會。它是介面,推論由連接的 Ollama 或其他模型服務執行。
Q2|RAG 知識庫會重新訓練模型嗎?
答案:不會。它檢索文件片段作為回答依據,仍需核對來源。
Q3|模型未出現時先檢查什麼?
答案:確認 Ollama 正在執行、ollama ls 有本機模型,且連線位址為 localhost:11434。
Q4|指定 DATA_DIR 的用途是什麼?
答案:將對話與設定保存在固定位置,便於續用及備份。
Q5|本機開啟 WebUI 能保證所有資料都不會送到外部嗎?
答案:不能。仍要確認模型供應端、Embedding、搜尋與外掛的資料路徑。
E完成狀態

確認 Open WebUI 能在本機開啟、建立管理帳號、連到 Ollama 本機模型並完成對話;再用一份非敏感小文件試用 Knowledge,核對答案來源,記下資料目錄與模型供應端。未完成實作前保持未勾選。

08

LM Studio:桌面模型環境

模型下載、GGUF/MLX 載入、CLI 與本機 API

LM Studio 把模型探索、下載、載入與聊天放在桌面介面,也能啟動本機 API Server。本課與第六課 Ollama 作工具比較,不必同時載入大型模型。官方目前支援 Apple Silicon M1 至 M4、macOS 14 或更新版本,建議 16GB 以上記憶體;你的 M4 Pro 48GB 符合建議級距,但實際負載仍取決於模型、量化、上下文及當下可用記憶體。

A重點觀念
下載和載入是兩個步驟

下載模型是把權重存到 SSD;選擇載入後,LM Studio 才配置執行所需的統一記憶體。卸載模型會釋放執行記憶體,但保留磁碟檔案。

GGUF 與 MLX 是不同格式與執行生態

LM Studio 可透過 llama.cpp 執行 GGUF;在 Apple Silicon 上也支援 MLX。下載時確認格式、發布者、相容 Runtime 及量化版本。LM Studio:格式與執行引擎

量化影響檔案大小和輸出表現

相同模型常有多種量化,4-bit 常見且較省空間,但品質和速度仍會因模型及實作而異。初學可找 GGUF Q4_K_M 或相容的 MLX 4-bit Instruct 版本。

上下文會增加 KV Cache 用量

執行時除了權重,也需空間給 KV Cache 和暫存。先設定 4096 tokens,觀察記憶體壓力後再逐步增加;模型標示的最大值不等於本機起始建議。

CLI 可以檢視、下載與管理模型

LM Studio App 至少開啟一次後,可用 lms 列出模型、載入、估算用量、啟動 Server 和卸載。圖形介面適合初次探索;CLI 方便重複執行和記錄。

API Server 留在本機

常見範例在 http://localhost:1234/v1 提供相容端點。預設不需要驗證時更應維持本機存取;要讓區網裝置使用前,先啟用 API Token 並確認網路邊界。Server 安全設定

針對 M4 Pro 48GB:第一次用 3B–8B Instruct、Q4 或 MLX 4-bit、4096 上下文。熟悉後再比較 12B–14B;20B–32B 先看載入估算、可用記憶體及 Swap。70B 級不作入門建議,需為 macOS、KV Cache 和其他 App 留空間。
階段模型範圍操作建議
第一次聊天3B–8B Instruct,Q4/MLX 4-bit上下文 4096,核對下載大小和來源。
品質與速度比較同模型不同格式,或 7B–14B固定提示與上下文,比較回答和記憶體。
較大型實驗20B–32B 量化模型先估算容量;Swap 增加或系統變慢就換小模型。
70B 級不作第一次測試先理解檔案及載入所需,避免耗盡可用記憶體。
B安裝、下載、CLI 與本機 API

1. 安裝官方 App

從 LM Studio 官方下載頁取得 macOS 版本,安裝並開啟一次。版本及介面會變動,依 App 與官方下載頁為準。首次下載模型需要網路及 SSD 空間。

2. 搜尋與下載小型 Instruct 模型

在模型探索介面搜尋 3B–8B 級 Chat/Instruct 模型,查看發布者、格式、量化、檔案大小及授權。介面入口會依版本位於 Discover,或「Settings → Local Models → Explore」。GGUF 可先選 Q4_K_M;MLX 則選 Apple Silicon 相容版本。下載完再從模型庫載入。

3. 載入並進行第一輪聊天

選剛下載的模型,先把 Context Length 設成 4096,其他設定先保留預設。LM Studio 開啟過一次後,在終端機可執行以下指令:

lms --help
lms ls
lms load --context-length 4096
lms ps

lms load 未指定模型時會提示選擇。lms ls 是磁碟上的模型,lms ps 是目前載入記憶體的模型;若找不到 lms,確認開啟過 App 並重開終端機。完成後卸載:

lms unload --all

4. 先估算,再觀察實際記憶體

將範例中的模型 key 替換成 lms ls 顯示的實際值:

lms load --estimate-only <模型 key>

估算會依上下文等設定而變,並非速度或可執行的保證。載入模型後觀察活動監視器、memory_pressure 和 sysctl vm.swapusage。

5. 啟動本機 API 並發送請求

從 Developer 頁啟動 Server,或執行 lms server start。接著列出模型 ID:

lms server start
curl http://localhost:1234/v1/models

將下方 MODEL_ID 換成清單回傳的模型 ID:

curl http://localhost:1234/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [
      {"role": "user", "content": "請用繁體中文簡短說明 GGUF 和 MLX 的差異。"}
    ],
    "temperature": 0.7,
    "stream": false
  }'

不再需要 API 時,在終端機執行 lms server stop,或在 Developer 頁關閉 Server。不要啟用區網服務或將埠號轉發到公網。

6. 比較工具前先卸載另一個模型

用 Ollama 和 LM Studio 比較時,先在 Ollama 執行 ollama stop 模型標籤,再載入 LM Studio 模型;不要同時載入多個大型模型。兩者的模型資料夾預設不同,不要假設權重會自動共用。

C實際紀錄

LM Studio 尚未確認安裝。型號資料沿用第一課;模型名稱、記憶體及 API 結果待實測。

項目紀錄確認方式
主機Mac mini · M4 Pro · 14 核 CPU · 48GB 統一記憶體第一課資料
macOS/LM Studio 版本待確認sw_vers、App「About」
模型與發布者待選擇及下載模型頁、lms ls
格式/量化/下載大小GGUF 或 MLX;實際值待確認下載項目資訊
上下文教學起點 4096;實際設定待測載入畫面或 lms ps
估算與記憶體壓力待測;第一課 Swap 是歷史快照載入估算、活動監視器、memory_pressure
聊天與生成速度回答品質、首字時間待測固定短提示並記錄實測
本機 API教學預設埠 1234;狀態待測/v1/models 與聊天請求
模型資料夾待確認;不預設與 Ollama 共用兩個工具各自的模型目錄設定
D小測驗
Q1|下載模型後就已經載入記憶體了嗎?
答案:不是。下載存檔到 SSD;選擇載入後才配置推論所需記憶體。
Q2|GGUF 和 MLX 是相同格式嗎?
答案:不是,格式與執行生態不同;LM Studio 在 Apple Silicon 支援兩者。
Q3|48GB 為什麼仍先從 4-bit 和 4096 上下文開始?
答案:記憶體仍須由 macOS、模型權重、KV Cache 和其他 App 共用,應依實測逐步增加負載。
Q4|哪個指令看目前載入的模型?
答案:lms ps;lms ls 則列出磁碟上的模型。
Q5|呼叫本機聊天 API 前,怎麼確認模型 ID?
答案:啟動 Server 後查看 http://localhost:1234/v1/models,使用回傳的實際 ID。
E完成狀態

完成安裝,下載並核對一個小型模型的來源、格式、量化及大小;使用 4096 上下文完成聊天,記錄估算與實際記憶體、Swap。再啟動本機 Server,確認 /v1/models 和一次聊天 API 成功,最後關閉 Server 並卸載模型。實際操作完成前保持未勾選。

09

llama.cpp 與 GGUF

Homebrew 安裝、Metal Offload、Context/KV Cache 與本機 API

本課直接以 LM Studio 已下載的 GGUF 權重執行 llama.cpp,從 CLI、Metal GPU Offload 與上下文記憶體實測,一路驗證到 llama-server 的 OpenAI 相容聊天 API。

A重點觀念
GGUF 是模型檔格式,llama.cpp 負責推論

llama.cpp 可直接載入 LM Studio 模型資料夾中的 GGUF,不必重複下載權重。LM Studio 和 llama.cpp 是不同操作介面/執行方式;這次確認了同一 GGUF 可由 llama.cpp CLI 與 Server 執行。

Apple Silicon 使用 Metal 後端

--list-devices 顯示 Metal 裝置 MTL0 Apple M4 Pro,證明這份 Homebrew build 可用 Metal。-ngl 999 請求將可用層盡量卸載至 GPU;實際速度仍依模型、提示與執行設定而變。

Prompt 與 Generation 是不同階段

Prompt throughput 主要反映輸入提示的 prefill;Generation throughput 反映逐 token 解碼。小模型的 CPU prefill 可能較快,但 GPU generation 可更快,不能只用一個速度數字比較。

Context 長度會帶來 KV Cache 記憶體壓力

--ctx-size 設定可用上下文容量。容量拉大會增加 KV Cache/記憶體壓力,但短提示的生成速度不一定因此變慢;要同時觀察速度、記憶體壓縮與 Swap。

Server 可直接提供 OpenAI 相容 API

llama-server 可在本機提供 /v1/models 與 /v1/chat/completions。載入單一模型時,最簡聊天請求可以省略 model 欄位。

Reasoning 也會消耗生成 token

這次最終答案雖只有「測試成功」,回應仍附帶長篇 reasoning_content,並計入 completion token 與生成時間。Think/reasoning 內容越長,通常代表更多 token 與延遲。

B安裝、CLI 與實作指令

1. 透過 Homebrew 安裝並確認版本

brew install llama.cpp
brew info llama.cpp
llama-cli --version
llama-server --version

本機紀錄:llama.cpp 0.5.0,build 11146、commit 7fe450e19,平台 Darwin arm64;相依套件為 libomp 23.1.2、ggml 0.25.3。

2. 檢查 CLI 與可用裝置

llama-cli --help
llama-server --help
llama-cli --list-devices
參數用途
--ctx-size設定上下文容量;本次伺服器使用 32768。
--flash-attn/-fa啟用 Flash Attention;本次 Server 使用 -fa on。
--device指定要使用的推論裝置。
--list-devices列出 build 可用的裝置與後端。
--gpu-layers/-ngl設定卸載至 GPU 的模型層數;本次用 -ngl 999。
--kv-offload控制是否將 KV Cache 卸載至支援的裝置。
--op-offload控制是否將可支援的運算卸載至裝置。
--verbose輸出較詳細的載入與執行診斷資訊。

--list-devices 的實際結果包含 BLAS = 1, Accelerate 與 MTL0 Apple M4 Pro (38338 MiB free);因此 Metal backend 已可用。

3. 直接載入 LM Studio 已下載的 2B GGUF

llama-cli   -m "$HOME/.lmstudio/models/lmstudio-community/Qwen3.5-2B-GGUF/Qwen3.5-2B-Q4_K_M.gguf"   --ctx-size 4096   -p "你好,請用繁體中文簡短回答:1+1 等於多少?"   -n 64

CPU 與 GPU 比較時,固定模型、提示與上下文,再分別使用 -ngl 0(CPU)及 -ngl 999(盡量 GPU Offload)。不同提示或執行條件的單次速度只作為該次紀錄。

4. 啟動 9B llama-server

llama-server   -m "$HOME/.lmstudio/models/lmstudio-community/Qwen3.5-9B-GGUF/Qwen3.5-9B-Q4_K_M.gguf"   -ngl 999   -c 32768   -fa on   --host 127.0.0.1   --port 8081

Server 成功載入模型並監聽 http://127.0.0.1:8081;紀錄顯示 n_ctx_slot = 32768、n_slots = 4。

5. 驗證模型清單與聊天 API

curl http://127.0.0.1:8081/v1/models

curl http://127.0.0.1:8081/v1/chat/completions   -H "Content-Type: application/json"   -d '{
    "messages": [
      {"role": "user", "content": "你好,請只回答:測試成功"}
    ]
  }'

聊天請求刻意不指定 model;Server 已載入單一模型,因此最簡請求即可成功。

C實際紀錄

安裝與硬體

項目實際紀錄
llama.cpp0.5.0 · build 11146 · commit 7fe450e19 · Darwin arm64
相依套件libomp 23.1.2 · ggml 0.25.3
裝置BLAS = 1, Accelerate;MTL0 Apple M4 Pro (38338 MiB free)
2B 模型~/.lmstudio/models/lmstudio-community/Qwen3.5-2B-GGUF/Qwen3.5-2B-Q4_K_M.gguf
9B 模型~/.lmstudio/models/lmstudio-community/Qwen3.5-9B-GGUF/Qwen3.5-9B-Q4_K_M.gguf

2B 初次 CLI 生成速度

測試PromptGeneration
第一次實測約 118.1 t/s約 121.2 t/s
另一次測試約 106.9 t/s約 110.2 t/s

2B CPU 與 GPU Offload 比較

執行方式PromptGeneration解讀
CPU248.4 t/s92.7 t/s這次測試的 Prompt prefill 較快。
GPU Offload144.3 t/s121.0 t/sGeneration 較 CPU 快;小模型不保證 GPU 在所有階段都較快。

這次 2B 實測顯示 CPU Prompt prefill 可較快,而 GPU Generation 較快。解讀時要分開看輸入處理與逐 token 生成。

9B CPU 與 GPU Offload 比較

執行方式PromptGeneration
CPU60.6 t/s28.8 t/s
GPU Offload148.6 t/s39.3 t/s

本次 GPU Prompt 約為 CPU 的 2.45 倍;Generation 約提升 36%。不同模型與上下文的效能仍須依本機實測判斷。

9B GPU 測試前後的記憶體與 Swap

時點記憶體狀態Swap
GPU 執行前Swap pool 約 5 GBused 3857.50 MB
GPU 執行後PhysMem 42G used(3742M wired、24G compressor),5168M unusedused 3857.50 MB,未增加

這次 9B GPU Offload 前後 Swap 使用量相同;只代表該次觀察未額外造成 Swap 成長。

Context 長度、速度與記憶體

ContextPromptGenerationPhysMemSwap
4K117.6 t/s39.2 t/s44G used(9168M wired、23G compressor),3061M unusedused 3849.44 MB
32K121.4 t/s39.2 t/s45G used(10G wired、23G compressor),1945M unusedused 3849.44 MB
64K116.9 t/s39.2 t/s45G used(11G wired、21G compressor),2737M unusedpool 7168 MB;used 5945.25 MB

短提示下,最大 Context 從 4K 拉到 64K 並未讓這組 Generation 速度下降;但可用 KV Cache 增加會帶來記憶體壓力。64K 相較 32K,該次 Swap used 增加 2095.81 MB(約 2.1 GB)。這是單次系統快照,不能當成所有模型與工作負載的固定耗用。

llama-server 與 API

項目驗證結果
啟動設定Qwen3.5-9B Q4_K_M · -ngl 999 · -c 32768 · -fa on · 127.0.0.1:8081
Server 狀態model loaded;listening on http://127.0.0.1:8081;n_ctx_slot = 32768;n_slots = 4
/v1/modelsn_ctx 32768 · n_ctx_train 262144 · n_params 8953803264 · size 5616076800 · ftype Q4_K - Medium
/v1/chat/completions不帶 model 的最簡請求成功;content 為「測試成功」。
Token 用量prompt 18 · completion 214 · total 232
API timingsPrompt 86.709 t/s · Generation 39.375 t/s
Server 安全提示:啟動日誌指出沒有設定 API key,且 CORS 允許所有來源。這次只綁定 127.0.0.1,適合本機學習;未來若要開放 LAN,先設定 API key,並限制允許的 CORS origins 與網路存取範圍。

39.375 t/s 與 CLI 9B GPU 的約 39.3 t/s 幾乎一致,說明這次 Server 與 CLI 的生成效能接近。

D小測驗
Q1|Prompt 和 Generation 速度分別反映什麼?
答案:Prompt 主要是輸入提示的 prefill;Generation 是模型逐 token 解碼,兩者瓶頸可能不同。
Q2|小模型的 CPU Prompt 比 GPU 快,代表 Metal 沒有作用嗎?
答案:不是。這次 GPU 的 2B Generation 較快;小模型、操作階段和測試條件會影響哪一端占優。
Q3|Context 設成 64K,短提示就一定會變慢嗎?
答案:不一定。這次短提示速度接近,但較大 Context 會增加 KV Cache/記憶體壓力,需監測 Swap。
Q4|單一模型已載入時,聊天 API 一定要傳 model 欄位嗎?
答案:這次最簡請求省略 model 仍成功;若服務端有多模型或客戶端要求,則以服務回傳的模型 ID 為準。
Q5|Server 顯示 CORS 全開與未設定 API key,為什麼本次仍只供本機學習?
答案:它只綁定 127.0.0.1。若改成 LAN 存取,就應加 API key 並限制來源與網路範圍。
Q6|短答案為何仍可能有較多 token 與延遲?
答案:回應另含長篇 reasoning_content;額外生成的 reasoning token 仍增加用量與時間。
E完成狀態與本課總結

已完成 Homebrew 安裝及版本確認、GGUF CLI 推論、Metal 裝置辨識、2B/9B CPU 與 GPU 比較、Context/KV Cache 與 Swap 觀察、Server 啟動,以及兩個 API 端點驗證;因此第九課標記完成。

本課實作鏈:GGUF → llama.cpp → Metal GPU Offload → Context/KV Cache → llama-server → OpenAI-compatible API。
10

MLX / mlx-lm:Apple Silicon 原生推論

原生推論、generation 效能與長 Context 記憶體壓力

承接第九課 llama.cpp 與 GGUF,本課改用 Apple Silicon 上的 MLX / mlx-lm 執行 Qwen3.5 4-bit 模型,記錄環境差異、2B/9B 單次推論、長 Context 記憶體與 Swap 變化,以及 4-bit/8-bit 規格題測試。課程實作與結論已完成,下一課銜接第十二課。

A重點觀念
MLX / mlx-lm 是 Apple Silicon 推論工具鏈

本次使用 mlx-community/Qwen3.5-2B-4bit 與 mlx-community/Qwen3.5-9B-4bit,以 mlx-lm 工具執行模型並測量 prompt prefill、逐 token generation 與記憶體使用。

系統 Python 與 uv tool 環境彼此獨立

uv tool install 會把命令列工具安裝在隔離環境。系統或 Homebrew 的 python3 看不到該環境中的 mlx-lm 套件 metadata,屬於預期的環境差異。

Prompt 與 Generation 需分開閱讀

Prompt throughput 是輸入提示的處理速度;Generation throughput 是逐 token 解碼速度。短 prompt 的計時更容易受初始化影響,不能只看 prompt 數字推論整體效能。

長 Context 會加重統一記憶體與 Swap 壓力

本次 9B 的 64K 測試期間,系統 unused memory 與 swap free 都很低,並在 warmup 階段手動停止。單次快照包含背景服務的負載,不等於模型單獨耗用量。

B指令|安裝、推論與工具驗證

1. 起始環境檢查

檢查項目實際結果
系統/Homebrew python3可 import mlx;但 mlx.__version__ 屬性不存在。
mlx_lm起始環境尚未安裝。

2. 以 uv 安裝 mlx-lm

uv tool install mlx-lm

安裝成功,uv 回報安裝 34 個 packages,並建立 18 個 executables。工具環境包含 mlx 0.32.3、mlx-lm 0.32.0、mlx-metal 0.32.3。

3. 確認命令列入口與 help

command -v mlx_lm.generate
mlx_lm.generate --help

command -v mlx_lm.generate 回傳 /Users/skbank/.local/bin/mlx_lm.generate;mlx_lm.generate --help 驗證成功。18 個 executables 中包含 mlx_lm.generate、mlx_lm.benchmark、mlx_lm.server、mlx_lm.chat、mlx_lm.convert 等入口。

Python 環境差異:系統/Homebrew python3 查到 MLX 0.32.1,但查不到 mlx-lm 的套件 metadata;mlx-lm 則安裝在 uv tool 隔離環境,其內含 MLX 0.32.3、mlx-lm 0.32.0 與 mlx-metal 0.32.3。兩邊版本與可見套件不同是正常現象。

4. 單次推論範例

mlx_lm.generate \
  --model mlx-community/Qwen3.5-2B-4bit \
  --prompt "請用繁體中文簡短說明 MLX 是什麼。"

這是便於初次試跑的範例指令。第一次執行會從 Hugging Face 下載模型;本課的實際效能數據以後面的 benchmark 與實測紀錄表為準。完整選項可用 mlx_lm.generate --help 查詢。

5. MLX 本機 API(延伸指令)

mlx_lm.server --model mlx-community/Qwen3.5-2B-4bit

官方預設會在本機 localhost:8080 提供相容聊天 API。這是延伸操作示例,並非本課的實測項目;官方文件提醒此伺服器僅有基本安全檢查,適合本機開發測試,不應直接當作對外正式服務。

C推論實測與第九課比較

MLX 首輪模型結果

模型PromptGenerationPeak memory
mlx-community/Qwen3.5-2B-4bit25 tokens
23.938 tok/s
200 tokens
178.837 tok/s
1.190 GB
mlx-community/Qwen3.5-9B-4bit28 tokens
106.100 tok/s
250 tokens
49.832 tok/s
5.244 GB

與第九課 llama.cpp GPU 的單次數據並列

模型/執行方式PromptGeneration
2B · llama.cpp GPU144.3 tok/s121.0 tok/s
2B · MLX / mlx-lm23.938 tok/s(25 tokens)178.837 tok/s(200 tokens)
9B · llama.cpp GPU148.6 tok/s39.3 tok/s
9B · MLX / mlx-lm106.100 tok/s(28 tokens)49.832 tok/s(250 tokens)

以這兩次單次紀錄計算,MLX 2B generation 約快 48%,MLX 9B generation 約快 27%;llama.cpp 的 2B 與 9B prompt throughput 都較高。2B prompt 只有 25 tokens,且短 prompt 較容易受初始化影響;各次提示、token 數與執行條件並非完整控制的同一組測試,這些數字只描述本次紀錄,不宜直接推論某工具整體一定較快。

DContext / KV 壓力測試

benchmark 參數確認

mlx_lm.benchmark --help

help 顯示參數包含 --prompt-tokens、--generation-tokens、--num-trials 與 --prefill-step-size 等,可設定提示長度、生成 token 數、重複次數及 prefill 步長。

4K、32K、64K 測試期間的系統記憶體快照

ContextPhysMemvm.swapusage
4K47G used(10G wired、22G compressor),135M unusedtotal 7168.00MB · used 6447.06MB · free 720.94MB
32K47G used(11G wired、21G compressor),334M unusedtotal 8192.00MB · used 7131.31MB · free 1060.69MB
64K47G used(12G wired、20G compressor),418M unusedtotal 9216.00MB · used 8321.31MB · free 894.69MB

以上是各 Context 測試時觀察到的系統整體快照;背景服務仍有負載,資料不能視為 MLX 模型本身的獨立記憶體用量。

64K benchmark 嘗試

mlx_lm.benchmark \
  --model mlx-community/Qwen3.5-9B-4bit \
  --prompt-tokens 65536 \
  --generation-tokens 128 \
  --num-trials 3

執行到 Running warmup.. 後,因當時記憶體壓力太高而手動停止。這次紀錄是人工中止的 warmup,不是 crash,也沒有完成 benchmark 結果;不補記未完成的吞吐量數據。

E4-bit/8-bit 規格題實測與品質觀察

關閉 Thinking 的正確參數

--chat-template-config '{"enable_thinking": false}'

本組比較使用 mlx-community/Qwen3.5-9B-4bit 與 mlx-community/Qwen3.5-9B-8bit,並以相同的關閉 Thinking 參數進行生成。

三盒題

模型PromptGenerationPeak memory答案表現
4-bit294.794 t/s50.673 t/s5.353 GB正確
8-bit90.060 t/s5.942 t/s9.741 GB正確

兩者答案都正確;這組測試中 4-bit 的 Prompt 與 Generation 速度較高,Peak memory 也較低。

第一組多條件規格題

模型PromptGenerationPeak memory
4-bit343.483 t/s50.543 t/s5.468 GB
8-bit257.957 t/s28.264 t/s9.848 GB

4-bit 將「轉帳流程總時長不得超過 10 分鐘」誤解為「10 分鐘無操作」,混淆流程總時長與閒置時間;8-bit 對這項規則的理解較準。

最後複雜規格題

模型PromptGenerationPeak memory
4-bit404.394 t/s50.297 t/s5.642 GB
8-bit311.064 t/s28.221 t/s9.980 GB

4-bit 把部分明確規則誤判為衝突,例如將「超過 10 分鐘才強制結束」推演成第 6 分鐘可能衝突,並質疑登出動作是否明確;原規則已寫明門檻及登出。8-bit 則把已明確的轉帳起點(進入第一個轉帳頁面)、OTP 逾時不重置 10 分鐘總時長,以及維護模式最高優先,誤判成模糊。

修正後結論與使用建議

不能簡單說 8-bit 一定比 4-bit 更聰明或更準。較高 bit 主要降低量化誤差,不保證推理品質穩定提升;三組實測中,品質表現會依題目而變,速度與記憶體則都是 4-bit 較佳。

以本次 M4 Pro 48GB 實測,建議 4-bit 作日常主力、8-bit 作交叉驗證。高風險規格應加入第二輪規則檢核,或再做跨模型驗證。

SA 實務提醒:「不得自行新增歧義」;分析時要「逐條對照原始規則」,不可把已明確的需求自行改寫成衝突或模糊。

第九課銜接與本課總結

第九課以 llama.cpp 執行 GGUF,2B/9B GPU generation 分別記錄為 121.0/39.3 tok/s;本課以 MLX / mlx-lm 執行 MLX 4-bit 模型,對應的單次 generation 為 178.837/49.832 tok/s。這兩組紀錄可用來理解不同執行工具在這台 Apple Silicon 主機上的實際表現,但測試條件不完全相同,不是嚴格的同條件競速。

長 Context 方面,本次 MLX 9B 在 64K 下出現明顯統一記憶體與 Swap 壓力,並於 warmup 階段手動停止;第九課 llama.cpp 64K 也曾記錄約 5.95GB Swap,但兩次背景負載與測試條件不同,不應據此判定哪個框架固定更省記憶體。

目前使用建議:以這台 M4 Pro 48GB、背景服務仍有負載的使用情況,MLX 9B 日常先控制在 32K 以內;只有在確有需求且清理背景程式後,再考慮測 64K。
F小測驗
Q1|uv 安裝 mlx-lm 後,為何系統 Python 查不到 mlx-lm 套件?
答案:uv tool install 把命令列工具放在隔離環境,與系統/Homebrew Python 的套件環境分開;只要 mlx_lm.generate --help 等工具入口可正常執行,就不代表安裝失敗。
Q2|Prompt throughput 和 Generation throughput 分別代表什麼?
答案:Prompt throughput 是模型處理輸入提示的速度;Generation throughput 是逐 token 產生回答的速度。兩者應分開看,也要留意提示長度和測試條件。
Q3|9B 模型的 64K benchmark 停在 warmup,能記錄成正式效能結果嗎?
答案:不能。該次測試因記憶體壓力而手動中止,沒有完成測量;只記錄中止前的系統記憶體快照,不填入不存在的 token/s 結果。
Q4|本課數據是否能證明 8-bit 一定比 4-bit 更準?
答案:不能。三組規格題的品質表現依題目而異;這次實測中 4-bit 速度較高、峰值記憶體較低,8-bit 可作交叉驗證,不代表所有模型或任務都會如此。
G完成狀態

本課已完成 mlx-lm 安裝與 CLI 驗證、2B/9B 推論測量、Context/Swap 壓力觀察,以及 4-bit/8-bit 規格題比較。高記憶體壓力測試的人工中止狀態也已如實記錄。下一課銜接第十二課「推論加速:KV Cache 與 Prompt Cache」。

課程狀態:已完成。建議將 4-bit 作為日常起點;遇到重要規格判斷時,使用第二輪規則檢核或其他模型交叉驗證。
11

量化 Quantization:品質與效率

MLX 自行量化、GGUF Q4_K_M 與 group size 品質比較

本課以 Qwen3.5-2B 在同一台 Mac 上進行 4-bit/8-bit 與 4-bit group size 實測,記錄實際 bits per weight、模型資料夾大小、Prompt/Generation throughput、Peak memory,以及多條件規格題的回答品質。

A重點觀念|位元數、權重容量與量化開銷
FP16

每個權重以 16 bits、約 2 bytes 儲存。精度較高,權重容量需求也較大;9B 模型只計權重約需 18 GB。

8-bit

每個權重大約 1 byte。9B 權重的名目估算約 9 GB,常作為縮小模型容量與保留較多權重精度的折衷。

4-bit

每個權重大約 0.5 byte。9B 權重的名目估算約 4.5 GB;檔案與執行時記憶體不會剛好等於這個理論值。

9B 權重容量的理論估算

權重格式每個權重的名目容量9B 權重粗估
FP162 bytes約 18 GB
8-bit1 byte約 9 GB
4-bit0.5 byte約 4.5 GB

以上用十進位 GB 估算純權重容量:參數量 × 每參數位元數 ÷ 8。量化還要保存 scale、group metadata,部分張量也可能保留較高精度,因此實際平均 bits/weight 與模型檔案容量會高於名目位元數。推論時還要另外計入 KV Cache、暫存空間、執行環境和 macOS 使用的記憶體。

GGUF 的 Q4_K_M 怎麼拆解

名稱部分意義
Q44-bit 量化類別;不是保證每個參數剛好只佔 4 bits。
KK-quant 區塊量化家族,透過分組及分層縮放資訊改善低位元量化的表示。
MMedium 混合精度配置;部分重要張量使用較高精度,讓整體在容量與品質間取得折衷。

Q4_K_M 常被定位為 GGUF 的大小、品質與速度平衡點。本質上仍須依模型、量化方式、推論後端及任務實測;可參考 llama.cpp 官方量化工具文件中的 Q4_K_M 用法與 量化格式程式定義。

B指令|確認 mlx_lm.convert 量化參數

先用本機安裝版本查看 CLI 選項:

mlx_lm.convert --help
參數用途本課註記
--hf-path來源 Hugging Face 模型路徑或模型 ID。本次來源為 Qwen/Qwen3.5-2B。
--mlx-pathMLX 格式輸出資料夾路徑。輸出資料夾需尚未存在。
--quantize啟用量化轉換。短參數為 -q。
--q-group-size每組共同量化的權重數量。本課比較 32、64、128;較大 group 通常有較少的 scale/metadata 開銷。
--q-bits設定量化位元數。本課比較 4-bit 與 8-bit。
--q-mode設定量化模式。本次核對的官方主線包含 affine、mxfp4、nvfp4、mxfp8;預設為 affine。
--quant-predicate選擇混合位元量化配方。本次核對的主線選項包含 mixed_2_6、mixed_3_4、mixed_3_6、mixed_4_6;字串配方目前搭配 affine 模式。
--dtype指定未量化參數儲存的浮點型別。本次核對的選項為 float16、bfloat16、float32。
--dequantize把量化模型解量化回浮點權重。短參數為 -d,不能與 --quantize 同時使用。

mlx-lm CLI 會隨版本更新;以上 --q-mode 與 mixed-bit recipe 選項依 2026-10-05 核對的官方 convert.py 參數定義整理。實際操作仍以本機 mlx_lm.convert --help 輸出為準。

C實際紀錄|同一 Qwen3.5-2B 的 4-bit/8-bit

來源模型固定為 Qwen/Qwen3.5-2B,兩組都用 group size 64,Thinking 關閉;只改 --q-bits。轉換輸出顯示原始模型重建約 4.57 GB。

4-bit 量化指令

mlx_lm.convert \
  --hf-path Qwen/Qwen3.5-2B \
  --mlx-path ~/AI/models/Qwen3.5-2B-4bit-self \
  --quantize \
  --q-bits 4 \
  --q-group-size 64

8-bit 量化指令

mlx_lm.convert \
  --hf-path Qwen/Qwen3.5-2B \
  --mlx-path ~/AI/models/Qwen3.5-2B-8bit-self \
  --quantize \
  --q-bits 8 \
  --q-group-size 64

兩組推論使用相同的自我介紹提示「請用繁體中文簡單介紹你自己,限制100字內。」和 --chat-template-config '{"enable_thinking": false}'。

設定實際 bits/weight資料夾大小PromptGenerationPeak memory
4-bit · group 644.503約 1.0 GB224.339 t/s183.581 t/s1.200 GB
8-bit · group 648.502約 1.9 GB232.793 t/s109.950 t/s2.140 GB

公平比較條件是同一原始模型、同一 group size 64,只改 q-bits。這次 4-bit 資料夾約為 8-bit 的一半、Peak memory 也約為一半;Generation 速度較快。這是本機這次實測結果,不推論所有模型與後端都會得到相同比例。

D實際紀錄|4-bit group size 32/64/128

固定原始模型、4-bit、推論提示及 Thinking 設定,只改轉換時的 --q-group-size。

Group size實際 bits/weight資料夾大小簡單自我介紹 GenerationPeak memory
325.003約 1.1 GB169.039 t/s1.318 GB
644.503約 1.0 GB183.228 t/s1.200 GB
1284.253973 MB191.528 t/s1.138 GB

Group 越大,共用同一組 scale 的權重越多,因此 metadata 開銷通常越少,資料夾與 Peak memory 也隨之下降。本次結果同時看到 generation 速度上升;但更大的 group 也可能增加量化誤差,不能只由體積或速度判定品質。

E實際紀錄|多條件規格題品質測試

三組固定同一原始模型、4-bit、同一 prompt、temperature = 0、Thinking 關閉,只改 group size。題目要求整理登入 idle timeout、轉帳例外、10 分鐘流程總上限及超時強制結束規則。

查看本次固定使用的規格題

不要顯示思考過程,只輸出最終答案。請整理以下需求並判斷是否有衝突:1. 使用者登入後 5 分鐘內無操作要自動登出。2. 若正在進行轉帳流程,即使超過 5 分鐘也不能登出。3. 轉帳流程最長不得超過 10 分鐘。4. 超過 10 分鐘仍未完成轉帳,要強制結束流程並登出。請輸出:A. 最終規則;B. 規則優先順序;C. 是否存在衝突以及如何解決。請用繁體中文,250字內。

Groupbits/weight大小PromptGenerationPeak memory品質觀察
g325.0031.1 GB794.975 t/s20.202 t/s1.453 GB三組中最接近正確;把 10 分鐘寫成「延長至 10 分鐘」,未明確說出它是獨立的流程總時長上限。
g644.5031.0 GB372.271 t/s15.348 t/s1.331 GBA 段寫「轉帳中則自動登出」,B 段卻說轉帳中不自動登出,前後自相矛盾。
g1284.253973 MB762.216 t/s66.985 t/s1.271 GB混淆一般狀態與轉帳狀態、規則優先順序,也未正確保留 10 分鐘總時長上限;本次品質最差。

這個測試的正確解讀是:一般登入狀態套用 5 分鐘 idle logout;轉帳進行中暫不套用 5 分鐘登出;轉帳流程另有獨立的 10 分鐘總時長上限,逾時就強制結束並登出。三組輸出都值得逐條對照原需求檢查。

F結果分析與使用建議

不能用單輪 tok/s 排定 group size

簡單自我介紹一輪的 Generation 是 g32 169.039、g64 183.228、g128 191.528 t/s;換成多條件規格題後則是 20.202、15.348、66.985 t/s,波動很大。複雜 prompt、執行路徑、快取與當下系統狀態都可能影響單輪計時,因此不把單輪 tok/s 當成穩定的 group size 排名。

兩種測試都較一致的觀察是模型資料夾與 Peak memory:g32 > g64 > g128。Group 變大後,本次檔案和記憶體用量逐級降低;量化誤差和任務品質則要另外實測。

設定建議用途實務結論
g32精確規格分析、條件判斷、高風險邏輯本次規格題最接近正確;重要工作仍要第二輪規則檢核。
g64日常使用與容量/品質平衡約 1.0 GB;若只保留一個版本,建議選 g64。
g128追求體積與效率的簡單任務本次最小、記憶體最低,但規格理解最差;不建議負責重要規格判斷。
高風險工作建議:銀行規格、交易邏輯與驗收條件使用 g32,並做第二輪規則檢核;不可只因單次速度快或模型檔案小,就直接採信輸出。
本課總結:量化主要交換的是精度、模型大小、記憶體與推論速度。提高 bit 數或縮小 group size 都不保證每題推理品質穩定提升;應以相同條件實測,並對重要規則做明確檢核。
G小測驗
Q1|9B 模型用 FP16、8-bit、4-bit 粗估純權重容量各是多少?
答案:約 18 GB、9 GB、4.5 GB;實際檔案會因 scale、group metadata、未量化張量等額外成本而更大。
Q2|為什麼 4-bit 的實際 bits/weight 會高於 4?
答案:量化群組還要保存 scale 和其他 metadata,部分權重也可能使用較高精度。
Q3|這次的速度比較能證明 g128 一定比 g64 快嗎?
答案:不能。單輪 tok/s 隨 prompt 和系統狀態大幅波動;應看同條件的多次實測與品質檢核。本次較穩定的結果是 group 越大,模型和 Peak memory 越小。
H完成狀態

已完成 FP16/8-bit/4-bit 容量估算、GGUF Q4_K_M 拆解、mlx_lm.convert 參數核對、Qwen3.5-2B 4-bit/8-bit 量化、group size 效率比較及多條件規格品質測試。實測資料、限制與使用建議均已整理。

課程狀態:已完成。下一課銜接第十二課「推論加速:KV Cache 與 Prompt Cache」。
12

推論加速:KV Cache 與 Prompt Cache

快取、長上下文與推測式解碼

本課把第九課的 Context/KV Cache 記錄延伸成可重複的快取實驗。先分清楚模型權重、KV Cache 與 Prompt Cache,再用本機 llama.cpp Server 重送相同提示、比較首次與重複請求。現有記憶體與速度數據只引用先前課程;本課尚未有新的快取命中實測,因此不代填結果。

A重點觀念
KV Cache 保存已處理 token 的注意力狀態

自回歸生成時,每一層會為已處理 token 保存 Key 與 Value。生成下一個 token 時可沿用過去狀態,不必把整段歷史從頭計算;新 token 進入後,快取通常會跟著增長,直到上下文、滑動視窗或服務端限制生效。

Prompt Cache 重用重複提示前綴

伺服器把先前請求已算好的提示前綴 KV 狀態留著;後續請求若含有相同 token 前綴,就可能略過該段 prefill。這會縮短重複提示的輸入處理,不代表模型權重已載入得更快,也不會消除每次生成新答案的解碼工作。

Prefill 與逐 token 解碼是兩種速度

Prompt/prefill throughput 衡量讀入提示的速度;Generation throughput 衡量逐 token 產生答案的速度。Prompt Cache 主要可能改善前者。短提示、快取命中、快取驅逐和背景工作都會讓單輪結果波動。

KV Cache 記憶體會受模型結構與上下文影響

簡化估算同時計入 K 和 V、Transformer 層數、上下文 token、KV heads、每個 head 維度、快取資料型別與並行序列數。GQA、滑動視窗、多模態架構、分頁配置及量化 metadata 會改變實際值,因此只把公式當容量直覺,不當精確用量。

快取量化用精度換記憶體

部分推論工具可降低 KV Cache 的 K/V 儲存精度,例如使用較低 bit 的 cache type。它可能減少快取佔用,但實際支援、速度和品質影響依模型與後端而異;先確認目前安裝版本的說明,逐項比較。

推測式解碼是另一種加速方法

Draft model 先提議一小段候選 token,再由目標模型驗證。它與 KV Cache 不同,可能加速逐 token 解碼,也多使用一個模型及額外記憶體;成效取決於草稿模型、接受率、硬體與實作。

KV Cache 粗估 bytes ≈ 2 × 層數 × 快取 token 數 × KV heads × head 維度 × 每元素 bytes × 同時序列數

係數 2 代表 Key 與 Value。若每元素以 FP16/BF16 儲存,可先用 2 bytes 粗估;8-bit 約 1 byte,4-bit 約 0.5 byte,但量化分組與 metadata 會增加額外空間。真正值請以執行工具的日誌和系統快照為準。

資料安全:磁碟上的 prompt cache 可能含有由原始提示推導出的狀態;把快取檔案與提示視為敏感資料,不放入公開資料夾或版本庫,並只用非機密測試文字。
B指令|本機快取對照實驗

1. 記下版本並檢查目前支援選項

llama-server --version
llama-server --help | grep -E 'cache-prompt|cache-reuse|cache-type-k|cache-type-v'

mlx_lm.generate --help

llama.cpp 各版本選項會變動。若 help 沒列出某個選項,就不要照抄該參數;Server 文件列出的提示快取與 K/V cache type,需以本機 build 實際支援為準。MLX-LM 的 help 可查看 --kv-bits、--kv-group-size、--quantized-kv-start、--prompt-cache-file 及 speculative decoding 選項。

2. 另開本機測試 Server

沿用第九課已下載的 9B GGUF。先確認檔案存在;這個測試使用新的 8082 埠,不會取代第九課的 8081 服務。只綁定本機位址。

llama-server -m "$HOME/.lmstudio/models/lmstudio-community/Qwen3.5-9B-GGUF/Qwen3.5-9B-Q4_K_M.gguf" -ngl 999 -c 32768 -fa on --host 127.0.0.1 --port 8082 --cache-prompt

若這個版本沒有 --cache-prompt,從 help 確認提示快取是否預設開啟;不要為了測試而把服務改綁到所有網路介面。Server 的 --cache-reuse 是額外的 KV shifting 重用設定,先讀目前版本說明,再決定是否另行比較。

3. 以完全相同的提示送出兩次請求

另開終端機,先送一次,再原封不動重跑同一段請求。用繁體中文短問題,保持相同 system/user messages、模型、Context 與生成上限。觀察 Server 日誌的快取重用資訊及 prompt eval token 數/時間;不同版本的日誌文字可能不同。

curl --silent --show-error http://127.0.0.1:8082/v1/chat/completions   -H "Content-Type: application/json"   -d '{
    "messages": [
      {"role": "system", "content": "請用繁體中文、80 字內回答。"},
      {"role": "user", "content": "請用一句話說明 KV Cache。"}
    ],
    "temperature": 0,
    "max_tokens": 80
  }'

請求成功後,按向上鍵重送相同內容一次。然後觀察第二次是否重用前綴。若要比較「共同前綴 + 不同問題」,固定 system 訊息,只更改 user 文字,再觀察實際共用長度;不同 token 前綴或被驅逐的快取可能無法命中。

4. 可選:比較 KV Cache 精度

若 llama-server --help 列出以下兩個選項,可在停止測試 Server 後另起一輪,將 K 與 V 都設為 Q8;每輪只改一項,記錄記憶體、速度、品質和日誌。Q8/Q4 的字串以本機 help 列出的有效值為準。

--cache-type-k q8_0 --cache-type-v q8_0

MLX-LM 的相應功能以 mlx_lm.generate --help 顯示的選項為準。Prompt cache file 不是空白路徑即可自動建立任意共享前綴;使用時需依 MLX-LM 官方 cache API 建立或載入相容於相同模型及快取設定的狀態。

C實際紀錄|舊資料參照與本課待測表

第九課既有的 Context/記憶體實測(不是本課新測試)

Context 設定Prompt throughputGeneration throughputPhysMem 快照Swap used
4K117.6 t/s39.2 t/s44G used;9168M wired;23G compressor;3061M unused3849.44 MB
32K121.4 t/s39.2 t/s45G used;10G wired;23G compressor;1945M unused3849.44 MB
64K116.9 t/s39.2 t/s45G used;11G wired;21G compressor;2737M unused5945.25 MB

在當時那次測量,64K 的 Swap 比 32K 增加約 2095.81 MB(約 2.1 GB);不能把它當成所有模型、Context 或快取策略的固定成本。第十課另有一次 9B/64K benchmark 在 warmup 期間因記憶體壓力而手動停止,沒有完成吞吐量測量。

第十二課新實驗(待在 Mac mini 實際執行後填入)

紀錄欄位首次請求/冷快取重複請求/暖快取
日期、llama.cpp build待填待填
模型、量化、ContextQwen3.5-9B Q4_K_M · 32K(預設實驗設定)相同設定
提示 token 數/快取命中資訊待填待填
Prompt eval 時間/吞吐量待填待填
Generation t/s/輸出 token 數待填待填
PhysMem/Memory Pressure/Swap執行前後快照待填執行前後快照待填
答案品質、錯誤或限制待填待填

讀數時同時記錄 Prompt 和 Generation。每次先用 sysctl vm.swapusage 及 memory_pressure 記錄背景狀態;比較多輪並確保模型、提示、輸出上限與當時背景負載相同。

D如何解讀結果
觀察到的現象合理解讀
暖快取 Prompt eval 時間下降可能重用了共同提示前綴;看伺服器快取日誌/token 數確認,重複跑至少數輪。
Generation t/s 接近符合 Prompt Cache 主要省下 prefill 的預期;新答案仍須逐 token 生成。
暖快取沒有改善可能前綴不相同、快取未啟用、請求落到不同 slot、快取被驅逐,或提示短到不易測出差異。
更大 Context 的記憶體上升可能容量配置或實際 KV 長度增加;依框架實作與 token 數確認,不從 context 上限直接推算實際 RSS。
Q8 KV Cache 記憶體較少若後端支持且實測確實下降,可作記憶體/品質/吞吐量的折衷選擇;不可假定每個模型或後端都會更快。
實驗公平性:快取命中、模型首次載入、提示 token 數、slot、Context、生成長度、後台程式與 Swap 都可能改變讀數。一次冷暖對照只能做初步觀察,不代表該配置的固定速度。
E小測驗
Q1|KV Cache 和 Prompt Cache 是相同的東西嗎?
答案:不是。KV Cache 保存模型已處理 token 的注意力狀態;Prompt Cache 是推論服務重用先前提示前綴 KV 狀態的一種做法。
Q2|Prompt Cache 命中後,為什麼答案生成時間還在?
答案:它主要省略重複前綴的 prefill;模型仍要逐 token 生成新的回覆。
Q3|為什麼 Context 上限與模型層數不夠精確算出 Mac 的實際快取用量?
答案:還需知道 KV heads、head 維度、dtype、同時序列數及框架配置;GQA、滑動視窗、量化與背景負載也會改變實際數值。
Q4|mlx_lm.generate 的 64K benchmark 在 warmup 被中止,可以填入 64K token/s 嗎?
答案:不能。第十課只有記錄人工中止與當時記憶體壓力,未完成 benchmark 就沒有可填的速度結果。
Q5|Prompt Cache 命中後能否把含私人提示的 cache file 公開分享?
答案:不應該。快取由提示內容衍生而來,應按敏感資料保管,只用非機密提示做練習。
F完成狀態

本課知識內容、指令範例、既有 Context 實測參照與待填記錄表已補齊。要完成整課,請在 M4 Pro 上跑完首次與重複提示對照,記下 llama.cpp build、快取重用跡象、Prompt/Generation 速度與記憶體/Swap;在此之前維持未勾選,不把舊課數據當成第十二課新實驗。

課程狀態:內容已補齊,實測待完成。下一課為第十三課「效能比較與工具選擇」。
13

效能比較與工具選擇

公平測試 Ollama、LM Studio、llama.cpp 與 MLX

本課整理前幾課的本機推論數據,學會分開比較模型載入、提示處理、逐 token 生成、整體延遲與記憶體壓力。先用 llama.cpp/MLX 的 benchmark 了解引擎表現,再用相同提示的 API 請求比較實際工作流程。先前數字的模型、提示長度和測量方法不同,只作歷史參照,不當作同條件排名。

A重點觀念
先問「正在比較哪個部分?」

模型載入時間、Prompt prefill、逐 token generation、第一個 token 延遲(TTFT)、完整回覆時間及記憶體用量,是不同指標。單看 generation tok/s 無法代表啟動等待、長提示或實際互動體驗。

微基準與完整請求回答不同問題

llama-bench 可分別測提示處理、生成及兩者組合,並重複執行、輸出平均值與標準差;官方說明指出其測量不含 tokenization 和 sampling。API 對照則較接近使用者流程,會受模板、請求傳輸與 server 設定影響。

要公平比較,固定輸入與執行條件

固定模型與權重版本、量化、提示文字、輸入 token 數、輸出上限、Context、temperature、批次/並行數、KV/Prompt Cache 狀態,以及是否計入模型載入。工具無法使用相同權重檔時,標明版本及差異。

權重差異會混入工具差異

GGUF 與 MLX 量化模型可能來自不同轉換或量化流程;即使名稱相似,也不能假設權重完全相同。比較同一執行器時,盡量使用相同模型檔;比較跨工具的實際使用方案時,將結論標成整體工作流程比較。

平均速度要和波動一起看

先暖機,再做多輪;報平均值與標準差,或中位數與範圍。第一次載入另列「冷啟動」,不要與模型已在記憶體的「暖請求」混在同一個 tok/s 數字裡。

Mac 的記憶體與背景負載也要記錄

Apple Silicon 的模型權重、KV Cache、macOS 和其他 App 共用統一記憶體。比較前後記下 Memory Pressure、壓縮記憶體及 Swap;切換工具前卸載上一個模型,避免把前一輪殘留的資源算到下一輪。

B指令|建立可重複的比較

1. 記錄本機工具版本與系統基線

llama-cli --version
llama-bench --help
mlx_lm.benchmark --help
ollama --version
lms --help
memory_pressure
sysctl vm.swapusage

CLI 選項會隨版本變化,先以各工具的 help 為準。開始前關閉或卸載不參與本輪的模型;每輪記錄日期、工具版本、模型檔案與量化、Context、後台 App 狀態及記憶體/Swap 基線。

2. 用 llama-bench 測 9B GGUF 的提示處理與生成

沿用第九課已下載的 Qwen3.5-9B Q4_K_M GGUF。這個例子固定 512 個提示 token、128 個生成 token、GPU offload 與 Flash Attention,重複 5 次並以 JSON 輸出。先確認該版本的 llama-bench --help 支援這些參數。

llama-bench -m "$HOME/.lmstudio/models/lmstudio-community/Qwen3.5-9B-GGUF/Qwen3.5-9B-Q4_K_M.gguf" -p 512 -n 128 -r 5 -ngl 999 -fa on -o json

將 Prompt processing 與 text generation 分開記錄;這個微基準不含 tokenization 和 sampling 的時間。若要看特定 Context 深度,先依 help 確認 -d 的意義與支援,再固定該參數。

3. 用 mlx-lm 固定 token 長度重複測量

mlx_lm.benchmark \
  --model mlx-community/Qwen3.5-9B-4bit \
  --prompt-tokens 512 \
  --generation-tokens 128 \
  --num-trials 5

這是 mlx-lm 的本機 benchmark 入口。兩種 benchmark 的提示構造與計時邊界可能不同,因此不要只把輸出的 t/s 並排就宣布勝負;同時做下一步的固定提示 API 實測,確認實際使用體感。

4. 用 Ollama API 查看完整請求時序

將 model 改成 ollama list 顯示的本機模型標籤,使用同一個請求重複多次。關閉串流以便取得單一 JSON 結果;回應會提供模型載入、Prompt evaluation 與 generation 的計時欄位。

ollama list

curl --silent --show-error http://127.0.0.1:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "替換成 ollama list 顯示的模型標籤",
    "messages": [
      {"role": "user", "content": "請用繁體中文,簡短說明什麼是本機語言模型。"}
    ],
    "stream": false,
    "keep_alive": "5m",
    "options": {"temperature": 0, "num_predict": 128}
  }'

回應中的 load_duration、prompt_eval_count、prompt_eval_cached_count、prompt_eval_duration、eval_count、eval_duration 與 total_duration 可協助分辨載入、快取提示及生成時間。時間欄位以奈秒表示;計算 tok/s 時使用 token 數 ÷ 秒數,勿把冷載入時間誤當成純解碼時間。

5. 預估 LM Studio 記憶體,再載入模型

lms ls
lms load --estimate-only "替換成 lms ls 顯示的 model key" --context-length 32768

--estimate-only 可在載入前查看資源估算;它是估算值,不是實際 Peak Memory。要實測時再以相同 Context 載入模型,記下實際 Memory Pressure 與 Swap。

C實際紀錄|前課資料參照與第十三課待測表

第九、十課既有數據(測量條件不完全相同)

來源/模型Prompt 輸入與速度Generation 輸出與速度Peak memory
第九課 · llama.cpp · 2B Q4_K_M · GPU offload144.3 t/s;該對照沒有記下可直接對齊的 prompt token 數121.0 t/s;不同提示長度該次對照未記錄
第九課 · llama.cpp · 9B Q4_K_M · GPU offload148.6 t/s;該對照沒有記下可直接對齊的 prompt token 數39.3 t/s;不同提示長度該次對照未記錄
第九課 · llama-server · 9B · Context 32K18 tokens · 86.709 t/s214 tokens · 39.375 t/s未記錄 API 峰值
第十課 · mlx-lm · 2B 4-bit23 tokens · 23.938 t/s200 tokens · 178.837 t/s1.190 GB
第十課 · mlx-lm · 9B 4-bit28 tokens · 106.100 t/s250 tokens · 49.832 t/s5.244 GB

這些紀錄的 prompt 長度、輸出 token 數、介面及計時方式不同,無法用來判定 llama.cpp 或 MLX 誰整體較快。第九課的 9B 64K Context 曾記錄 Swap used 5945.25 MB(32K 時為 3849.44 MB);第十課的 MLX 9B 64K benchmark 則在記憶體壓力下於 warmup 手動中止,沒有完成吞吐量測量。

第十三課同條件比較(完成實測後填寫)

固定項目/紀錄欄位llama.cppMLXOllama 或 LM Studio
日期、工具版本、執行模式待填待填待填
模型 repo/檔案、revision、量化待填待填待填
Context、輸入 token、輸出上限、temperature512/128,0(預設比較條件)512/128,0(預設比較條件)512/128,0(預設比較條件)
冷載入時間、暖機輪數待填待填待填
Prompt t/s/TTFT;是否含快取待填待填待填
Generation t/s;平均值與波動5 輪待填5 輪待填5 輪待填
完整回覆時間、輸出 token、答案品質待填待填待填
Memory Pressure、PhysMem、Swap 前後值待填待填待填

若同一模型版本無法在三種工具中以完全相同的權重與量化執行,請把實驗標示為「日常工作流程比較」,記錄各自的模型檔案,避免說成單純的引擎速度對決。

D比較流程與工具選擇
  1. 先定義任務:聊天、長提示摘要、程式碼或批次請求;答案品質和延遲門檻先寫清楚。
  2. 準備基線:確認硬體、系統、工具與模型版本,記憶體壓力平穩;每輪只執行一個推論服務。
  3. 固定請求:相同提示、chat template、上下文上限、最大輸出 token、sampling 與快取狀態。不可用 23-token prompt 的一次數據對比 512-token benchmark。
  4. 區分冷、暖兩種結果:冷啟動單獨記錄載入;暖機後重複至少 5 輪,記錄每輪或平均與離散程度。
  5. 同時看資源和答案:記錄 tok/s、TTFT、完整時間、Memory Pressure、Swap,以及答案是否遵守固定規格。
工具適合先試的工作比較時要記得
Ollama快速下載、命令列對話與本機 API用 API 的載入、Prompt 與 Generation 欄位拆開計時;固定 keep-alive 與快取狀態。
LM Studio圖形介面管理模型、載入設定及本機服務先用 resource estimate 做容量預判,再記下 Context、GPU offload、Flash Attention 等實際設定。
llama.cppGGUF、Metal offload、細部參數與可重複 microbenchmarkllama-bench 測量範圍不含 tokenization/sampling;另以 API 或真實提示測端到端延遲。
MLX / mlx-lmApple Silicon 上原生執行、MLX 模型與相關研究/轉換流程模型轉換、量化版本和 benchmark 方法會影響比較;確認輸入 token 數及測量邊界。
M4 Pro 48GB 的選擇方法:先挑能載入目標模型、維持可接受 Memory Pressure/Swap、答案品質符合任務的工具;再比較暖機速度、延遲、吞吐量與操作便利性。高峰 tok/s 只有在條件和品質相同時才有比較價值。
E小測驗
Q1|前課資料中,MLX 9B 的 generation t/s 高於 llama.cpp 9B,能證明 MLX 一定更快嗎?
答案:不能。模型量化、提示/輸出 token 數、計時方式及版本不同;必須同條件重複測量。
Q2|為什麼要分開記錄 Prompt throughput、Generation throughput 與冷載入時間?
答案:它們分別反映輸入處理、逐 token 解碼及模型載入階段,瓶頸與使用者感受不同。
Q3|llama-bench 的 tok/s 是否包含 tokenization 和 sampling 時間?
答案:官方文件指出不包含;要評估完整互動流程,還需跑固定提示的 API/實際任務測試。
Q4|LM Studio 顯示的記憶體 estimate 可以當作實際 Peak Memory 嗎?
答案:不行。它是載入前的資源估算;實際用量需在相同 Context 和模型設定下載入,查看 macOS 記憶體與 Swap。
Q5|跨工具無法使用完全相同的權重檔時,如何表述結果?
答案:列出模型 repo/檔案、revision 與量化差異,稱為實際工作流程比較,不把差異歸因於執行引擎本身。
F完成狀態

本課已補上 benchmark 概念、Ollama API 計時欄位、llama.cpp/MLX 測量指令、LM Studio 記憶體估算,以及前課數據的限制說明。要勾選完成,請在 Mac mini 上用固定條件跑完至少兩個工具的五輪比較,填入模型與版本、Prompt/Generation、冷暖載入、Memory Pressure/Swap 和答案品質;沒有新實測前保持未勾選。

課程狀態:內容已補齊,跨工具實測待完成。下一課為第十四課「圖像與影片生成」。
NEXT STEPS · 14—25

後續課程預留區

第十四課的圖像與影片生成均已完成;原有語音實作紀錄已歸回第十五課。第十六至第二十五課維持原有目錄名稱與位置,第十二、十三課仍待固定條件的跨工具實測。

14

圖像與影片生成

圖像與影片生成完成|報告版驗收通過

本堂先完成 Qwen-Image 2.1 的圖像生成與圖片編輯,再建立獨立的 ComfyUI + MiniMax H3 環境,完成中文對話、聲音、嘴型同步、分段影片生成、Parasyte Turbo LoRA 對比、角色連貫性修正與報告版驗收。

A14-1 目標與本機工具

目標是在 Apple Silicon 上以 MLX 執行 Qwen-Image 2.1,完成文字生圖、圖片編輯與多參考圖測試,並記錄速度、記憶體和 Swap 的實際變化。

實驗平台

Mac mini M4 Pro,48GB 統一記憶體;Apple Silicon/MLX 本機推論。

模型與環境

Qwen-Image 2.1;Python 3.12.14、mlx-vlm==0.7.4、mlx==0.32.3、mlx-metal==0.32.3。

本機 4-bit 權重

~/AI/models/Qwen-Image-2.1-MLX-4bit,約 9.8GB。

專案位置

~/AI/projects/qwen-image-2.1-mlx/

最終採用本機 MLX 4-bit 權重搭配 mlx-vlm 專用 Qwen-Image pipeline,避免推論時再抓取原始大模型。
B14-2 路線選擇與踩坑

曾先嘗試 stock mflux。它會重新下載 Qwen/Qwen-Image-2.1 原始約 33GB 權重,與已準備好的本機 MLX 4-bit 模型不同;發現後中止下載,並清掉約 6.4GB cache。最後改走 mlx-vlm 專用 Qwen-Image pipeline,直接載入本機量化權重,沒有再下載原始大模型。

踩坑結論:選工具前先確認它實際支援的模型格式與載入路徑。工具名稱支援 Apple Silicon,不代表它會自動使用手上已有的 MLX 量化權重。
C14-3 Text-to-Image 基準測試

以 512×512、8 steps、seed 42、guidance 1.0 建立低解析度基準。先量到 Muliao 常駐時的記憶體壓力;檢查發現兩個 MLX worker 約使用 19GB 與 5.9GB。再暫停這兩個 worker,在乾淨環境用相同條件重跑;另以 768×768、16 steps 觀察品質設定提高後的成本。

設定/環境模型載入生成+儲存總時間Runtime peakMLX peakSwap結果
512×512
8 steps
seed 42/guidance 1.0
Muliao 常駐
0.185 秒26.687 秒26.871 秒約 9.27GB約 13.59GiB約 353MB → 13.8GB成功生成;背景服務造成明顯記憶體/Swap 壓力。
512×512
8 steps
seed 42/guidance 1.0
暫停 Muliao
0.182 秒22.491 秒22.673 秒9.272GB13.592GiB2355.50MB → 2355.50MBSwap 未增加;相較常駐時生成+儲存快約 15.7%。
768×768
16 steps
seed 42/guidance 1.0
0.182 秒96.588 秒(4.29×)96.771 秒(4.27×)9.324GB18.196GiB(+33.9%)2295.25M → 4037.88M(+約 1.70GiB)約 6.037 秒/step;安全監控在收尾時觸發,但 PNG 已成功輸出。
基準結論:512×512/8 steps 是穩定、低風險的起始設定。768×768/16 steps 能完成,但已進入高記憶體壓力區;不建議直接跳到 1024×1024/30 steps。
D14-4 Image-to-Image 圖片編輯
實驗設定模型載入生成+儲存總時間MLX peakRuntime peakSwap 增量
單物件修改:綠色植物 → 紅花玻璃花瓶512×512、4 steps、guidance 1.0、seed 420.184 秒16.384 秒17.511 秒14.370GiB約 10.935GB+1.318GiB
夜間氛圍:白天辦公室 → 暖琥珀色夜景512×512、4 steps0.185 秒16.123 秒17.241 秒14.370GiB10.951GB+0.569GiB
單物件修改觀察

紅花玻璃花瓶成功生成;筆電、桌面、光線與背景大致保留。

夜景修改觀察

構圖、筆電、桌面與主要物件位置大致保留,場景轉為暖琥珀色夜間氛圍。

E14-5 多參考圖融合:14-5-3 因 Swap 保護中止

以原始辦公室圖和紅花花瓶版本進行多圖融合。當輪設定 Swap 相對基線增加超過 1GiB 即中止;保護條件觸發後停止推論,沒有產生輸出圖,因此這輪不算完成的融合結果。

項目紀錄
中止原因Swap 相對基線增加觸發 1GiB 保護門檻。
輸出未產生融合圖;標記為「因 Swap 保護中止」,不是成功結果。
中止後 Swap約 4.83GiB → 4.45GiB。
若日後另開一輪:把 reference processing resolution 降到 384,輸出仍維持 512×512,並保留 1GiB Swap 增量中止門檻。這是新的低記憶體設定,細節可能較少,不能視為原測試重跑。
F安全方法與圖像觀察
安全中止

多參考圖實驗監看 Swap 相對增量,超過 1GiB 即停止。中止後若 Mac 操作正常,不需手動清 Swap;若仍明顯卡頓,先等「活動監視器」記憶體壓力回到綠色,再做其他 MLX 工作。

公平比較

Benchmark 固定 prompt、seed、steps 與 guidance;同時記錄載入、生成、儲存和結束時的記憶體狀態。

看整體記憶體

macOS 顯示的 free RAM 不等於可安全使用的空間;一起觀察 PhysMem、compressed、Swap 與 Memory Pressure。

預設設定判斷

模型「能跑」不代表適合日常預設;應同時考慮等待時間、峰值記憶體、Swap 與其他常駐工作。

Qwen-Image 2.1 的編輯結果偏向保持語意與構圖一致,不保證未要求修改的區域像素級完全不動。夜景修改會重新理解整體光照關係,而非只把畫面均勻染暗。
V14-B 影片生成完整流程

圖像部分完成後,影片實作以 Mac mini M4 Pro 48GB 為平台,分成 14-B-1 至 14-B-5。每一步都先保留可回復的輸出,再進入下一輪,避免把一次長片生成當成唯一結果。

14-B-1|獨立環境

建立 ~/AI/ComfyUI-H3/ 與隔離 venv;ComfyUI v0.39.0、Python 3.12.14、PyTorch 2.14.0,MPS 最小 tensor 測試通過。

14-B-2|H3 工作流

準備 MiniMax H3 的 GGUF/Apple Silicon 相容節點、影片 VAE、音訊 VAE 與文字編碼器;使用獨立的模型與輸出路徑。

14-B-3|短片與對話

先用短片驗證兩位角色、中文對白、聲音與嘴型同步;採用一個鏡頭一次一位角色開口,降低嘴型套錯與聲音混用。

14-B-4|LoRA 對比

以相同場景比較 base 與 Parasyte Turbo LoRA;LoRA 版本保留作質感 A/B 參考,報告版採用角色較穩定、光線較乾淨的設定。

階段做法結果與決策
短片測試先驗證對白、音訊、嘴型和場景對話可用;多人同時說話不穩,改用分鏡輪流開口。
問題觀察檢查黃色圓點、橘紅色光斑、角色漂移問題版本保留作比較,不直接作報告輸出。
15 秒生成拆成約 5 秒片段;固定 seed 77002;768×1376、24 fps每段可獨立重做,降低長片段的角色重置。
連貫性修正Motion Context 接續前段尾端約 22 個影格,檢查臉部、髮型、服裝、座位與背景移除不穩定或含明顯光斑的影格,再合成 ContinuityFix。
報告版輸出保留 H.264/AAC 原檔並做解碼與時間軸驗收得到 14.833 秒、356 frames 的基準影片。
核心學習:先確認環境,再用短片驗證聲音與嘴型;接著用固定種子和分段生成控制角色連貫性,最後才提高畫面尺寸、整理剪接並做驗收。
W14-B-5 報告版驗收
驗收項目結果紀錄
交付影片通過/Users/skbank/AI/ComfyUI-H3/output/video/H3_Office_15sec_ContinuityFix_768x1376.mp4
畫面規格通過768×1376、24 fps、H.264 High、356 frames、14.833333 秒。
聲音規格通過AAC-LC、32 kHz、立體聲、14.833344 秒;與影片長度差約 11 微秒。
播放完整性通過影片與音訊 ffmpeg 解碼通過;PTS 單調遞增;沒有 0.5 秒以上黑畫面或 1 秒以上凍結。
角色連貫性通過抽查 0.5、4.5、8.5、12.5、14.4 秒;臉部、髮型、服裝、座位與背景可辨識且穩定。

完整驗收紀錄:/Users/skbank/Documents/Codex/2026-10-08/referenced-chatgpt-conversation-this-is-an/14-B-5_報告版驗收與紀錄.md。抽查畫面與影片原檔保留在本機,方便之後報告或重做時比對。

本版允許自然的手勢、眼神與嘴型變化;驗收標準是角色可辨識、服裝與場景穩定、剪接可接受,不要求逐影格像素完全相同。
G第十四堂進度
圖像生成

完成|文字生圖、單物件編輯、夜間氛圍修改與多參考融合限制均已整理;14-5-3 的中止不列為成功成果。

影片生成

完成|MiniMax H3 環境、短片對話、LoRA 對比、15 秒分段生成、角色連貫性修正與報告版驗收均已記錄。

第十四堂整體:已完成。圖像與影片兩條實作路線均已完成,報告版影片與完整過程紀錄已保存。
15

音訊、語音與音樂 AI

實作紀錄:音訊基礎、Whisper STT、TTS/Voice Cloning 與即時語音助理

第十五堂「音訊、語音與音樂 AI」整理已完成的音訊基礎、語音辨識、語音合成、Voice Cloning、即時語音助理與端到端延遲優化紀錄。

A15-1 音訊基礎與 ffmpeg

音訊檔案承載的是取樣後的波形。語音模型通常不直接把檔案位元組當作文字,而是先把波形轉成頻譜等特徵,再交給模型;語音合成則由文字與說話者條件產生新的音訊波形。

工具版本

實測使用 ffmpeg 9.0.2。

常用輸入規格

16 kHz、單聲道(mono);WAV 可保留未壓縮 PCM,MP3 則以有損壓縮減少檔案大小。

測試訊號

產生 5 秒、440 Hz 的正弦波,確認合成、取樣率和檔案輸出流程。

檔案大小觀察

同一段測試音的 WAV 約 156K,MP3 約 15K;大小差異來自編碼方式。

格式/測試設定實測觀察
WAV16 kHz、mono、PCM約 156K;適合保留原始取樣資料供模型輸入。
MP316 kHz、mono約 15K;檔案較小,但經有損壓縮。
440 Hz 測試音5 秒、16 kHz、mono用固定頻率訊號檢查 ffmpeg 音訊產生與轉檔。

可重做的基本指令

ffmpeg -version
ffmpeg -f lavfi -i "sine=frequency=440:duration=5:sample_rate=16000" -ac 1 -c:a pcm_s16le tone_440hz_16k_mono.wav
ffmpeg -i tone_440hz_16k_mono.wav -ar 16000 -ac 1 -c:a libmp3lame -q:a 2 tone_440hz_16k_mono.mp3
ffmpeg -i input_audio.wav -ar 16000 -ac 1 -c:a pcm_s16le speech_16k_mono.wav
概念鏈:音訊波形 → 頻譜/模型特徵 → STT 或 TTS 模型。取樣率、聲道數與音量會影響前處理;轉檔前先確認來源格式,避免不必要的重採樣或音量失真。
B15-2 Whisper STT

使用 mlx-whisper 在同一段 60 秒測試音訊上比較 Tiny、Small 與 Medium。CER(Character Error Rate,字元錯誤率)越低,代表逐字稿與參考文字的字元差異越少。

模型60 秒音訊處理時間CER觀察
Tiny5.121 秒61.72%速度最快,但錯字較多。
Small5.907 秒35.89%速度與辨識品質最均衡,是目前的 sweet spot。
Medium7.542 秒36.84%比 Small 慢,這次測試的 CER 也沒有更好。
辨識觀察:測試中「值日生」沒有被正確辨識。Small 在這組測試取得最低 CER;仍要用實際音訊、口音與噪音條件評估,不能只依模型尺寸推定品質。
C15-3 TTS/Voice Cloning
CustomVoice

Qwen3-TTS 0.6B CustomVoice 8-bit,選用 Vivian 聲音;第二次 TTS 生成耗時 3.980 秒,輸出音訊長 6.24 秒。

即時因子 RTF

3.980 ÷ 6.24 ≈ 0.64。低於 1 代表生成速度快於輸出音訊的播放速度。

Voice Cloning

Qwen3-TTS 0.6B Base、bf16;使用 15 秒、24 kHz、mono 參考音與 ref_text,成功完成克隆。使用者主觀評價為「很像」。

參考音整理

參考音已移至 ~/AI/datasets/audio/,集中保存後續實驗會用到的音訊資料。

參考音長度測試

參考音長度該次執行耗時判讀
5 秒111.190 秒首次執行包含 warm-up,不代表穩態生成時間。
10 秒0.831 秒成功完成生成。
15 秒1.246 秒成功完成生成。
品質比較限制:ref_text 與參考音內容沒有完整對齊,因此這組 5/10/15 秒測試不能用來做嚴格的聲音品質比較;5 秒的首次執行也受 warm-up 影響。
D15-4 即時語音助理
錄音來源

AirPods Pro 經 AVFoundation 裝置 :0 輸入;擷取格式為原生 24 kHz mono。

音量檢查

ffmpeg volumedetect 讀值:mean -55.4 dB、max -30.3 dB;後續錄音增加 +15 dB,再轉為 16 kHz mono。

語音處理流程

AirPods Pro/AVFoundation :0
  → +15 dB、轉 16 kHz mono
  → Whisper STT
  → LM Studio Native API(/api/v1/chat,reasoning: "off")
  → Qwen3-TTS
  → afplay 播放

LM Studio Native API 實測

項目結果
API/api/v1/chat,設定 reasoning: "off"
Reasoning 輸出 token0
生成速度117.4 tok/s
TTFT0.112 秒
LLM 處理時間0.275 秒

一次完整語音往返

錄音STTLLMTTS總流程
5.236 秒1.207 秒0.275 秒4.137 秒19.566 秒
流程維持錄音 → Whisper → LM Studio Native API(reasoning off)→ Qwen3-TTS → afplay。常駐版播放後按 Enter 開始下一輪,按 Ctrl+C 結束。
E15-4-6 延遲 Benchmark 與優化

先跑三輪原始流程作為流程級基線。錄音提示雖相同,Whisper 的逐字稿和回答長度並不一致,因此這不是固定語句、固定輸出長度的嚴格 benchmark。

輪次錄音STTLLMTTSAI 處理可播放前播放完整流程
15.2831.3750.3755.0296.77912.06314.62726.691
25.2762.1850.6726.3429.19914.47520.19034.666
35.2681.2840.2453.1054.6359.9036.76116.664
平均5.2761.6150.4314.8256.87112.14713.85926.007

單位:秒。AI 處理=STT+LLM+TTS;可播放前=錄音+AI 處理;完整流程另含音訊播放。

基線限制:第一、三輪逐字稿辨識為「字幕by索兰娅」,第二輪則辨識到一段重複對話。回答內容長度不同,會連帶影響 TTS 與播放時間,基線只能用來看整體流程量級,不能當成固定語句對照。

Qwen3-TTS 常駐化結果

將 Vivian 模型改為程式啟動時載入一次,之後每輪重用。模型啟動至就緒耗時 2.465 秒,屬一次性成本。

常駐版輪次TTS可播放前完整流程比較說明
第 1 輪2.777 秒10.006 秒21.562 秒相較基線平均,TTS 少 42.4%、可播放前少 17.6%、完整流程少 17.1%。
第 2 輪0.637 秒7.286 秒10.922 秒回答較短,不可直接與基線平均作等長內容比較;用來確認模型可重複生成。
瓶頸判讀

reasoning off 後,LLM 約 0.3~0.4 秒,已不是主要延遲來源。固定錄音 5 秒本身就是一段等待時間。

有效優化

讓 TTS 模型常駐可避免每輪重載;第一輪與基線平均的 TTS、可播放前與完整流程都有改善。

下一步:若要提升即時感,優先實作 VAD/偵測說完即停錄,並評估 streaming TTS,減少固定錄音等待與等待完整音檔生成的時間。
F15-4-7 延遲數據判讀與下一輪實驗

下面的比例是依本課三輪基線平均值計算的資料推算,不是新增的 Mac 實測。它能幫助安排優化優先順序,但三輪且每輪辨識內容不同,仍不足以證明某一項改動一定造成同樣幅度的改善。

TTS 是 AI 處理主要耗時

平均 4.825 秒 ÷ AI 處理 6.871 秒 ≈ 70.2%。在這組流程中,先減少 TTS 等待比再縮短已約 0.431 秒的 LLM 階段更有機會改善體感。

LLM 約占 AI 處理 6.3%

平均 0.431 秒 ÷ 6.871 秒 ≈ 6.3%。這和 Native API 的 0.112 秒 LLM TTFT 是兩個不同指標;兩者都不等於第一段語音的等待時間。

錄音是播放前等待的一部分

平均錄音 5.276 秒 ÷ 可播放前 12.147 秒 ≈ 43.4%。VAD 可望避免固定錄滿 5 秒,但需要校準停頓門檻,避免把句中停頓誤判成說完。

把時間戳記分清楚

時間點事件適合回答的問題
T0開始收音整段互動從何時開始?
T1VAD 判定使用者說完停止收音本身等了多久?
T2STT 得到最終逐字稿說完到文字辨識完成花多久?
T3LLM 第一個文字 tokenLLM TTFT 是多少?
T4第一段 TTS 音訊可播放說完到聽到回覆的延遲(T4 − T1)是多少?
T5整段回覆播放完畢說完到整個回合結束花多久?
不要混用 TTFT 和第一段語音延遲:本課記錄的 0.112 秒是 LM Studio LLM TTFT;目前非串流流程會等到 TTS 音檔生成完成才播放,因此需要額外量 T4,才能知道使用者何時真正聽到第一個音訊樣本。原三輪基線未記錄 T1、T3、T4 的精確時間戳,不能事後推算這些值。

實作順序:先 VAD,再串流 TTS

  1. 固定輸入:先用同一段錄音與同一個 LLM 回答文字測流程,將辨識品質變因排除;之後再用即時麥克風測 VAD。
  2. 加入 VAD 停止錄音:目前 AirPods 擷取為 24 kHz mono;若採用 Silero VAD 的 16 kHz 路徑,先轉成 16 kHz mono。將靜音結束等待時間與語音前後保留(padding)當作可調參數。Silero 文件中的 100 ms 靜音及 30 ms padding 是程式預設值,只適合作為起始測試值,需用自己的停頓、噪音與口音調整。
  3. 再處理 TTS 串流:把 LLM 產生的完整回答分成自然語句,逐段交給 TTS,收到可播放的 PCM/音訊片段就開始播放,同時生成後續片段。逐句生成後再合併不一定是真正串流,請確認模型介面確實能在合成尚未結束時持續輸出片段。
  4. 量測並聽品質:每種設定用相同輸入至少跑 5 輪;記錄中位數與每輪結果,另確認是否截斷句尾、漏掉第一個字、句間停頓不自然或音質破碎。不同回答長度不能直接當作公平比較。

Qwen3-TTS 官方專案目前說明其模型支援串流與非串流生成;這不代表本機已安裝的套件版本或目前使用的後端一定暴露相同串流介面,動手改程式前先確認實際版本與呼叫 API。VAD 的靜音等待與 padding 定義可參考 Silero VAD 原始碼文件。

設定/輪次說完→逐字稿完成LLM TTFT說完→第一段語音整段回覆播放完辨識/語音品質觀察
固定 WAV 基線 · 1待量待量待量待量固定逐字稿與回答
VAD · 1待量待量待量待量檢查句中停頓與句尾有無截斷
VAD + 串流 TTS · 1待量待量待量待量檢查首段音訊、段落銜接與漏字

資料狀態:上表是下一輪實測表,空格代表尚未測量,不是零秒。建議每種設定至少 5 輪,再比較中位數;目前舊基線只有 3 輪,且內容不一致。

本機優化順序:先確認錄音音量與逐字稿穩定 → 量到 VAD 結束點 → 讓 TTS 常駐 → 實作真正的首段音訊串流 → 用相同素材比較首段語音延遲與品質。這樣每次只改一個主要因素,才看得出改善來自哪裡。

延伸資料:Qwen3-TTS 官方專案與串流說明 · Silero VAD 靜音門檻與語音 padding 參數

G小測驗
為什麼三輪基線不能當成嚴格的固定語句 benchmark?
答案:Whisper 的逐字稿及回答長度不同,TTS 和播放時間因此也不同。
常駐 TTS 的第一輪改善,主要說明了什麼?
答案:避免每輪重新載入 TTS 模型能降低延遲;啟動時的 2.465 秒模型載入成本只付一次。
若要減少固定 5 秒錄音的等待,接下來可嘗試什麼?
答案:以 VAD 偵測說話結束並停止錄音,再評估 streaming TTS。
基線裡 LLM 約占 AI 處理時間 6.3%,下一步最值得優先觀察哪個階段?
答案:先看 TTS;它約占本次 AI 處理平均時間的 70.2%。這是依三輪不同內容資料算出的優先順序線索,不是因果證明。
0.112 秒的 LLM TTFT,能不能代表使用者 0.112 秒後就聽到語音?
答案:不能。它只量到 LLM 第一個文字 token;還要量 TTS 第一段音訊可播放時間,才能算說完到第一段語音的延遲。
H完成狀態
第十五堂已完成。音訊基礎、mlx-whisper、Qwen3-TTS CustomVoice/Voice Cloning、即時語音助理與常駐 TTS 延遲優化均已實際操作。本次新增的是既有三輪數據的比例推算與下一輪實驗設計,沒有新增實測;VAD 停錄與串流 TTS 的驗證留待後續操作。
16

視覺語言模型:理解圖像與影片

圖片 token、mlx-vlm 與多模態服務

課程預留|讓模型讀取圖片或影片,並觀察多模態輸入帶來的額外需求。

重點觀念

待課程完成後補入。

指令

待實作後補入可複製指令。

實際紀錄

預留模型、素材與回覆準確度。

小測驗

待課程完成後補入。

17

RAG 文件問答與知識庫

文件切塊、Embedding、檢索與回答生成

課程預留|以自己的文件建置有來源依據的本機問答流程。

重點觀念

待課程完成後補入。

指令

待實作後補入可複製指令。

實際紀錄

預留文件集、Embedding 與檢索結果。

小測驗

待課程完成後補入。

18

AI Agent 與本機模型

工具呼叫、MCP、相容 API 與沙箱概念

課程預留|了解 Agent 的任務流程、地端模型限制與安全執行環境。

重點觀念

待課程完成後補入。

指令

待實作後補入可複製指令。

實際紀錄

預留工具、模型與任務執行結果。

小測驗

待課程完成後補入。

19

編輯器整合與 Vibe Coding

在開發工具中連接本機模型並完成小型實作

課程預留|比較程式開發模型,建立可驗證的本機協作流程。

重點觀念

待課程完成後補入。

指令

待實作後補入可複製指令。

實際紀錄

預留編輯器、端點與程式任務結果。

小測驗

待課程完成後補入。

20

Apple Foundation Models

系統模型、Swift 呼叫與 Core ML/ANE/MLX 分工

課程預留|依照支援機型和系統版本,整理 Apple 系統模型的使用方式。

重點觀念

待課程完成後補入。

指令

待實作後補入程式範例。

實際紀錄

預留裝置、系統版本與 API 結果。

小測驗

待課程完成後補入。

21

多台 Mac 推論叢集

Thunderbolt、MLX 分散式、exo 與 RPC 方案

課程預留|評估多機推論的連線、分工方式、限制與現實效益。

重點觀念

待課程完成後補入。

指令

待實作後補入可複製指令。

實際紀錄

預留機器規格、網路和推論數據。

小測驗

待課程完成後補入。

22

MLX 語言模型微調

資料集、LoRA 訓練、驗證與匯出

課程預留|從整理訓練資料到評估微調前後的差異。

重點觀念

待課程完成後補入。

指令

待實作後補入可複製指令。

實際紀錄

預留資料版本、參數、訓練曲線與測試結果。

小測驗

待課程完成後補入。

23

影像模型 LoRA 微調

訓練圖像準備、標註、生成與前後對照

課程預留|比較影像模型在 Mac 上的微調工具與成果品質。

重點觀念

待課程完成後補入。

指令

待實作後補入可複製指令。

實際紀錄

預留訓練素材、設定與生成對照。

小測驗

待課程完成後補入。

24

PyTorch MPS 微調

MPS 後端、PEFT LoRA 與 Embedding 微調

課程預留|了解 PyTorch MPS 的支援範圍,並與 MLX 工作流程比較。

重點觀念

待課程完成後補入。

指令

待實作後補入可複製指令。

實際紀錄

預留套件版本、硬體使用與訓練結果。

小測驗

待課程完成後補入。

25

偏好對齊與模型預訓練

DPO、GRPO 與小型模型的完整訓練流程

課程預留|整合偏好對齊與從零訓練的基礎概念,補上完整實驗流程。

重點觀念

待課程完成後補入。

指令

待實作後補入可複製指令。

實際紀錄

預留訓練資料、資源需求與成果驗證。

小測驗

待課程完成後補入。

延伸參考

框架與檔案格式會持續演進;之後上手實作時,請以工具官方文件和模型發布頁的相容資訊為準。