Serve 配置文件#

本节将帮助你

  • 理解 Serve 配置文件的格式。

  • 学习如何使用 Serve 配置文件在生产环境中部署和更新你的应用。

  • 学习如何为 Serve 应用列表生成配置文件。

Serve 配置文件是推荐用于在生产环境中部署和更新应用的方式。它允许你完全配置与 Serve 相关的一切，包括代理等系统级组件以及单个部署参数等应用级选项（回顾如何配置 Serve 部署）。一个主要的好处是，你可以通过修改 Serve 配置文件动态更新单个部署参数，而无需重新部署或重启应用。

提示

如果你正在虚拟机上部署 Serve，可以结合 serve deploy CLI 命令使用 Serve 配置文件。如果你正在 Kubernetes 上部署 Serve，可以将 Serve 配置文件嵌入到 Kubernetes 的 RayService 自定义资源中，以便

Serve 配置文件是具有以下格式的 YAML 文件

proxy_location: ...

http_options: 
  host: ...
  port: ...
  request_timeout_s: ...
  keep_alive_timeout_s: ...

grpc_options:
  port: ...
  grpc_servicer_functions: ...
  request_timeout_s: ...

logging_config:
  log_level: ...
  logs_dir: ...
  encoding: ...
  enable_access_log: ...

applications:
- name: ...
  route_prefix: ...
  import_path: ...
  runtime_env: ... 
  deployments:
  - name: ...
    num_replicas: ...
    ...
  - name:
    ...

该文件包含 proxy_location、http_options、grpc_options、logging_config 和 applications。

proxy_location 字段配置代理运行的位置，用于处理流向集群的流量。你可以将 proxy_location 设置为以下值

  • EveryNode（默认）：在集群中至少有一个副本 actor 的每个节点上运行代理。

  • HeadOnly：只在头节点上运行一个代理。

  • Disabled：完全不运行代理。如果你只使用部署句柄调用你的应用，请设置此值。

http_options 如下所示。请注意，HTTP 配置对于你的 Ray 集群是全局的，并且不能在运行时更新。

  • host：Serve HTTP 代理的主机 IP 地址。这是可选的，可以省略。默认情况下，host 设置为 0.0.0.0 以公开暴露你的部署。如果你使用 Kubernetes，必须将 host 设置为 0.0.0.0 才能将你的部署暴露在集群外部。

  • port：Serve HTTP 代理的端口。此参数是可选的，可以省略。默认情况下，端口设置为 8000。

  • request_timeout_s：允许你设置请求的端到端超时时间，超时后将在另一个副本上终止并重试。默认情况下没有请求超时。

  • keep_alive_timeout_s：允许你设置 HTTP 代理的 keep alive 超时。更多详情请参阅此处

grpc_options 如下所示。请注意，gRPC 配置对于你的 Ray 集群是全局的，并且不能在运行时更新。

  • port：gRPC 代理监听的端口。这些是可选设置，可以省略。默认情况下，端口设置为 9000。

  • grpc_servicer_functions：要添加到 Serve gRPC 代理的 gRPC add_servicer_to_server 函数的导入路径列表。Servicer 函数需要在 Serve 运行的环境中可导入。默认值为空列表，表示 gRPC 服务器未启动。

  • request_timeout_s：允许你设置请求的端到端超时时间，超时后将在另一个副本上终止并重试。默认情况下没有请求超时。

logging_config 是全局配置，你可以配置控制器、代理和副本的日志。请注意，你也可以设置应用和部署级别的日志配置，这会优先于全局配置。更多详情请参阅日志配置 API 此处。

以下是每个应用的字段

  • name：每个应用的名称，由 serve build 自动生成。每个应用的名称必须唯一。

  • route_prefix：可以通过指定的路由前缀通过 HTTP 调用应用。默认值为 /。每个应用的路由前缀必须唯一。

  • import_path：你的顶层 Serve 部署的路径（或传递给 serve run 的相同路径）。最简单的配置文件只包含 import_path。

  • runtime_env：定义应用运行的环境。使用此参数来打包应用依赖项，例如 pip 包（有关支持的字段，请参阅运行时环境）。如果指定了 runtime_env，则 import_path 必须在其中可用。Serve 配置的 runtime_env 只能在其 working_dir 和 py_modules 中使用远程 URI；不能使用本地 zip 文件或目录。有关运行时环境的更多详细信息。

  • deployments (optional)：一个部署选项列表，允许你覆盖部署图代码中指定的 @serve.deployment 设置。此列表中的每个条目必须包含部署 name，该名称必须与代码中的名称匹配。如果省略此部分，Serve 将使用代码中指定的参数启动图中的所有部署。参阅如何配置 serve 部署选项。

  • args：传递给应用构建器的参数。

下面是遵循上述格式的文本 ML 模型示例的配置

proxy_location: EveryNode

http_options:
  host: 0.0.0.0
  port: 8000

applications:
- name: default
  route_prefix: /
  import_path: text_ml:app
  runtime_env:
    pip:
      - torch
      - transformers
  deployments:
  - name: Translator
    num_replicas: 1
    user_config:
      language: french
  - name: Summarizer
    num_replicas: 1

该文件使用与 serve run 相同的 text_ml:app 导入路径，并在 deployments 列表中包含翻译和摘要部署的两个条目。这两个条目都包含 name 设置以及其他一些配置选项，例如 num_replicas。

提示

deployments 列表中的每个单独条目都是可选的。在上面的示例配置文件中，你可以省略 Summarizer，包括其 name 和 num_replicas，文件仍然有效。部署文件时，Summarizer 部署仍然会部署，使用应用程序代码中 @serve.deployment 装饰器中设置的配置。

使用 serve build 自动生成 Serve 配置#

你可以使用一个工具从代码自动生成此配置文件。serve build 命令接受应用导入路径作为参数，并生成一个包含应用代码中所有部署及其参数的配置文件。调整这些参数以在生产环境中管理你的部署。

$ ls
text_ml.py

$ serve build text_ml:app -o serve_config.yaml

$ ls
text_ml.py
serve_config.yaml

serve_config.yaml 文件包含

proxy_location: EveryNode

http_options:
  host: 0.0.0.0
  port: 8000

grpc_options:
  port: 9000
  grpc_servicer_functions: []

logging_config:
  encoding: TEXT
  log_level: INFO
  logs_dir: null
  enable_access_log: true

applications:
- name: default
  route_prefix: /
  import_path: text_ml:app
  runtime_env: {}
  deployments:
  - name: Translator
    num_replicas: 1
    user_config:
      language: french
  - name: Summarizer

请注意，使用 serve build 时，runtime_env 字段将始终为空，必须手动设置。在这种情况下，如果 torch 和 transformers 未全局安装，你应该将这两个 pip 包包含在 runtime_env 中。

此外，serve build 在其自动生成的文件中包含默认的 HTTP 和 gRPC 选项。你可以修改这些参数。

无需重启副本即可动态更改参数 (user_config)#

你可以使用 user_config 字段为你的部署提供结构化配置。你可以将任意 JSON 可序列化对象传递给 YAML 配置。然后 Serve 会将其应用于所有正在运行和未来的部署副本。应用用户配置不会重启副本。这种部署连续性意味着你可以使用此字段动态地

  • 调整模型权重和版本，无需重启集群。

  • 调整模型组合图的流量分配百分比。

  • 配置你的部署的任何功能开关、A/B 测试和超参数。

要启用 user_config 功能，请实现一个 reconfigure 方法，该方法接受一个 JSON 可序列化对象（例如，字典、列表或字符串）作为其唯一参数

@serve.deployment
class Model:
    def reconfigure(self, config: Dict[str, Any]):
        self.threshold = config["threshold"]

如果你在创建部署时（即在装饰器或 Serve 配置文件中）设置了 user_config，Ray Serve 会在部署的 __init__ 方法之后立即调用此 reconfigure 方法，并将 user_config 作为参数传入。你还可以通过使用新的 user_config 更新 Serve 配置文件并将其重新应用到 Ray 集群来触发 reconfigure 方法。有关更多信息，请参阅原地更新。

对应的 YAML 片段是

...
deployments:
    - name: Model
      user_config:
        threshold: 1.5