3FS README

The project's README from github.com/deepseek-ai/3FS. As one markdown file: README.md.

Fire-Flyer File System

Build License

The Fire-Flyer File System (3FS) is a high-performance distributed file system designed to address the challenges of AI training and inference workloads. It leverages modern SSDs and RDMA networks to provide a shared storage layer that simplifies development of distributed applications. Key features and benefits of 3FS include:

Documentation

Performance

1. Peak throughput

The following figure demonstrates the throughput of read stress test on a large 3FS cluster. This cluster consists of 180 storage nodes, each equipped with 2×200Gbps InfiniBand NICs and sixteen 14TiB NVMe SSDs. Approximately 500+ client nodes were used for the read stress test, with each client node configured with 1x200Gbps InfiniBand NIC. The final aggregate read throughput reached approximately 6.6 TiB/s with background traffic from training jobs.

Large block read throughput under stress test on a 180-node cluster

To benchmark 3FS, please use our fio engine for USRBIO.

2. GraySort

We evaluated smallpond using the GraySort benchmark, which measures sort performance on large-scale datasets. Our implementation adopts a two-phase approach: (1) partitioning data via shuffle using the prefix bits of keys, and (2) in-partition sorting. Both phases read/write data from/to 3FS.

The test cluster comprised 25 storage nodes (2 NUMA domains/node, 1 storage service/NUMA, 2×400Gbps NICs/node) and 50 compute nodes (2 NUMA domains, 192 physical cores, 2.2 TiB RAM, and 1×200 Gbps NIC/node). Sorting 110.5 TiB of data across 8,192 partitions completed in 30 minutes and 14 seconds, achieving an average throughput of 3.66 TiB/min.

3. KVCache

KVCache is a technique used to optimize the LLM inference process. It avoids redundant computations by caching the key and value vectors of previous tokens in the decoder layers. The top figure demonstrates the read throughput of all KVCache clients (1×400Gbps NIC/node), highlighting both peak and average values, with peak throughput reaching up to 40 GiB/s. The bottom figure presents the IOPS of removing ops from garbage collection (GC) during the same time period.

KVCache Read Throughput KVCache GC IOPS

Check out source code

Clone 3FS repository from GitHub:

git clone https://github.com/deepseek-ai/3fs

When deepseek-ai/3fs has been cloned to a local file system, run the following commands to check out the submodules:

cd 3fs
git submodule update --init --recursive
./patches/apply.sh

Install dependencies

Install dependencies:

# for Ubuntu 20.04.
apt install cmake libuv1-dev liblz4-dev liblzma-dev libdouble-conversion-dev libdwarf-dev libunwind-dev \
  libaio-dev libgflags-dev libgoogle-glog-dev libgtest-dev libgmock-dev clang-format-14 clang-14 clang-tidy-14 lld-14 \
  libgoogle-perftools-dev google-perftools libssl-dev libclang-rt-14-dev gcc-10 g++-10 libboost1.71-all-dev build-essential

# for Ubuntu 22.04.
apt install cmake libuv1-dev liblz4-dev liblzma-dev libdouble-conversion-dev libdwarf-dev libunwind-dev \
  libaio-dev libgflags-dev libgoogle-glog-dev libgtest-dev libgmock-dev clang-format-14 clang-14 clang-tidy-14 lld-14 \
  libgoogle-perftools-dev google-perftools libssl-dev gcc-12 g++-12 libboost-all-dev build-essential

# for openEuler 2403sp1
yum install cmake libuv-devel lz4-devel xz-devel double-conversion-devel libdwarf-devel libunwind-devel \
    libaio-devel gflags-devel glog-devel gtest-devel gmock-devel clang-tools-extra clang lld \
    gperftools-devel gperftools openssl-devel gcc gcc-c++ boost-devel

# for OpenCloudOS 9 and TencentOS 4
dnf install epol-release wget git meson cmake perl lld gcc gcc-c++ autoconf lz4 lz4-devel xz xz-devel \
    double-conversion-devel libdwarf-devel libunwind-devel libaio-devel gflags-devel glog-devel \
    libuv-devel gmock-devel gperftools gperftools-devel openssl-devel boost-static boost-devel mono-devel \
    libevent-devel libibverbs-devel numactl-devel python3-devel

Install other build prerequisites:

Build 3FS

Build 3FS in build folder:

# Replace <method> with 'g++10' or 'g++11' based on your environment
cmake -S . -B build \
      -DCMAKE_CXX_COMPILER=clang++-14 -DCMAKE_C_COMPILER=clang-14 \
      -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
      -DSHUFFLE_METHOD=<method>
cmake --build build -j 32

Due to the historical use of std::shuffle, binaries compiled with different compiler versions (e.g., g++10 vs. g++11 +) may be incompatible (issue). To resolve this, you must explicitly specify -DSHUFFLE_METHOD during compilation to lock in a consistent shuffle algorithm:

Build 3FS use Docker

Run a test cluster

Follow instructions in setup guide to run a test cluster.

Report Issues

Please visit https://github.com/deepseek-ai/3fs/issues to report issues.

3FS (deepseek-ai/3FS)

Searching Database…

10.3K ·GitHub
Что это такое?3FS (Fire-Flyer File System) — высокопроизводительная распределённая файловая система, созданная DeepSeek для хранения данных при обучении и инференсе ИИ-моделей в большом масштабе. Она объединяет тысячи SSD и сотни узлов хранения за RDMA-сетью в один общий слой хранения.
Монтировать её как обычную файловую систему или использовать специальный API?Она предоставляет стандартный, хорошо известный файловый интерфейс, который опирается на сервисы метаданных без состояния и транзакционное хранилище ключ-значение вроде FoundationDB, поэтому большинство приложений работает с обычными файловыми вызовами. Отдельный API USRBIO доступен для максимальной пропускной способности.
Как запустить тестовый кластер?Клонируйте репозиторий вместе с подмодулями, установите необходимые зависимости для сборки, соберите 3FS (при желании можно использовать готовые Docker-образы для сборки TencentOS-4 или OpenCloudOS-9), затем следуйте руководству Setup Guide проекта, чтобы поднять тестовый кластер.
Что нужно установить перед сборкой?Нужны libfuse 3.16.1+, FoundationDB 7.1+ и Rust-тулчейн (минимум 1.75.0, рекомендуется 1.85.0+), а также рабочее окружение для сборки на C++/CMake.
Есть ли подводные камни при сборке?Бинарники, собранные разными версиями GCC (g++10 и g++11+), могут быть несовместимы из-за особенностей поведения std::shuffle, поэтому нужно явно задать -DSHUFFLEMETHOD и использовать одно и то же значение на протяжении всего срока работы развёрнутого кластера.
Это для одной машины или нужен целый кластер?Система создана для развёртываний на множестве узлов масштаба дата-центра по InfiniBand/RDMA. В собственном бенчмарке DeepSeek использовались 180 узлов хранения с двумя сетевыми картами по 200 Гбит/с и NVMe SSD, а также более 500 клиентских узлов, поэтому запустить её на одном ноутбуке не получится.
Насколько 3FS быстра на практике?На тестовом кластере из 180 узлов совокупная скорость чтения достигала около 6,6 TiB/s, а бенчмарк GraySort отсортировал 110,5 TiB данных по 8 192 партициям за 30 минут 14 секунд.
Для чего здесь используется KVCache?3FS выступает как более дешёвая альтернатива DRAM с большей ёмкостью для кэширования векторов ключ/значение при инференсе LLM; в тестах DeepSeek пиковая скорость чтения клиентов достигала около 40 GiB/s.
Зачем сочетать RDMA с NVMe SSD?Сочетание RDMA и NVMe позволяет 3FS разделить вычислительные узлы и узлы хранения (CRAQ обеспечивает строгую согласованность), при этом по всему кластеру сохраняется скорость, близкая к локальному диску, а именно это нужно крупным конвейерам обучения и инференса.
What are similar projects?ceph, scylladb, hadoop, redpanda, nebula, kafka, tikv, seaweedfs
Size
6 MB
Stars
10.3K
Updated
CommitMay 07
Age
1y
Commits · 90 Days