配置 Ray Serve 部署#

Ray Serve 部署的默认值是探索的良好起点。为了进一步定制扩展行为、资源管理或性能调优，您可以配置参数来更改 Ray Serve 部署的默认行为。

使用本指南学习配置部署的基础知识

  • 您可以为 Ray Serve 部署配置哪些参数

  • 您可以指定参数的不同位置。

可配置参数#

您还可以参考 @serve.deployment 装饰器的 API 参考。

  • name - 在应用中唯一标识此部署的名称。如果未提供，则使用类或函数的名称。

  • num_replicas - 控制处理对此部署请求的副本数量。可以是正整数（副本数量保持不变），或 auto（副本数量将按默认配置自动扩缩，详见 Ray Serve 自动扩缩）。默认为 1。

  • ray_actor_options - 传递给 Ray Actor 装饰器的选项，例如资源要求。有效选项包括：accelerator_type, memory, num_cpus, num_gpus, object_store_memory, resources 和 runtime_env。更多详情请参见 - Serve 中的资源管理

  • max_ongoing_requests - 在未收到响应的情况下发送到此部署副本的最大查询数量。默认为 5（请注意，默认值在 Ray 2.32.0 中从 100 更改为 5）。这可能是配置 性能调优 的重要参数。

  • autoscaling_config - 配置自动扩缩行为的参数。如果设置此参数，则不能将 num_replicas 设置为数字。有关自动扩缩可配置参数的更多详细信息，请参见 Ray Serve 自动扩缩。

  • max_queued_requests - [实验性] 将在每个调用者（代理或 DeploymentHandle）处排队等待对此部署的最大请求数量。一旦达到此限制，后续请求将引发 BackPressureError（对于句柄）或返回 HTTP 503 状态码（对于 HTTP 请求）。默认为 -1（无限制）。

  • user_config - 要传递给部署的 reconfigure 方法的配置。此配置可以动态更新，而无需重新启动部署的副本。user_config 必须是完全 JSON 可序列化的。更多详情请参见 Serve 用户配置。

  • health_check_period_s - 副本之间健康检查调用的间隔时间。默认为 10 秒。健康检查默认是对副本进行的无操作 Actor 调用，但您可以在部署中使用“check_health”方法定义自己的健康检查，当不健康时抛出异常。

  • health_check_timeout_s - 副本等待健康检查方法返回的超时时间（秒）。默认为 30 秒。

  • graceful_shutdown_wait_loop_s - 副本在关闭前等待直到没有更多工作要完成的时间。默认为 2 秒。

  • graceful_shutdown_timeout_s - 在副本被强制终止前，等待其正常关闭的时间。默认为 20 秒。

  • logging_config - 部署的日志配置（例如日志级别、日志目录、JSON 日志格式等）。详情请参见 LoggingConfig。

如何指定参数#

您可以在两个位置指定上述参数

  1. 在您的应用代码中。

  2. 在 Serve 配置文件中，这是生产环境推荐的方法。

通过应用代码指定参数#

您可以通过两种方式在应用代码中指定参数

  • 在首次定义部署时，在 @serve.deployment 装饰器中

  • 在修改部署时，使用 options() 方法

在首次定义部署时，使用 @serve.deployment 装饰器指定部署参数

# File name: configure_serve.py

from ray import serve


@serve.deployment(
    name="Translator",
    num_replicas=2,
    ray_actor_options={"num_cpus": 0.2, "num_gpus": 0},
    max_ongoing_requests=100,
    health_check_period_s=10,
    health_check_timeout_s=30,
    graceful_shutdown_timeout_s=20,
    graceful_shutdown_wait_loop_s=2,
)
class Example:
    ...


example_app = Example.bind()

使用 .options() 方法修改已定义部署的参数。修改现有部署允许您重用部署定义并在运行时动态设置参数。


example_app = Example.options(
    ray_actor_options={"num_cpus": 0.2, "num_gpus": 0.0}
).bind()

通过 Serve 配置文件指定参数#

在生产环境中，我们建议通过 Serve 配置文件配置单个部署。您可以在不修改应用代码的情况下更改参数值。了解更多关于如何在 生产指南 中使用 Serve 配置的信息。

applications:
- name: app1
  import_path: configure_serve:translator_app
  deployments:
  - name: Translator
    num_replicas: 2
    max_ongoing_requests: 100
    graceful_shutdown_wait_loop_s: 2.0
    graceful_shutdown_timeout_s: 20.0
    health_check_period_s: 10.0
    health_check_timeout_s: 30.0
    ray_actor_options:
      num_cpus: 0.2
      num_gpus: 0.0

优先级顺序#

您可以在不同位置为参数设置不同的值。对于每个单独的参数，优先级顺序（从高到低）如下：

  1. Serve 配置文件

  2. 应用代码（通过 @serve.deployment 装饰器或 .options()）

  3. Serve 默认值

换句话说，如果您在配置文件和应用代码中都为某个部署指定了参数，Serve 将使用配置文件中的值。如果仅在代码中指定，Serve 将使用您在代码中指定的值。如果您在任何地方都没有指定参数，Serve 将使用该参数的默认值。

例如，以下应用代码包含一个名为 ExampleDeployment 的部署

@serve.deployment(num_replicas=2, graceful_shutdown_timeout_s=6)
class ExampleDeployment:
    ...

example_app = ExampleDeployment.bind()

然后您使用以下配置文件部署应用

applications:
  - name: default
    import_path: models:example_app 
    deployments:
      - name: ExampleDeployment
        num_replicas: 5

Serve 使用配置文件中设置的值 num_replicas=5 和应用代码中设置的值 graceful_shutdown_timeout_s=6。所有其他部署设置都使用 Serve 默认值，因为您未在代码或配置文件中指定它们。例如，health_check_period_s=10，因为 Serve 默认每 10 秒对部署进行一次健康检查。

提示

请记住，ray_actor_options 算作一个单独的设置。配置文件中的整个 ray_actor_options 字典将覆盖图代码中的整个 ray_actor_options 字典。如果您在代码中设置了 ray_actor_options 中的单个选项（例如 runtime_env、num_gpus、memory），但在配置文件中没有设置，如果配置文件中有 ray_actor_options 字典，Serve 仍然不会使用代码中的设置。它会将这些缺失的选项视为用户从未设置，并转而使用默认值。这种字典覆盖行为也适用于 user_config 和 autoscaling_config。