{"id":6231,"library":"runai-model-streamer-gcs","title":"Run:AI Model Streamer for GCS","description":"The Run:AI Model Streamer for GCS is a Python library that allows efficient loading and streaming of machine learning models directly from Google Cloud Storage without needing to fully download the entire model to local disk. It's part of the broader Run:AI model-streamer project, offering an abstraction for various object stores. The current version is 0.15.8, and it follows an infrequent release cadence, typically tied to the core `model-streamer-base` package.","status":"active","version":"0.15.8","language":"en","source_language":"en","source_url":"https://github.com/run-ai/model-streamer","tags":["gcs","google-cloud-storage","model-streaming","machine-learning","cloud-storage"],"install":[{"cmd":"pip install runai-model-streamer-gcs","lang":"bash","label":"Install GCS Streamer"}],"dependencies":[{"reason":"Required for interacting with Google Cloud Storage.","package":"google-cloud-storage","optional":false},{"reason":"Core functionality for model streaming.","package":"model-streamer-base","optional":false}],"imports":[{"symbol":"GCSStreamer","correct":"from runai.model_streamer.gcs import GCSStreamer"}],"quickstart":{"code":"import os\nfrom runai.model_streamer.gcs import GCSStreamer\n\n# --- Setup GCS Path (replace with your actual path) ---\n# For a real scenario, ensure your environment is authenticated with GCP.\n# E.g., by setting GOOGLE_APPLICATION_CREDENTIALS or using `gcloud auth login`.\n# This example uses a placeholder and will not work without a valid GCS path and auth.\n\ngcs_model_path = os.environ.get(\n    'GCS_MODEL_PATH',\n    'gs://your-bucket-name/path/to/your/model.pt' # REPLACE THIS\n)\n\n# --- Example 1: Stream a file-like object ---\n# Useful for frameworks that can load directly from file-like objects (e.g., PyTorch torch.load)\ntry:\n    if not gcs_model_path.startswith('gs://your-bucket-name'): # Check if placeholder is still there\n        print(f\"Attempting to stream from: {gcs_model_path}\")\n        with GCSStreamer.open(gcs_model_path, 'rb') as f:\n            # In a real scenario, you'd load your model here, e.g., model = torch.load(f)\n            print(f\"Successfully opened GCS object for streaming: {gcs_model_path}\")\n    else:\n        print(\"Skipping streaming example: GCS_MODEL_PATH not set or is placeholder.\\nSet GCS_MODEL_PATH environment variable or modify the script.\")\nexcept Exception as e:\n    print(f\"Error during streaming: {e}\")\n\n# --- Example 2: Download to a local temporary file ---\n# Useful for frameworks that require a local file path (e.g., Hugging Face, TensorFlow)\nlocal_temp_path = '/tmp/my_streamed_model.tmp'\ntry:\n    if not gcs_model_path.startswith('gs://your-bucket-name'): # Check if placeholder is still there\n        print(f\"Attempting to download from: {gcs_model_path} to {local_temp_path}\")\n        GCSStreamer.download_file(gcs_model_path, local_temp_path)\n        # In a real scenario, you'd load your model here, e.g., model = MyFramework.load(local_temp_path)\n        print(f\"Successfully downloaded GCS object to: {local_temp_path}\")\n    else:\n        print(\"Skipping download example: GCS_MODEL_PATH not set or is placeholder.\\nSet GCS_MODEL_PATH environment variable or modify the script.\")\nexcept Exception as e:\n    print(f\"Error during download: {e}\")\nfinally:\n    if os.path.exists(local_temp_path):\n        os.remove(local_temp_path) # Clean up temporary file\n        print(f\"Cleaned up temporary file: {local_temp_path}\")\n","lang":"python","description":"This quickstart demonstrates how to use `GCSStreamer` to either stream a model directly from Google Cloud Storage as a file-like object or download it to a temporary local file. Ensure your environment is authenticated with GCP and `GCS_MODEL_PATH` is set to a valid object path (e.g., `gs://my-bucket/models/my_model.pt`). This code includes checks to prevent execution with placeholder paths."},"warnings":[{"fix":"Refer to Google Cloud's documentation for authenticating Python applications to GCP services (e.g., `gcloud auth application-default login` or setting `GOOGLE_APPLICATION_CREDENTIALS` to a service account key file).","message":"GCP Authentication is required for accessing Google Cloud Storage. Ensure your environment variables (`GOOGLE_APPLICATION_CREDENTIALS`) or default GCP project authentication is correctly configured. Without proper authentication, all GCS operations will fail with permission errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always install/upgrade both `runai-model-streamer-gcs` and `model-streamer-base` together, or let `pip` manage the base dependency automatically when installing `runai-model-streamer-gcs`.","message":"The `runai-model-streamer-gcs` package strictly depends on the `model-streamer-base` package with the same major and minor version (e.g., `~=0.15.8`). When upgrading, ensure both packages are updated simultaneously to avoid compatibility issues.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult your ML framework's documentation on model loading. If it supports loading from a file-like object, `GCSStreamer.open` is more efficient. Otherwise, use `GCSStreamer.download_file`.","message":"The library supports two main patterns: `GCSStreamer.open` for streaming as a file-like object and `GCSStreamer.download_file` for downloading to a local path. Choose the method appropriate for your ML framework, as some require a local file path (e.g., certain Hugging Face model loaders) while others can load from file-like objects (e.g., PyTorch's `torch.load`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your Python environment is within the supported range (3.8-3.11). Check the project's official `pyproject.toml` or `setup.py` for updated `requires_python` metadata if you encounter compatibility issues with newer Python versions.","message":"The `runai-model-streamer-gcs` package officially requires Python versions between 3.8 and 3.11 (inclusive). While it might function with newer Python versions, compatibility is not guaranteed, and issues may arise. PyPI metadata explicitly states `requires_python: >=3.8,<3.12`.","severity":"deprecated","affected_versions":"0.15.x and earlier"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}