在當前眾多 AI 和數據科學應用中，Python 已成為最主流的編程語言之一。為了方便用戶在這些場景中更高效地使用 JuiceFS，我們在社區版 v1.3 中推出了 JuiceFS Python SDK（下文簡稱 Python SDK）。它不僅簡化了對 JuiceFS 的訪問方式，還提升了在受限環境下的可用性。例如在 Serverless 場景中，用戶通常無法自己掛載文件系統，通過 Python SDK，無需掛載即可直接讀寫 JuiceFS 中的數據，極大提升了靈活性。同時，在特定高性能場景下，Python SDK 提供了更優的性能和體驗。

本文將簡要介紹 Python SDK 的功能特性，以及我們在性能方面的一些探索實踐。歡迎社區用戶嘗試這一新功能，并反饋使用體驗和建議。

01 Python SDK 功能概覽

JuiceFS Python SDK 提供了多類接口，從文件操作到生態集成，覆蓋多樣的使用場景。

JuiceFS 客戶端接口

juicefs.Client 封裝了 JuiceFS 客戶端的主要功能。它不僅支持諸如 open、rename 等標準文件系統操作，還提供了如 warmup、summary、rmr 等擴展功能接口，便于開發者實現更復雜的管理需求。

用戶可以通過 Python 的 help() 函數快速查看相關文檔和接口說明，針對每個類和對象都可以單獨查看其方法和用途，從而快速了解其功能。

初始化 JuiceFS 客戶端的方式也非常簡潔。用戶只需傳入文件系統的名稱（name）與元數據地址（meta）兩個參數即可完成初始化。完成初始化后，開發者便可以像使用本地文件系統一樣，列出根目錄內容或進行文件操作。

兼容 Python 原生文件接口

JuiceFS Python SDK 提供的文件操作接口，與 Python 原生的 open() 方法返回的文件對象保持兼容。也就是說，當用戶使用 client.open() 打開一個文件后，返回的對象支持與標準 Python 文件對象一致的操作方法，例如 read()、write()、seek()、close() 等。用戶可以非常方便地將 JuiceFS 的文件系統無縫集成進已有的 Python 代碼邏輯中，而無需額外學習或適配新的 API。無論是在數據預處理、模型訓練，還是日志管理等場景中，都可以直接使用 Python SDK 進行文件讀寫操作。

支持 fsspec 接口，輕松集成 Ray

為了更好地支持 AI 訓練與數據科學等高性能數據處理場景，JuiceFS Python SDK 提供了對 fsspec 接口的原生支持。fsspec 是 Python 生態中用于統一文件系統訪問的標準抽象層，已被廣泛集成到如 Ray 等主流 AI 框架中。

JuiceFS 能夠無縫對接 AI 工具鏈，讓用戶無需修改業務邏輯，即可像操作本地磁盤一樣，便捷地接入 JuiceFS 存儲，在提升 I/O 性能的同時，降低數據管理和擴展成本。

以下是一個典型示例，展示如何將 JuiceFS 作為 fsspec 的后端文件系統使用：

import fsspec

import ray

import sys

sys.path.append('.')

import sdk.python.juicefs.juicefs.spec

jfs = fsspec.filesystem("jfs", auto_mkdir=True, name="myjfs", meta="redis://localhost")

dsjfs = ray.data.read_csv('/ray_demo_data.csv', filesystem=jfs)

dsjfs.count()

只需提供文件系統名稱和元數據地址等必要參數，其余的使用方式則與其他基于 fsspec 的抽象文件系統保持一致。

這一設計進一步提升了 JuiceFS 在如 Ray 等分布式計算框架中的可用性與集成效率，幫助用戶更輕松地將 JuiceFS 融入現有的數據加載與處理流程。

擴展 API

除了常規的文件操作接口，JuiceFS Python SDK 還支持一系列擴展 API，例如 summary、info 等。這些接口在命令行工具中廣泛使用，很多用戶已較為熟悉。

在 Python SDK 中，這些擴展命令的返回結果以字典（dict）形式呈現，便于在腳本中進行訪問與索引。例如，使用 summary 接口時，可以直接通過鍵值方式獲取文件或目錄的統計信息：

summary_info = client.summary("/path/to/dir")

print(summary_info["fileCount"])

這種字典結構的返回形式使得用戶在編寫自動化腳本時更加方便，也更易于集成到現有的 Python 數據處理邏輯中。

02 性能探索：FFRecord 數據加載實踐 3 倍于 FUSE

在使用 FUSE 訪問數據時，單次 I/O 請求的上限為 128KB，即便通過 direct I/O 可提升至 1MB，但一次完整的數據讀取，仍然會被內核切分成多個小塊，造成額外的 I/O 請求放大。 這些小請求是同步串行提交的，在訪問冷數據（即尚未緩存在本地的數據）時，會顯著拉高延遲，降低整體吞吐性能；同時，連續的多個請求還會啟動 JuiceFS 的預讀流程，導致不必要的讀放大。

我們希望通過 Python SDK 繞過 FUSE 的請求粒度限制，支持更大尺寸的請求，避免碎片帶來的性能影響。為了驗證在 Python SDK 的性能表現，我們以幻方開源的數據集格式 FFRecord 為例，設計并實現了一個基于 Python SDK 的 FFRecord 數據加載 demo。FFRecord 是幻方開源的一種數據格式，具有合并小文件、減少讀取開銷、支持隨機批量讀取和數據校驗等優勢。關于 FFRecord 的設計意圖和價值可以參考幻方的一篇博客 。

在使用 FUSE 加載 FFRecord 數據時，遇到的核心問題之一是上文提到的請求粒度受限——FUSE 默認每次最大讀取請求為 128KB。當讀取請求被切分為多個 128KB 的塊，會顯著放大 I/O 延遲。同時，JuiceFS 客戶端在處理連續的讀取請求時，會自動進行一定范圍內的預讀。這會造成 2~4 倍的數據讀放大，進一步增加系統負擔。

為此，我們基于 Python SDK 實現一個 FFRecord dataloader 來優化性能。在我們設計的一組測試中，生成了一個包含 1000 個樣本的數據集，單個 sample 大小約為 3MB±500KB。實驗結果顯示，使用 Python SDK 加載數據，相較于默認的 FUSE 掛載方式，單 worker 和多 worker 場景下的加載性能分別提升了約 3.75 倍和 4 倍。

該 demo 的實現邏輯：底層通過 file_reader 類解析并校驗 FFRecord 文件格式，包括對 sample 和文件頭的處理。header 部分在初始化時加載并按格式記錄所有樣本的 offset 信息，為后續讀取提供支持。此外，file_reader 提供了 read_one 和 read_batch 兩種接口，便于在單樣本或批量樣本讀取時靈活調用，也為后續開發和擴展提供了便利。

在當前 Python SDK 實現中仍存在一些限制，例如不支持并發 read_ batch，只能串行執行。后續會將并發 read_batch 下沉至動態鏈接庫中完成，或在 Python 中實現異步邏輯。此外，在支持 num_workers 并發加載時，需要在每個 worker 進程中初始化 JuiceFS 客戶端實例。這是因為主進程 fork 子進程時，客戶端資源無法共享，因此需要單獨初始化。這一設計雖帶來額外開銷，但總體負擔不大。

上層的 dataset 和 dataloader 實現相對簡單，直接調用底層 reader 即可完成加載流程。我們還提供了一個數據集生成腳本，用于生成 demo.ffr 文件并進行加載，相關代碼都已經整理進社區版代碼庫，供大家參考。

03 Python SDK 安裝

目前，JuiceFS 的 Python SDK 已經在 v1.3-beta1 版本發布。該 SDK 復用了JuiceFS Java SDK中依賴的底層動態鏈接庫，該庫中實現了 JuiceFS 客戶端的核心對象與功能。

在 Python SDK 中，我們通過 Python 接口將這些底層功能進行了暴露，方便用戶直接在 Python 環境中調用。因此，安裝過程并不復雜，主要包括兩個步驟：一是編譯動態鏈接庫，二是打包并安裝 Python 模塊即可。詳情，可參考官網文檔。

04 小結

Python SDK 為 JuiceFS 帶來了更靈活的集成方式，既兼容 Python 原生文件接口，也適配了 fsspec 統一抽象層，能夠更方便地集成到如 Ray 等 AI 組件中使用。在高性能訪問方面，我們在 FFRecord 數據加載這一特定場景進行了探索，初步驗證了它的性能潛力。

完整的示例代碼已提交至社區版倉庫，歡迎大家參考使用。我們也期待更多社區用戶參與試用和反饋，共同推動 Python SDK 能力的持續完善。

希望這篇內容能夠對你有一些幫助，如果有其他疑問歡迎加入 JuiceFS 社區與大家共同交流。

總結

以上是生活随笔為你收集整理的JuiceFS v1.3-beta1：新增 Python SDK，特定场景性能 3 倍于 FUSE的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。