【2026 最新】Fugleramme 教學：Raspberry Pi 本機鳥鳴 AI 電子紙圖鑑實作

2026 年 9 月 15 日，一個會「聽鳥」的電子紙畫框登上 Hacker News。到 9 月 16 日抓取時，Show HN 討論串已有 1,173 points、158 則留言；大家追問的不是 AI 多聰明，而是能不能自己做、換到別的地區還認不認得、誤判怎麼調。這篇 Fugleramme 教學就從這三個問題出發。

你不必先買 Raspberry Pi、麥克風或電子紙。本文會先用 fake detector 把軟體管線跑通，再教你選硬體、換成台灣鳥種素材、做誤判 A/B，最後用刷新、耗電、離線、回滾與授權清單驗收。這是一篇給第一次做本機音訊 AI 作品的人看的實作指南；程式指令可以複製，但每一關也會告訴你「看到什麼才算過」。

先說結論：先完成一幅會更新的圖，再追求完美辨識

電子紙鳥圖鑑＝耳朵（BirdNET-Go）＋排版師（Fugleramme）＋畫布（Web／電子紙）。BirdNET-Go 從音訊產生物種事件；Fugleramme 輪詢 API、找插畫並排版；瀏覽器或 Inky 面板只負責顯示。把三段拆開，任何一段故障都不必整套重裝。

• 今天就能完成：在一般電腦用 fake detector 跑 web kiosk，確認鳥種、插畫、標籤與排版會更新。
• 買硬體後才驗：真實收音、BirdNET-Go 推論、電子紙刷新、溫度與牆插耗電；本文沒有把 web smoke test 冒充硬體測試。
• 台灣化的關鍵：先對齊 BirdNET-Go 實際輸出的科學名，再補自有插畫與來源紀錄；只翻譯中文名稱不會自動補出鳥圖。

Fugleramme 教學先懂架構：AI 不直接畫鳥

Fugleramme 官方專案目前的做法很克制：BirdNET-Go 在本機分類聲音，Fugleramme 讀取偵測結果，把科學名映射到既有插畫，最後才產生一張頁面。它不是文字生成圖片，也不會每聽到一次同種鳥就重畫；顯示模式與 refresh floor（最短保持時間）共同決定何時更新。

這種拆法與 AI Agent Harness 的觀念很像：不要讓模型吞掉整個系統責任，而是把輸入、狀態、轉換與輸出做成能個別檢查的介面。若你想看另一個「先模擬、後接硬體」的案例，可對照 Show-Harness × GUMI 模擬器教學。

Fugleramme 教學步驟一：用 fake detector 做零硬體 smoke test

先準備 Git 與 uv。以下固定到 AlphaLab 本次重跑的 commit，避免日後 main 改動後指令與畫面漂移：

git clone https://github.com/arnegiacomo/fugleramme.git
cd fugleramme
git checkout 12b4d9110b70749c194d4e9b40994e01cbcd9c84
uv sync --locked

開第一個終端機，讓 fake detector 在本機模擬 BirdNET-Go：

uv run fugleramme-fake-detector \
  --host 127.0.0.1 --port 18090

再開第二個終端機，把 Fugleramme 指向它：

uv run fugleramme-dev \
  --detector http://127.0.0.1:18090 \
  --host 127.0.0.1 --port 18080

瀏覽器開 http://127.0.0.1:18080/ 看 kiosk，管理頁是 /admin。最後用專案自帶檢查確認 detector API：

uv run fugleramme-check \
  --detector http://127.0.0.1:18090

AlphaLab 在 macOS、Python 3.12.13 上實際完成 uv sync --locked、fake detector、web-only service 與 fugleramme-check；檢查回報物種統計、latest、life list 與語言端點皆可讀，沒有 Inky 硬體時服務仍持續提供 Web 畫面。更新檢查因 GitHub 端回傳 403 而失敗，但沒有讓本機顯示管線停止；這也提醒你把「核心作品可運作」與「能上網檢查更新」分成兩個驗收項目。

Fugleramme 教學步驟二：依成品選 Raspberry Pi 與電子紙

真正容易花錯錢的地方，是把「展示畫面」與「持續分類聲音」當成同一個負載。若家中已有 BirdNET-Go，畫框端只要讀 API；若要一台 Pi 同時收音、推論、排版與驅動面板，才需要完整本機方案。官方目前的 container 文件也明確把它定位為 web-only；要從 SPI 驅動 Inky，應走一般 Raspberry Pi 安裝。

完整方案最該優先投資的是收音與散熱，不是更大的 RAM。麥克風位置、風罩與環境噪音直接影響分類輸入；Pi 5 長時間推論則要保留主動散熱與通風。若你想建立更通用的「模型—硬體—介面」檢查方法，可延伸看 Model Hardware Standard 教學。

步驟三：上 Pi、接 BirdNET-Go，但先讀再跑 installer

官方安裝文件以 Raspberry Pi OS Lite 64-bit、Trixie 或更新版本為基準。與其直接把遠端腳本 pipe 給 shell，先下載、閱讀，再執行：

curl -fsSL \
  https://raw.githubusercontent.com/arnegiacomo/fugleramme/main/install.sh \
  -o install.sh
less install.sh
bash install.sh

安裝器會詢問 BirdNET-Go 是由這台 Pi 管、在同機其他位置，還是在區域網路另一台主機，並設定 Web port、SPI／I2C 與 systemd。新機常需要 reboot 才能驅動面板。完成後先在 BirdNET-Go 管理頁選到正確音訊裝置，再填實際經緯度；位置會影響 range filter，不能沿用專案作者在挪威的範例座標。

步驟四：把台灣鳥種對到正確學名與插畫

先把「台灣會出現哪些鳥」與「目前模型會輸出哪些標籤」分開。中華民國野鳥學會 2026 臺灣鳥類名錄可以當在地候選清單，但真正的檔名必須以你安裝的 BirdNET-Go 輸出為準。Fugleramme 固定 commit 內附的 assets/birdnet_labels_v2.4.txt可先這樣查：

rg -i 'Pycnonotus sinensis|Urocissa caerulea|Passer montanus' \
  assets/birdnet_labels_v2.4.txt

在本文固定的 commit 中，白頭翁 Pycnonotus sinensis、台灣藍鵲 Urocissa caerulea與麻雀 Passer montanus都能在 v2.4 標籤檔找到；但 bundled classic 鳥圖只有麻雀已有對應，前兩者在該目錄未找到。這只是對指定 commit 的檔案盤點，不代表未來版本或其他 artwork style 仍相同。

自訂圖放在 assets/artwork/custom/birds/，檔名要把科學名轉成小寫連字號，例如 pycnonotus-sinensis.webp。先用官方工具預覽，確認透明邊緣、紙色 halo 與比例：

uv run python tools/add_bird.py ~/Desktop/bird.png \
  --species 'Pycnonotus sinensis' \
  --preview /tmp/pycnonotus-preview.png \
  --dry-run

預覽通過後再正式加入。個人畫框的 custom 目錄不會替你檢查來源；只要把圖分享、提交或散布，就要在 manifest.json與 ATTRIBUTION.md留下作者、原圖連結與授權。遇到舊學名時，先查 BirdNET 實際標籤與 Fugleramme alias，不要只改中文顯示名。

步驟五：用環境噪音做 false-positive A/B

誤判測試最常犯的錯，是同時換麥克風、調 threshold、開動態門檻又改位置，最後不知道是哪一項有效。Fugleramme 的初始 BirdNET-Go 範本把 confidence threshold 設為 0.8、overlap 設為 2.2、false-positive filter 設為 level 2、dynamic threshold 關閉，並用 15 秒 interval 抑制同物種重複記錄。這是一個起點，不是全台通用答案。

1. 先固定真值：挑一批你能人工確認「有鳥／無鳥／是哪一種」的片段；無法重播時，至少安排相同時段、相近天候與固定噪音事件，做多輪配對。
2. 先修輸入：移開風口、馬達與道路直達聲，室外麥克風加風罩；輸入被風吹爆時，調模型門檻只是掩蓋問題。
3. 一次改一項：先試 threshold，再試 false-positive filter；每輪保留設定、片段、人工標籤與輸出。
4. 同時看漏接：誤判變少但已知真鳥也消失，不叫改善。用「誤判／小時、已知鳥鳴漏接數、重複通知數」一起比較。
5. 別把 interval 當分類器：它只限制同物種再次記錄的間隔，能減少洗版，不能把摩托車重新判成正確鳥種。

音訊 Agent 也常遇到「管線通了，但輸入品質決定體驗」的問題；想看另一種本機音訊工作流，可讀 Nari × Qwen3-TTS 本機語音 Agent 教學。

步驟六：刷新、耗電、離線與回滾怎麼驗收？

作品掛上牆前，至少跑完以下五關。這裡刻意不給「保證續航幾小時」：麥克風、音效卡、Pi 型號、螢幕與電源轉換損耗都會改變結果，應以牆插量測取代猜測。

1. 刷新：先在 Web 選 Collage、Latest bird、Newest arrival 三種模式，製造同種與不同種事件；確認 panel refresh 是最短保持時間，不是固定倒數計時器。
2. 耗電：連續量至少一個完整日夜，記錄平均功率、峰值、溫度與是否降頻；再用實測平均功率除電池可用瓦時估續航，並保留安全餘量。
3. 離線：模型、字典與插畫完成下載後切斷 WAN，保留區域網路，確認 BirdNET-Go 偵測、Fugleramme 管理頁、Web／面板刷新仍可用；天氣、外部圖片、通知與更新要另外逐項測。
4. 重啟：拔電再開，確認 systemd、音訊裝置、BirdNET-Go 位址與自訂圖都恢復；只在當次 shell 能跑不算完成。
5. 回滾：先記住一個已驗收版本並關閉自動更新；新版有問題時，依官方操作以 git fetch --tags、git checkout <known-good-version>、uv sync、sudo systemctl restart fugleramme-frame回到已知狀態。

如果 Fugleramme 代管 BirdNET-Go，官方更新流程在換 detector 版本前會備份偵測資料庫；但自訂鳥圖、設定與你自己的測試紀錄仍應另做備份。更完整的可重跑思路可搭配 最小 AI Agent Harness 實作。

授權矩陣：MIT 不能蓋過模型、鳥圖與資料

截至 2026 年 9 月 16 日，Fugleramme 程式碼是 MIT；但它串接的 BirdNET-Go repo 目前 LICENSE是 CC BY-NC-SA 4.0，含 NonCommercial 條件。classic 插畫集合、字型、AVONET 體重資料與 OpenFauna 別名也各有條款。若成品要公開展示、打包散布或商用，必須逐層盤點，不能只在頁尾放一句 MIT。

最實際的做法是把官方 classic attribution當範本：每個共享資產都能回到作品、作者、來源與授權。若用途會產生收入，先替換或另行取得 BirdNET-Go 與素材的適用授權，再談產品化。

五個最常踩的坑

1. 先買滿硬體才開機：web-only smoke test 還沒過，電子紙只會多一個難查的變因。
2. 用俗名當檔名：插畫映射依科學名；中文名、英文名與分類修訂都可能讓你找錯檔。
3. A/B 同時改五項：誤判下降也無法歸因，下一次換環境就重來。
4. 把 refresh 或 interval 當排程：前者是面板最短保持時間，後者是同物種重複偵測間隔，兩者都不是「每 N 分鐘必定換圖」。
5. 只看根目錄 LICENSE：程式碼、模型、插畫、字型與資料是不同授權層。

常見問題 FAQ

1. 一定要 Raspberry Pi 5 嗎？

不一定。只做畫框、連外部 BirdNET-Go 時，官方列出 Pi Zero 2 W、Pi 4 與 Pi 5；要同機持續分類時，官方完整方案建議 Pi 5 2 GB 與主動散熱。

2. 沒有電子紙能完成 Fugleramme 教學嗎？

可以。Web kiosk 顯示同一張圖，可先用瀏覽器、HDMI 或另一台裝置驗證；container 目前也走這條 web-only 路徑。

3. BirdNET-Go 能辨識台灣鳥嗎？

先查你的模型標籤，不要用一句「支援／不支援」概括。本文固定的 v2.4 標籤檔可找到多個台灣常見種與特有種，但插畫覆蓋是另一件事；還要用正確地點、真實錄音與本地真值驗收。

4. 它可以完全離線嗎？

核心偵測與顯示應用是本機／自架架構，但「完全離線」要逐項驗。先把模型、字典與素材下載好，再切 WAN 測偵測、資料庫、管理頁與刷新；更新及任何外部整合另算。

5. 可以用行動電源或電池嗎？

可以設計，但不要先猜續航。電子紙維持畫面省電，不代表 Pi 上的持續音訊推論省電；先用牆插量完整日夜，再依電池可用瓦時、轉換損耗與峰值負載估算。

6. threshold 越高越好嗎？

不是。提高門檻通常會同時減少誤判與真鳥命中；先修位置與風噪，再以同一份真值一次改一項。

7. 可以拿來商用嗎？

不能只憑 Fugleramme 的 MIT 就下結論。目前 BirdNET-Go repo 授權含 NonCommercial，鳥圖與資料也有姓名標示／相同方式分享條件；商用前要替每一層取得合適權利。

8. 更新壞掉怎麼辦？

回到你已驗收的 tag。更新前記版本、備份設定與 custom 資產；有問題時 checkout 已知版本、重新 uv sync並重啟 service，確認正常後再決定是否恢復自動更新。

給新手的五個重點

1. 先用 fake detector 證明 API、插畫與版面，再把真實麥克風接進來。
2. 把 BirdNET-Go、Fugleramme、Web／電子紙視為三個可獨立替換與驗收的零件。
3. 台灣化先對科學名與模型標籤，再補鳥圖；中文名只是顯示層。
4. 誤判 A/B 一次只改一項，同時記錄誤判與漏接。
5. 發布或商用前拆開檢查程式、模型、插畫、字型與資料授權。