ray-project/ray · 上手攻略

• 仓库：ray-project/ray
• 链接：https://github.com/ray-project/ray
• 分类：ai / llm-infra
• 作者：Jay
• 更新：2026-07-09

这是什么

Ray 是一个统一分布式 AI 计算框架，用于将 Python 和 AI 应用从单机扩展到集群。核心由两部分组成：

• Ray Core：轻量级分布式运行时，提供 Task（无状态函数）、Actor（有状态工作进程）、Object（集群范围可访问的对象）三个核心抽象
• Ray AI Libraries：针对 ML 工作流的高级库全家桶，包括 Ray Data（分布式数据集）、Ray Train（分布式训练）、Ray Tune（超参数搜索）、Ray RLlib（强化学习）、Ray Serve（模型服务）

一句话定位：让你用同一套 Python 代码，从笔记本无缝扩展到数千节点集群，不需要懂分布式系统。

解决什么问题

ML 和 LLM 工作流的三大挑战：

1. 单机算力不够：大模型训练/推理、微调、SFT 需要多机多卡，单机环境无法承载
2. 分布式门槛高：手动管理进程间通信、任务调度、容错，复杂度极高
3. 资源利用率低：GPU 空闲、任务排队、机器利用率参差不齐

Ray 通过声明式的分布式原语，把这些问题抽象掉，让数据科学家和 ML 工程师专注业务逻辑。

快速安装

pip install ray

启动本地集群（单机器，默认：

import ray
ray.init()  # 自动检测本机 CPU/GPU，启动本地 Ray 节点

⚠️ 注意：ray.init() 不带参数时会隐式调用；生产环境显式传参更清晰。

连接已有集群：

ray.init(address="ray://123.456.7.89:6379")

查看 Dashboard：

# ray.init() 后自动在 http://localhost:8265 启动 Dashboard
# 也可以手动：
ray dashboard

核心用法

1. Ray Core：Task（无状态并行）

把普通 Python 函数变成分布式任务，只需加装饰器：

import ray

ray.init()

@ray.remote
def square(x):
    return x * x

# 并行提交 4 个任务，自动调度到可用 CPU 核心
futures = [square.remote(i) for i in range(4)]
results = ray.get(futures)
print(results)  # [0, 1, 4, 9]

带资源请求的 Task：

@ray.remote(num_gpus=1, num_cpus=2, memory=4 * 1024**3)
def train_model(data):
    # 这个任务需要 1 GPU + 2 CPU + 4GB 内存
    ...

2. Ray Core：Actor（有状态服务）

Actor 是有状态的长生命周期工作进程，适合模拟服务或持有共享状态：

@ray.remote
class Counter:
    def __init__(self):
        self.i = 0

    def increment(self):
        self.i += 1
        return self.i

    def get(self):
        return self.i

counter = Counter.remote()  # 在集群某节点启动一个 Actor 进程
ray.get(counter.increment.remote())  # 1
ray.get(counter.increment.remote())  # 2
ray.get(counter.get.remote())        # 2

3. Ray Data：分布式数据集

Ray Data 提供类似 Pandas API 的分布式数据处理，底层自动切分、并行执行：

import ray.data

# 从多种数据源创建 Dataset
ds = ray.data.read_json("s3://my-bucket/*.json")

# 分布式 map 转换
ds = ds.map_batches(lambda batch: ...)

# 与 Ray Train、Ray Tune 集成直接传给训练 pipeline
ds迭代：
for batch in ds.iter_batches():
    print(batch)

📝 版本注意：Ray 2.x 系列中 ray.data API 有较大变化，老项目请确认 Ray 版本（ray --version）。

4. Ray Train：分布式训练

PyTorch 分布式训练简化版：

from ray import train
from ray.train.torch import TorchTrainer

def train_func(config):
    # 标准 PyTorch 训练循环
    for epoch in range(num_epochs):
        # train_step...
        train.report({"loss": loss.item(), "accuracy": acc})

trainer = TorchTrainer(
    train_func,
    scaling_config=train.ScalingConfig(
        num_workers=4,   # 4 GPU
        use_gpu=True,
    ),
    run_config=train.RunConfig(checkpoint_config=train.CheckpointConfig(...)),
)

result = trainer.fit()

5. Ray Tune：超参数搜索

与 Ray Train 无缝集成，支持网格搜索、随机搜索、贝叶斯优化（基于 Optuna）等：

from ray import tune

def train_func(config):
    lr = config["lr"]
    # 训练逻辑...
    train.report({"val_accuracy": accuracy})

tuner = tune.Tuner(
    train_func,
    param_space={"lr": tune.grid_search([1e-4, 1e-3, 1e-2])},
    run_config=train.RunConfig(
        num_samples=5,
        metric="val_accuracy",
        mode="max",
    ),
)
results = tuner.fit()

6. Ray Serve：模型推理服务

一行命令将 PyTorch / Llama 等模型部署为 HTTP API：

import ray
from ray import serve

@serve.deployment(num_replicas=2, ray_actor_options={"num_gpus": 1})
class LLMServe:
    def __init__(self):
        from transformers import pipeline
        self.generator = pipeline("text-generation", model="gpt2")

    def __call__(self, prompt: str) -> str:
        return self.generator(prompt, max_new_tokens=50)[0]["generated_text"]

ray.init()
serve.run(LLMServe.bind(), route_prefix="/generate")
# HTTP API: POST /generate  with body {"prompt": "..."}

7. Ray Cluster on Kubernetes（生产推荐）

# 安装 KubeRay operator
helm install kuberay-operator kuberay/kuberay-operator

# 提交 RayJob
kubectl apply -f ray-job.yaml

生产环境的 GPU 调度、Auto-scaling、故障恢复全由 KubeRay 统一管理。

典型适用场景

坑与注意

1. Ray 版本差异大：Ray 1.x → 2.x → 3.x API 变化显著，生产环境务必锁定版本；建议用 Docker 镜像或 Anyscale 以避免本地环境问题
2. Actor 状态一致性：Actor 方法串行执行，有状态并发场景注意锁或分区设计
3. 资源请求要精确：num_gpus=1 表示任务独占 1 个 GPU；GPU 分片（如 0.5 GPU）需用 Fractional GPUs（需集群配置支持）
4. Object Store 内存：ray.memory 显示 Object Store 使用情况，过大易 OOM；批量任务要注意 batch size
5. Dashboard 端口：8265 端口有时被占，可 ray.init(dashboard_port=XXXX) 手动指定
6. Kubernetes 门槛：KubeRay operator 安装对集群版本有要求（Kubernetes ≥ 1.19），小团队建议先用 Anyscale 托管版

与同类对比

结论： - 选 Ray：AI/ML 全生命周期（训练+调参+推理+服务），且需要 Auto-scaling - 选 Spark：已有大数据（HDFS/Spark 生态）基础设施，大规模 ETL - 选 Dask：纯 Python 科学计算，不需要分布式调度，熟悉的 NumPy API - 选 Horovod：专用深度学习训练，已有 MPI 集群

一句话推荐结论

Ray 是 AI 时代最强"一本多用的"分布式框架：从 LLM 训练（Tune + Train）到推理服务（Serve）到批处理（Data），一行代码从笔记本扩展到千节点集群，是构建 AI 平台的事实标准底层。