下載與安裝

SAMFIT 在你自己的機器上跑，所以要先把它裝起來。以下是每一步，以及這台機器需要具備什麼。

最低需求

裝好之後開啟「系統設定」頁按一次硬體檢測，SAMFIT 會實際量這台機器：模型載入時間、單張編碼、一次提示、推論的 VRAM 峰值、資料碟寫入速度，然後告訴你能不能標註、能不能追蹤影片、該用哪一種訓練配方。上面那些 VRAM 數字是門檻比對，不是猜的。

訓練的 VRAM 峰值與每步耗時要按「含訓練步數」那顆按鈕才會量，因為它會真的跑兩個訓練步、佔用顯示卡約二十秒。標準檢測不會動到訓練路徑。

下面的安裝步驟只裝 SAMFIT 自己的相依套件。模型與工具鏈要先就位，否則第 4 步會停在檢查。

SAM 3 本體

這是模型本身，SAMFIT 只是包在外面的工作室。先照 Meta 在 github.com/facebookresearch/sam3 的說明，把 sam3 裝進一個 Python 3.12 環境。下面這行要能印出版本號才算成功。

python -c "import sam3; print(sam3.__version__)"

基礎權重的存取權

facebook/sam3 在 Hugging Face 上是受管制的權重庫。先用瀏覽器開那一頁接受授權條款，再在本機登入，否則第一次載入模型會停在下載階段的授權錯誤。這一步很容易被忽略，因為它不是「安裝」而是「授權」。

python -m pip install "huggingface_hub[cli]"
hf auth login

基礎權重約 3 GB，第一次載入模型時才會下載，所以那一次會明顯比之後慢。

Node.js 與 pnpm

網頁介面需要它們。啟動腳本第一次會自動執行 pnpm install，但不會替你安裝 pnpm 本身。

node --version
npm install -g pnpm
pnpm --version

ffmpeg 與 ffprobe

只有要處理影片時才需要，而且兩個都要。官方的 ffmpeg 套件本來就含 ffprobe，只要確認兩個都在 PATH 上。

ffmpeg -version
ffprobe -version

1. 取得原始碼
從 GitHub 取得，之後更新只要再拉一次。
```
git clone https://github.com/chaoyunghuang/samfit.git
cd samfit
```
2. 安裝相依套件
在已經裝好 SAM 3 的那個 Python 環境裡，補上網頁層與訓練層需要的套件。用的必須是同一個直譯器，否則後端會找不到 sam3。
```
python -m pip install -r backend/requirements.txt
```
3. 允許執行本機腳本
Windows 預設不執行 .ps1。下面這行只影響目前這個視窗，不會更動系統設定。
```
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
```
若不想改動任何原則，也可以直接用 powershell -ExecutionPolicy Bypass -File .\start.ps1 啟動。
4. 啟動
腳本會依序檢查環境、起後端、等待健康檢查、第一次執行時安裝前端相依、起前端，然後開瀏覽器。
```
.\start.ps1
```
工作室在 http://localhost:3000，後端在 http://127.0.0.1:8770。
5. 登入並配對這台機器
在這個網站的「我的帳號」頁按「配對新機器」取得一枚裝置權杖，只會顯示一次。接著在本機工作室開啟「系統設定」頁，右側「配對這台機器」面板有貼上的欄位。
```
http://localhost:3000/settings
```
貼上時會立刻向這個網站驗證，權杖不對當場就會說。配對後只會回報硬體能力，影像、標註與專案內容都不會離開你的機器；面板上的「會送出哪些資料」可以逐欄看到實際內容。

顯示卡驅動與 CUDA Toolkit 請從 NVIDIA 官方取得，這個網站不轉發驅動安裝檔。 SAMFIT 會偵測你目前的驅動與 CUDA 版本並判讀是否符合需求，不符時會指出要裝哪一版。

「因為這個系統上停用指令碼執行」: 就是第 3 步。開一個新的 PowerShell 視窗，先執行 Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass，再跑 start.ps1。
「Could not find the sam3 environment」: 啟動腳本預設去找 %USERPROFILE%\.conda\envs\sam3\python.exe。若你的環境不在那裡，把 SAMFIT_PYTHON 設成那個直譯器的完整路徑再啟動。
「Backend dependencies are missing」: 第 2 步裝到了別的環境。用腳本印出來的那個 python 重跑一次 pip install，路徑要一模一樣。
pnpm 找不到: 前端相依沒辦法自動安裝。先 npm install -g pnpm，再重新執行 start.ps1。
第一次載入模型停在 401 或 403: 基礎權重在 Hugging Face 上受管制。用瀏覽器開 huggingface.co/facebook/sam3 接受授權條款，再執行 hf auth login，然後重試。
設定頁一直說找不到 SAM 3 原始碼: 只用 pip 裝套件時會這樣。SAMFIT 另外會看 SAM3_REPO 指向的原始碼目錄；把它設成你的 sam3 檢出路徑就會消失。只是標註與推論不受這個警告影響。
權杖貼上後說被拒絕: 權杖只顯示一次，重新整理後就看不到了。回到「我的帳號」撤銷舊的、配對一枚新的即可。