●Change8

Migrating to Ray ray-2.48.0

Version ray-2.48.0 introduces 9 breaking changes. This guide details how to update your code.

Released: 7/18/2025

9
Breaking Changes
9
Migration Steps
8
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

RunConfigRunConfigV1internal_api.memory_summaryray._private.stateImageRetrieverDeploymentConfig.RouterConfigPrefixAwareReplicaSetvllm.PoolingOutput

Breaking Changes

●Issue #1

Removed subclass relationship between RunConfig and RunConfigV1 in Ray Train, requiring code to use the new RunConfig API directly.

●Issue #2

Removed indirection layers of node initialization in Ray Serve, which may affect custom node setup scripts.

●Issue #3

Removed random v0 logic from serve endpoints in Ray Serve, breaking any code that relied on the previous v0 endpoint behavior.

●Issue #4

Removed usage of internal_api.memory_summary() in Ray Serve, requiring callers to switch to the public memory summary APIs.

●Issue #5

Removed usage of ray._private.state in Ray Serve, requiring migration to supported public state APIs.

●Issue #6

Removed ImageRetriever class and related tests from the LLM serving codebase, breaking imports of this class.

●Issue #7

Removed botocore dependency in Ray Serve LLM; code that imported botocore from Ray Serve will fail.

●Issue #8

Updated vLLM version to 0.9.2, which introduces API changes (e.g., vllm.PoolingOutput) that may break existing integrations.

●Issue #9

Prefix-aware scheduler refactor for PrefixAwareReplicaSet changes GPU allocation handling, requiring updates to deployment configs.

Migration Steps

  1. 1
    Update code to use the new RunConfig API directly and remove references to RunConfigV1.
  2. 2
    Replace any calls to internal_api.memory_summary() with the public memory summary APIs.
  3. 3
    Migrate away from ray._private.state to supported public state interfaces.
  4. 4
    Remove imports of the ImageRetriever class and adopt alternative retrieval mechanisms.
  5. 5
    If your code imported botocore via Ray Serve LLM, remove those imports as the dependency is no longer bundled.
  6. 6
    Review and adapt to vLLM 0.9.2 API changes, especially handling of vllm.PoolingOutput.
  7. 7
    Update DeploymentConfig definitions to include the new RouterConfig field for custom request routers.
  8. 8
    Adjust PrefixAwareReplicaSet configurations to follow the new GPU allocation guidelines.
  9. 9
    Verify custom request routing implementations are compatible with the new RouterConfig API.

Release Summary

This release adds Delta Lake support, new collective operations, custom request routing, and offline policy evaluation, while also delivering numerous performance improvements and bug fixes across Ray Data, Train, Serve, Tune, and RLlib.

Need More Details?

View the full release notes and all changes for Ray ray-2.48.0.

View Full Changelog