ossfs read performance tuning - Object Storage Service - Alibaba Cloud Documentation Center

Tune ossfs parameters to maximize read throughput in read-only workloads.

Important

Applies to ossfs 1.91.3 and later. Get the latest version from Install ossfs.

Read modes

ossfs provides three read modes for different workloads.

Default mode

Best for small files that fit in the page cache and large files with random reads. If AI training image reads perform poorly in direct read mode despite some random read operations, switch to default mode.

ossfs caches file data in both memory and local disk, consuming twice the file size in total cache.

With 6 GB of available page cache for dirty pages, the default mode theoretically supports files up to 3 GB.
Set parallel_count for concurrent downloads and multipart_size for download chunk size.

Direct read mode

Best for sequential reads of large files with limited random access, such as loading large Safetensors files in AI reasoning scenarios.

Enable this mode with the -odirect_read option.
ossfs buffers data within [-direct_read_backward_chunks * direct_read_chunk_size, +direct_read_prefetch_chunks * direct_read_chunk_size]. Defaults: direct_read_chunk_size = 4 MB, direct_read_prefetch_chunks = 32, direct_read_backward_chunks = 1, giving a window of [-4 MB, +128 MB]. Limited random reads are supported. For example, if consecutive Safetensors reads fall within [-32 MB, +32 MB], set -odirect_read_backward_chunks=8 to retain 32 MB before the current offset.
Adjust direct_read_prefetch_chunks and direct_read_chunk_size to increase parallel prefetch and maximize bandwidth.

Hybrid read mode

Best for mixed workloads of small files (cacheable in page cache) and large files with limited random access, such as loading large Safetensors files in AI inference scenarios. For random reads spanning wide offset ranges, default mode performs better.

Enable this mode with the -odirect_read option.
Set direct_read_local_file_cache_size_mb as the threshold to switch to direct read. For example, with 6 GB of page cache, set -odirect_read_local_file_cache_size_mb=3072 to switch when downloaded data reaches 3 GB.
ossfs buffers data within [-direct_read_backward_chunks * direct_read_chunk_size, +direct_read_prefetch_chunks * direct_read_chunk_size]. Defaults: direct_read_chunk_size = 4 MB, direct_read_prefetch_chunk = 32, direct_read_backward_chunks = 1, giving a window of [-4 MB, +128 MB]. Limited random reads are supported. For example, if consecutive Safetensors reads fall within [-32 MB, +32 MB], set -odirect_read_backward_chunks=8 to retain 32 MB before the current offset.
Adjust direct_read_prefetch_chunks and direct_read_chunk_size to increase parallel prefetch and maximize bandwidth.

Recommendations

If ossfs reads and writes the same file simultaneously, use the default read mode.

If ossfs only reads files, or reads and writes different files:

File type	Recommended mode
Only small files	Use the default read mode.
Only large files	For sequential reads or random reads of Safetensors files with narrow offset ranges, use direct read mode. For random reads with wide offset ranges, use the default read mode. If unsure, or if performance remains poor after adjusting direct_read_backward_chunks, use default mode.
Small files and large files	For sequential reads or random reads of Safetensors files with narrow offset ranges, use hybrid read mode. For random reads with wide offset ranges, if unsure, or if performance remains poor after adjusting direct_read_backward_chunks, use default mode.

Note

If direct read or hybrid read mode performs poorly, switch to default mode, which caches data on local disk. Disk I/O then becomes the bottleneck — use a high-performance disk such as ESSD AutoPL with appropriate provisioned and burst performance settings.