Registry / ai-ml / runai-model-streamer

runai-model-streamer

JSON →
library0.16.1pypypi✓ verified 22d ago

The Run:ai Model Streamer is an open-source Python SDK designed to accelerate the loading of large AI models onto accelerators, such as GPUs or TPUs. It achieves this by streaming tensors directly from various storage locations (local, S3, GCS, Azure Blob Storage) to GPU memory, bypassing local disk buffering, and optimizing for the SafeTensors file format. The current version is 0.15.8, with releases occurring somewhat regularly, indicating active development.

pip install runai-model-streamer
INSTALL
IMPORT
SIG · RUNAI-MODEL-STREAM
R
runai-model-streamer
ai-mlpythonv0.16.1
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.16.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
4/5 runs
py 3.11
✕ build_error
4/5 runs
py 3.12
✕ build_error
4/5 runs
py 3.13
✕ build_error
4/5 runs
py 3.9
✕ build_error
3/5 runs
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

SafetensorsStreamer
from runai_model_streamer import SafetensorsStreamer

This quickstart demonstrates how to use `SafetensorsStreamer` to initiate streaming of a model. It creates a dummy `safetensors` file for a runnable example. For actual use, `file_path` should point to your model. When working with cloud storage (S3, GCS, Azure), ensure the respective `runai-model-streamer-*` package is installed and authentication environment variables (e.g., `GOOGLE_APPLICATION_CREDENTIALS` for GCS, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` for S3, `AZURE_CLIENT_ID` for Azure) are correctly configured. The `stream_file` method starts the streaming process, and `get_tensors()` can then be used to retrieve tensors.

import os from runai_model_streamer import SafetensorsStreamer # This is a placeholder for a safetensors file. In a real scenario, # 'model.safetensors' would be a path to your model file. # For a runnable example, you might create a dummy file or adapt to a real path. # If streaming from cloud storage, ensure appropriate backend package is installed # and environment variables for authentication are set (e.g., GOOGLE_APPLICATION_CREDENTIALS for GCS). # For local testing, ensure 'model.safetensors' exists or is mocked. # Example of creating a dummy safetensors file for local quickstart demonstration try: from safetensors.torch import save_file import torch dummy_tensor = {'tensor_key': torch.randn(10, 10)} save_file(dummy_tensor, 'model.safetensors') file_path = "model.safetensors" print(f"Attempting to stream from: {file_path}") with SafetensorsStreamer() as streamer: streamer.stream_file(file_path) print("Successfully started streaming.") # In a real scenario, you would then iterate and process tensors: # for name, tensor in streamer.get_tensors(): # gpu_tensor = tensor.to('cuda:0') # Or another accelerator # print(f"Streamed tensor: {name}, shape: {gpu_tensor.shape}") print("Streamer context closed.") except ImportError: print("To run this quickstart with a dummy file, install 'safetensors' and 'torch':") print("pip install safetensors torch") print("Alternatively, replace 'model.safetensors' with an actual path to your model file.") except Exception as e: print(f"An error occurred during quickstart: {e}") print("Ensure the file_path is correct and necessary system libraries (libcurl4, libssl1.1_1) are installed.") print("If streaming from cloud storage, verify environment variables for authentication are set.")
Debug
Known issues
breakingThe C++ backend of the streamer requires specific system libraries: `libcurl4` and `libssl1.1_1`. Without these, the Python SDK will not function correctly, leading to runtime errors during model streaming. This is a common installation footgun, especially in minimal container environments.
fix
Ensure `libcurl4` and `libssl1.1_1` are installed on your system or within your container image. For Debian-based systems, this typically involves `sudo apt-get install libcurl4-openssl-dev libssl-dev` (or similar packages matching the required versions).
affects: All versions
gotchaWhen streaming from cloud object storage (S3, GCS, Azure Blob Storage), specific `runai-model-streamer-*` backend packages (e.g., `runai-model-streamer-gcs`) must be installed in addition to the core `runai-model-streamer` package. Furthermore, proper authentication credentials must be configured via environment variables or service account files for the SDK to access the storage buckets.
fix
Install the relevant backend package (`pip install runai-model-streamer-[gcs|s3|azure]`). Configure environment variables such as `GOOGLE_APPLICATION_CREDENTIALS` (for GCS), `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` (for S3), or `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET` (for Azure). Refer to the documentation for specific authentication methods.
affects: All versions
deprecatedOlder versions of `runai-model-streamer` used with vLLM, particularly with `tensor-parallel-size > 1`, exhibited pickling errors or issues with distributed streaming across multiple GPUs. This primarily affected distributed loading.
fix
Upgrade to `runai-model-streamer` version 0.15.x or later. Ensure `vllm[runai]` is updated. When using `vllm serve`, include `--model-loader-extra-config '{"distributed":true}'` for optimal distributed loading from object storage.
affects: < 0.15.x (specifically before fixes for #11819 and #130 on GitHub)
gotchaThe `Run:ai Model Streamer` is primarily optimized for the `SafeTensors` file format, which enables efficient zero-copy loading directly from storage. While it may handle other formats, performance benefits are most pronounced with `SafeTensors`.
fix
Store your AI model weights in the `SafeTensors` format for maximum performance. Tools and libraries like Hugging Face's `safetensors` facilitate saving models in this format.
affects: All versions
gotchaSetting environment variables like `RUNAI_STREAMER_CONCURRENCY` and `RUNAI_STREAMER_MEMORY_LIMIT` can significantly impact performance and resource consumption. Incorrect tuning can lead to suboptimal loading times or out-of-memory issues.
fix
Carefully tune `RUNAI_STREAMER_CONCURRENCY` (number of OS threads for reading) and `RUNAI_STREAMER_MEMORY_LIMIT` (CPU buffer size) based on your specific model size, available CPU memory, and network bandwidth to object storage. Refer to the official documentation for guidance on these tunable parameters and their impact on performance.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'runai_model_streamer'
The 'runai-model-streamer' package is not installed in the current Python environment or is not accessible.
fix
pip install runai-model-streamer
ImportError: No module named 's3fs'
You are attempting to stream a model from an S3 bucket, but the necessary 's3fs' backend package was not installed along with 'runai-model-streamer'. (Similar errors occur for 'gcsfs' or 'adlfs' for GCS/Azure respectively).
fix
Install 'runai-model-streamer' with the relevant cloud storage extra: 'pip install runai-model-streamer[s3]' for S3, 'pip install runai-model-streamer[gcs]' for GCS, or 'pip install runai-model-streamer[azure]' for Azure.
safetensors.safetensors_rust.SafetensorsError: Error while deserializing header
The model file specified is either corrupt, not a valid SafeTensors file, or has an invalid header, preventing the streamer from efficiently loading it.
fix
Verify the integrity and format of the .safetensors file; ensure it's a legitimate SafeTensors file, or download a fresh, uncorrupted version.
RuntimeError: CUDA error: no CUDA-capable device is detected
The ModelStreamer was configured to load tensors directly onto a CUDA device (e.g., 'device="cuda"') but no NVIDIA GPU with CUDA support is available or properly set up in the system.
fix
Ensure a CUDA-enabled GPU is installed with correct drivers, or initialize ModelStreamer with 'device="cpu"' if no GPU is intended for use.
Upgrade
Version history
0.16.1latest on PyPI · released Jul 13, 2026
Audit
Dependencies
libcurl4requiredRequired system library for C++ backend functionality.
libssl1.1_1requiredRequired system library for C++ backend functionality.
runai-model-streamer-gcsoptionalRequired for streaming models from Google Cloud Storage.
runai-model-streamer-s3optionalRequired for streaming models from AWS S3 or S3-compatible object stores.
runai-model-streamer-azureoptionalRequired for streaming models from Azure Blob Storage.
vllmoptionalUsed for accelerated LLM inference; `runai-model-streamer` integrates with vLLM.
Agent activity
47 hits · last 30 days
node
40
OpenAI (training)
2
Bingbot
1
Resources