Select Page
Ornith 1.5 35B 值得用嗎？自我改進、實測與本地部署解析

Ornith 1.5 35B 值得用嗎？自我改進、實測與本地部署解析

by | 9 月 17, 2026 | AI, 模型

Ornith 1.5 把本地 AI 的一個老問題攤得很清楚：每秒吐出多少 token，和最後有沒有把工作做完，是兩回事，35B-A3B 版本靠 MoE 架構降低每個 token 的運算量，在公開實測中展現速度優勢，也出現思考太久、額度用完卻沒交出程式碼的案例。

如果你想找一顆接在本地程式代理後面的模型，Ornith 1.5 35B 值得列入測試，評估時要一起看量化格式、記憶體餘裕、工具相容性與任務完成率，下面先拆開「自我改進」的意思，再看官方評分、兩組不同硬體的實測，以及實際上手順序。

Ornith 1.5 更新了什麼？先分清楚三種模型

Ornith 1.5 家族包含 9B Dense、35B MoE 與 397B MoE。手機部署的主角是 9B-Mobile 量化版本，與旗艦商用模型比較的宣傳則主要圍繞 397B。本文聚焦中間的 35B-A3B，不能把另外兩款的部署條件或成績直接套過來。版本資訊可從 官方模型集合查看。

如果你看過 Ornith 1.0 的自我拆解任務方式，這次最主要的延伸是把「生成訓練任務」也納入改善流程。

自我改進發生在訓練期間，下載後不會自動改寫權重

依照 Ornith 官方技術說明，模型在訓練中依序扮演三個角色：先根據程式庫與過去解題紀錄出題，再安排工具、指令與拆解方法，最後嘗試解題。結果回饋到強化學習流程，讓題目、執行安排與解法一起改善。

出題也有條件：題目要能驗證、難度合適，而且不能一直重複，官方把目標成功率設在約 20%，讓模型練習有挑戰但仍可能解出的題目。這個百分比是訓練課程的設計目標，不是產品的答題正確率。

可以把它想成練習寫程式時，不只修答案，也回頭調整練習題與測試方式。

下載回來的則是訓練後的模型權重，日常對話、保存記憶或反覆提示，不代表權重正在持續更新。

AlphaLab 對自我改進邊界的分析也提醒，環境與評分規則仍由人設計，分數上升還要確認是否真的學會解題。

35B-A3B 的 A3B，不是記憶體只要放下 3B

MoE 每次只選部分專家參與計算，但其他專家的權重仍要有地方存放。活躍參數主要影響每一步的運算量，總權重與快取才是估算記憶體的起點。官方 35B 模型頁列出約 3B 活躍參數，BF16 權重約 70GB，原生上下文為 262,144 token，模型規格與啟動範例可作為設定依據。

以目前 官方 GGUF 檔案清單為例，Q4_K_M 單一模型檔約 21.71GB，換算約 20.22GiB，這還沒加上推論引擎、上下文快取或視覺投影檔，因此「有 24GB 顯示記憶體」只能作為測試起點，不能直接承諾長上下文與多個並行任務都放得下。

12GB 或 16GB 顯示卡若想跑這個 Q4 檔，通常還得規劃部分權重放在系統記憶體，或改用其他量化版本，能載入模型、能順利對話、能在長任務中維持速度，應分開驗收。Mac 使用統一記憶體，也要預留系統空間，可搭配 本地 AI 的記憶體與頻寬選擇理解這個差別。

官方評分顯示程式能力進步，但要連測試框架一起看

以下是官方模型卡中同尺寸模型的部分成績。

Ornith 1.5 的結果為團隊自報的五次執行平均，並非本文重跑，也不等於所有電腦都會得到相同結果。

測試Ornith 1.5 35BOrnith 1.0 35BQwen3.6 35B
Terminal-Bench 2.1／Terminus-267.864.252.5
SWE-bench Verified79.075.673.4
SWE-bench Pro59.650.449.5
Ornith 1.5 35B、Ornith 1.0 35B 與 Qwen3.6 35B 的三項官方程式評分比較
資料來源：Ornith 35B 官方模型卡。各項測試使用各自的評測設定，不能相加成通用能力分數。

Terminal-Bench 的上述結果使用 Terminus-2，SWE-bench 使用 OpenHands。工具、提示、可用時間與上下文都會影響代理表現。「追平 Claude Opus」應限於官方列出的特定 397B 比較，無法據此宣稱 35B 全面取代商用模型。

對上 Qwen3.8 27B：生成得快，整個任務卻可能更慢

DIY Smart Code 的 Benchy 本地測試使用 RX 7900 XTX 24GB、Ryzen 9、64GB 系統記憶體與 Ollama，比較兩款 Q4 模型。Ornith 測試標示 32K 上下文。這是作者自建測試集的一組案例，量化檔案與測試工具的細節限制了外部重現，不能當成通用排名。

同一組 Benchy 案例Ornith 1.5 35BQwen3.8 27B
通過項目18／2120／21
生成速度約 74 tok/s約 58 tok/s
提示處理速度約 850 tok/s約 240 tok/s
整組耗時約 26 分鐘約 17 分鐘
Benchy 測試中 Ornith 與 Qwen 的通過項目、生成速度、提示處理速度與總耗時比較
資料來源：DIY Smart Code，2026 年 8 月 22 日公開案例。數值依逐字稿約數整理，並非本文實測。

最有參考價值的是 DAG 非同步任務排程題：Ornith 花了約 18,000 個思考 token，耗盡輸出額度後沒有交出最終 Python 程式，Qwen 則完成程式並通過該題檢查。所以每秒輸出較快，仍可能因為思考與重試較多，拖長整個工作的時間。

這也不能反推成所有 MoE 都不擅長推理，或 Qwen 永遠比較穩，模型、量化、引擎與題型都不同，架構本身不能單獨解釋全部差異，要比較自己的程式任務，可參考 Qwen3.8 27B 本地部署教學，固定測試條件再重跑。

雙 GB10 的 NVFP4 實測：減少搬運，也能讓解碼加速

CyberQ 的雙 GB10 實測是在另一套硬體與 vLLM 環境中比較 BF16 與 NVFP4。它固定解碼 800 token，暖機後取三次量測中位數，因此較適合觀察格式差異，不適合直接和前面的 Ollama 成績排高低。

雙 GB10／TP=2BF16NVFP4
解碼吞吐量48.41 tok/s101.86 tok/s
12,001 token 提示處理2,767 tok/s4,141 tok/s
CyberQ 雙 GB10 測試中 BF16 解碼 48.41 tok/s 與 NVFP4 101.86 tok/s 的比較
解碼約為 2.10 倍。這是特定硬體與引擎的量測結果。

該測試的 NVFP4 路徑先以低位元格式搬運權重，再反量化計算。當瓶頸是記憶體頻寬，減少搬運量就可能抵銷反量化成本。這是推論效率改善，不能解讀成硬體原生算力增加。

品質抽查中，兩種格式在 AIME 2026 都完成並答對 23／30 題，各有 7 題被輸出上限截斷。兩邊共同完成的 22 題答案一致，但答案一致不代表逐 token 的思考過程相同，也不能延伸成量化完全不損失品質。

本地部署怎麼開始？先讓短任務與工具呼叫跑通

先選權重格式與執行工具。桌面試用可從 GGUF 與 Ollama、llama.cpp 相容工具開始，伺服器則參考官方 vLLM 或 SGLang 範例。還不確定差別，可先看 本地大模型推論框架比較。

下載時認明 原始模型庫、官方 GGUF與 官方 NVFP4。另有 AtomicChat 的 GGUF 轉換版本可比較，請記錄實際檔名與量化等級，同樣寫 Q4 不表示所有檔案與執行結果完全相同。

測試時先縮短上下文、一次處理一個請求，確認記憶體與基本輸出正常，再逐步拉長。官方雖提供延伸到約 1M token 的設定，卻也提醒長上下文縮放可能影響一般長度的品質，不必第一次啟動就把視窗開到最大。

接代理前，再測試工具名稱、參數、工具結果回傳，以及模型能否繼續下一步。模型能輸出 tool_calls，只代表這段格式可用，MCP 伺服器還需要由代理程式接上。純聊天成功，不能代替完整工具流程驗收。

最後設定整個任務的時間、輸出與重試上限，並檢查所用引擎是否支援獨立思考額度。只縮小總輸出上限，可能更早截斷最終答案。日常試用可先用幾個有明確驗收條件的小任務，比較完成時間、人工修正量與失敗原因，再決定是否放入長時間自動化工作。

授權與手機部署，哪些說法還要保留？

T客邦的發布報導有助於了解系列定位，但授權敘述與官方 metadata 不一致。

本文以官方模型頁標示的 MIT 為準。

同樣地，9B-Mobile 支援行動裝置的宣稱，不能保證每一款手機都有足夠可用記憶體、支援對應模型格式，或能維持長上下文。先確認使用的 App、量化檔與裝置條件，比直接照搬桌面版的速度數字有用。

常見問題

Ornith 1.5 35B-A3B 是只有 3B 參數嗎？

不是。它是 35B 級 MoE 模型，每個 token 約啟用 3B 參數。儲存與載入仍需考慮完整權重，以及快取和引擎額外用量。

Ornith 1.5 放在本地使用會自己越來越聰明嗎？

官方的自我改進是訓練流程。下載後一般執行推論，不會因為聊天次數增加就自動更新模型權重。

24GB 顯示卡一定能跑 35B 的完整上下文嗎？

不能保證。官方 Q4_K_M 檔約 20.22GiB，還需預留引擎與快取空間。應從短上下文實測，再逐步調整。

Ornith 1.5 和 Qwen3.8 27B 該選哪個？

先用自己的任務比較。公開 Benchy 案例中 Ornith 生成較快，Qwen 通過較多項目。這組結果只適用於該測試條件。

這是美國團隊所推出的模型

Ornith 支援工具呼叫，就能直接連 MCP 嗎？

還需要代理程式與 MCP 連接層。應測試參數格式、工具執行與結果回傳的整個流程。

先看能否完成你的工作，再看分數有多高

Ornith 1.5 值得研究的地方，是它把練習題、工具安排與解法放進同一條訓練流程。而對本地使用者來說，35B-A3B 的實際價值仍要靠任務驗收：能不能在現有記憶體內跑穩、工具是否接得上，以及等待之後有沒有拿到可用成果。

先挑幾個你每週真的會做的工作，讓 Ornith 與現有模型各跑一次。保留設定、耗時與失敗紀錄，往往比看一張總排名更容易做出選擇。若想了解前述測試工具的設計，可再看 Benchy 測試工具建置說明。

Docker 學習日誌：看懂 docker build，從映像建置到容器更新

by | 9 月 16, 2026 | Docker, MIS

學 Docker 時，很容易先記住一串指令，等到遇上「明明 build 成功，服務卻沒有更新」，才發現還有一些觀念需要釐清。

這篇從一條常見的建置指令出發，記錄映像、標籤、建置範圍與快取的關係，再整理部署時值得注意的七件事。範例使用通用的 Python API 專案名稱，方便套用到自己的環境。

一、先看懂這條指令

假設專案根目錄叫做 my-project，在該目錄執行：

docker build -t demo-api:1 -f api/Dockerfile .
指令片段意義
docker build依照 Dockerfile 建立映像
-t demo-api:1將映像命名為 demo-api，標籤設為 1
-f api/Dockerfile指定要使用的 Dockerfile
.以目前目錄作為建置範圍，也就是 build context

docker build：依照配方製作映像

Dockerfile 描述建置步驟；image（映像）是產物；container（容器）則是由映像建立、可以啟動的執行個體。

常見指令包括：

  • FROM：選擇基礎映像，開始一個建置階段。
  • RUN：在建置過程執行命令，例如安裝套件。
  • COPY：將檔案複製到映像內。
  • CMD：設定容器啟動時預設執行的命令。

映像由多個檔案系統層組成，但不能把「每條 Dockerfile 指令」都當成「新增一層檔案」。例如 CMD、ENV 主要記錄設定；FROM 則引入基礎映像。可參考 Dockerfile 官方說明。

-t demo-api:1：給映像一個容易引用的名稱

demo-api 是映像名稱，1 是 tag（標籤）。標籤由使用者自行命名，Docker 不會因為寫了 1，就自動幫你維護版本歷史。

如果再次使用同一標籤建出不同映像，demo-api:1 會改為指向新映像。舊映像若沒有其他標籤，可能顯示為 <none>；若仍被容器引用，就不能直接當作可清除的垃圾。

已存在的容器不會因為 tag 改指向新映像，就自動換版本。

實際發布時，可以改用 demo-api:1.0.1 這類明確標籤，並約定不覆寫已發布版本，讓追蹤與回復更容易。標籤本身是可變的引用，詳見 Docker image tag。

-f api/Dockerfile：選擇配方的位置

在本文這種本機目錄建置方式中，未指定 -f 時，Docker 預設使用 context 根目錄下的 Dockerfile。

-f api/Dockerfile 表示使用子目錄內的檔案，不代表把 build context 改成 api/。

.：決定 COPY 能從哪裡拿檔案

假設專案包含以下內容：

路徑用途
api/Dockerfile建置配方
api/main.pyAPI 程式
api/requirements.txtPython 套件清單
shared/共用模組
compose.yaml服務設定
.dockerignore建置時要排除的檔案

Dockerfile 可以寫：

COPY api/main.py /app/main.py
COPY shared/ /app/shared/

這裡一般 COPY 的來源路徑，是從 build context 根目錄算起，不是從 Dockerfile 所在的目錄算起。COPY --from 則是另一種情境，可從其他階段或指定來源複製。

因此，在專案根目錄執行：

docker build -t demo-api:1 -f api/Dockerfile .

如果已經進入 api/，也可以明確把 context 指回上一層：

docker build -t demo-api:1 -f Dockerfile ..

重點是最後的路徑包含哪些檔案。詳見 Build context。

二、建置與部署時要注意的七件事

1. 控制 context 大小，避免帶入不需要的檔案

專案裡可能放著資料集、備份、套件目錄與環境設定。這些東西通常不需要拿來建置。

可以在 context 根目錄放入 .dockerignore：

.git/
.env
.env.*
!.env.example
.venv/
node_modules/
**/__pycache__/
**/*.pyc
data/
backups/
*.tar
*.tar.gz

請依專案調整：如果建置真的需要 data/ 中的檔案，就不能整個排除。

現代 Docker 常使用 BuildKit，能跳過未使用的檔案，並減少重複傳輸。因此，「整個目錄一定會先全部打包送出」並不是通用的描述。但明確排除無關檔案，仍能減少負擔，也避免 COPY . . 把環境設定或備份帶進映像。參考 BuildKit 與 .dockerignore 說明。

2. 安裝套件可能需要網路，離線部署要事先準備

以下建置步驟通常需要連到套件來源：

RUN apt-get update \
    && apt-get install -y --no-install-recommends curl \
    && rm -rf /var/lib/apt/lists/*

RUN pip install --no-cache-dir -r requirements.txt

基礎映像若尚未存在，也可能需要下載。使用內部套件庫或已備妥的離線套件時，做法則會不同。

若部署環境無法上網，一種常見方式是在可上網、且目標平台相容的準備機建好映像，再匯出：

docker image save -o demo-api_1.tar demo-api:1

把檔案搬到目標主機後載入：

docker image load -i demo-api_1.tar

save 和 load 處理的是映像；Compose 設定、環境變數、掛載檔案與資料庫資料，需要另外準備。若有多個服務，也要備齊各服務使用的映像。參考 docker image save 與 docker image load。

此外，同一份 Dockerfile 在不同日期重新建置，不一定得到完全相同的套件。需要可重現的版本時，應管理套件鎖定檔、基礎映像 digest 與建置來源。參考 Docker 建置最佳實務。

3. Cache 能加速建置，但不會主動檢查套件是否更新

Docker 會依指令、前面的建置狀態與相關輸入，判斷是否能重用快取。

以常見的單階段 Dockerfile 為例，調整順序可以減少重做的工作：

WORKDIR /app

COPY api/requirements.txt ./requirements.txt
RUN pip install --no-cache-dir -r requirements.txt

COPY api/main.py ./main.py
COPY shared/ ./shared/

這樣只修改程式碼時，前面的套件安裝步驟通常仍能使用快取；修改套件清單時，才需要重新安裝。參考 快取最佳化。

但 RUN apt-get update ... 或 RUN pip install ... 若命中快取，就不會實際執行，也不會上網確認是否有新版。一般 COPY 的內容或相關檔案中繼資料改變，則可能讓快取失效；只改檔案修改時間並不足以觸發。參考 快取失效規則。

需要停用建置快取時：

docker build --no-cache -t demo-api:1 -f api/Dockerfile .

如果也要嘗試更新基礎映像，可加上 --pull：

docker build --pull --no-cache -t demo-api:1 -f api/Dockerfile .

--no-cache 與 --pull 用途不同。另外，Dockerfile 裡的 pip --no-cache-dir 只控制 pip 的下載快取，不會關閉 Docker 的建置快取。Docker 旗標可參考 Buildx build 說明。

4. 定期看磁碟使用量，再決定清理範圍

多次建置後，可能累積舊映像與 build cache。因為映像之間可以共享層，磁碟占用不一定是每建一次就增加一份完整映像大小。

先查看：

docker system df
docker image ls

若要清除未被容器引用的 dangling 映像，可以執行：

docker image prune

這個命令會先要求確認；加上 -f 才會省略確認。-a 會把清理範圍擴大到所有未被容器引用的映像，包含有標籤、可能留作回復用途的版本。

映像清理也不等於清空 build cache，不必把兩者混為一談。參考 docker image prune 與 Build cache 管理。

5. Build 成功後，還要讓服務使用新映像

假設 compose.yaml 中有以下服務：

services:
  api:
    image: demo-api:1
    ports:
      - "127.0.0.1:8000:8000"

此設定假設應用程式在容器內監聽 0.0.0.0:8000，並將主機端連線限制在本機。api 是 Compose 服務名稱，demo-api:1 是映像名稱，兩者用途不同。

建置完成後，在 Compose 檔案所在目錄執行：

docker compose up -d api

Compose 偵測到映像或設定變更時，通常會重建容器。如果希望明確要求重建，即使沒有偵測到變更，也可以用：

docker compose up -d --force-recreate api

所以，--force-recreate 是強制重建的選項，不是更新映像唯一的方法。參考 docker compose up。

docker compose restart api 則是重新啟動既有容器，不能用來切換到剛建好的映像。參考 docker compose restart。

重建之前，也要知道資料放在哪裡：

資料位置重建容器時要注意的事
容器可寫層刪除舊容器時，裡面的資料會一併失去
具名 volume重新掛載相同 volume 可沿用資料；刪除 volume 另當別論
主機 bind mount資料保留在主機路徑，需確保仍掛載相同位置
外部資料庫或儲存服務需確認連線設定及新版程式的資料相容性

沒有掛載 volume，不代表重建一定安全。 上傳檔案、SQLite 或日誌若只存在容器內，就可能遺失。參考 Docker 儲存說明。

更新後可查看：

docker compose ps
docker compose logs --tail=100 api

接著實際呼叫 API 或檢查健康狀態。容器正在執行，與應用程式已正常提供服務，是兩件需要分別確認的事。

6. 搬映像之前，確認 CPU 架構

常見平台包括 linux/amd64（一般 x86-64 主機）與 linux/arm64（ARM64 主機）。

未特別指定時，建置平台通常跟隨 builder 的預設平台。不同架構的單一平台映像，不能假設能在另一台主機原生執行。

可以先檢查映像：

docker image inspect demo-api:1 --format '{{.Os}}/{{.Architecture}}'

若 builder 已具備跨平台建置能力，可明確指定目標：

docker buildx build --platform linux/amd64 --load -t demo-api:1 -f api/Dockerfile .

這裡 --load 會將單一平台建置結果載入本機映像儲存區。跨平台的 RUN 步驟可能需要模擬器、原生節點或其他支援，基礎映像與套件也必須支援目標平台。

遇到 exec format error 時，架構不符是排查方向之一，也要檢查執行檔與腳本格式。跨平台原理與前提可參考 Multi-platform builds。

7. 建置時做基本自檢，讓問題早點出現

假設程式需要 requests 套件與 curl 指令，可以在安裝完成後加入：

RUN python -c "import requests" && command -v curl

這種自檢可以提早發現套件漏裝或命令不存在。命令回傳非零狀態時，該次建置會失敗。

但自檢只能涵蓋實際檢查的項目，不能保證部署環境中的資料庫、網路、權限或完整功能都正常。建置時也應避免匯入會立刻連線正式服務的模組。

還有一個容易忽略的地方：這次 build 失敗，之前的同名映像可能仍然存在。 不要只看 docker image ls 有沒有該 tag，就認為這次建置成功。

三、把日常更新整理成固定步驟

以下假設位於專案根目錄，使用前面的 Compose 設定，而且既有容器也是由同一個 Compose 專案建立。

先建置：

docker build -t demo-api:1 -f api/Dockerfile .

確認成功後，再更新服務：

docker compose up -d api

查看狀態與日誌，再驗證實際功能：

docker compose ps
docker compose logs --tail=100 api

如果使用 Bash 自動串接建置與更新，可以使用 &&，確保前一步成功才繼續：

docker build -t demo-api:1 -f api/Dockerfile . && docker compose up -d api

若原本使用 docker compose -p demo ... 指定專案名稱，後續操作也要維持相同的 -p demo，避免操作到另一組服務。

這次學習後，我會在每次更新時依序確認：建置用了哪些檔案、產出了哪個映像、服務是否已使用新映像，以及資料是否放在能持續保存的位置。把這幾件事分開檢查，就比較容易找出更新流程卡在哪一步。

Microduck 組裝教學：從零件、系統安裝到雙足機器人第一次行走

Microduck 組裝教學：從零件、系統安裝到雙足機器人第一次行走

by | 9 月 16, 2026 | Raspberry Pi, RaspberryPI, 硬體

在網路上看到一個很適合小朋友們學習機器人的專案，想推薦給大家，要把 AI 放進機器人，和在電腦上跑一個聊天模型，是兩種很不同的實作。程式可以重新執行，但舵機方向裝反、電壓接錯，或姿態感測器固定不牢，機器人不會靠多問幾次提示詞就自己修好。

Microduck 是一個小型雙足機器人專案，透過 3D 列印結構、Dynamixel 舵機、姿態感測器與預先訓練的行走策略，將模擬中的控制能力帶到實機。AI-FanGe 整理的建置版本提供原始碼與預建系統映像，讓第一次組裝不必同時從零處理作業系統、依賴套件和強化學習訓練。

我認為這個專案最適合拿來學習的，是機械、電控、感測與模型之間怎麼配合。先把同一個版本穩定復刻，再談換舵機或增加功能，會比一開始就把所有零件都改成便宜替代品更容易成功。

Microduck 教學專案提供的實機展示，呈現雙足結構與頭部動作
實機展示素材來自 AI-FanGe 教學專案，不是本文自行組裝的測試成果。封面另為 AI 生成概念圖，不作為零件外觀或接線依據。

先看懂架構：Pi 負責推論，舵機負責動作

Microduck-build-tutorial把軟體分成兩個主要目錄。microduck/是在 Raspberry Pi Zero 2 W 上執行的部署程式，mjlab_microduck/則是 MuJoCo／MjLab 強化學習訓練環境。兩者不要混為一談。

  • 感測：IMU 提供姿態與角速度，舵機回報關節狀態。
  • 指令：鍵盤或藍牙手把提供前進、後退與轉向需求。
  • 推論：Pi 載入 walk.onnx，根據目前狀態與指令產生關節目標。
  • 執行：Pi 經 USB 連到 OpenRB-150，再透過 Dynamixel 通訊總線控制舵機。
  • 回授：下一輪讀取新的姿態與關節狀態，持續修正動作。

這裡的 AI 是行走控制策略，不是大型語言模型在即時逐句指揮每一顆馬達。預建映像已包含策略，第一次復刻不需要先訓練。若之後改變結構、重量或致動器特性，才需要重新評估原本模型能不能沿用。

本次復刻的範圍是運動模組，不包含攝影機與語音對話。會走路、會轉頭，不代表已經能看懂環境或和你聊天，這些功能需要另外加上感測硬體與軟體。

想比較不同開源機器人的學習方向，可以接著看站內的 HopeJR 機器人與手臂控制介紹。機械操作與雙足步態的目標不同，但都需要把感測、驅動與控制策略一起考慮。

採購前先對版本，別把兩份 BOM 混在一起

截至 2026 年 9 月 8 日查核，這份教學採用 Pi Zero 2 W 與 OpenRB-150。完整機械配置可裝 15 顆舵機，但目前 README 與行走程式實際控制的是 14 顆 XL330-M288-T，對應雙腿 10 顆、頭頸 4 顆。嘴部 ID 15 是額外的開合關節，不是目前行走策略必要的關節。採購時先決定是否要裝嘴部，別把「15 顆機械結構」誤認為「行走模型一定需要 15 顆」。

但 microduck/docs/bom.md仍可看到包含 19 顆舵機、RPI Robot HAT 與另一種電池配置的資料。這代表文件中存在不同配置，不能拿舊清單的數量、電源接法與目前部署程式隨意拼在一起。本文以本次教學的根目錄 README 與目前程式為主。

零件數量用途
Pi Zero 2 W1執行控制與行走策略
OpenRB-1501連接舵機通訊總線
XL330-M288-T14 + 選配 1雙腿 10、頭頸 4、嘴部 1
BNO08x IMU1量測姿態與角速度
microSD116GB 起，32GB 較寬裕
3D 列印結構件1 套依本版本模型製作
供電與開關1 套電壓、電流另行核對
螺絲與線材依裝配固定、通訊與供電
Microduck 主要零件清單，包含 Pi Zero 2 W、OpenRB-150 與 14 顆 XL330 舵機
主要零件速查，數量依本次教學配置，不是所有 Microduck 版本通用的採購單。

另外還需要能進行列印或代印的管道、合適螺絲起子、電表，以及必要的線材處理工具。電池、穩壓、保險與線徑不能只照名稱採購，必須依實際電壓、峰值電流與接頭規格確認。

舵機為什麼不能只看價格，直接換成便宜的？

DIY 不一定比買成品便宜，尤其多顆智慧舵機容易成為主要支出。除了馬達本身，還要計入列印失敗、接頭、工具、運費與備品，因此我不會把不同版本、不同地區的舊價格直接加總，當成今天一定能買到的總預算。

替代舵機需要比對的，也不只是扭力。外殼尺寸、固定孔、輸出軸、重量、速度、間隙、通訊協定、回授資料與控制延遲都可能不同。機械上裝得進去，不代表控制程式相容，更不代表原本的行走策略還能保持平衡。

如果真的要更換，應先確認結構能否固定，再處理驅動介面與關節校正，接著檢查模擬中的致動器參數，必要時重新訓練。並非每次更換都必須從零重做，但也不能預設只改一個型號名稱就能走。若只是想先學機器人組裝，也可以參考站內的 Pupper 開源機器狗實作，比較四足與雙足平台的學習需求，舊文價格則不應當作目前報價。

下載原始碼與列印檔，先完成不通電的裝配

原始碼可從 GitHub 專案頁下載 ZIP，或在開發電腦使用 Git。這一步只取得檔案，不會操作機器人。

git clone https://github.com/AI-FanGe/Microduck-build-tutorial.git
cd Microduck-build-tutorial

根目錄提供 microduck3D打印.3mf，microduck/cad/也有 CAD 相關檔案。先確認檔案與目前採用的裝配版本一致，不要把不同版本的腿、頭部與電源艙混印。PLA 可以作為起點，但方向、支撐、孔位與配合公差仍須依實際零件確認。

  • 先整理左右腿與頭頸零件，確認沒有鏡像裝反。
  • 檢查螺絲長度，避免頂住舵機內部或穿透結構。
  • 預留關節活動所需線長，但不要讓線材垂進齒輪或夾點。
  • 先對好舵機中立位置與零點，再固定輸出端，不能只憑外觀鎖緊。
  • 首次通電前再確認所有固定件、極性與絕緣，調整接線時先斷電。

組裝可以分成腳部與左右腿、軀幹支架、頸部、頭部，再合體整理線材。先鎖好之後會被其他零件擋住的螺絲孔，再裝覆蓋其上的舵機。從動盤與支撐環也要檢查轉動阻力，不能用過度鎖緊來換取表面上的穩固。電池尺寸與控制板位置會影響空間和重心，別以強塞方式固定。

供電是最重要的關卡，不要靠關閉保護解決問題

教學 README 寫的是成品 6V 電池方案，但「標示 6V」不代表充飽後、空載時或負載變化時都恰好是 6.0V。必須量測實際輸出，並確認整條供電路徑符合零件規格。

依 ROBOTIS XL330-M288-T 原廠文件，輸入範圍為 3.7 至 6.0V，建議電壓為 5.0V。不要把超過上限的電池直接接到 XL330，也不要為了讓機器繼續動就取消輸入電壓錯誤保護。如果電壓不穩，應先處理電源、線材與負載問題。

另外，OpenRB-150 原廠規格的板子輸入範圍，不等於舵機也能承受同樣電壓。原廠也列出 DYNAMIXEL 埠電流限制，14 顆舵機同時動作時，不能假設一條 USB 線或板載電源路徑一定足夠。Pi 應有穩定的 5V 供電，舵機電源、分配方式與共地則要依控制板文件設計，不能把板上的小電流 5V 腳當成整機電源。

這次實作的關鍵，是把舵機的大電流供電與控制板通訊分開，舵機有獨立的配電路徑，Pi 則由穩壓後的 5V 供電。這與 README 中較簡化的電源流程描述並不完全相同，因此不能只看總線連線就認定所有電力都經過 OpenRB。若採外部舵機配電，須核對 VDD 隔離、共地、線徑與保護，不讓外部電源反灌控制板，也不要照著線色猜接法。

程式中的電壓模型參數也不是硬體額定值，不能看到模擬常數就照著供電。沒有電路與電池經驗時，先請熟悉硬體的人檢查，不建議把自行製作電池組當成第一次實作。測試時使用支架或安全吊掛，手指遠離活動關節，並保留能立即切斷動力的方式。

設定舵機 ID 與 IMU，讓軟體認得實際裝配

舵機最好在正式串接前逐顆設定與標記。OpenRB-150 可以搭配 DYNAMIXEL Wizard 2.0，原廠預設提供 usb_to_dynamixel韌體。若板子曾被改刷其他程式，需先確認它仍處於可用的 USB 通訊橋接模式。

目前教學使用 Protocol 2.0 與 1Mbps。ID 必須和程式一致，線在總線上的實際排列不等於 ID 會自動依序產生。

在 Wizard 中先只接一顆舵機，Scan 找到裝置後設定 ID 與通訊速度，再依目前設定核對 Return Delay Time。確認周圍無干涉後，才啟用扭矩讓它回到中立位置，接著斷電再裝配。未設定的舵機可能都是相同 ID，一次全部串上會難以分辨。不要把操作示範中的保護關閉動作視為必要步驟。

  • 右腿 ID 1 至 5：右踝、右膝、右髖俯仰、右髖橫滾、右髖偏航。
  • 左腿 ID 6 至 10：左踝、左膝、左髖俯仰、左髖橫滾、左髖偏航。
  • 頭頸 ID 11 至 14：頭部俯仰、頸部俯仰、頭部偏航、頭部橫滾。
  • ID 15：選配嘴部，不能假設目前行走程式會驅動它。

IMU 使用 BNO080／BNO085／BNO086 系列模組，依模組標示確認電源，I2C 的 SDA 對應 GPIO2，SCL 對應 GPIO3。安裝方向與固定方式會影響姿態解讀，不能把感測器旋轉後仍沿用未確認的設定。

目前 constants.py還包含右膝與左膝的相反方向零點偏移，這些是特定裝配的校正，不是通用數值。若一啟動就往奇怪方向扭，先停機檢查 ID、零點、方向與 IMU，不要靠提高增益硬撐。

系統安裝：使用預建映像，先跑通第一次開機

1. 從正式 Release 取得映像

先到 image.v1 發布頁，下載 microduck.img.xz。這是教學作者提供的第三方映像，不是 Raspberry Pi 官方原版映像，寫入前應確認來源。

下載完成後計算 SHA256。macOS 使用第一段，Linux 使用第二段。

shasum -a 256 microduck.img.xz
sha256sum microduck.img.xz

本次查核 image.v1 資產的 GitHub SHA256 為下列值。未來若作者重新發布檔案，應以當次 Release 的值為準。校驗一致代表檔案符合發布資產，不等於已完成安全稽核。

096885dc32fb5b1db2ad69ba6bea868d8ab988f2b47c0d884eb63ba0dfdcb5c4

2. 寫入 microSD

安裝 Raspberry Pi Imager，裝置選 Raspberry Pi Zero 2 W，作業系統選自訂映像，再指定剛下載的檔案與 microSD。寫入會清除所選儲存裝置，務必確認不是電腦內部磁碟。

這份自訂映像的教學要求在 OS customization 提示選擇 No，使用它自己的初始化方式。不要把這個做法誤套成所有 Raspberry Pi 映像都應該關閉自訂設定。寫入與驗證完成後，才把卡放進 Pi。

3. 連上 2.4GHz Wi-Fi

Pi Zero 2 W 的無線網路是 2.4GHz。可依 README 在 bootfs 的 network-config修改 Wi-Fi，或接上 mini HDMI 螢幕與鍵盤，在 Pi 終端設定，鍵盤需要合適的 USB OTG 轉接。第一次啟動需要等待分區擴展完成，期間不要隨意拔電。

使用本次映像的預設帳號 user與密碼 password登入後，立刻執行 passwd換掉預設密碼。不要把 SSH 直接開放到公網。下面命令是在 Pi 上執行，依 nmcli 官方說明，--ask會互動詢問 Wi-Fi 密碼，避免將密碼直接寫在命令列。

passwd
nmcli device wifi list
sudo nmcli --ask device wifi connect "你的WiFi名稱"
hostname -I

先查看連線設定名稱，再將實際使用的設定開啟自動連線。下列的名稱是連線設定名稱，不一定和 Wi-Fi 名稱完全相同。

nmcli -f NAME,TYPE,AUTOCONNECT connection show
sudo nmcli connection modify "你的連線設定名稱" connection.autoconnect yes

如果平常用的是 wpa_cli 管理 Linux 無線網路，這裡要留意工具不同。本次映像的教學使用 NetworkManager／nmcli，不要在沒有確認管理方式前，混用另一套設定流程。

4. 從電腦用 SSH 連線

ssh [email protected]

若名稱找不到，到路由器查看 Pi 的 IP，再改用該 IP 連線。若出現主機金鑰變更警告，先確認是不是自己重新刷過同一台 Pi，並核對裝置，不能遇到警告就直接刪除紀錄繼續。

首次執行：先會停止，再讓它走

先將機器人安全支撐，確認關節周圍沒有人手。程式開始時就會啟用扭矩並回到中立姿態，不是等你按前進才會動。也不要同時啟動多個控制程式爭用舵機總線。

以下是在 SSH 登入 Pi 後執行的命令。預建映像已提供部署目錄、虛擬環境與行走模型。

cd ~/microduck
PYTHONPATH=src .venv/bin/python src/main.py
  • v：切換行走。
  • 方向鍵上／下：前進與後退。
  • 方向鍵左／右：轉向。
  • x：速度指令歸零，不是硬體急停。
  • i：顯示或隱藏 IMU 資訊。
  • q：結束控制迴圈。

需要從另一個 SSH 視窗要求停止時，使用以下命令。它是軟體停止機制，不應取代測試區的實體斷電措施。

cd ~/microduck
PYTHONPATH=src .venv/bin/python src/stop.py

一般結束使用，先停止控制並支撐好機器人，再正常關閉 Pi。等待關機完成後，才關閉主電源。若有冒煙、異味或機構卡死等危險狀況，應立即切斷動力，不要為了正常關機而延誤。

sudo shutdown -h now

藍牙手把模式：為什麼一連上就斷 SSH？

預建映像包含無頭手把服務，可以不開電腦終端就啟動控制。第一次配對，可在 Pi 上開啟 bluetoothctl，再執行下列互動命令，把範例 MAC 換成掃描到的手把位址。

bluetoothctl
power on
agent on
scan on
pair XX:XX:XX:XX:XX:XX
trust XX:XX:XX:XX:XX:XX
connect XX:XX:XX:XX:XX:XX
scan off
quit

配對前先讓手把進入配對模式，看到確認要求時核對裝置後再接受。不同手把的按鍵映射可能不同，以下以本次教學的映射為準。

  • 按住 START 約 2 秒：啟動控制迴圈。
  • A：切換行走。
  • 左搖桿：前後與左右速度。
  • 右搖桿左右：轉向。
  • B：停止控制迴圈。
  • 同時按住左右扳機約 2 秒：要求正常關機。

這個版本的背景服務會在手把連線後關閉 Wi-Fi，以改善 2.4GHz 藍牙連線穩定性。因此 SSH 中斷不一定是 Pi 當機，先關閉手把，等 Wi-Fi 恢復後再連線。這是本專案的服務設計，不是所有 Raspberry Pi 藍牙連線都會這樣。

常用維護命令：分清楚在電腦還是 Pi 執行

前面的 Python 命令是在 Pi 上跑。下面的 Makefile 命令則是在開發電腦的 Microduck-build-tutorial/microduck目錄執行，需要可用的 make、rsync 與 SSH 環境，Windows 使用者可採 WSL。明確指定 [email protected]，避免預設 SSH 別名或帳號不符。

cd Microduck-build-tutorial/microduck
make sync [email protected]
make voltage [email protected]
make imu [email protected]

make sync會把本機程式同步到 Pi，因此只應在確認本機版本正確、已備份 Pi 上個人修改後使用。部分檢查目標也會先同步，不是完全不改動遠端檔案的只讀診斷。若只是第一次使用預建映像，先用前面的 SSH 操作即可。

修改依賴後，才執行以下同步與依賴更新命令。

make setup [email protected]

需要啟動控制時，先做好安全支撐，再執行下面這一行。它會先同步程式，接著讓機器人進入控制流程。

make run [email protected]

需要停止時，在另一個終端機執行下面這一行，並注意失去扭矩後機器人可能倒下。

make stop [email protected]

控制停止、機器人已支撐妥當後，才執行正常關機。

make shutdown [email protected]

訓練環境負責產生可部署策略，但重新訓練不是第一次開機的必要步驟。目前匯出腳本產生的檔名為 policy.onnx，部署端則讀取 src/agents/walk.onnx。不能只把任意 ONNX 改名就認為能用，仍須核對觀測、關節順序、動作尺度與模型版本。替換前保存可用的舊模型，再進行受控測試。

遇到問題，先查這四個地方

  • 找不到 Pi：確認 2.4GHz Wi-Fi、首次啟動是否完成、路由器是否分配 IP，以及手把服務是否暫時關閉 Wi-Fi。
  • 舵機不回應：先檢查供電和極性，再查 OpenRB USB 裝置、韌體、舵機 ID、波特率與插頭。不要帶電拔插舵機線。
  • 一啟動就倒或關節扭錯：停止後核對左右腿 ID、膝部零點、關節方向、IMU 固定與安裝方向，別急著換模型。
  • 程式無法啟動或總線被占用：先確認背景控制是否已執行，查看服務狀態與日誌，不要用多開程序的方式重試。

在 Pi 上可以用以下命令查看背景服務的狀態與近期日誌。這些命令不會啟動行走。

systemctl status microduck-gamepad.service
journalctl -u microduck-gamepad.service -n 80 --no-pager

常見問題

Microduck 一定要先訓練 AI 才能走嗎？

不需要。本次預建映像包含 walk.onnx 行走策略，第一次復刻先完成裝配、供電、舵機與 IMU 檢查，再使用既有模型。更換硬體或開發新步態時，才進一步評估訓練需求。

這次教學到底需要幾顆舵機？

完整機械配置可裝 15 顆，目前行走程式使用其中 14 顆，雙腿 10 顆、頭頸 4 顆。嘴部 ID 15 為額外關節，採購前先決定是否安裝嘴部，並核對版本。

可以用較便宜的舵機替換 XL330 嗎？

可以研究替代方案，但需要確認結構尺寸、通訊、回授、速度與控制特性。差異可能需要改機構、驅動與模擬參數，甚至重新訓練，不是一定能直接替換。

手把連線後，SSH 斷線正常嗎？

本版本的無頭手把服務會暫時關閉 Wi-Fi，以改善藍牙穩定性。關閉手把後 Wi-Fi 應恢復，可再用 SSH 連線。若沒有恢復，再查看服務日誌。

標示 6V 的電池可以直接接上嗎？

不能只看標稱值。XL330 原廠輸入上限為 6.0V，必須確認充飽與負載變動時的實際電壓，並檢查電流、穩壓與配電能力。不要靠取消電壓保護來處理異常。

我的建議：先把一台做穩，再開始改造

Microduck 讓具身控制不再只是研究論文裡的概念，你可以看到一個姿態讀值如何影響關節命令，也能理解為什麼模擬成功不等於實機一定穩定。但這仍是需要調校的硬體專案，不是刷完映像就保證能走的家電。

先鎖定同一個版本，確認供電與關節，再跑通預建模型。等到站立、停止、行走與關機都能重複完成，再逐步嘗試外觀、動作或訓練上的改變。每次只改一個因素，保留原本能用的程式與模型，除錯會容易得多。

原始資料可從 AI-FanGe 建置教學與上游 Pollen Robotics Microduck繼續閱讀。此整理未經本文作者實機驗證，正式通電前仍須依零件原廠文件檢查。程式庫根目錄與部分子目錄、檔案採不同授權，若要修改散布或商用，應逐項核對，不宜把整個專案一概當成同一授權。

Mole 教學：免費 Mac 清理工具，安裝、磁碟分析與常用命令

Mole 教學：免費 Mac 清理工具，安裝、磁碟分析與常用命令

by | 9 月 15, 2026 | Apple, Mac

Mac 空間快滿時，我會先找出到底是哪些資料夾變大，再決定要清快取、移除軟體，還是整理下載過的 AI 模型。

Mole 把這些工作集中在終端機裡，輸入 mo 就能用方向鍵操作，涵蓋磁碟分析、清理、解除安裝、系統維護與即時監控。

對已經使用 Homebrew、Codex 或本地模型的 Mac 使用者，Mole 很適合當作日常維護工具，它能協助回收空間、找出資源占用，但清掉檔案並不代表 CPU 會自動變快。先知道瓶頸在哪裡，才不會刪了一堆快取，最後只是讓軟體重新下載相同資料。

Mole 免費嗎，終端機版和 DMG App 差在哪裡

目前的 Mole GitHub 專案 是免費開源 CLI，採 GPL-3.0 授權。

Mole for Mac 繁體中文官網 提供的是另外一款付費原生圖形介面 App。免費開源的說法應對應 CLI，不能套用到所有同名版本。

CLI 適合用鍵盤操作、希望檢查原始碼，或要把結果交給其他程式處理的人，原生 App 則提供視覺化磁碟樹狀圖、App 管理、選單列狀態等操作介面，對不想開終端機的人更直覺，官方目前標示 App 為一次購買、終身更新，一份授權可用於兩台 Mac，實際價格和條款以購買頁為準。本文以下以免費 CLI 為主。

安裝 Mole，先確認 Homebrew 能使用

按下 Command 加空白鍵，搜尋「終端機」。如果已安裝 Homebrew，先檢查版本，再安裝 Mole。

brew --version
brew install mole
mo --version
mo

還沒裝 Homebrew，可以到 Homebrew 官網取得安裝命令。安裝完成後，照終端機顯示的 Next steps 設定環境，再重新開啟終端機。Apple Silicon 和 Intel 的安裝位置可能不同，直接照自己電腦輸出的步驟最穩。

輸入管理員密碼時，終端機通常不會顯示字元或星號，輸入完按 Enter 即可。Mole 只有在操作需要較高權限時才會提出要求，不必把每一條命令都加上 sudo。

第一次使用，我會從 Analyze 開始

先執行磁碟分析，沿著最大的資料夾往下查看。比起直接啟動清理，這一步更容易理解自己的硬碟用在哪裡。

mo analyze

也可以指定範圍，縮小到下載資料夾或外接磁碟。外接磁碟不包含在預設總覽裡，要另外指定。

mo analyze ~/Downloads
mo analyze /Volumes

使用方向鍵瀏覽，需要判斷內容時在 Finder 開啟對應位置。Analyze 內的移除操作會在確認後將所選項目移到垃圾桶，這和部分清理命令的刪除行為不同。要立即回收實際空間，還要考慮垃圾桶是否已清空。操作快捷鍵以畫面下方提示為準。

AI 模型快取很大，但它不一定是垃圾

本地 AI 工作流常會保存多個模型版本、量化格式與下載快取，依照 Hugging Face 官方快取說明，Hub 檔案快取預設位於 ~/.cache/huggingface/hub，設定過 HF_HOME 或 HF_HUB_CACHE 時則可能在別處。可以先用 Mole 查看預設快取的上層資料夾。

mo analyze ~/.cache/huggingface

模型檔值得保留與否，取決於近期是否還會使用，以及重新下載的成本。你可以先列出每個模型的用途，保留常用版本，再逐一移除已淘汰的模型。不同快取版本可能共用檔案，適合搭配模型下載工具自身的管理功能，避免只刪掉某個片段後留下不完整模型。

如果你正在比較 llama.cpp、MLX 與 Ollama 的本地推理方式，要特別留意不同工具可能各自保存權重。整理時先確認模型屬於哪個工具，才知道之後要從哪裡重新取得。

做 ComfyUI 本地影音工作流 時也一樣，模型、輸入素材和生成成果應分開管理。尚未交付的成品有保留價值，不能只因為容量大就把整個輸出目錄視為可刪快取。

Clean 清快取，先看 dry-run 結果

準備清理時，先預覽會處理哪些路徑。需要保留的快取可以加入保護清單，再執行清理。

mo clean --dry-run
mo clean --whitelist

確認預覽內容後，以下命令會實際進行清理。

mo clean

清理範圍包括符合規則的快取、日誌、暫存與已移除 App 的殘留。清理後部分軟體第一次開啟可能要重建快取或重新下載資料，這是規劃清理時間時需要考慮的成本。Mole 的保護規則可以減少誤操作，但仍要自己確認預覽清單是否包含工作需要的資料。

瀏覽器也要分清楚快取和設定。Chrome 擴充功能的存放位置和一般網頁快取用途不同，不要自行把整個 Chrome 使用者資料夾都當成垃圾刪除。

需要追查剛才做了什麼，可以查看操作紀錄。

mo history
mo history --json

Uninstall 移除 App，也檢查相關殘留

不用的軟體可以交給 Uninstall，一起檢查能明確對應到該 App 的相關檔案。先做預覽，確認選取的是正確程式與版本。

mo uninstall --dry-run

確定要解除安裝後，再執行下方命令並選取 App。

mo uninstall

如果 App 本體早已刪除，改用 mo clean 檢查殘留比較合適。同一套軟體的不同版本可能共用資料，所以「完整移除」不能理解成所有相似名稱的資料夾都應一起消失，仍在使用的共用資料需要保留。

Optimize 與 Status，分別處理維護和觀察

遇到縮圖、搜尋或系統服務異常，可以先預覽 Optimize 的維護項目。它會依系統狀況略過不適用的工作，不能把它當成每台 Mac 都會得到相同效果的加速按鈕。

mo optimize --dry-run

確認項目後才執行實際維護，需要排除的工作可用保護設定管理。

mo optimize --whitelist
mo optimize

只想了解目前 CPU、記憶體、磁碟、網路與電力狀態時，用唯讀的 Status 儀表板即可。按 q 可以離開。

mo status

對跑本地模型的人來說，可以在載入模型前後觀察記憶體壓力，再在生成內容時看 CPU 和磁碟活動。如果空間回收了，運算仍然慢，就應繼續檢查模型大小、同時執行的工作與記憶體，而不是反覆清理相同快取。

開發者可以用 Purge 整理專案產物

許多舊專案占空間，是因為 node_modules、target、build 或 dist 長期保留。Purge 會以專案為單位整理候選項目，先設定要掃描的資料夾，再做預覽。

mo purge --paths
mo purge --dry-run

看清楚清單後，實際清理使用以下命令。

mo purge

Purge 會永久刪除你確認的項目。原則上這些產物能重新建立，但自己的專案可能把手工修改內容或唯一成品放進 build 或 dist，所以仍需先核對。清掉依賴後，下一次開發也要重新安裝，應保留套件清單與 lockfile。

下載資料夾裡的舊安裝包則交給 Installer。先確認是否還需要離線重裝，再決定移除。

mo installer --dry-run

以下會進入安裝包的實際移除流程。

mo installer

Mole 常用命令速查

工作起手命令使用重點
查看空間mo analyze先瀏覽，移除需確認
查看狀態mo status唯讀監控
清理快取mo clean –dry-run先預覽，再執行 clean
移除 Appmo uninstall –dry-run先確認程式與殘留
系統維護mo optimize –dry-run先確認維護項目
專案產物mo purge –dry-run正式執行可能永久刪除
舊安裝包mo installer –dry-run先確認是否仍需保存
Mole 磁碟分析、狀態監控與清理命令速查表
先從查看與預覽開始，再依需要執行對應操作

整合 Raycast，減少每天開終端機的步驟

Mole 官方提供快速啟動器腳本，可以加入 Clean、Uninstall、Optimize、Analyze 與 Status。以下命令請逐行操作，先下載官方腳本，用 less 閱讀內容，按 q 離開閱讀畫面，確認後才執行最後一行。

curl -fsSL https://raw.githubusercontent.com/tw93/Mole/main/scripts/setup-quick-launchers.sh -o setup-mole-launchers.sh
less setup-mole-launchers.sh
bash setup-mole-launchers.sh
  1. 開啟 Raycast Settings，進入 Extensions 的 Script Commands
  2. 新增腳本目錄 ~/Library/Application Support/Raycast/script-commands
  3. 執行 Reload Script Directories 重新載入
  4. 在 Raycast 搜尋 analyze 或 status，開啟相應功能

清理指令仍然會啟動 Mole 本身的操作流程。快速啟動器的價值在於少打字，並不代表能略過對清理範圍的判斷。官方腳本在找到 Alfred 設定時，也會建立對應 workflow。

讓 Codex 協助讀取磁碟報告

Mole 已有 JSON 輸出，適合把資料交給 Codex 整理。可以請 Codex 解釋哪些資料夾占空間，以及哪些是模型、快取、安裝包或專案產物，再由自己決定下一步。

mo analyze --json ~/Documents
mo status --json
mo history --json

可以這樣下提示詞。以下是整理報告的範例，並不會自動開始刪除。

請使用 Mole 的唯讀分析與 JSON 輸出，整理我指定資料夾的空間占用。按模型檔、專案依賴、生成成果與安裝包分類，列出路徑、容量與可能用途。請保留正在使用的模型和唯一成品，先提供清理建議，等我指定項目後再執行刪除。

JSON 報告可能包含使用者名稱與專案路徑。把它交給雲端服務時，就和 Mole 本身在本機掃描是兩個不同的資料處理步驟，可以先限制分析範圍。

更新、移除與常見錯誤

用 Homebrew 安裝的版本，更新時指定 Mole 即可。

brew update
brew upgrade mole

不再需要這個工具時，用原本的套件管理方式解除安裝。

brew uninstall mole

如果用官方安裝腳本安裝，則使用 mo update 更新與 mo remove 移除工具本身。不要把 mo uninstall 和 mo remove 混在一起，前者是管理其他 App，後者是移除 Mole。

遇到 Bundled status binary not found，先確認版本與命令位置。如果原本是 Homebrew 安裝，可用以下方式重新安裝套件，恢復遺失的執行檔。

command -v mo
mo --version
brew reinstall mole

原本使用官方腳本安裝時，依錯誤訊息執行 mo update，或重新執行官方安裝流程。若電腦同時裝了兩個版本，先整理命令搜尋路徑，避免更新了一份，實際卻執行另一份。

FAQ

Mole 可以完全免費使用嗎

CLI 版可以，GitHub 專案採 GPL-3.0 開源授權。原生 Mole for Mac App 是另外的付費產品，兩者的授權和介面不同。

Mole 清理後一定會讓 Mac 變快嗎

不一定。它可以協助回收空間與處理部分維護工作，效能是否改善仍取決於磁碟剩餘空間、記憶體壓力、背景程序和實際工作負載。

Mole 有 Windows 版嗎

主要產品針對 macOS，官方 GitHub 目前另有實驗性的 windows 分支。不要把 Mac 的 Homebrew 命令與清理規則直接套到 Windows，也不要假設兩邊功能完全相同。

Analyze 和 Clean 都會刪除檔案嗎

Analyze 主要供瀏覽分析，選取移除後會確認並移到垃圾桶。Clean 會按清理規則實際刪除資料，第一次操作先使用 dry-run 預覽。

我會怎麼把 Mole 放進日常工作

第一次先跑 Analyze 和 Status，弄清楚容量與資源占用。空間不足時再預覽 Clean，需要移除 App 時用 Uninstall，舊專案交給 Purge。這樣比較容易把每次清理和實際問題對上，也能保留常用模型與工作成果。

我很喜歡 Mole 把路徑、大小與操作結果攤開的方式。對經常下載模型、建立測試專案與輸出影音素材的人，能知道硬碟裡放了什麼，比每次容量不足才四處翻資料夾方便得多。

功能與命令依 Mole 官方文件核對，原生 App 資訊可看 繁體中文官網，清理行為的保護範圍可參考 官方安全說明。

AI 數位人本地部署教學：Qwen3、Qwen3-TTS、LiveTalking 串接

AI 數位人本地部署教學：Qwen3、Qwen3-TTS、LiveTalking 串接

by | 9 月 14, 2026 | AI, QWEN, TTS, 虛擬人, 語音合成, 語音辨識

把 AI 對話、即時語音和會動的人像放在同一台電腦上，現在已經可以做出一套不依賴雲端 API 的互動數位人，用 faster-whisper 聽懂麥克風，讓 Qwen3 產生回答，再交給 Qwen3-TTS 合成聲音，最後由 LiveTalking 完成口型同步與 WebRTC 串流。

先講我的結論。這套方案的價值是隱私、角色控制與離線能力，不是安裝後完全沒有成本。模型權重下載完成後確實不需要按次支付 API 費用，但顯卡、記憶體、硬碟、電力與維護時間仍然是成本，所謂 8GB 顯存能跑，也必須以較小的 LLM、量化權重和分階段載入為前提．若想讓 14B LLM、Whisper large-v3、1.7B TTS 與口型模型同時常駐，16GB 顯存仍可能不夠。

整套本地 AI 數位人怎麼運作

這不是單一模型，而是一條由五個服務組成的即時管線。

  1. VAD 判斷使用者何時開始與停止說話
  2. faster-whisper 把麥克風聲音轉成文字
  3. Qwen3 與 llama.cpp 根據角色設定產生回答
  4. Qwen3-TTS 把回答轉成指定音色的語音
  5. LiveTalking 接收音訊並驅動嘴型，再透過 WebRTC 顯示互動人像

這種模組化做法和我之前整理的 Hugging Face speech-to-speech 本地即時語音 Agent 是同一條思路。每一層都能替換，但每一層也有自己的模型、連接埠與執行環境。LiveTalking 不會自動知道 Qwen3-TTS 在哪裡，兩者中間仍需要官方支援的 TTS 外掛，或一個把生成音訊送到 /humanaudio 的橋接程式。

先算顯存，不要先相信 8GB 宣傳

元件RTX 4090 範例占用低顯存調整
Qwen3-14B Q4_K_M約 9GB改用 8B 或 4B 的 Q4_K_M
faster-whisper large-v3約 3GB改用 medium，準確度會有取捨
Qwen3-TTS 1.7B約 4GB改用 0.6B 或依序載入服務
Wav2Lip 256約 1.3GB降低批次並避免其他 GPU 程式常駐
Qwen3、Whisper、Qwen3-TTS 與 Wav2Lip 的顯存占用比較圖
這是 RTX 4090 整合環境的估計值，不同量化、上下文長度與 CUDA 版本都會改變結果

四個元件加起來約 17.3GB，還沒算 CUDA context、瀏覽器與暫存空間。16GB 顯卡跑到 99% 甚至整台機器失去回應，並不意外。6GB 顯存可以先用 Qwen3-4B 的 GGUF 量化版，並把語音辨識改成 medium。8GB 到 12GB 則適合 Qwen3-8B 搭配較小 TTS，或讓部分元件使用 CPU。若想了解 GGUF、llama.cpp 與 Ollama 的取捨，可以先看 本地大模型推理框架比較。

第一步，在 Windows 準備 WSL 2

這套整合方式把 llama.cpp 放在 Windows，語音與數位人服務放在 Ubuntu 24.04 的 WSL 2。先用系統管理員身分開啟 PowerShell。

wsl --update
wsl --install -d Ubuntu-24.04

Windows 使用者目錄的 .wslconfig 可以設定記憶體與鏡像網路。32GB 是範例，請依實際 RAM 調整，不要把主機記憶體全部交給 WSL。

[wsl2]
memory=32GB
networkingMode=mirrored

[experimental]
hostAddressLoopback=true

修改後重啟 WSL。

wsl --shutdown

進入 Ubuntu 後先用 nvidia-smi 檢查 GPU。NVIDIA 的 Linux 驅動不要再裝進 WSL，CUDA passthrough 由 Windows 顯示卡驅動提供。AMD 顯卡不能照搬這套 CUDA 整合包，需要改走 ROCm 支援的元件，或把無法使用 ROCm 的部分移到 CPU。

專案最好放在 Linux 家目錄，不要直接在 /mnt/c 執行。這能避開 I/O 速度、權限與換行格式問題。

mkdir -p ~/setup
cp -r "/mnt/c/Users/YOUR_NAME/Desktop/AI/." ~/setup/
cd ~/setup
sudo apt update
sudo apt install -y ffmpeg dos2unix python3-venv
dos2unix *.sh
chmod +x *.sh

第二步，用 llama.cpp 啟動 Qwen3

llama.cpp 提供 OpenAI 相容 HTTP 服務，語音管線不必知道底層跑的是 GGUF。16GB 以上可以從 Qwen3-14B 的 Q4_K_M 開始，8GB 到 12GB 建議改成 8B，4GB 到 6GB 則從 4B 測試。

llama-server -m E:\llama.cpp\models\Qwen3-14B-Instruct-Q4_K_M.gguf ^
  -np 1 -c 8192 -fa on --temp 1.0 --top-p 0.95 ^
  --host 0.0.0.0 --port 8090

新版 llama.cpp 文件也開始使用 llama serve 名稱，實際命令要以下載版本為準。Windows 的 8080 有時落在 Hyper-V 保留範圍，所以範例改用 8090。若服務無法綁定，可以先檢查保留埠。

netsh interface ipv4 show excludedportrange protocol=tcp

第三步，安裝即時語音管線

Hugging Face 官方 speech-to-speech 現在以 serve、talk 和 local 為主要命令，舊資料裡的 --mode 已經淘汰。先建立獨立環境，再安裝 faster-whisper 額外依賴。

python3 -m venv ~/venvs/s2s
source ~/venvs/s2s/bin/activate
python -m pip install --upgrade pip
pip install "speech-to-speech[faster-whisper]"

以下範例把 LLM 指向 Windows 上的 llama.cpp。不同版本的 STT 參數名稱可能調整，正式啟動前先執行 speech-to-speech serve --help 對照目前安裝版本。

speech-to-speech serve \
  --stt faster-whisper \
  --stt_model_name large-v3 \
  --language zh \
  --llm_backend responses-api \
  --tts qwen3 \
  --model_name Qwen3-14B-Instruct-Q4_K_M \
  --responses_api_base_url http://127.0.0.1:8090/v1 \
  --responses_api_api_key "" \
  --responses_api_stream \
  --enable_live_transcription

模型全部下載完成後，可以設定 HF_HUB_OFFLINE=1 驗證斷網狀態。這一步比口頭宣稱本地化更可靠，因為只要還有任一個後端指向雲端，就不算完整離線。

第四步，準備 Qwen3-TTS 與參考聲音

Qwen3-TTS 官方最簡單的安裝方式是獨立建立 Python 3.12 環境。它支援聲音克隆、音色設計與串流輸出。更多模型差異和 ComfyUI 節點用法，可以延伸看 Qwen3-TTS 音色設計整理。

conda create -n qwen3-tts python=3.12 -y
conda activate qwen3-tts
pip install -U qwen-tts

參考音訊建議控制在 5 到 15 秒，只留單一說話人，沒有音樂與明顯環境聲。參考文字必須和音訊實際內容完全相同，否則容易出現漏字、錯字與音色漂移。情緒也會一起被模仿，所以不要用過度激動的片段當作一般對話基準。

ffmpeg -i ~/setup/ref.wav -ac 1 -ar 16000 -c:a pcm_s16le ~/s2s/ref.wav
ffprobe -v error -show_entries stream=sample_rate,channels,codec_name \
  -show_entries format=duration -of default=nw=1 ~/s2s/ref.wav

只應克隆自己或已取得明確授權的聲音。把真人聲紋放入公開服務前，也要考慮檔案存取權限、提示注入與未授權冒用。

第五步，製作自然的待機人像

人像素材不適合直接使用張嘴、手擋住嘴巴或劇烈轉頭的畫面。先生成嘴唇閉合、正面或微側面的基準圖，再用 Wan2.2 圖生影片做五秒左右的待機動作。提示詞只描述動作，不要重新描述人物外觀，能減少五官漂移。

電影感 16 比 9 構圖，一位成年東亞女性位於畫面右側三分之一，深色安靜房間，左側保留大量空間，螢幕冷光照亮臉部，輪廓帶柔和暖光，嘴唇自然閉合，雙手不遮擋嘴部，自然皮膚紋理，淺景深，真實攝影質感

負面提示詞

張嘴，說話，露齒，正面平光，明亮背景，過高對比，過度曝光，人物置中，多人，手遮擋嘴部，文字，浮水印，塑膠皮膚，過度修圖，卡通，3D 渲染

待機動畫提示詞

人物保持坐姿，只有細微自然呼吸，緩慢眨眼一次，頭部輕微移動後回到原位，嘴唇全程閉合，鏡頭完全鎖定，沒有縮放，沒有切鏡

關閉自動提示詞增強，輸出比例盡量和原圖相同。Wan2.2 常見原生片段是 81 幀、16 FPS，約五秒。若要二十秒待機，不要期待模型一次生成毫無漂移的長鏡頭，可以在自然停頓點循環短片。其他數位人生成思路可參考 LongCat 數位人工作流。

第六步，安裝 LiveTalking

LiveTalking 官方目前測試的環境是 Ubuntu 24.04、Python 3.12、PyTorch 2.9.1 與 CUDA 12.8。下面命令照官方版本撰寫，但 PyTorch 下載來源仍應配合自己的 CUDA 驅動，不要盲目安裝 cu128。

git clone https://github.com/lipku/LiveTalking.git
cd LiveTalking
conda create -n livetalking python=3.12 -y
conda activate livetalking
pip install torch==2.9.1 torchvision==0.24.1 torchaudio==2.9.1 \
  --index-url https://download.pytorch.org/whl/cu128
pip install -r requirements.txt

下載官方提供的 wav2lip256.pth 後，把它放到 models，並改名成 wav2lip.pth。範例角色資料夾則解壓到 data/avatars。完成後啟動 WebRTC 服務。

python app.py --transport webrtc --model wav2lip \
  --avatar_id wav2lip256_avatar1 \
  --stun 'stun:stun.l.google.com:19302'

瀏覽器開啟 http://localhost:8010/index.html，按下開始連線。正式讓外部裝置使用時，官方提醒需要 TCP 8010 和 WebRTC 使用的 UDP 連接埠。不要直接把整段 UDP 範圍暴露到公網，應優先放在可信任區網、VPN 或經過限制的防火牆環境。

自己製作 Wav2Lip 角色時，可以把短影片轉成 avatar 資料。素材要維持正面可見、光線穩定與嘴部清楚。

python avatars/wav2lip/genavatar.py \
  --video_path data/video/avatar.mp4 \
  --img_size 256 \
  --avatar_id my_avatar

第七步，正確啟動與串接

我會把服務拆成四個終端視窗，照下面順序啟動。每一步都先確認健康狀態，再開下一個服務。

  1. Windows 啟動 llama.cpp，確認 http://127.0.0.1:8090/v1/models 有回應
  2. WSL 啟動 Qwen3-TTS 或 speech-to-speech，先完成單句語音測試
  3. WSL 啟動 LiveTalking，確認 8010 網頁能顯示待機角色
  4. 最後啟動橋接程式，把 TTS 產生的音訊送入 LiveTalking 的 /humanaudio

作者提供的一鍵整合包包含自訂腳本與橋接程式，並不是 Hugging Face、Qwen 或 LiveTalking 的官方發行版。下載前應先檢查檔案來源、雜湊值、啟動腳本和網路連線，不要把未知執行檔直接放進主要工作電腦。想要長期維護，我更建議從官方專案建立環境，再自行補一個最小橋接層。

WebSocket failed 怎麼排查

  • 先確認服務真的啟動。7860、8010 與 8090 是不同服務，瀏覽器頁面存在不代表後端 WebSocket 已連線
  • 檢查 WSL 網路。修改 .wslconfig 後一定要執行 wsl --shutdown，鏡像網路與 hostAddressLoopback 才會重新載入
  • 確認 Windows 防火牆。先只開必要 TCP 埠，在同一台電腦測通後再處理區網
  • 不要混用 localhost。容器、WSL 與 Windows 各自看到的 127.0.0.1 可能不是同一個服務
  • 確認瀏覽器麥克風權限。遠端網頁通常需要 HTTPS 或 localhost 才能取得安全的麥克風權限
  • 降低 Noise Gate。如果網頁已連線但偵測不到聲音，先關閉門檻測試，再逐步調高
  • 調整 VAD 停頓。約 900 到 1200 毫秒比較不容易搶話，但設定越長，回答開始時間也越慢

可以改成真正的 3D 角色嗎

可以，但不是把 Wav2Lip 模型換成一個 3D 檔案就完成。現在這條路線以 2D 影像或待機影片為基礎，口型模型直接修改臉部像素。真正的 3D 角色需要另外加入 Unity、Unreal Engine 或 WebGL renderer，再把 TTS 音訊轉成 viseme、音素或 blendshape 權重，驅動角色的嘴型、表情、眼神與骨架。

保留 VAD、Whisper、Qwen3 與 Qwen3-TTS，替換最後一層即可。新的輸出流程會變成 TTS 音訊、音素時間軸、3D blendshape、即時 renderer。若只是想讓角色有更豐富動作，可以先使用 LiveTalking 的自訂動作設定或多段待機素材，成本會比完整 3D 低很多。

本地不等於沒有風險

角色資料、聲音與對話都留在本機，確實能降低資料送往雲端的風險。但只要把服務開到區網或公網，就要重新考慮驗證、連接埠、惡意音訊、提示注入與檔案上傳。對話記憶也不是安裝完成就會永久存在，長期記憶需要另外接資料庫、摘要或向量檢索，否則聊天變長後仍可能忘記前文或開始胡亂延伸。

LiveTalking 官方也明確要求，使用此專案製作並發布到平台的內容必須包含 LiveTalking 浮水印與標誌。正式商用前要再確認每個模型、角色素材、聲音和整合程式的授權，不要只看程式能不能跑。

官方資源與參考資料

FAQ

8GB 顯存真的可以跑本地 AI 數位人嗎

可以做出可用版本，但不適合讓 14B LLM、large-v3、1.7B TTS 與口型模型全部以高規格同時常駐。建議改用 Qwen3-8B 或 4B 量化版、較小 TTS、較低 batch，必要時把部分模型放到 CPU。

可以完全離線，不使用任何 API 嗎

可以。前提是 STT、LLM、TTS 和數位人全部使用本地後端，而且模型與依賴已下載完成。設定 HF_HUB_OFFLINE=1 並在斷網環境測試，才能確認沒有隱藏的雲端依賴。

可以用英文或其他語言聊天嗎

可以，但 STT、LLM 與 TTS 三層都要支援目標語言。Whisper 與 Qwen3 的多語能力較完整，最終自然度通常由 TTS 音色與參考音訊決定。中英混合時要額外測試專有名詞、數字與語速。

Mac 可以照這篇安裝嗎

不能原封不動照做，因為本文整合路線依賴 Windows、WSL 與 CUDA。llama.cpp、Whisper 和部分 speech-to-speech 元件可以改走 Apple Silicon 的 Metal 或 MLX，但 LiveTalking 口型模型與整合腳本需要另外確認 macOS 支援，不能直接套用 NVIDIA 命令。

最後怎麼選

如果只是想快速聊天，雲端語音助手會更省時間。如果需求是讓私人對話留在本機、建立固定角色、接自己的資料或研究數位人介面，這套模組化管線就很值得做。我的建議是先讓文字對話跑通，再加入 STT 和 TTS，最後才接 LiveTalking。一次啟動所有元件，只會讓錯誤來源變得難以判斷。

真正值得學會的不是某個一鍵包，而是知道聲音在哪裡變成文字，回答在哪裡生成，音色在哪裡被控制，口型又由哪一個服務驅動。把這五層拆清楚後，未來換模型、換角色、換前端，整套系統仍然能繼續使用。