跳至主要内容

MPK 合約

MPK 是嵌入在已編譯的模型封存檔中的推論合約。它是一個名為 mpk.json 或 *_mpk.json 的 JSON 檔案，路由規劃器和後續提取器會讀取該檔案。模型封存檔本身是普通的 .tar.gz 檔案，透過 Model 載入。

此頁面將兩個概念分開：

  • 封存檔 — 一個 .tar.gz 發布單元，包含二進位檔案、設定檔、權重和 MPK 合約 JSON。
  • 合約 — *_mpk.json JSON 檔案，它是推論路由的權威來源。

有關位元級合約和安全規則，請參閱 MPK 合約（貢獻者參考）。

為什麼要使用單一 .tar.gz 封存檔​

在 Modalix 上的模型有很多不同的部分（已編譯的 MLA 圖、CVU 核心、設定檔、權重）。將它們打包到一個經過簽名的 .tar.gz 封存檔中，意味著：

  • 原子性 — 要嘛整個模型都載入，要嘛完全不載入。
  • 版本控制 — MPK 合約宣告其結構描述版本；不相容的合約會在早期被拒絕。
  • 來源 — 一個成品，用於計算檢查總和、簽名和發布。
  • 可重現性 — 在給定相同的封存檔和 MPK 合約的情況下，框架的規劃器會做出相同的路由決策。

MPK 合約是唯一的權威 JSON​

模型封存檔可能包含其他 JSON 檔案；框架僅將 mpk.json 或 *_mpk.json 視為推論合約。不要從封存檔中的其他 JSON 推斷模型拓撲 — 合約的規則是「如果不在 MPK 合約中，則該項目不存在」。

此規則可確保框架的規劃器具有確定性。

載入模型封存檔​

應用程式不會直接呼叫封存檔載入器 API。使用 .tar.gz 路徑建構 Model；Model 會執行封存檔驗證、將安全的內容提取到內部佈局中、解析 MPK 合約，然後執行路由規劃。

僅接受完全小寫的 .tar.gz 模型封存檔。在檢查封存檔之前，會拒絕 .mpk、.tgz、.tar 和單獨的 .gz 檔案。

安全防護​

由於模型封存檔來自系統外部，因此載入採用預設拒絕策略。每個接受的封存檔都會通過嚴格的矩陣測試。

  1. 擴展允許清單 — 僅接受 .tar.gz 格式。
  2. 大小限制 — 封存檔、條目和總體 JSON 位元組限制。
  3. 條目數量限制 — 防止類似「zip炸彈」的封包。
  4. JSON 深度限制 — 防止解析器堆疊耗盡。
  5. 路徑遍歷保護 — 正規化的路徑會拒絕絕對路徑和 .. 區段。
  6. UTF-8 驗證 — 條目路徑必須是有效的 UTF-8。
  7. Unicode 混淆字元拒絕 — 視覺上容易混淆的路徑字元會被拒絕。
  8. 檔案類型允許清單 — 僅提取已知的檔案類型。
  9. JSON 重複鍵拒絕 — 在任何深度重複的鍵都會被拒絕。
  10. 結構描述驗證 — 合約和載入器端的元資料必須與受支援的結構描述相符。
  11. 必要區段驗證 — 必須存在推論合約和模型二進位檔。
  12. 核心允許清單 — 參考的核心必須位於框架的已知集合中。

較高層級會將失敗報告為 NeatError，並帶有結構化的 io.* 或 mpk.* 錯誤碼。

相關類型​

  • Model — 公開的進入點，用於載入 .tar.gz 模型封存檔，並公開路由片段。
  • MpkContract 和相關的內部結構 — 從 mpk.json / *_mpk.json 解析的推論合約。

更多資訊​

  • MPK 合約（貢獻者參考） — 位元組級別的規則和欄位語義。
  • 「MPK 合約」 — 設計深入探討的 §0.16 和 §15。
  • 「模型封存檔安全矩陣」 — 設計深入探討的 §91。