使用JSON配置文件定义和部署服务-人工智能平台PAI-阿里云

在EAS中，可以通过一个JSON格式的配置文件来定义和部署在线服务。当准备好JSON配置文件后，便可通过EAS控制台、EASCMD客户端或SDK等多种方式完成服务部署。

一、准备JSON配置文件

部署服务的核心是创建一个包含所有必需配置的JSON文件。对于初次使用者，建议在控制台的服务部署页面进行基础配置，系统会自动生成对应的JSON内容，可以在此基础上进行修改和扩展。

示例文件service.json如下，完整的参数列表及详细描述参见附录：JSON参数说明。

{
    "cloud": {
        "computing": {
            "instances": [
                {
                    "type": "ecs.c7a.large"
                }
            ]
        }
    },
    "containers": [
        {
            "image": "****-registry.cn-beijing.cr.aliyuncs.com/***/***:latest",
            "port": 8000,
            "script": "python app.py"
        }
    ],
    "metadata": {
        "cpu": 2,
        "instance": 1,
        "memory": 4000,
        "name": "demo"
    }
}

二、使用JSON文件部署服务

控制台

登录PAI控制台，在页面上方选择目标地域，并在右侧选择目标工作空间，然后单击进入EAS。
在推理服务页签，单击部署服务。在部署服务页面，选择自定义模型部署 > JSON独立部署。
输入准备好的JSON文件，单击部署。等待一段时间，当服务状态变为运行中时，表明服务部署成功。

EASCMD

通过客户端工具EASCMD，可以在自己服务器上对模型服务进行管理，包括创建、查看、删除及更新服务。具体操作步骤如下：

下载并认证客户端
如果您使用的是DSW开发环境并使用官方镜像，则已预置EASCMD客户端（路径：/etc/dsw/eascmd64），否则请下载并认证客户端。

执行部署命令

在JSON文件所在目录，执行以下命令部署服务。以Windows64版本为例。更多操作请参见命令使用说明。

eascmdwin64 create <service.json>

其中：<service.json>需要替换为实际的JSON文件名称。

说明

如果您使用的是DSW开发环境，需要上传JSON配置文件，请参见上传与下载文件。

系统返回如下类似结果。

[RequestId]: 1651567F-8F8D-4A2B-933D-F8D3E2DD****
+-------------------+----------------------------------------------------------------------------+
| Intranet Endpoint | http://166233998075****.cn-shanghai.pai-eas.aliyuncs.com/api/predict/test_eascmd |
|             Token | YjhjOWQ2ZjNkYzdiYjEzMDZjOGEyNGY5MDIxMzczZWUzNGEyMzhi****                   |
+-------------------+--------------------------------------------------------------------------+
[OK] Creating api gateway
[OK] Building image [registry-vpc.cn-shanghai.aliyuncs.com/eas/test_eascmd_cn-shanghai:v0.0.1-20221122114614]
[OK] Pushing image [registry-vpc.cn-shanghai.aliyuncs.com/eas/test_eascmd_cn-shanghai:v0.0.1-20221122114614]
[OK] Waiting [Total: 1, Pending: 1, Running: 0]
[OK] Waiting [Total: 1, Pending: 1, Running: 0]
[OK] Service is running

Python SDK

您还可以参考使用EAS Python SDK部署模型将训练获得的模型部署为EAS在线服务。

附录：JSON参数说明

参数	是否必选	描述
metadata	是	服务的Meta信息。具体参数配置，详情请参见metadata参数说明。
cloud	否	计算资源与专有网络配置，详情请参见cloud参数说明。
containers	否	镜像配置，详情参见containers参数说明。
dockerAuth	否	当镜像来源于私有仓库时，需配置dockerAuth，值为镜像仓库的`用户名:密码`经Base64编码后的字符串。
networking	否	服务的调用配置。具体参数配置，详情请参见networking参数说明。
storage	否	表示服务存储挂载等相关信息。详细配置说明，请参见存储挂载。
token	否	表示访问鉴权的Token字符串。如果未指定，则系统自动生成。
aimaster	否	为多机分布式推理服务开启算力检测与容错。
model_path	是	使用processor部署时必选。model_path和processor_path分别为模型和Processor的输入数据源地址，均支持以下格式的地址： OSS地址：地址链接可以是具体文件路径或文件夹路径。 HTTP地址：所需文件必须为TAR.GZ、TAR、BZ2或ZIP等压缩包。本地路径：如果使用`test`命令进行本地调试，则可以使用本地路径。
oss_endpoint	否	OSS的Endpoint，例如oss-cn-beijing.aliyuncs.com。其他取值请参见地域和Endpoint。说明默认无需指定该参数，会使用当前地域的内网OSS地址，来进行模型文件或Processor文件的下载。当跨地域访问OSS时，需要指定该参数。例如：当您在杭州地域部署服务时，model_path中填写了北京地域的OSS地址，则需要使用该参数来指定北京地域的OSS公网访问地址。
model_entry	否	表示模型的入口文件，可以包含任意文件。如果未指定，则使用model_path中的文件名。主文件路径会传递给Processor中的initialize()函数。
model_config	否	表示模型的配置，支持任意文本。该参数值会传递给Processor中initialize()函数的第二个参数。
processor	否	如果使用官方提供的预置Processor，则直接在此指定Processor Code即可。Processor在`eascmd`中使用的Code请参见预置Processor。如果使用自定义Processor，则无需配置该参数，只需要配置processor_path、processor_entry、processor_mainclass和processor_type参数。
processor_path	否	Processor相关的文件包路径，可以参见model_path参数的描述信息。
processor_entry	否	Processor的主文件。例如libprocessor.so或app.py，其中包含了预测所需的`initialize()`函数和`process()`函数的实现。当processor_type为cpp或python时，必须指定该参数。
processor_mainclass	否	Processor的主文件，JAR包中的mainclass。例如com.aliyun.TestProcessor。当processor_type为java时，必须指定该参数。
processor_type	否	processor实现的语言，取值如下： cpp java python
warm_up_data_path	否	用于模型预热的请求文件路径。更多关于模型预热功能的介绍，详情请参见模型服务预热。
runtime.enable_crash_block	否	当服务实例因Processor代码异常发生Crash后，服务实例是否会自动重启。取值如下： true：表示服务实例不自动重启，以保留现场进行问题排查。 false：默认值，表示服务实例自动重启。
autoscaler	否	表示模型服务自动水平扩缩容的配置信息。具体参数配置，详情请参见水平自动扩缩容。
labels	否	为EAS服务配置标签。格式为`key:value`。
unit.size	否	表示分布式推理配置下单实例部署的机器数。默认值为2。
sinker	否	支持将服务所有的请求和响应记录持久化保存到大数据MaxCompute或日志服务SLS中。具体参数配置，详情请参见sinker参数说明。
confidential	否	通过配置系统信任管理服务，保证服务部署和调用的过程中数据、模型和代码等信息可以安全加密，实现安全可验证的推理服务。格式如下：说明安全加密环境主要针对您挂载的存储文件，请先完成存储文件的挂载再打开该功能。 `"confidential": { "trustee_endpoint": "xxxx", "decryption_key": "xxxx" }` 参数配置说明如下，更详细的内容介绍，请参见安全加密推理服务。 trustee_endpoint：系统信任管理服务Trustee的URI。 decryption_key：解密密钥的KBS URI。例如`kbs:///default/key/test-key`。

metadata参数说明

一般参数

参数	是否必选	描述
name	是	服务名称，必须在同一地域内唯一。
instance	是	服务启动的实例数量。
workspace_id	否	设置工作空间ID参数后，服务将只能在指定的PAI工作空间之内使用。例如：`1405**`。
cpu	否	每个实例需要的CPU数量。
memory	否	每个实例需要的内存数量，取值为整型，单位为MB。例如，`"memory": 4096`表示每个实例需要4 GB内存。
gpu	否	每个实例需要的GPU数量。
gpu_memory	否	使用EAS资源组或资源配额时配置GPU切分功能，实现多实例共享单卡。
gpu_core_percentage	否	使用EAS资源组或资源配额时配置GPU切分功能，实现多实例共享单卡。
qos	否	实例的服务质量，可选参数值为空或BestEffort。当qos指定为BestEffort时，表示进入CPU共享模式。使实例完全按照显存和内存进行调度，不再受节点的CPU数量限制，节点上的所有实例共享CPU。此时cpu字段表示，按CPU共享模式时，单个实例能使用的最大配额。
resource	否	资源组ID，配置策略如下：如果服务部署在公共资源组，则可以忽略该参数，此时服务进行按量付费。如果服务部署在专属资源组，则配置该参数为资源组ID。例如eas-r-6dbzve8ip0xnzt****。
cuda	否	服务需要使用的cuda版本。服务运行时，会自动将指定版本的cuda挂载到实例的`/usr/local/cuda`目录中。目前支持的cuda版本为：8.0，9.0，10.0，10.1，10.2，11.0，11.1，11.2。使用示例为：`"cuda":"11.2"`。
rdma	否	表示分布式推理配置下，是否开启RDMA网络。设置为1表示开启RDMA网络。若未配置rdma参数，则表示关闭RDMA网络。说明当前仅使用灵骏智算资源部署的服务可以使用RDMA网络。
enable_grpc	否	表示是否开启服务网关的GRPC连接，取值如下： false：默认值，表示网关不开启GRPC连接，默认支持HTTP请求。 true：表示网关开启GRPC连接。说明如果使用自定义镜像部署服务时，镜像中的服务端实现为GRPC，则需要通过该参数将网关的协议切换成GRPC。
enable_webservice	否	表示是否开启webserver，从而部署为一个AI-Web应用： false：默认值，表示不开启webserver。 true：表示开启webserver。
type	否	配置为LLMGatewayService，即可部署LLM智能路由服务。JSON文件配置方法，请参见部署LLM智能路由服务。

高级参数

重要

请您慎重调整高级参数。

参数		是否必选	描述
rpc	batching	否	是否开启Server端Batching，用于GPU模型加速，仅支持预置processor模式。取值如下： false：默认值，关闭Server端Batching。 true：开启Server端Batching。
	keepalive	否	设置单个请求的最长处理时间（单位：毫秒）。如果请求处理时长超过该值，服务端将返回408超时并关闭连接。默认值：专属网关600000。应用型专属网关（ALB）不支持此项配置。
	io_threads	否	每个实例用于处理网络IO的线程数量，默认值为4。
	max_batch_size	否	每个Batch的最大Size，默认值为16，仅支持预置processor模式。仅rpc.batching取值为true时，该参数生效。
	max_batch_timeout	否	每个Batch的最大Timeout，默认值为50毫秒，仅支持预置processor模式。仅rpc.batching取值为true时，该参数生效。
	max_queue_size	否	创建异步推理服务时，队列最大长度，默认值为64。队列满时，服务端返回450并关闭连接。为保证服务端不会压力过载，队列可以提前通知客户端向其他实例进行重试。对于RT较长的服务队列，可以适当减小队列长度，以避免请求在队列中堆积导致大量请求超时。
	worker_threads	否	每个实例中用于并发处理请求的线程数，默认值为5，仅支持预置processor模式。
	rate_limit	否	表示开启QPS限流功能，并限制实例处理的最大QPS。默认为0，表示关闭QPS限流功能。例如：该参数配置为2000，当QPS高于2000时，会拒绝请求并返回429（Too Many Requests）。
	enable_sigterm	否	取值如下： false（默认值）：实例进入退出状态时不会发送SIGTERM信号。 true：在服务实例进入退出状态时，系统会立即向主进程发送SIGTERM信号，服务内进程收到该信号后需要在信号处理函数中进行自定义的优雅退出操作，若不处理该信号可能导致主进程收到信号后直接退出，从而使优雅退出失败。
rolling_strategy	max_surge	否	服务滚动更新过程中，多于指定实例数，最多可以额外创建的实例个数。该参数可以为正整数，表示实例个数；也可以为百分比，例如2%。默认比例为2%。增大该参数可以提高服务更新速度。例如：服务实例个数指定为100，该参数配置为20，则服务更新开始后会立即创建20个新实例。
rolling_strategy	max_unavailable	否	服务滚动更新过程中，最大不可用的实例个数。该参数可以在服务更新过程中，为新实例释放资源，避免服务因空闲资源不足而更新卡住。目前在专有资源组中，该参数默认为1；在公共资源组中，该参数默认为0。例如：该参数为N，则服务更新开始时会立即停止N个实例。说明如果空闲资源充足，可以将该参数配置为0。该参数配置过大可能会影响服务稳定性。因为在服务更新瞬间，可用实例个数会减少，则单实例承载的流量会变大。您需要权衡服务稳定性和资源情况来配置该参数。
eas.termination_grace_period		否	表示实例的优雅退出时间，单位为秒，默认为30秒。 EAS服务采用滚动更新的策略，实例会先进入Terminating状态，服务会先将流量从要退出的实例上切走，实例等待30秒后将已收到的请求处理完成后退出。如果请求处理时间很长，为保证服务更新时，状态为in progress的请求都能被处理完，您可以将该参数值适当调大。重要如果将该参数值调小则会影响服务稳定性，将该参数配置过大则会导致服务更新速度过慢，如果无特别需求请不要配置该参数。
scheduling	spread.policy	否	服务实例调度时的打散策略，支持以下几种策略： host：按照节点来打散，实例尽可能分散在不同的节点上。 zone：按照节点所在的可用区来打散，实例尽可能分散在不同的可用区。 default：按照默认策略进行调度，无主动打散的逻辑。配置示例： `{ "metadata": { "scheduling": { "spread": { "policy": "host" } } }`
resource_rebalancing		否	取值如下： false（默认值）：不启用该功能。 true：EAS会周期性地在高优先级资源上创建探针实例。如果探针实例调度成功，则会以指数增长方式创建更多探针实例，直至调度失败。同时，成功调度的探针实例完成初始化并且进入就绪状态后，会替换低优先级资源上的实例。该功能可以解决以下问题：在服务滚动更新过程中，正在终止的实例仍会占用资源，导致新创建实例启动在公共资源组上，由于公共资源限制，后续新实例会重新调度回专属资源组上。当同时使用竞价实例和常规实例时，系统会定期检查竞价实例是否可用，如果可用，则会将常规实例迁移至竞价实例上。
workload_type		否	如果您希望将EAS服务部署成任务的形式来使用，可将该参数配置为elasticjob。更多关于弹性Job服务的使用介绍，请参见弹性Job服务。
resource_burstable		否	支持为使用专属资源组部署的EAS服务启用弹性资源池功能： true：表示开启。 false：表示关闭。
shm_size		否	配置实例的共享内存，直接对内存进行读写操作，无需数据的复制或传输。单位为GB。

cloud参数说明

参数		是否必选	描述
computing	instances	否	使用公共资源组部署服务时，需设置该参数，表示使用的资源规格列表。当实例规格竞价失败或库存不足时，按照配置顺序依次尝试使用下一个实例规格创建服务。 type: 资源规格 spot_price_limit为可选参数：当配置该参数时：表示对应实例规格使用竞价实例，并指明价格上限。单位为CNY，支持按量付费。当不配置该参数时：表示对应实例规格为普通的按量付费实例。 capacity：配置使用该机型的实例数目上限。可以是数字，如“500”；也可以是字符串，如“20%”。配置后，如果机型实例数目达到上限，即使该机型还有库存资源也不会再使用。例如：服务总的实例数为200，配置A机型的capacity为20%，即该服务最多只会使用A机型拉起40个实例，其余的实例将通过其他规格拉起。
computing	disable_spot_protection_period	否	使用竞价实例时，需设置该参数，取值如下： false（默认值）：表示在竞价实例创建成功后，默认有1小时保护期。在保护期内即使市场价格超过了出价，实例也不会被释放。 true：表示禁用保护期，无保护期实例会始终比有保护期实例优惠10%左右。
networking	vpc_id	否	分别表示为EAS服务绑定的专有网络VPC、交换机和安全组。
	vswitch_id	否
	security_group_id	否

示例如下：

{
    "cloud": {
        "computing": {
            "instances": [
                {
                    "type": "ecs.c8i.2xlarge",
                    "spot_price_limit": 1
                },
                {
                    "type": "ecs.c8i.xlarge",
                    "capacity": "20%"
                }
            ],
            "disable_spot_protection_period": false
        },
        "networking": {
            "vpc_id": "vpc-bp1oll7xawovg9*****",
            "vswitch_id": "vsw-bp1jjgkw51nsca1e****",
            "security_group_id": "sg-bp1ej061cnyfn0b*****"
        }
    }
}

containers参数说明

使用自定义镜像部署服务时，详情请参见自定义镜像。

参数		是否必选	描述
image		是	使用镜像部署时必填。用于部署模型服务的镜像地址。
env	name	否	镜像执行时的环境变量名称。
env	value	否	镜像执行时的环境变量取值。
command		二者必选其一	镜像的入口命令，只支持单一命令形式，不支持复杂脚本，如：cd xxx && python app.py，这种形式请使用下面的script参数来指定，command字段适应于镜像中无/bin/sh命令的场景。
script		二者必选其一	镜像的入口执行的脚本，可指定较为复杂的脚本形式，多行以\n或分号分隔。
port		否	容器端口。重要由于EAS引擎监听固定的8080/9090端口，因此容器端口需要避开8080/9090端口。该端口一定要和command中的xxx.py文件配置的端口保持一致。
prepare	pythonRequirements	否	实例启动前安装的python requirements列表，要求镜像中在系统路径中存在python和pip命令，list格式，如： `"prepare": { "pythonRequirements": [ "numpy==1.16.4", "absl-py==0.11.0" ] }`
prepare	pythonRequirementsPath	否	实例启动前安装的python requirements.txt文件地址，要求镜像中在系统路径中存在Python和pip命令，requirements.txt可直接打在镜像中，也可以由外部存储挂载的方式挂载到服务实例中，如： `"prepare": { "pythonRequirementsPath": "/data_oss/requirements.txt" }`

networking参数说明

参数

是否必选

描述

gateway

否

为EAS服务配置的专属网关。

gateway_policy

否

rate_limit：服务的全局限流，即服务每秒接收的最大请求数。
- enable：是否打开限流。取值true表示打开限流，false表示关闭限流。
- limit：限流值。
  说明
  共享网关的服务会默认配置单服务为 1000qps，服务器组为 10000qps。专属网关无默认值。
concurrency_limit：服务的全局并发控制，即服务瞬时正在处理的最大请求数。应用型专属网关（ALB）暂不支持该设置。
- enable：是否打开限流。取值true表示打开限流，false表示关闭限流。
- limit：限流值。

限流配置示例：

{
    "networking": {
        "gateway_policy": {
            "rate_limit": {
                "enable": true,
                "limit": 100
            },
            "concurrency_limit": {
                "enable": true,
                "limit": 50
            }
        }
    }
}

sinker参数说明

参数		是否必选	描述
type		否	支持配置以下两种存储类型： maxcompute：大数据MaxCompute。 sls：日志服务SLS。
config	maxcompute.project	否	MaxCompute项目名称。
	maxcompute.table	否	MaxCompute数据表。
	sls.project	否	SLS项目名称。
	sls.logstore	否	SLS的Logstore。

配置示例如下：

存储到MaxCompute

"sinker": {
        "type": "maxcompute",
        "config": {
            "maxcompute": {
                "project": "cl****",
                "table": "te****"
            }
        }
    }

存储到日志服务SLS

"sinker": {
        "type": "sls",
        "config": {
            "sls": {
                "project": "k8s-log-****",
                "logstore": "d****"
            }
        }
    }

附录：JSON配置示例

上述参数在JSON文件中的配置示例如下：

{
  "token": "****M5Mjk0NDZhM2EwYzUzOGE0OGMx****",
  "processor": "tensorflow_cpu_1.12",
  "model_path": "oss://examplebucket/exampledir/",
  "oss_endpoint": "oss-cn-beijing.aliyuncs.com",
  "model_entry": "",
  "model_config": "",
  "processor_path": "",
  "processor_entry": "",
  "processor_mainclass": "",
  "processor_type": "",
  "warm_up_data_path": "",
  "runtime": {
    "enable_crash_block": false
  },
  "unit": {
        "size": 2
    },
  "sinker": {
        "type": "maxcompute",
        "config": {
            "maxcompute": {
                "project": "cl****",
                "table": "te****"
            }
        }
    },
  "cloud": {
    "computing": {
      "instances": [
        {
          "capacity": 800,
          "type": "dedicated_resource"
        },
        {
          "capacity": 200,
          "type": "ecs.c7.4xlarge",
          "spot_price_limit": 3.6
        }
      ],
      "disable_spot_protection_period": true
    },
    "networking": {
            "vpc_id": "vpc-bp1oll7xawovg9t8****",
            "vswitch_id": "vsw-bp1jjgkw51nsca1e****",
            "security_group_id": "sg-bp1ej061cnyfn0b****"
        }
  },
  "autoscaler": {
    "min": 2,
    "max": 5,
    "strategies": {
      "qps": 10
    }
  },
  "storage": [
    {
      "mount_path": "/data_oss",
      "oss": {
        "endpoint": "oss-cn-shanghai-internal.aliyuncs.com",
        "path": "oss://bucket/path/"
      }
    }
  ],
  "confidential": {
        "trustee_endpoint": "xx",
        "decryption_key": "xx"
    },
  "metadata": {
    "name": "test_eascmd",
    "resource": "eas-r-9lkbl2jvdm0puv****",
    "instance": 1,
    "workspace_id": "1405**",
    "gpu": 0,
    "cpu": 1,
    "memory": 2000,
    "gpu_memory": 10,
    "gpu_core_percentage": 10,
    "qos": "",
    "cuda": "11.2",
    "enable_grpc": false,
    "enable_webservice": false,
    "rdma": 1,
    "rpc": {
      "batching": false,
      "keepalive": 5000,
      "io_threads": 4,
      "max_batch_size": 16,
      "max_batch_timeout": 50,
      "max_queue_size": 64,
      "worker_threads": 5,
      "rate_limit": 0,
      "enable_sigterm": false
    },
    "rolling_strategy": {
      "max_surge": 1,
      "max_unavailable": 1
    },
    "eas.termination_grace_period": 30,
    "scheduling": {
      "spread": {
        "policy": "host"
      }
    },
    "resource_rebalancing": false,
    "workload_type": "elasticjob",
    "shm_size": 100
  },
  "features": {
    "eas.aliyun.com/extra-ephemeral-storage": "100Gi",
    "eas.aliyun.com/gpu-driver-version": "tesla=550.127.08"
  },
  "networking": {
    "gateway": "gw-m2vkzbpixm7mo****"
  },
  "containers": [
    {
      "image": "registry-vpc.cn-shanghai.aliyuncs.com/xxx/yyy:zzz",
      "prepare": {
        "pythonRequirements": [
          "numpy==1.16.4",
          "absl-py==0.11.0"
        ]
      },
      "command": "python app.py",
      "port": 8000
    }
  ],
  "dockerAuth": "dGVzdGNhbzoxM*******"
}