Serve 配置文件#

本节将帮助您

了解 Serve 的配置文件格式。
学习如何使用 Serve 配置在生产环境中部署和更新您的应用程序。
学习如何为一组 Serve 应用程序生成配置文件。

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

提示

如果您正在 VM 上部署 Serve，则可以使用 Serve 配置配合serve deploy CLI 命令。如果您正在 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: ...
  external_scaler_enabled: ...
  deployments:
  - name: ...
    num_replicas: ...
    ...
  - name:
    ...

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

代理配置#

字段 proxy_location 配置了在哪里运行代理以处理集群流量。您可以将 proxy_location 设置为以下值

EveryNode (默认): 在集群中具有至少一个副本的每个节点上运行一个代理。
HeadOnly: 只在主节点上运行单个代理。
Disabled: 完全不运行代理。如果您只使用部署句柄调用您的应用程序，请设置此值。

HTTP 配置#

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 配置#

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 此处。

应用程序配置#

您将一个或多个部署配置为 Serve 应用程序的一部分。请参阅部署配置。

以下是每个 application 的字段

name: 由 serve build 自动生成的每个应用程序的名称。每个应用程序的名称必须是唯一的。
route_prefix: 可以通过指定的路由前缀通过 HTTP 调用应用程序。它默认为 /。每个应用程序的路由前缀必须是唯一的。
import_path: 到您的顶级 Serve 部署的路径（或传递给 serve run 的相同路径）。最简单的配置文件仅包含一个 import_path。
runtime_env: 定义应用程序运行的环境。使用此参数打包应用程序依赖项，例如 pip 包（有关支持的字段，请参阅运行时环境）。如果指定了 import_path，则该路径必须在 runtime_env 中可用。Serve 配置的 runtime_env 只能在其 working_dir 和 py_modules 中使用远程 URI；它不能使用本地 zip 文件或目录。有关运行时环境的更多详细信息。
external_scaler_enabled: 启用外部扩展 API，该 API 允许您通过 REST API 从 Ray 集群外部扩展部署。启用后，您不能对该应用程序中的任何部署使用内置自动扩展（autoscaling_config）。默认为 False。有关详细信息，请参阅外部扩展 API。
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，则应在 runtime_env 中包含这两个 pip 包。

此外，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"]

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

相应的 YAML 片段是

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

Serve 配置​​​文件#

代理配置#

HTTP 配置#

gRPC 配置#

日志配置#

应用程序配置#

示例配置#

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

动态更改参数而不重启副本（user_config）#

Serve 配置文件#

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

动态更改参数而不重启副本（`user_config`）#