InvokeOptions 结构体 ===================== InvokeOptions Definition --------------------------- .. code-block:: cpp struct InvokeOptions { // 以 1/1000 cpu 核为单位 int cpu; // 以 1MB 为单位 int memory; // 除了 CPU 和内存之外的自定义资源 std::unordered_map customResources; // 自定义扩展 std::unordered_map customExtensions; // Pod 标签，仅在部署到 Kubernetes 时生效 std::unordered_map podLabels; std::vector labels; std::unordered_map affinity; size_t retryTimes = 0; bool (*retryChecker)(const Exception &e) noexcept = nullptr; size_t priority = 0; bool alwaysLocalMode = false; bool preferredPriority = true; bool preferredAntiOtherLabels = false; bool requiredPriority = false; std::string groupName = ""; InstanceRange instanceRange; int recoverRetryTimes = 0; RuntimeEnv runtimeEnv; }; InvokeOptions 说明 ------------------ 函数调用选项，用于指定调用资源等功能。 InvokeOptions 参数 ~~~~~~~~~~~~~~~~~~ +--------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------+------------------------+ | **名称** | **类型** | **描述** | **默认值** | +==========================+===============================================+=================================================================================================+========================+ | cpu | int | 指定 CPU 核心资源，以 `1/1000` CPU 核为单位。 | ``500`` | +--------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------+------------------------+ | memory | int | 指定内存资源，以 `1MB` 为单位。 | ``500`` | +--------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------+------------------------+ | customResources | std::unordered_map | 自定义资源，当前支持配置异构资源与磁盘资源。 | - | | | | | | | | | • 磁盘资源支持 "disk"，单位：GB 。 | | | | | • 异构资源支持 "GPU/XX/YY" 和 "NPU/XX/YY"， | | | | | XX 为卡的型号，如 Ascend910B4，支持正则表达式。YY 可以是 count、HBM、latency、stream。 | | +--------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------+------------------------+ | customExtensions | std::unordered_map | 用户自定义配置（例如函数并发性）。也用作 metrics 的用户自定义 tag，用于采集用户信息。 | - | +--------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------+------------------------+ | podLabels | std::unordered_map | 指定实例位置的 pod 标签（低可靠实例不支持配置）。**仅在 Kubernetes 上部署时生效**。 | - | +--------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------+------------------------+ | labels | std::vector | 用于函数实例的亲和、反亲和标签（格式如：`"key"` ， `"key:value"`）。 | - | +--------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------+------------------------+ | affinity | std::unordered_map | 定义函数实例调度的亲和性、反亲和性（待废弃）。 | - | +--------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------+------------------------+ | retryTime | size_t | 无状态函数的重试次数。 | ``0`` | +--------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------+------------------------+ | retryChecker | bool (*)(const YR::Exception &e) noexcept | 无状态函数的重试判断钩子，默认空（当 `retryTimes = 0` 时无效）。 | - | +--------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------+------------------------+ | priority | size_t | 定义无状态函数的优先级。 | ``0`` | +--------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------+------------------------+ | alwaysLocalMode | bool | 指定 cluster mode 强制在本地使用多线程运行用户函数（在 `local mode` 模式下不生效）。 | ``false`` | +--------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------+------------------------+ | preferredPriority | bool | 是否开启优先级调度。开启后，当传入多个弱亲和条件，按顺序匹配打分，出现一个满足的即可调度成功。 | ``true`` | +--------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------+------------------------+ | requiredPriority | bool | 是否开启优先级调度。开启后，当传入多个强亲和条件，按顺序匹配打分， | ``false`` | | | | 当传入多个强亲和条件都不满足时，调度失败。 | | +--------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------+------------------------+ | preferredAntiOtherLabels | bool | 是否开启反亲和不可选资源。开启后，当传入多个弱亲和条件都不满足时，调度失败。 | ``false`` | +--------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------+------------------------+ | groupName | string | 指定成组实例调度器 name，默认空。 | ``""`` | +--------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------+------------------------+ | instanceRange | InstanceRange | 函数实例个数 Range 范围配置，用于配置调度/部署一组函数实例的范围。 | - | | | | 详见 `struct-InstanceRange <./struct-InstanceRange.html>`_ 。 | | +--------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------+------------------------+ | recoverRetryTimes | int | 实例最大恢复次数（当实例异常退出时，自动以最新状态恢复实例）。默认 ``0``，即不进行自动恢复。 | ``0`` | | | | 注：并不保证所有指定的重试次数都会完成，存在不可恢复的异常场景时， | | | | | openYuanrong会提前停止重试并抛出异常。 | | +--------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------+------------------------+ | runtimeEnv | RuntimeEnv | 配置跨语言调用 Python 函数时的运行时环境。详见 `RuntimeEnv <./RuntimeEnv.html>`_ 。 | - | +--------------------------+-----------------------------------------------+-------------------------------------------------------------------------------------------------+------------------------+ 关于 retryTime 和 retryChecker ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 注：无状态函数，以下由框架重试的错误码，不占用重试次数： 1. ERR_RESOURCE_NOT_ENOUGH 2. ERR_INSTANCE_NOT_FOUND 3. ERR_INSTANCE_EXITED 建议由用户决定是否重试的错误码： 1. ERR_USER_FUNCTION_EXCEPTION 2. ERR_REQUEST_BETWEEN_RUNTIME_BUS 3. ERR_INNER_COMMUNICATION 4. ERR_SHARED_MEMORY_LIMIT 5. EDERR_OPERATE_DISK_FAILED 6. ERR_INSUFFICIENT_DISK_SPACE `retryTime` 和 `retryChecker` 暂时不支持有状态函数，否则会抛出异常。示例用法见 `FunctionHandler::Options <../../C%2B%2B/FunctionHandler-Options.html>`_ 。 关于 alwaysLocalMode ~~~~~~~~~~~~~~~~~~~~~~~~~~ - 在 cluster mode 模式下指定 `alwaysLocalMode` 为 ``true`` 来调用无状态函数时，生成的 ObjectRef 也是 local 的，可以通过 `bool ObjectRef::IsLocal() const` 方法检查。 - 在 cluster mode 模式下指定 `alwaysLocalMode` 为 ``true`` 来创建有状态函数时，已经确定了该有状态函数是否在本地多线程创建，后续的调用不再需要指定是否在本地执行。 当前不支持 `Wait` 、 `Get` 、 `Cancel` 接口以及 `Invoke` 参数调用时混用 local 和 cluster 的 ObjectRef ，否则抛出异常。当 cluster mode 初始化线程池为空但仍然调用了 `alwaysLocalMode` 的无状态或有状态函数，也会抛出异常。 关于 customExtensions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ customExtensions 表示用户自定义的配置，接收用户自定义的 key/value 键值对，常见的配置如下： +---------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------+---------------------+ | **key，std::string 类型** | **value，std::string 类型** | **描述** | **默认值** | +===========================+=============================+========================================================================================================+=====================+ | Concurrency | 并发度 | 实例并发度。限制：``[1,1000]``。 | ``1`` | +---------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------+---------------------+ | lifecycle | detached | 支持 detached 模式。 | — | +---------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------+---------------------+ | init_call_timeout | init 调用超时时间 | init 调用超时时间，单位为秒。如果未配置，将以 openYuanrong 部署时配置时间为准，详见 | — | | | | `runtime 配置 <../../../../../deploy/deploy_processes/parameters.html#runtime>`_ 中的 | | | | | ``--runtime_init_call_timeout_seconds``。 | | +---------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------+---------------------+ | ReliabilityType | 实例可靠性配置 | 配置 ``low`` 时，将减少实例数据持久化次数，不支持 Recover，不支持配置 pod Labels。 | — | +---------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------+---------------------+ | DELEGATE_DIRECTORY_INFO | 自定义目录 | 支持创建、删除子目录能力。当实例创建时，若用户自定义目录存在且有读写权限，则在该目录下创建 | ``'/tmp'`` | | | | `子目录` 作为工作目录；否则，在 ``'/tmp'`` 目录下创建子目录作为工作目录。当实例销毁时，工作目录销毁。 | | | | | 其中，用户函数可以通过 ``INSTANCE_WORK_DIR`` 环境变量获取工作目录。 | | +---------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------+---------------------+ | DELEGATE_DIRECTORY_QUOTA | 子目录配额大小 | 取值范围大于 0 M 小于 1 TB；如果没有该配置，默认 512 M；配置 ``-1`` 则不监控；单位：MB。 | ``512`` | +---------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------+---------------------+ | DELEGATE_DOWNLOAD | 代理用户下载代码 | 支持代理下载用户代码，例如如从 OBS 中下载，详情见下方 DELEGATE_DOWNLOAD 详细配置表。 | - | +---------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------+---------------------+ | GRACEFUL_SHUTDOWN_TIME | 自定义优雅退出时间 | 实例优雅退出超时时间，单位：秒。限制：≥0；0 表示立即退出，不保证能够完成用户的优雅退出函数； | — | | | | 若配置 <0，则使用部署时的系统配置作为超时时间，参考 | | | | | `runtime 配置 <../../../../../deploy/deploy_processes/parameters.html#runtime>`_ 中的 | | | | | ``--kill_process_timeout_seconds``。 | | +---------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------+---------------------+ | RECOVER_RETRY_TIMEOUT | 自定义 recover 超时时间 | 实例 recover 超时时间，单位：毫秒。限制：>0。 | ``10 * 60 * 1000`` | +---------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------+---------------------+ | AFFINITY_POOL_ID | 自定义亲和 pool 池 ID | 对于实例创建，当遇到资源不足（或者亲和条件不满足）时，内核将创建指定 poolID 的 POD，用于实例调度。 | — | | | | **仅在 Kubernetes 上部署时生效**。 | | +---------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------+---------------------+ DELEGATE_DOWNLOAD配置 ^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------------------------+----------------------------------+--------------------------------------------------+ | **key，std::string 类型** | **value，std::string 类型** | **描述** | +============================+==================================+==================================================+ | storage_type | 存储服务类型 | 当前支持从 obs 下载(s3) | +----------------------------+----------------------------------+--------------------------------------------------+ | hostName | 存储服务地址 | obs 地址 | +----------------------------+----------------------------------+--------------------------------------------------+ | bucketId | 桶名 | obs 桶名 | +----------------------------+----------------------------------+--------------------------------------------------+ | objectId | 对象名 | obs 对象名 | +----------------------------+----------------------------------+--------------------------------------------------+ | sha256 | 待下载的对象文件 sha256 值 | 通过 sha256 进行文件校验，确保下载文件完整性 | +----------------------------+----------------------------------+--------------------------------------------------+ | temporaryAccessKey | 访问 obs 桶的鉴权信息 | 访问 obs 桶的鉴权信息 | +----------------------------+----------------------------------+--------------------------------------------------+ | temporarySecretKey | 访问 obs 桶的鉴权信息 | 访问 obs 桶的鉴权信息 | +----------------------------+----------------------------------+--------------------------------------------------+ | securityToken | 访问 obs 桶的鉴权信息 | 访问 obs 桶的鉴权信息 | +----------------------------+----------------------------------+--------------------------------------------------+ customExtensions 中输入用户自定义 `metrics tag` 时： .. code-block:: cpp YR::InvokeOptions opt; opt.customExtensions.insert({"YR_Metrics", "{\"endpoint\":\"127.0.0.1\", \"project_id\":\"my_project_id\"}"}); 键为 `YR_Metrics`，值为自定义 label 的 JSON 字符串： Prometheus 中选择 `metrics name` 为 `yr_app_instance_billing_invoke_latency`，可在采集到的 invoke 信息中找到自定义 tag 信息： .. code-block:: shell yr_app_instance_billing_invoke_latency{ ... endpoint="127.0.0.1", ...} 关于 customResources ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 配置磁盘资源 ^^^^^^^^^^^^^^^^^^^^ `customResources` 所配置的磁盘资源，单位统一为 GB。 使用示例如下： .. code-block:: cpp YR::InvokeOptions opt; opt.customResources.insert({"disk", 10}) 在调度任务成功执行后，openYuanrong支持用户进程通过读取环境变量 `YR_DISK_MOUNT_POINT` 来获取已分配磁盘的挂载路径信息。