fastsafetensors is an efficient safetensors model loader.
This library is tested with python 3.9-13 and pytorch 2.1-2.7.
Disclaimer: This repository contains a research prototype. It should be used with caution.
# Features
We introduced three major features to optimize model loading performance:
1. Batched, lazy tensor instantiations
2. GPU offloading for sharding, type conversions, and device pointer alignment.
3. GPU Direct Storage enablement for file loading from storage to GPU memory
A major design difference from the original safetensors file loader is *NOT* to use `mmap`.
It loads tensors on-demand with mmap'ed files,
but unfortunately, it cannot fully utilize high-throughput I/O such as NVMe SSDs.
So, we asynchronously transfer files in parallel to saturate storage throughput.
Then, fastsafetensors lazily instantiates tensors at GPU device memory with DLPack.
Another design change is to offload sharding and other manipulations on tensors to GPUs.
The original loader provides slicing for sharding at user programs before copying to device memory. However, it incurrs high CPU usages for host memory accesses.
So, we introduce a special APIs to run sharding with `torch.distributed` collective operations such as `broadcast` and `scatter`.
The offloading is also applied to other tensor manipulations such as type conversions.
The above two design can be naturally extended to utilize device-to-device data transfers with GPU Direct Storage.
The technology helps to minimize copy overheads from NVMe SSDs to GPU memory with host CPU and memory bypassed.
## Basic API usages
`SafeTensorsFileLoader` is a low-level entrypoint. To use it, pass either `SingleGroup()` for simple inference or `ProcessGroup()` (from `torch.distributed`) for tensor-parallel inference. The loader supports both CPU and CUDA devices, with optional GPU Direct Storage (GDS) support. You can specify the device and GDS settings using the `device` and `nogds` arguments, respectively. Note that if GDS is not available, the loader will fail to open files when `nogds=False`. For more information on enabling GDS, please refer to the NVIDIA documentation.
After creating a `SafeTensorsFileLoader` instance, first map target files and a rank using the `.add_filenames()` method. Then, call `.copy_file_to_device()` to trigger the actual file copies on aggregated GPU memory fragments and directly instantiate a group of Tensors. Once the files are loaded, you can retrieve a tensor using the `.get_tensor()` method. Additionally, you can obtain sharded tensors by `.get_sharded()`, which internally run collective operations in `torch.distributed`.
Important: To release the GPU memory allocated for tensors, you must explicitly call the `.close()` method. This is because Fastsafetensors allows multiple tensors to share a limited number of GPU memory fragments. As a result, it is the user's responsibility to ensure that all tensors are properly released before calling `.close()`, which will then safely release the underlying GPU memory.
`fastsafe_open` is an easier entrypoint. You can force turning off GDS and run in the fallback mode if `nogds==True`. However, users must be aware of the above tricky memory management model, which should be fixed in future releases.
```python
with fastsafe_open(filenames=[filename], nogds=True, device="cpu", debug_log=True) as f:
for key in f.get_keys():
t = f.get_tensor(key).clone().detach() # clone if t is used outside
```
## Code of Conduct
Please refer to [Foundation Model Stack Community Code of Conduct](https://github.com/foundation-model-stack/foundation-model-stack/blob/main/code-of-conduct.md).
## Publication
Takeshi Yoshimura, Tatsuhiro Chiba, Manish Sethi, Daniel Waddington, Swaminathan Sundararaman. (2025) Speeding up Model Loading with fastsafetensors [arXiv:2505.23072](https://arxiv.org/abs/2505.23072) and IEEE CLOUD 2025.
## Install from PyPI
See https://pypi.org/project/fastsafetensors/
```bash
pip install fastsafetensors
```
## Install from source
```bash
pip install .
```
Raw data
{
"_id": null,
"home_page": null,
"name": "fastsafetensors",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Takeshi Yoshimura <tyos@jp.ibm.com>",
"keywords": "fastsafetensors, safetensors, GDS",
"author": null,
"author_email": "Takeshi Yoshimura <tyos@jp.ibm.com>",
"download_url": "https://files.pythonhosted.org/packages/6b/27/23794b8baed8811a9e99364dd7344d828b04daadfc0ed31075d344471414/fastsafetensors-0.1.15.tar.gz",
"platform": null,
"description": "fastsafetensors is an efficient safetensors model loader.\nThis library is tested with python 3.9-13 and pytorch 2.1-2.7.\n\nDisclaimer: This repository contains a research prototype. It should be used with caution.\n\n# Features\n\nWe introduced three major features to optimize model loading performance:\n1. Batched, lazy tensor instantiations\n2. GPU offloading for sharding, type conversions, and device pointer alignment.\n3. GPU Direct Storage enablement for file loading from storage to GPU memory\n\nA major design difference from the original safetensors file loader is *NOT* to use `mmap`.\nIt loads tensors on-demand with mmap'ed files,\nbut unfortunately, it cannot fully utilize high-throughput I/O such as NVMe SSDs.\nSo, we asynchronously transfer files in parallel to saturate storage throughput.\nThen, fastsafetensors lazily instantiates tensors at GPU device memory with DLPack.\n\nAnother design change is to offload sharding and other manipulations on tensors to GPUs.\nThe original loader provides slicing for sharding at user programs before copying to device memory. However, it incurrs high CPU usages for host memory accesses.\nSo, we introduce a special APIs to run sharding with `torch.distributed` collective operations such as `broadcast` and `scatter`.\nThe offloading is also applied to other tensor manipulations such as type conversions.\n\nThe above two design can be naturally extended to utilize device-to-device data transfers with GPU Direct Storage.\nThe technology helps to minimize copy overheads from NVMe SSDs to GPU memory with host CPU and memory bypassed.\n\n## Basic API usages\n\n`SafeTensorsFileLoader` is a low-level entrypoint. To use it, pass either `SingleGroup()` for simple inference or `ProcessGroup()` (from `torch.distributed`) for tensor-parallel inference. The loader supports both CPU and CUDA devices, with optional GPU Direct Storage (GDS) support. You can specify the device and GDS settings using the `device` and `nogds` arguments, respectively. Note that if GDS is not available, the loader will fail to open files when `nogds=False`. For more information on enabling GDS, please refer to the NVIDIA documentation.\n\nAfter creating a `SafeTensorsFileLoader` instance, first map target files and a rank using the `.add_filenames()` method. Then, call `.copy_file_to_device()` to trigger the actual file copies on aggregated GPU memory fragments and directly instantiate a group of Tensors. Once the files are loaded, you can retrieve a tensor using the `.get_tensor()` method. Additionally, you can obtain sharded tensors by `.get_sharded()`, which internally run collective operations in `torch.distributed`.\n\nImportant: To release the GPU memory allocated for tensors, you must explicitly call the `.close()` method. This is because Fastsafetensors allows multiple tensors to share a limited number of GPU memory fragments. As a result, it is the user's responsibility to ensure that all tensors are properly released before calling `.close()`, which will then safely release the underlying GPU memory.\n\n`fastsafe_open` is an easier entrypoint. You can force turning off GDS and run in the fallback mode if `nogds==True`. However, users must be aware of the above tricky memory management model, which should be fixed in future releases.\n\n```python\nwith fastsafe_open(filenames=[filename], nogds=True, device=\"cpu\", debug_log=True) as f:\n for key in f.get_keys():\n t = f.get_tensor(key).clone().detach() # clone if t is used outside\n```\n\n## Code of Conduct\n\nPlease refer to [Foundation Model Stack Community Code of Conduct](https://github.com/foundation-model-stack/foundation-model-stack/blob/main/code-of-conduct.md).\n\n## Publication\n\nTakeshi Yoshimura, Tatsuhiro Chiba, Manish Sethi, Daniel Waddington, Swaminathan Sundararaman. (2025) Speeding up Model Loading with fastsafetensors [arXiv:2505.23072](https://arxiv.org/abs/2505.23072) and IEEE CLOUD 2025.\n\n\n## Install from PyPI\n\nSee https://pypi.org/project/fastsafetensors/\n\n```bash\npip install fastsafetensors\n```\n\n## Install from source\n\n```bash\npip install .\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "High-performance safetensors model loader",
"version": "0.1.15",
"project_urls": {
"Repository": "https://github.com/foundation-model-stack/fastsafetensors"
},
"split_keywords": [
"fastsafetensors",
" safetensors",
" gds"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a270bd6cea1c2117747f01bf31cc803bf2fcaab9eccef8c1b3fc51a7ec71b9c0",
"md5": "a1601479246c408b70773094a81a6426",
"sha256": "e883b40c6edd655dedf187bfd88f7555e155dd203cf1a0459e0394c4e81e0ea4"
},
"downloads": -1,
"filename": "fastsafetensors-0.1.15-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "a1601479246c408b70773094a81a6426",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.9",
"size": 1571206,
"upload_time": "2025-07-18T07:15:45",
"upload_time_iso_8601": "2025-07-18T07:15:45.125976Z",
"url": "https://files.pythonhosted.org/packages/a2/70/bd6cea1c2117747f01bf31cc803bf2fcaab9eccef8c1b3fc51a7ec71b9c0/fastsafetensors-0.1.15-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0f1507b1fafa944b20a580177f38433558891fcec924637d18f6906e583f75b0",
"md5": "27febe31d8e4a61b888f52d7955379d5",
"sha256": "df8d9202fea6cf417989c0dd9fdb72578ece6ab7aa3f0d20a228a051c2847d34"
},
"downloads": -1,
"filename": "fastsafetensors-0.1.15-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "27febe31d8e4a61b888f52d7955379d5",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.9",
"size": 1589512,
"upload_time": "2025-07-18T07:15:47",
"upload_time_iso_8601": "2025-07-18T07:15:47.566589Z",
"url": "https://files.pythonhosted.org/packages/0f/15/07b1fafa944b20a580177f38433558891fcec924637d18f6906e583f75b0/fastsafetensors-0.1.15-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c79e281d3ad961869444bfbcb2fb5f90b95533b1cbccd1f05dfe9faff61da95d",
"md5": "51af2e824d45c09ce702c6f58898190b",
"sha256": "67d5833682082c505352fdafff51ca648328354bab9dce1fec68dbdb32c32a53"
},
"downloads": -1,
"filename": "fastsafetensors-0.1.15-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "51af2e824d45c09ce702c6f58898190b",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.9",
"size": 1618465,
"upload_time": "2025-07-18T07:15:49",
"upload_time_iso_8601": "2025-07-18T07:15:49.732004Z",
"url": "https://files.pythonhosted.org/packages/c7/9e/281d3ad961869444bfbcb2fb5f90b95533b1cbccd1f05dfe9faff61da95d/fastsafetensors-0.1.15-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d3261809e145eb47ff24fe1687636112c724d15d30f7c93240f8529c287dd757",
"md5": "ae6e1d63ad5361a41026840d9eeec540",
"sha256": "0640e2aee484405e5ff36847d31db897103d4e2108e4e622d558dd69e39d2e91"
},
"downloads": -1,
"filename": "fastsafetensors-0.1.15-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "ae6e1d63ad5361a41026840d9eeec540",
"packagetype": "bdist_wheel",
"python_version": "cp313",
"requires_python": ">=3.9",
"size": 1618832,
"upload_time": "2025-07-18T07:15:51",
"upload_time_iso_8601": "2025-07-18T07:15:51.879803Z",
"url": "https://files.pythonhosted.org/packages/d3/26/1809e145eb47ff24fe1687636112c724d15d30f7c93240f8529c287dd757/fastsafetensors-0.1.15-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d217a1cb8b7d99a22120c9ad62fdad71aa4db014f367c7615411a6a913b24955",
"md5": "8f119b886c25430259c6e34653d42af0",
"sha256": "ffeea735311828a5dd2b76399744befdfd36efbc49ab48af7430f984456aa9a5"
},
"downloads": -1,
"filename": "fastsafetensors-0.1.15-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "8f119b886c25430259c6e34653d42af0",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 1567005,
"upload_time": "2025-07-18T07:15:54",
"upload_time_iso_8601": "2025-07-18T07:15:54.315417Z",
"url": "https://files.pythonhosted.org/packages/d2/17/a1cb8b7d99a22120c9ad62fdad71aa4db014f367c7615411a6a913b24955/fastsafetensors-0.1.15-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6b2723794b8baed8811a9e99364dd7344d828b04daadfc0ed31075d344471414",
"md5": "e4ba0d4d4bc214ff8a1643b36b0dbf12",
"sha256": "7e1551fa5050b24477a5c3b7ee1c5d2e2198a6c1a10b4d10966f9d832acfd457"
},
"downloads": -1,
"filename": "fastsafetensors-0.1.15.tar.gz",
"has_sig": false,
"md5_digest": "e4ba0d4d4bc214ff8a1643b36b0dbf12",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 38930,
"upload_time": "2025-07-18T07:15:55",
"upload_time_iso_8601": "2025-07-18T07:15:55.487444Z",
"url": "https://files.pythonhosted.org/packages/6b/27/23794b8baed8811a9e99364dd7344d828b04daadfc0ed31075d344471414/fastsafetensors-0.1.15.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 07:15:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "foundation-model-stack",
"github_project": "fastsafetensors",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "fastsafetensors"
}
JSON
