DOOMFLY 安裝教學：把果蠅大腦跑在自己的電腦上打 Doom

Facebook Line Messenger Telegram

果蠅大腦接上 Doom 的那波實驗，九月初剛在開源圈刷完一輪：四組開發者把同一份公開的果蠅神經接線資料接進 Minecraft、Doom、Super Mario 64 與 Beat Saber，遊戲畫面餵給模擬神經元，神經活動再轉成按鍵。這篇帶你做下一步：把其中文件最完整的一個專案 DOOMFLY 裝進自己的電腦，跑出你自己的果蠅腦控制器。

先把終點畫面講清楚。裝好之後，你的螢幕上會有兩個終端機加一個瀏覽器：模擬服務的終端機跑 Python，166,700 個神經元與 2,500 多萬條連線在本機逐步積分；觀看頁的終端機跑介面的開發伺服器；瀏覽器則是觀眾席，即時顯示遊戲畫面與神經讀值。要注意瀏覽器只負責看，官方安裝文件明言整套模擬「不能在瀏覽器或邊緣函式裡執行」，計算全程在你的 Python 環境裡。

文內的指令、檔名與參數，全部對照 2026 年 9 月 9 日的最新提交（commit 71ecf53）與官方安裝文件整理；照這個釘選版本走，就不會被專案後續更新弄亂。Windows 用戶要先有心理準備：官方只提供 macOS 與 Linux 的終端機語法，其餘系統得自行轉換。

成功的畫面長怎樣，以及它證明不了什麼

成功的判準不是角色玩得好。DOOMFLY 的說明文件開頭就把狀態寫死：這是「進行中的實驗訓練，尚未證明學會生存」，目前的 v6 候選模型沒有通過視覺、制約與生存三道驗證。官方給你的驗收點有三個：模擬服務啟動時，終端機印出一行狀態 JSON（status 是 running，附 run_id、condition 與 port）；用 curl 查 /health 有回應；查 /state 時序號持續更新。做到這三件事，「畫面進、神經算、按鍵出」整條路徑就已經接通。

角色在場景裡繞圈、撞牆，都可能是接通之後的正常表現；官方文件對這類檢查的定調很一致：這些是數值與因果的工程檢查，不是技能、學習或自然運動語意的證據。換句話說，「會動」與「學會」是兩件事，而這正是整份專案最值得帶走的觀念。想補齊事件背景與四個專案的對照，可以回頭看我們之前的整理。

預設上場的競技場叫 combat_survival，規則在 baseline 文件裡寫得很具體：開局 100 發子彈，敵人隨時間增補、同時上線以八名為限，彈藥箱撿走後八秒重生，角色死亡當下開新的一局，沒有時間限制；神經狀態跨局延續，但接線權重在 baseline 裡固定不變。看懂這些規則，你才分得清楚哪些是遊戲引擎的環境設定，哪些是神經模型的輸出。

出發前要備齊的環境與三個數字

官方安裝文件開出的前置是：Python 3.11、一個 C++ 編譯器、數 GB 的可用記憶體；觀看頁另需 Node.js 22.13 以上。神經資料有三份，合計約 1.1GB：細胞註記檔約 14.5MB、神經傳遞物質檔約 43.3MB、連接權重檔約 1.05GB。這三個位元組數都寫在原始碼隨附的資料鎖定檔裡，下載前就能把空間估好。

需求檔把版本全部鎖死：brian2 2.5.1、numpy 1.24.4、vizdoom 1.3.0 等，檔頭註解自述這套環境沿用上游發表模型的隔離設定，所以 Python 版本不要隨手換新。另外兩個官方警告值得抄下來：小記憶體的機器不要同時跑多份全量模擬；審計日誌會輪替（單檔 20MB 加四份備份），而且每小時另產生 gzip 封存，要長時間跑之前先確認硬碟空間。

還不想下載 1.1GB？先在瀏覽器看懂這份腦圖

MaleCNS 官網的 Explore 頁面提供兩個免安裝入口。Neuroglancer 場景可以直接在瀏覽器檢視三維資料：em-clahe 圖層是電子顯微影像，按空白鍵能切換顯示；cns-seg 圖層標示神經細胞，官方範例就是把搜尋詞從 DNa01 換成 DP1m，觀察另一類細胞；presyn 與 postsyn 兩個圖層點開後，能看到目前選中神經的突觸前後位置。neuPrint 平台則提供搜尋、形態與連接分析，需要申請帳號取得 token。

MaleCNS 官方網站 Explore 頁面的 Neuroglancer 分頁，左側是三維神經場景檢視器，右側是分割識別清單，下方文字說明 em-clahe、cns-seg 圖層並示範把搜尋詞從 DNa01 換成 DP1m — MaleCNS 官網 Explore 頁的 Neuroglancer 場景：把搜尋詞從 DNa01 換成 DP1m 是官方文件自己寫的入門範例，presyn 與 postsyn 圖層也在同一段說明裡（圖片來源：Janelia）

Neuroglancer 場景還有一批預設關閉的隱藏圖層，用右上角的堆疊按鈕（顯示 6/37）叫出：例如把 FlyWire 與 hemibrain 兩套其他果蠅連接組的神經網格轉換到同一個座標空間對照觀看，或是標示已知資料缺陷的區域。對入門者來說這些先記著就好，真正用得上的是搜尋與圖層開關。另外，官方下載頁還提供程式化路線：用 pip 安裝 neuprint-python，申請帳號拿到 token，就能直接查詢特定神經的註記與連接，不必把整份 1.1GB 的原始資料抓下來。

這兩個入口看的都是結構，還不是動態。資料本身以 CC-BY 授權開放，v1.0 在 2026 年 6 月 8 日釋出；論文 9 月 3 日出刊是另一個時間點，引用時別把兩者混為一談。接下來的安裝，就是把這份結構資料變成會隨時間運算的模型。

建立 Python 環境，下載三份資料並驗雜湊

以下指令都在終端機執行。先取得程式，並釘到本文對照的版本：

git clone https://github.com/nftechie/doomfly.git
cd doomfly
git checkout 71ecf53d78eaffaf1a57ed7b0ccf5d458abc9f33

接著建立專屬虛擬環境，安裝鎖定版本的需求檔。官方把「先升級 pip」排在安裝之前，這個順序有理由：安裝指令用了 –build-constraint 參數，舊版 pip 不認得。

GitHub 上 nftechie doomfly 倉庫 README 的 Run the neural experiment 段落，載明 Python 3.11、C++ 編譯器與數 GB 記憶體的前置需求，並附虛擬環境與鎖定版本需求檔的安裝指令 — DOOMFLY 官方 README 的安裝段落：環境需求、需求檔與下載驗證腳本都在同一頁，文內指令都照這個釘選版本就位（圖片來源：GitHub）

python3.11 -m venv .venv-neural
source .venv-neural/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-neural.txt -r doom/requirements.txt \
  --build-constraint neural-build-constraints.txt

然後是資料。官方 README 內建一段下載腳本（MIT 授權，可直接照抄執行），行為很單純：照 doom/datasets.json 的登錄清單抓檔，已存在的檔案跳過下載，每份都計算 SHA-256，與 data-provenance 目錄裡的鎖定值逐一比對，對不上就中止。跑完之後，connectome_data/malecns_v1/ 底下會出現三個 feather 檔，這一步就是全程最大的下載量。

GitHub 上 doomfly 倉庫 doom datasets.json 檔案頁面，登錄 malecns_v1 資料集的三個檔案 annotations.feather、neurotransmitters.feather 與 edges.feather，各自帶官方下載網址 — doom/datasets.json 是資料的登錄清單：三個 feather 檔的官方來源網址都寫在這裡，下載腳本照它抓檔（圖片來源：GitHub）

建造核心與跑測試：官方自己給了兩份清單

資料就位後，照順序執行四個模組指令，每個成功結束再跑下一個：

python -m doom.connectome malecns_v1
python -m doom.prepare
python -m doom.audit_data
python -m doom.build_kernel

build_kernel 會呼叫 clang++ 把運算核心編成共享程式庫，以原子方式替換舊檔；執行期會拒絕過期或被改動的二進位檔，這是官方文件明寫的防護。模型匯入後保留的規模是 166,700 個神經元與 25,582,938 條有向連線紀錄。順帶一個容易踩的口徑陷阱：研究端介紹常見的「約 1.25 億」指的是突觸接觸點（repo 裡的對應數字是 124,177,617 個 contacts），跟 2,500 多萬條連線紀錄是兩種計法，不要拿來互相比大小。

測試這關，官方有兩份清單。主 README 點名三個檔案：test_doom.py 有 8 個測試函數、test_doom_reference.py 有 1 個、test_doom_live_training.py 有 4 個；而 baseline 參考文件 doom/README.md 的清單把最後一個換成 test_connectome.py（7 個），組合與總數都不一樣。訓練文件另外寫明，整套訓練相關驗證是 28 項測試通過。無論跑哪一份，官方的但書都相同：通過軟體測試，不是生物有效性的證據。

python -m pytest tests/test_doom.py tests/test_doom_reference.py tests/test_doom_live_training.py -q

啟動模擬服務與觀看頁，用兩個端點驗收

開兩個終端機。模擬服務的那個跑 baseline（不加任何學習參數的固定版本，也是預設值）：

python -m doom.server --model baseline --port 8766 \
  --audit-dir outputs/doom/tutorial-baseline

預期輸出是一行 JSON：status 為 running，附 run_id、condition（預設 intact）與 port。服務只綁在本機 127.0.0.1:8766，對外只有 /health 與 /state 這類唯讀查詢端點，沒有遠端控制或寫入介面，這是官方文件寫明的安全邊界。接著驗收：

curl http://127.0.0.1:8766/health
curl http://127.0.0.1:8766/state

/health 回報服務狀態，/state 回報目前的模擬內容。剛啟動時模型還在載入，等服務終端機出現 running 那行再查；連續查詢時，序號或時間應該持續更新。

另一個終端機回到同一個專案目錄，啟動觀看頁：

cd doom-ui
npm ci
echo "DOOM_STREAM_ORIGIN=http://localhost:8766" > .dev.vars
npm run dev

打開終端機顯示的本機網址。這個頁面只向模擬服務取得畫面與讀值，瀏覽器本身沒有在計算神經網路；只開網頁、沒開服務，畫面不會動。觀看頁對過期訊號的處理是直接顯示離線，沒有預錄內容遞補，官方在介面文件裡把這一點寫得很清楚。傳輸設計也誠實：每個牆鐘秒最多擷取八張真實畫面、以一秒為單位打包成不可變更的批次，瀏覽器照原始擷取時間戳播放，延遲約 2.5 秒；頁面上顯示的模擬速度是實測值，不是宣稱值。換句話說，當你的機器算得慢，頁面會老實告訴你慢。

六個官方條件實驗：先問控制依不依賴視覺

跑通之後，最好玩的部分才開始。伺服器內建六個具名消融條件，用 –condition 指定，而且每一幀都會標記當下的條件，紀錄不會混在一起：

條件	官方行為	對照後能回答的問題
intact（預設）	完整視覺輸入	參考組，其餘條件都跟它比
blank_vision	視覺輸入歸零	畫面拿掉之後角色還會動嗎？動作能不能全歸因於當下看到的內容
frozen_vision	視覺凍結在起始畫面	沒有新畫面之後，轉向與移動模式改變多少
retina_disconnected	視網膜細胞的對外連線權重歸零	結構性切斷輸入後，下游還剩多少活動
all_edges_disconnected	全部連線權重歸零	完整的零活動對照；官方測試也用它驗證下游歸零
controls_clamped	神經照常運算，控制輸出鎖在零	把「神經有活動」與「控制有傳輸」拆成兩件事看

對照的原則，官方已經幫你鋪好一半：–seed 的預設值是 41027，直接寫在原始碼裡，不必自己生亂數；同一組 seed 之下每次只改一個條件，再用 –audit-dir 把各次執行的紀錄分開存放，比較才有意義。做法就是停掉目前的服務、換一個條件重啟，例如：

python -m doom.server --model baseline --condition blank_vision --seed 41027 \
  --audit-dir outputs/doom/tutorial-blank

也要記住官方文件反覆出現的立場：單一 seed、單輪執行的差異是工程證據，撐不起生物結論。訓練文件結尾把「宣稱學會生存」需要的證據清單開得很明白：有用的感覺反應、線索特定的制約、搭配凍結與打亂對照的獨立訓練輪、訓練時沒見過的條件下的存活效益，以及記憶保持與記憶消除的檢查。六個條件實驗只是這條長路的起點。

想開學習模式？先看官方自己寫下的紅線

DOOMFLY 有實驗性學習版本，官方開法如下：

python -m doom.server --model experimental-v6 --learning --port 8766 \
  --audit-dir outputs/doom/tutorial-learning \
  --checkpoint-dir outputs/doom/tutorial-learning/checkpoints \
  --checkpoint-seconds 300 --resume

三件事先講在前面。v6 的視覺、制約與生存三道驗證都沒有通過，官方直播頁自標 EXPERIMENTAL 與 UNVALIDATED；訓練文件寫得更直白：改變權重不是成功學習的證明，而且先前的記憶改變在其中一個測試起點上是有害的。學習模式還有硬限制：原始碼規定它必須搭配 intact 條件、關閉額外獎勵、使用預設解碼器，想跟消融條件混用，服務會直接拒絕啟動。至於 checkpoint，它還原的是神經狀態，不是遊戲進度：重啟後競技場開新的一局，被中斷的那一局不計入，官方對這個邊界毫不掩飾。

學習的作用範圍也只有一小塊：多巴胺調控的可塑性規則，作用在 4,184 條既有的 KC 到 MBON11 連線上，其餘接線與控制器全部固定。把它理解成「整顆腦在學習」，是這類展示最常見的誤讀。

卡關時按症狀查

症狀	優先檢查
Source checksum mismatch	該檔下載不完整。移走對應檔案後重跑下載腳本（完整存在的檔會自動跳過），不要關掉雜湊驗證硬繼續
找不到 python3.11	Python 3.11 是否已安裝、是否在搜尋路徑。3.11 是官方指定的版本，換新版本不在文件支援範圍
pip 不接受 –build-constraint	是否先升級過 pip、是否用對 Python 版本；官方把升級 pip 排在安裝前一步
核心編譯失敗或找不到編譯器	C++ 工具鏈是否完整；建置腳本實際呼叫的是 clang++
觀看頁顯示離線	/health 是否回應、模擬服務還在跑嗎、.dev.vars 是否放在 doom-ui 目錄裡
程式被系統終止	記憶體是否不足、是否同時跑了多份全量模擬

還原與隔離的手段都在官方文件裡：–audit-dir 讓每次實驗的紀錄各自獨立；checkpoint 保留兩個原子世代，損壞會被完整性檢查擋下；下載腳本可以重複執行；要整個重來，就照官方的 Reproduce 段落，從建造指令重跑一遍。

授權邊界，以及跑完之後你真正擁有什麼

授權分三層：DOOMFLY 的程式碼是 MIT；MaleCNS 資料是 CC-BY 4.0，改作要標註出處；專案宣告與 id Software、Bethesda、ZeniMax 無關，也不授予任何商標權。遊戲端用的是 ViZDoom 1.3.0 隨附、可自由散佈的場景資產，也就是 Doom 引擎的競技場，不是商業版的戰役內容。

跑完這一套，你擁有的是一個可重現的實驗環境：資料有雜湊、版本有釘選、每一幀有條件標記、每次執行有審計紀錄。起步的目標訂在「能接收刺激、輸出動作，而且能說明差異」，在官方文件的標準裡，這已經是完整的作品規格。想把神經讀值接到自己寫的小遊戲，解碼器的介面與讀值都在 doom/README.md 裡。而「把開源模型搬回自己裝置上跑」這個方向，我們先前介紹過手機離線執行 LLM 的 Google AI Edge Gallery，以及在手機上即時驅動 3D 數位人的 MNN TaoAvatar；DOOMFLY 算是同一條路上最「生物」的一站。

最後一個判斷留給你：六個條件實驗跑完，如果 blank_vision 與 intact 的行為差異小得出乎意料，先懷疑自己的對照設計（seed、輪數、紀錄方式），再懷疑果蠅。這份專案最難得的地方，就是把「如何誠實地自我懷疑」寫成了可以執行的指令。