smallpond：基于 DuckDB 与 3FS 的轻量数据处理框架使用指南

smallpond 是 DeepSeek 开源的轻量数据处理框架，构建在 DuckDB 与 3FS（Fire-Flyer 文件系统）之上，面向 PB 级数据集的高性能处理，无需长期运行的服务即可操作。

一、项目官方信息

二、官方图片

smallpond 仓库社交预览图：

三、环境要求

• Python 3.8 到 3.12；
• 一个 Python 环境即可，pip 安装即用；
• 若要发挥集群性能，配合 DeepSeek 3FS 并行文件系统。

四、部署步骤

1. 安装

pip install smallpond

2. 下载示例数据

wget https://duckdb.org/data/prices.parquet

3. 开发模式

pip install .[dev]
pytest -v tests/test*.py

五、使用方法

快速开始

import smallpond

# 初始化会话
sp = smallpond.init()

# 读取 parquet
df = sp.read_parquet("prices.parquet")

# 按 ticker 哈希重分区
df = df.repartition(3, hash_by="ticker")

# 用 partial_sql 执行 SQL 聚合
df = sp.partial_sql(
    "SELECT ticker, min(price), max(price) FROM {0} GROUP BY ticker",
    df
)

# 写出结果
df.write_parquet("output/")
print(df.to_pandas())

核心特性

• 基于 DuckDB 的高性能数据处理；
• 可扩展到 PB 级数据集；
• 无需长驻服务，操作简单。

性能表现

在 50 计算节点 + 25 存储节点的集群上跑 GraySort 基准，smallpond 30 分 14 秒排序 110.5 TiB 数据，平均吞吐 3.66 TiB/min。

六、常见问题 FAQ

Q1：smallpond 是什么？ 基于 DuckDB 与 3FS 的轻量数据处理框架，面向 PB 级数据。

Q2：怎么安装？ pip install smallpond，支持 Python 3.8–3.12。

Q3：核心 API 有哪些？ init()、read_parquet()、repartition()、partial_sql()、write_parquet()。

Q4：需要常驻服务吗？ 不需要，无长驻服务，脚本式运行即可。

Q5：性能如何？ GraySort 基准下 50+25 节点集群 30 分钟排序 110.5 TiB，吞吐 3.66 TiB/min。

Q6：底层依赖什么？ DuckDB 做计算，3FS 做并行存储。

七、跳转链接

• GitHub 仓库：https://github.com/deepseek-ai/smallpond
• 文档：https://deepseek-ai.github.io/smallpond/
• 3FS：https://github.com/deepseek-ai/3FS