cuOpt Self-hosted Service Python客户端

cuOpt Self-hosted Service Python客户端是一个Python接口，用于访问用户管理的硬件上运行的NVIDIA cuOpt。

通过pip安装cuopt-sh-client

$ pip install .

使用CLI运行客户端

安装后，可以通过以下方式访问命令行实用程序

$ cuopt_sh cuopt_problem_data.json

如果出现问题超时，将返回请求ID。可以将ID传回CLI进行重新轮询，如下所示。这可以多次进行，直到返回结果。

$ cuopt_sh cuopt_problem_data.json
Request timed out.
Re-check the status with the following command:
cuopt_sh '{"reqId": "78238a58-d052-40b4-8dae-852be8f7906e"}'

$ cuopt_sh '{"reqId": "78238a58-d052-40b4-8dae-852be8f7906e"}'
{'response': ...}

参数列表

使用'cuopt_sh -h'检查帮助以获取更多信息。

  data:   cuOpt problem data file or a request id to repoll. If the -f option is used, this indicates the path of a file accessible to the server.
    -f:   Indicates that the DATA argument is the relative path of a cuOpt data file under the server's data directory.
    -o:   Override the default name of the result file if the server has been configured with a results directory.
-pt:  Number of seconds to poll for a result before timing out and returning a request id to re-query. Defaults to 120.
    -i:   Host address of the cuOpt server (default 0.0.0.0)
    -p:   Port of the cuOpt server (default 5000)
    -s:   Use ssl (default False)
    -c:   Path to self signed certificates only, skip for standard certificates (default "") 
    -l:   Log level (critical,error,warning,info,debug)
-ov:  If set, only validates input

最佳实践：使用本地数据文件选项（-f和-o）

描述cuOpt问题的数据可能相当大，并且如果服务器可以从其本地文件系统中读取文件而不是通过HTTP接收它们，则大多数情况下性能会更好。要使用此功能，请执行以下操作

• 配置服务器以使用本地数据目录 (见下文)
• 将cuOpt数据文件写入服务器的本地数据目录。文件可以放在数据目录的根目录，也可以放在数据目录下的某个路径。
• 使用-cuOpt CLI的-f选项指定文件名。给出相对于服务器本地数据目录根的数据文件路径。

示例

# Copy the file to the server's data directory with scp (or some other mechanism)
$ scp cuopt_problem_data.json my_server:/path/of/cuOpt/data/directory/

# Indicate to the CLI that the data is in the server's local data directory with the name 'cuopt_problem_data.json'. Note that a relative path is used.
$ cuopt_sh -f cuopt_problem_data.json

cuOpt的结果通常比输入数据小得多，并且可以很容易地通过HTTP返回。然而，将结果写入输出文件也可能很方便。要使用此功能，请执行以下操作

• 配置服务器以使用本地结果目录，并设置将结果写入磁盘的结果大小阈值(见下文)
• 使用-o选项指定结果文件的特定名称，或让服务器使用默认名称。
• 从cuOpt的响应中读取指定的文件。

示例

$ cuopt_sh -f cuopt_problem_data.json
{'result_file': 'cuopt_problem_data.json.result'}

$ scp my_server:/path/of/cuOpt/results/directory/cuopt_problem_data.json.result .

数据压缩

cuOpt服务器可以接受使用Python msgpack库或Python zlib库压缩的数据。为了获得最高的效率，建议使用Python生成JSON数据并将其写入文件使用msgpack。但是，如果数据未使用msgpack写入，则可以使用msgpack或zlib对其进行压缩，或保持未压缩状态。

直接从Python运行客户端

使用可选的ip、port和use_ssl参数初始化CuOptServiceSelfHostClient

	from cuopt_sh_client import CuOptServiceSelfHostClient
        cuopt_service_client = CuOptServiceSelfHostClient(ip, port)

获取优化路线

要通过HTTP提交cuOpt数据文件

        # Send cuOpt data over HTTP
	# Data may be the path to a file OR a dictionary containing
	# a cuOpt problem
        optimized_routes = cuopt_service_client.get_optimized_routes(
            path_to_cuopt_problem_data
        )

要指定位于服务器数据目录中的数据文件

        # Tell the cuOpt server that the data is in its local data directory
        optimized_routes = cuopt_service_client.get_optimized_routes(
            relative_path_under_servers_data_directory, filepath = True
        )

问题数据文件应包含以下详细信息的JSON对象

    cost_waypoint_graph_data
    travel_time_waypoint_graph_data
    cost_matrix_data
    travel_time_matrix_data
    fleet_data
    task_data
    solver_config

此客户端包含一个示例数据文件'cuopt_problem_data.json'。

有关更多详细信息，请参阅https://docs.nvda.net.cn/cuopt/user-guide/serv-api.html

为本地文件功能配置cuOpt服务器

默认情况下，cuOpt服务器中未启用本地文件功能。要配置此功能，请设置以下环境变量，在服务器的容器环境中。

环境变量

要启用从本地文件系统读取cuOpt数据文件，请设置以下内容

• CUOPT_DATA_DIR: cuOpt服务器容器环境中的目录的绝对路径。通常，此路径是容器外存在的一个卷的挂载点。

要启用将cuOpt数据文件写入本地文件系统，请设置以下内容

• CUOPT_RESULT_DIR: cuOpt服务器容器环境中的目录的绝对路径。通常，此路径是容器外存在的一个卷的挂载点。
• CUOPT_MAX_RESULT: cuOpt将通过HTTP返回的结果的最大字节数。要将所有结果写入磁盘，请将此值设置为0。默认值为250。
• CUOPT_RESULT_MODE: 应用到cuOpt创建的结果文件的Linux文件模式（如chmod命令）。默认值为644。

Docker示例

在此示例中，我们运行图像cuoptimage并将本地目录./data和./results分别挂载到容器的/cuopt_data和/cuopt_resulst。我们设置环境变量以告诉cuOpt数据和结果目录的位置，并将所有结果写入文件而不是通过HTTP（CUOPT_MAX_RESULT=0）。

$ docker run --rm --gpus=all --network=host -v `pwd`/data:/cuopt_data  -v `pwd`/results:/cuopt_results -e CUOPT_DATA_DIR=/cuopt_data -e CUOPT_RESULT_DIR=/cuopt_results -e CUOPT_MAX_RESULT=0 -it cuoptimage

目录权限

挂载到cuOpt容器的数据和结果目录需要可由容器用户读取和写入，并且必须设置执行权限。如果不这样做，容器将打印错误消息并退出。请在运行cuOpt服务器之前确保正确设置这些目录的权限。

当使用docker运行cuOpt并使用默认容器用户时

• cuOpt数据目录应由组0（即root组）可读和可执行
• cuOpt结果目录应由组0可写和可执行

当使用docker运行cuOpt并使用--user标志仅设置UID时

• cuOpt数据目录应由组0或指定的UID可读和可执行
• cuOpt结果目录应由组0或指定的UID可写和可执行

当使用docker运行cuOpt并使用--user标志设置UID和GID时

• cuOpt数据目录应由指定的UID或指定的GID可读和可执行
• cuOpt结果目录应由指定的UID或指定的GID可写和可执行