[Ray] Propagate third-party env vars to Ray workers via prefix matching (#34383)

Signed-off-by: Kourosh Hakhamaneshi <kourosh@anyscale.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

vllm/ray/ray_env.py

@@ -10,8 +10,7 @@ logger = init_logger(__name__)
 
 CONFIG_HOME = envs.VLLM_CONFIG_ROOT
 
-# This file contains a list of env vars that should not be copied
-# from the driver to the Ray workers.
+# Env vars that should NOT be copied from the driver to Ray workers.
 RAY_NON_CARRY_OVER_ENV_VARS_FILE = os.path.join(
     CONFIG_HOME, "ray_non_carry_over_env_vars.json"
 )
@@ -29,51 +28,89 @@ except json.JSONDecodeError:
     )
     RAY_NON_CARRY_OVER_ENV_VARS = set()
 
+# ---------------------------------------------------------------------------
+# Built-in defaults for env var propagation.
+# Users can add more via VLLM_RAY_EXTRA_ENV_VAR_PREFIXES_TO_COPY and
+# VLLM_RAY_EXTRA_ENV_VARS_TO_COPY (additive, not replacing).
+# ---------------------------------------------------------------------------
+DEFAULT_ENV_VAR_PREFIXES: set[str] = {
+    "VLLM_",
+    "LMCACHE_",
+    "NCCL_",
+    "UCX_",
+    "HF_",
+    "HUGGING_FACE_",
+}
+
+DEFAULT_EXTRA_ENV_VARS: set[str] = {
+    "PYTHONHASHSEED",
+}
+
+
+def _parse_csv(value: str) -> set[str]:
+    """Split a comma-separated string into a set of stripped, non-empty tokens."""
+    return {tok.strip() for tok in value.split(",") if tok.strip()}
+
 
 def get_env_vars_to_copy(
     exclude_vars: set[str] | None = None,
     additional_vars: set[str] | None = None,
     destination: str | None = None,
 ) -> set[str]:
-    """
-    Get the environment variables to copy to downstream Ray actors.
+    """Return the env var names to copy from the driver to Ray actors.
 
-    Example use cases:
-    - Copy environment variables from RayDistributedExecutor to Ray workers.
-    - Copy environment variables from RayDPClient to Ray DPEngineCoreActor.
+    The result is the union of:
+
+    1. Env vars registered in ``vllm.envs.environment_variables``.
+    2. Env vars in ``os.environ`` matching a prefix in
+       ``DEFAULT_ENV_VAR_PREFIXES`` + ``VLLM_RAY_EXTRA_ENV_VAR_PREFIXES_TO_COPY``.
+    3. Individual names in ``DEFAULT_EXTRA_ENV_VARS`` +
+       ``VLLM_RAY_EXTRA_ENV_VARS_TO_COPY``.
+    4. Caller-supplied *additional_vars* (e.g. platform-specific).
+
+    Minus any names in *exclude_vars* or ``RAY_NON_CARRY_OVER_ENV_VARS``.
 
     Args:
-        exclude_vars: A set of vllm defined environment variables to exclude
-            from copying.
-        additional_vars: A set of additional environment variables to copy.
-            If a variable is in both exclude_vars and additional_vars, it will
-            be excluded.
-        destination: The destination of the environment variables.
-    Returns:
-        A set of environment variables to copy.
+        exclude_vars: Env vars to exclude (e.g. worker-specific ones).
+        additional_vars: Extra individual env var names to copy.  Useful
+            for caller-specific vars (e.g. platform env vars).
+        destination: Label used in log messages only.
     """
-    exclude_vars = exclude_vars or set()
-    additional_vars = additional_vars or set()
+    exclude = (exclude_vars or set()) | RAY_NON_CARRY_OVER_ENV_VARS
 
-    env_vars_to_copy = {
-        v
-        for v in set(envs.environment_variables).union(additional_vars)
-        if v not in exclude_vars and v not in RAY_NON_CARRY_OVER_ENV_VARS
-    }
-
-    to_destination = " to " + destination if destination is not None else ""
-
-    logger.info(
-        "RAY_NON_CARRY_OVER_ENV_VARS from config: %s", RAY_NON_CARRY_OVER_ENV_VARS
+    # -- prefixes (built-in + user-supplied, additive) ----------------------
+    prefixes = DEFAULT_ENV_VAR_PREFIXES | _parse_csv(
+        envs.VLLM_RAY_EXTRA_ENV_VAR_PREFIXES_TO_COPY
     )
+
+    # -- collect env var names ----------------------------------------------
+    # 1. vLLM's registered env vars
+    result = set(envs.environment_variables)
+    # 2. Prefix-matched vars present in the current environment
+    result |= {name for name in os.environ if any(name.startswith(p) for p in prefixes)}
+    # 3. Individual extra vars (built-in + user-supplied, additive)
+    result |= DEFAULT_EXTRA_ENV_VARS | _parse_csv(envs.VLLM_RAY_EXTRA_ENV_VARS_TO_COPY)
+    # 4. Caller-supplied extra vars (e.g. platform-specific)
+    result |= additional_vars or set()
+    # 5. Exclude worker-specific and user-blacklisted vars
+    result -= exclude
+
+    # -- logging ------------------------------------------------------------
+    dest = f" to {destination}" if destination else ""
+    logger.info("Env var prefixes to copy: %s", sorted(prefixes))
     logger.info(
         "Copying the following environment variables%s: %s",
-        to_destination,
-        [v for v in env_vars_to_copy if v in os.environ],
+        dest,
+        sorted(v for v in result if v in os.environ),
     )
+    if RAY_NON_CARRY_OVER_ENV_VARS:
+        logger.info(
+            "RAY_NON_CARRY_OVER_ENV_VARS from config: %s",
+            RAY_NON_CARRY_OVER_ENV_VARS,
+        )
     logger.info(
-        "If certain env vars should NOT be copied, add them to %s file",
+        "To exclude env vars from copying, add them to %s",
         RAY_NON_CARRY_OVER_ENV_VARS_FILE,
     )
 
-    return env_vars_to_copy
+    return result