---
# System prepended metadata

title: 實驗流程設計

---

MineStudio 實驗流程設計：Horizon-Aware Low-Level Control in Minecraft
資料收集與標註流程

資料來源： 使用 MineStudio 已下載的多任務資料集（如 minestudio-data-6xx 至 10xx-v110）以及事件序列資料集（EventDataset）作為訓練數據來源。這些資料包含了 Minecraft 中各種任務（如導航、挖掘、合成等）的原始螢幕影像序列及對應的環境資訊和事件標記
hackmd.io
。我們先將原始資料轉換為方便取用的格式（例如 MineStudio 提供的 LMDB 管線），並利用其事件抽取工具擷取出每段包含單一互動任務的片段
hackmd.io
。

一般任務標註： 對於有明確事件結束標記的任務（如 Mine、Craft 等），可以直接依據 EventDataset 中的事件完成時間來確定該互動片段的結束點。接著對這些片段進行「剩餘步數」標註：從每段互動完成的時刻開始反向，給前面的每一幀標記還需要多少步驟（actions）可以結束當前互動。例如，在互動結束前的倒數第 $k$ 帧標記「剩餘 $k$ 步」直到結束，最後一帧（互動完成時刻）標記剩餘 $0$ 步。這種反向重標策略可以為模型提供逐步接近完成時的監督信號
hackmd.io
hackmd.io
。

Navigate 任務額外標註： 對於導航類任務，由於資料中可能缺乏明確的結束事件，我們基於座標位移來定義完成標準
hackmd.io
。利用 RawDataset 中每幀的 meta_info（玩家座標 xpos,ypos,zpos 等），計算玩家相對目標的位移變化。如果玩家在一段連續時間內移動距離超過預定閾值（表示顯著接近目標），我們視其為達到了導航目標的完成事件
hackmd.io
。依據這一定義，自動判定導航片段中的「目標接近」時刻，並同樣以反向方式計算該片段各幀的剩餘步數標記。為了增加標記的準確性，可結合目標物體能見度資訊：例如使用 MineStudio 中的 SAM-2 影像分割與追蹤工具，從互動結束時刻反向追蹤目標物體，標記每幀中目標是否出現在視野中
hackmd.io
。這將用於後續的能見度標註（目標在當前影像中是否可見），作為模型的輔助輸出。

抽窗與右設限： 資料預處理時，我們對每段互動片段從完成點向前截取固定長度的序列窗口。例如每段取長度為 2L 的序列（涵蓋完成時刻往前的 2L 幀）作為一個訓練樣本
hackmd.io
。這樣可以確保樣本序列的末端是互動的完成（或接近完成）狀態。對於長於窗口的互動，超出窗口部分被截斷，此時該樣本的互動在窗口內「未完成」，我們將其標記為右設限（right-censored）樣本
hackmd.io
。也就是說，如果一個窗口沒有包含互動完成事件，則視作在該窗口內任務仍未結束，模型在訓練時需將此情況納入考量。總體而言，透過反向抽窗與重標，我們為每一幀提供了「到互動結束還剩幾步」的監督訊號，並區分了正常完成與截尾（設限）兩種情形，為後續生存分析模型的訓練奠定基礎
hackmd.io
。

模型與 Lightning Module 設計

模型總覽： 我們設計一個 **動作預測模型（APM）** 來實現地平線感知的低階控制
hackmd.io
。模型以 Transformer-XL 為骨幹網路，用於編碼最近一段時間的觀察序列和動作歷史。在每個推理步，模型輸入包括近期的原始 RGB 影像、目標相關的視覺線索（例如目標物件的遮罩或類別）以及互動類型等資訊
hackmd.io
。Transformer-XL 提供帶記憶的順序編碼能力，使模型能夠從時間序列資訊中預測任務尚需的步數。

Logistic-Hazard Head（地平線預測頭）： 在 Transformer-XL 編碼輸出之後，接上一個離散時間生存分析頭部。具體而言，我們採用 logistic-hazard 建模剩餘時間的條件終止機率，即將「在第 $k$ 個時間箱完成」的概率作為預測目標
hackmd.io
。Head 由多個小型 MLP 或等價的線性層組成，每個時間區間（time bin）對應一個獨立的輸出單元，用 sigmoid 函數輸出該區間的危險率 $h_k$（即在尚未結束的條件下於第 $k$ 步結束的機率）
hackmd.io
。這種參數化允許非比例風險，也就是模型對不同時間段的結束概率可學習不同模式，而不強制假設恆定的時間影響
github.com
。透過這些條件機率，我們可以得到任務完成時間的整體分佈：$p(T=k) = h_k \prod_{j<k}(1-h_j)$，以及對應的存活函數 $S(k) = \prod_{j\le k}(1-h_j)$
hackmd.io
。模型最終可以計算出預期剩餘步數 $E[T]$，作為對地平線的估計。此外，我們將輸出的整個分佈用於評估校準度，確保模型不僅預測一個標量，而是給出一個校準過的完成時間分佈
hackmd.io
。

Visibility Head（能見度預測頭）： 除了時間分佈，我們增加一個並行的能見度預測頭。該頭部輸出一個二元分類概率，預測目標物體在當前觀測畫面中是否可見。實現上，可對 Transformer-XL 的隱狀態接一個小型的 MLP 或線性層來輸出能見度標籤。能見度預測作為輔助任務，提供了一種信號來偵測目標是否已出現在視野中（例如導航任務中已看見目的地物件）
hackmd.io
hackmd.io
。這個信號非常重要：它可作為恢復觸發或提前終止的依據——當模型預測目標已可見且剩餘步數概率分佈顯示即將完成時，低階控制器即可決定結束當前動作序列，通知高階系統目標達成；反之，若預測能見度持續為否且剩餘時間預期不斷延長，可能表示陷入停滯，需要觸發恢復動作或讓高層重新規劃
hackmd.io
。

損失函數與右設限支持： 我們採用生存對數似然損失（亦稱 Nnet-survival 方法）來訓練 logistic-hazard head，使其適應有截尾資料的情境
hackmd.io
。對於每一個訓練樣本，我們根據其標記的完成步數或右設限情況構造目標：如果在第 $k$ 幀互動完成，則視第 $k$ 時間箱為發生事件，之前的箱均為生存；若窗口結束時仍未完成（右設限），則視該樣本在所有時間箱中均存活。損失計算上，我們最大化生存Likelihood：$\mathcal{L} = \sum_{\text{事件發生前}} \log(1-h_j) + \text{(事件發生時)}\log(h_k)$，對於右設限樣本則只有前面的存活項
hackmd.io
。這等價於對每個時間箱的二元分類使用交叉熵損失，但以整段序列的對數似然作為目標進行反向傳播
github.com
。此外，我們將能見度預測頭的輸出與對應的能見度標記（由前述影像遮罩追蹤得到）計算二元交叉熵損失，與生存損失加權相加作為總損失。Lightning Module 的 training_step 將執行上述兩部分損失的計算與梯度反傳，使模型同時學習「剩餘步數分佈」和「目標能見度」兩項能力。

時間分箱策略： 由於不同任務的互動長短可能差異較大，我們設計 **「前密後疏」的分箱策略來平衡預測精度和範圍。直觀而言，我們對較短的剩餘時間使用較細的時間刻度，確保模型能精細預測接近完成時的步數；對較長的剩餘時間使用較寬的刻度，以避免過多的參數維度及資料稀疏。【例如】可以將時間軸前段按單步或小區間劃分（例如1步/箱），隨著時間增加逐漸擴大箱長（例如後段用5步、10步為一箱）。這種前密後疏的離散化讓模型在短時地平線上具備高解析度，在長時地平線上仍能覆蓋足夠範圍。** 同時，我們計劃進行等寬分箱作為對照消融實驗，即使用固定長度（等步數）的時間箱來訓練模型，以比較不同分箱方式對模型性能（特別是校準和預測準確度）的影響。

PyTorch Lightning 設計與多GPU支持： 我們將上述模型封裝進 LightningModule 中，以簡化訓練流程管理。LightningModule 將定義模型架構、forward 推理、training_step 和 validation_step 等方法。透過 PyTorch Lightning，我們可以很方便地支援分散式訓練與多 GPU 加速：在實驗中使用兩張 Nvidia A6000 GPU，設定 Lightning Trainer 的 devices=2, accelerator="gpu", strategy="ddp" 即可啟用DDP (Distributed Data Parallel) 訓練。Lightning 會自動處理模型和數據在多卡之間的同步和梯度聚合。我們也會利用 Lightning 的回調與 logging 機制來監控如訓練過程中的 NLL、IBS 等指標，以及在驗證集上的校準曲線等。整體框架將與 MineStudio 已有的訓練工具鏈對接，使用其資料載入和環境模擬介面，但訓練主迴圈由 Lightning 接管以確保多GPU高效運行。

模型測試與 Baseline 比較

離線評估（Offline Evaluation）： 首先在離線資料上評估模型的時間預測表現，並與 MC-Controller (AHP) 模型進行比較。評估指標包括：負對數似然（NLL）－衡量模型對實際完成時間的概率估計的對數損失；整合 Brier 分數（IBS）－評價預測生存曲線在各時間點的平均平方誤差，數值越低表示預測風險越準確；以及校準曲線－檢查預測的完成機率分佈與真實情況的吻合程度
hackmd.io
hackmd.io
。特別地，我們會繪製模型預測的生存機率與實際生存率的對比圖，以觀察模型是否偏向低估或高估完成機率。Baseline 模型 MC-Controller 提供了一個標量預測地平線的方法（Adaptive Horizon Prediction, AHP），我們將其視為對照：透過相同的測試數據，比較我們的**分佈式地平線預測（APM）**在NLL和IBS上的表現是否優於標量方法，並且校準曲線是否更加貼近對角線（即預測概率更為可信）
hackmd.io
。預期我們的方法因為考慮了環境變異和提供了完整分佈，在這些離線指標上將顯著優於 AHP
hackmd.io
。

overshoot 行為分析： 在離線資料中，我們也將分析 overshoot 等不良行為的發生率。Overshoot 被定義為「當互動實際應該結束時，低階控制器仍然繼續執行同樣的原子動作超過必要步數」
hackmd.io
。透過我們的剩餘步數標註，可以精確定位 overshoot 事件（例如當剩餘步數已為0但仍有額外動作執行時）。我們將統計在測試集中 overshoot 事件的頻率，並比較我們的模型與 AHP baseline 的差異
hackmd.io
。預期 AHP 由於只是預測一個標量門檻，可能會導致較多 overshoot（因為預測不準時無法及時停下），而我們的模型透過校準的完成時間分佈，能更早察覺互動應結束，從而減少這類事件
hackmd.io
。

線上整合測試（Online Integration Experiments）： 在線上評估中，我們將把所提模型嵌入 MineStudio 的推理管線，與高階決策模組共同作用，檢驗在任務成功率與效率上的提升情況
hackmd.io
。具體包含兩部分實驗：

ROCKET-1/2 + APM： 將本模型與現有的 ROCKET 系統進行結合測試。ROCKET-1/2 是先前構建的高階任務規劃與低階執行框架，我們將在其中加入 APM 模組調節查詢節奏。對照組採用原本 固定頻率提示 的方式（例如每固定 $n$ 步向高層詢問下一步），實驗組則使用我們自適應的 $k'$ 週期更新機制
hackmd.io
hackmd.io
：高階指令的查詢間隔由模型預測的 $E[T]$ 動態決定，即低階控制器根據預期剩餘步數自我調節執行步數，在預期尚有較多步要走時延長高層查詢間隔，當預期接近完成或出現異常時及時請求高層。評估指標包括高階提示/LLM 調用次數以及最終任務成功率
hackmd.io
。我們將比較使用APM後，高階(Large Language/Visual Model)的調用頻率是否顯著降低，同時任務成功率是否保持或提升。理想情況下，APM 應能在不降低成功率的前提下，大幅減少高層規劃干預次數和 token 成本（LLM輸入輸出字數），驗證其在降計算/延遲成本上的效益
hackmd.io
hackmd.io
。

DEPS + APM： DEPS 是另一種多目標規劃方法，具有子目標選擇機制，會根據每個子任務的預估步數排序執行順序
hackmd.io
。然而原始 DEPS 僅在高層選擇階段使用了地平線預估，低階執行上仍需頻繁輪詢檢查
hackmd.io
。我們將把 APM 整合到 DEPS 框架中，作為低階執行的終止檢查器：在執行每個子目標時，由 APM 實時判斷該子任務是否應該終止或需要恢復/重規劃
hackmd.io
。比較方案包括：原始 DEPS（高層有序子目標 + 低層無終止預測）、加入固定節拍終止檢查的 DEPS（例如每固定步檢查一次，但不使用APM預測）、以及 DEPS + APM 完整方案
hackmd.io
。我們將衡量三者在重新規劃次數（高層因低階執行問題而介入的頻率）、LLM/VLM 調用次數與 token 消耗、以及最終任務成功率上的差異
hackmd.io
。預期 DEPS 在結合 APM 後，因為低階能自行判斷何時結束或恢復，會顯著減少高層 replan 次數和高層指令總調用量，同時成功率提升或至少持平。特別是那些需要長時間連續操作的子任務，APM 的校準地平線感知應能避免拖延或過度執行，從而提升整體效率。

結果評估與可視化： 我們將對上述離線和線上實驗結果進行詳細分析和可視化。例如，繪製校準曲線比較 MC-Controller 的 AHP 與我們 APM 的預測可信度；統計表格列出不同方法的 NLL、IBS；以及任務成功率、平均互動長度、Overshoot率等關鍵指標比較
hackmd.io
hackmd.io
。同時，我們會展示一些具體案例片段：例如某任務中，使用 APM 時低階控制器正確預估還需若干步就能完成而提早停止，相較之下 AHP 版本因預估不准繼續執行導致 overshoot 的畫面。透過這些對比，我們將驗證「分佈式 > 標量」地平線預測的優勢，以及我們所提出的地平線感知在減少高層干預和避免無效行動上的效用
hackmd.io
。

實驗執行細節與環境

硬體環境： 實驗將在實驗室提供的兩張 Nvidia A6000 GPU 上進行。每張 A6000 擁有強大的計算能力和顯存，允許我們訓練較大型的 Transformer 模型並進行分布式訓練。透過 PyTorch Lightning 的 DDP 支持，可充分利用兩張 GPU 進行並行計算，加速模型收斂。同時，確保所有實驗在相同硬體環境下執行，以提供可比的結果。

軟體環境： 已安裝最新版本的 MineStudio 平台以及其所需的 MineDojo 模擬器、依賴庫和內建工具鏈。MineStudio 提供了從資料處理、模型訓練到環境交互的一整套模組，已經在本地配置完畢
hackmd.io
hackmd.io
。我們將使用 Python 3.9 和 PyTorch（Lightning）作為模型實現框架；此外，由於需要高層 LLM 的配合（如 ChatGPT API 等）以及視覺模型，實驗環境中也包含相關的 API 金鑰和模組設定。版本控制方面，我們使用 Git 來追蹤實驗代碼（如LightningModule實現、訓練腳本等），並配合 Hydra/YAML 等配置管理實驗參數，以方便重現每次實驗設定。

資料處理與工具鏈： 得益於 MineStudio 的官方資料模組，我們可以快速進行資料的處理與加載
hackmd.io
。例如使用 MineStudio 已提供的 LMDB 轉換工具將原始影像序列存儲為高效查詢的資料庫，利用事件抽窗功能提取帶標記的互動片段，並用其可視化介面檢查標註的正確性
hackmd.io
。在標註階段需要的影像分割（SAM-2）和Backward Relabel工具，MineStudio/ROCKET 平台中也已實作，我們將直接沿用這些模組來輔助標註和資料增強
hackmd.io
。整體流程從資料讀取、預處理到模型訓練都可以依靠這些現有工具，大大減少開發工作量並確保與先前工作的一致性。

訓練與推理過程： 利用 PyTorch Lightning 進行訓練時，每次 epoch 會迭代 LMDB 資料集中所有抽取的互動序列樣本。我們將根據需要調整 batch size（視 GPU 記憶體而定）來充分利用兩張 GPU 的並行計算能力。在每個 training_step，模型會對一個 batch 的序列進行前向計算，輸出 hazard 分佈和能見度預測，計算對應的生存分析損失和能見度損失，並進行反向傳播和參數更新。Lightning 會自動處理梯度在多GPU之間的同步。在訓練過程中，定期評估驗證集上模型的 NLL、IBS 和校準等指標，並根據這些指標調整超參數（例如時間分箱數量、learning rate 等）。推理時（如在線上實驗中），我們會將訓練好的模型權重載入，然後通過 MineStudio 的推理介面在 Minecraft 環境中執行。推理管線包括：高階系統下發指令→低階 APM 持續根據觀測決定行動並評估剩餘步數→在適當時機（由 APM 判斷或高階超時）結束當前指令執行並反饋結果給高階，然後進入下一輪高階決策。MineStudio 的環境接口將用於重置環境、執行動作並獲取觀測，確保我們的模型可以無縫地作用於真實的Minecraft模擬任務中。

與 MC-Controller Repo 的整合建議

模型架構替換： MC-Controller 專案原本使用自適應地平線預測 (AHP) 作為低階策略的一部分，其特點是在模型中加入一個標量的地平線預測信號
hackmd.io
。我們的整合思路是替換/升級 MC-Controller 中相關部分，將原先預測單一剩餘步數的模組替換為我們的分佈式地平線預測模組 (APM)。實現上，可以在 MC-Controller 的代碼中新增我們的 logistic-hazard head 和 visibility head：例如在其模型定義中（如 SimpleNetwork 類別）使 use_pred_horizon=True 時改為產生多維的 hazard 輸出。我們會擴充原本的 pred_horizon MLP 輸出大小（例如從16維擴展到我們設定的時間箱數量），並修改 forward 過程，讓推理時不再僅取 argmax 作為剩餘步數估計，而是得到整個分佈，用其期望值 $E[T]$ 作為地平線特徵
hackmd.io
。此外，增加一個預測能見度的輸出節點。整體而言，模型的大部分結構（如圖像和目標的融合、動作輸出頭）可與原始代碼保持一致，只是在地平線預測部份進行替換，使之從標量輸出升級為向量分佈輸出
hackmd.io
。

輸入與特徵對齊： MC-Controller 利用了 MineCLIP 等對高階目標文字的編碼，以及遊戲觀察作為模型輸入。我們的模型額外引入了目標物體遮罩作為視覺輔助特徵，以及可能的上一段動作序列資訊
hackmd.io
。為了與 MC-Controller 整合，可考慮利用其現有架構中的 ExtraObsEmbedding 或其他途徑將目標 segmentation 等加入模型輸入維度。例如，在執行導航或互動任務時，如果MineStudio已能提供當前目標的分割遮罩，我們可以將其作為額外的一個圖像通道或特徵拼接到模型輸入（MC-Controller repo 中 use_extra_obs 的管道)
GitHub
。這樣做可以提升我們模型在MC-Controller框架下的表現，同時保持對原架構的改動最小（僅增加額外特徵而不破壞原有功能）。在沒有遮罩的情況下，我們的模型也能僅依賴RGB觀察和高階指令表示進行預測，只是能見度頭的監督可能需要由其他方式判斷（例如根據距離閾值來粗略標記目標是否“可見”）。

訓練策略整合： 我們有兩種方式將 LightningModule 訓練融入 MC-Controller repo：其一是直接在 MC-Controller 原始訓練管線中嵌入我們的模型與損失。這需要修改 MC-Controller 的訓練腳本（如 main.py 或 train 模組），將損失計算部分替換為我們的 survival loss + visibility loss，並確保資料加載使用我們預處理後帶標註的數據（可能格式需要從 LMDB 轉為 MC-Controller 可讀取的形式，如 numpy 張量或 dataset 對象）。由於 MC-Controller 本身也是 PyTorch，整合我們的模型應該相對順利：我們可以參考其 loss.py 來實現生存分析的 loss，確保反向傳播梯度正確傳遞到 hazard head 的每個時間bin參數
github.com
。第二種方式，是保持我們Lightning訓練流程獨立，僅在推理或評估時與MC-Controller互動。比如，我們可先用MineStudio資料訓練APM模型，然後在MC-Controller的推理代碼中調用我們的模型來獲取地平線預測分佈，並將$E[T]$或相應量餵給MC-Controller原本的政策網路。MC-Controller在執行時每步會有觀察輸入，我們可以在其中插入我們模型的計算，然後把得到的地平線特徵替換原本MC-Controller中 horizon embedding 的計算。這種方法幾乎不改動MC-Controller的訓練邏輯，只是在推理時替換了地平線信號的來源。

代碼架構與參數對接： MC-Controller repo 的結構清晰，如 configs 資料夾定義了模型和訓練的參數。我們可以藉由新增一份配置（例如 model=apm.yaml）來定義我們模型相對於原模型的差異，如 use_pred_horizon: true、horizon_bins: N（我們的時間箱數）、use_visibility: true 等。透過此配置，主程式可以識別使用我們的APM模型類型。然後在 src/models 中新增對應的類別（繼承自原SimpleNetwork或LightningModule封裝），在 forward 中實現我們的輸出，同時在 src/utils/loss.py 中新增 survival loss 計算函式，供訓練時調用
hackmd.io
。由於Lightning已經包含許多便利功能，如果希望保持MC-Controller訓練流程簡潔，我們也可以在LightningModule內實現訓練步驟，然後在MC-Controller的train loop中簡單調用Lightning的Trainer.fit()來跑。我們還需要確保使用相同的資料集劃分與評估流程，以公平比較新舊模型。MC-Controller提供的評估腳本（如 parallel_eval.py）可用來對比模型在相同遊戲關卡/任務上的表現。我們將修改其中數據輸出部分，將我們模型預測的分佈指標也打印或保存，方便後續分析校準曲線等。

與高階系統的介面： MC-Controller 本身聚焦於低階控制策略，與高階目標透過MineDojo環境互動。整合APM後，我們需要確保高階指令的交互介面不被破壞。例如，在高階下達一個目標（如“採集木材”）後，MC-Controller會連續執行低階動作直到任務完成或超時。我們的APM可以在此循環中每步提供剩餘步數的預估以及能見度信號。如果我們要更深入結合高階LLM（例如Rocket系統），則需在MC-Controller的主循環中加入我們的k′自調節拍機制：讓MC-Controller在執行低階動作序列時，根據APM的預測決定是否提前終止並反饋高階。這可能涉及在MC-Controller代碼中增加檢查，比如每步或定期計算目前APM的$E[T]$，若低於某閾值或目標已能見則提前終止該回合。由於MC-Controller是open-world多任務架構，為避免衝突，我們可以將這種行為做成可選配置（例如 use_apm_termination: true），僅在需要時啟用。

總之，通過以上步驟，我們能將具地平線感知的低階控制模型平滑地融入MC-Controller的整套系統中
hackmd.io
。這不僅允許直接比較新舊方法的表現
hackmd.io
（證明我們的分佈式預測優勢），也為後續在真實任務中部署提供了一個成熟的代碼基礎。整合完成後的系統預計將在低階決策效率和高階協調上都有明顯改善，為碩士論文的實驗部分提供有力支撐。