概述

fsspec-bosfs (以下简称 bosfs) 是一个基于 Python 接口的文件系统实现，用以便捷访问百度云对象存储 BOS 服务。通过 bosfs，用户可以使用标准的 fsspec 接口操作存储于 BOS 中的数据。

安装

使用 pip 安装 pyftpdlib

$ pip install bosfs

查看是否安装成功

$ pip show bosfs

快速开始

配置访问凭证

两种方式，优先级如下：

1. 初始化 BOSFileSystem 时通过参数指定

   import bosfs
   fs = bosfs.BOSFileSystem(endpoint='http://bj.bcebos.com', access_key='{your ak}', secret_key='{your sk}', sts_token=None)

2. 配置环境变量

   export BCE_ACCESS_KEY_ID=xxx
   export BCE_SECRET_ACCESS_KEY=xxx
   export BOS_ENDPOINT=xxx

示例：基本读写

1. 通过 bosfs 列举 BOS 上的数据

   import bosfs
   fs = bosfs.BOSFileSystem(endpoint='http://bj.bcebos.com', access_key='xxx', secret_key='xxx')
   res = fs.ls('/mybucket/')
   print(res)

2. 通过 bosfs 读取 BOS 上的数据

   import bosfs
   
   fs = bosfs.BOSFileSystem(endpoint='http://bj.bcebos.com', access_key='xxx', secret_key='xxx')
   with fs.open('/mybucket/README.md') as f:
       print(f.readline())

3. 通过 bosfs 写入数据到 BOS

   import bosfs
   import os
   
   fs = bosfs.BOSFileSystem(endpoint='http://bj.bcebos.com', access_key='xxx', secret_key='xxx')
   object_name = "file1"
   data = os.urandom(10 * 2**20)
   with bosfs.open(object_name, "wb") as f_wb:
       f_wb.write(data)

更多使用方法可参考 fsspec 文档。

示例：Ray

Ray是一个分布式的Python开源库，能帮助用户将自己的程序快速分布式化。在Ray之上运行的PyTorch、TensorFlow等训练器可以利用Ray的特性，在异构集群上做数据预处理、分布式训练，还可以使用Ray Data并行化进行数据加载、预处理和训练。

在Ray上，通过fsspec接口可以直接访问bos上的数据并解析。

1. 生成两个csv文件，上传到bos

Name,Age,Gender,Grade
Alice,14,F,88
Bob,15,M,92
Charlie,14,M,85
David,15,M,90
Eva,14,F,95

Name,Age,Gender,Grade
Fiona,15,F,89
George,14,M,87
Hannah,15,F,91
Ian,14,M,84
Julia,15,F,93

2. 使用ray.data去取csv文件

import bosfs
import ray
import pyarrow
from pyarrow._fs import PyFileSystem

fs = bosfs.BOSFileSystem(endpoint='http://bj.bcebos.com', access_key='xxx', secret_key='xxx')

# 读取mybucket的csv_dir/目录下的多个csv文件
ds = ray.data.read_csv(paths="bos://mybucket/csv_dir/", filesystem=fs)

# 输出数据集的schema
print(ds.schema())

# 输出数据集的记录数
print(ds.count())

# 输出前3行
ds.show(3)

3. 输出

2025-04-03 21:43:28,551 INFO worker.py:1752 -- Started a local Ray instance.
Column  Type
------  ----
Name    string
Age     int64
Gender  string
Grade   int64
10
'Name': 'Alice', 'Age': 14, 'Gender': 'F', 'Grade': 88}                                                                                       
{'Name': 'Bob', 'Age': 15, 'Gender': 'M', 'Grade': 92}                                                                                        
{'Name': 'Charlie', 'Age': 14, 'Gender': 'M', 'Grade': 85}

示例：PyArrow

PyArrow是Apache Arrow库的一个python实现，通过提供高性能的内存列存储格式，可以让应用程序和数据无缝连接。 它实现了不同数据处理系统之间的高效数据交换。 通过将其存储接口委托给fsspec，PyArrow可以通过统一的接口访问各种存储后端。

当然，PyArrow也可以通过bosfs来便捷地访问BOS。

示例1：

import bosfs
import pyarrow
from pyarrow._fs import PyFileSystem
import pyarrow.dataset as ads

fs = bosfs.BOSFileSystem(endpoint='http://bj.bcebos.com', access_key='xxx', secret_key='xxx')

# 读取mybucket的student.parquet文件
ds = ads.dataset("bos://mybucket/student.parquet", filesystem=fs)

# 输出数据集的schema
print(ds.schema)

# 输出数据集的记录数
print(ds.count_rows())

# 输出第一条记录
print(ds.take([0]))

示例2：

import bosfs
import pyarrow
from pyarrow._fs import PyFileSystem
from pyarrow.fs import FSSpecHandler

fs = bosfs.BOSFileSystem(endpoint='http://bj.bcebos.com', access_key='xxx', secret_key='xxx')

# 生成一个PyArrow filesystem
py_fs = PyFileSystem(FSSpecHandler(fs))

# 通过PyArrow filesystem接口读取BOS数据
with py_fs.open_input_file("bos://mybucket/student.parquet") as f:
    f.read()

读写性能

测试环境

• 测试机器：16 核 32G 内存, 3Gbps 网络带宽

性能测试结果

单文件顺序读写性能

多文件并发读写性能

使用限制

• 当前 bosfs 暂不支持 async 模式