尧图网站建设 
Rivet Actors RunnerConfigVariant 详解serverless 与 normal 两种 Runner 配置模式【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actorsRunnerConfigVariant是 Rivet Actors 中用于标识Runner 配置类型的枚举它区分了两种完全不同的资源调度与运行形态serverless按需弹性伸缩与normal常驻运行。本文以 RunnerConfigVariant.md 为骨架结合仓库内 Rust / TypeScript / Go 多语言 SDK 的生成代码与后端核心类型定义完整讲解该枚举的序列化值、各语言实现形态、配套的RunnerConfig配置结构差异以及在GET /runner-configs接口中的实际用法帮助你准确理解并正确配置 Rivet Actors 的 Runner 运行模式。枚举定义与序列化值RunnerConfigVariant是一个仅有两种取值的简单枚举其序列化wire format值定义如下NameValueServerlessserverlessNormalnormal需要注意的是这里的 Value 是字符串形式的 JSON 序列化值而不是整数索引。该枚举在 HTTP API 中作为查询参数、以及在RunnerConfig对象中作为判别字段discriminator出现均使用上述字符串值进行传输。后端核心类型的权威定义该枚举在服务端最底层的定义位于 engine/packages/types/src/keys/namespace/runner_config.rs它同时给出了整数表示存储/内部使用与字符串表示传输/外部使用两套形态#[derive(Clone, Copy, Debug, Serialize, Deserialize, strum::FromRepr, ToSchema)] #[serde(rename_all snake_case)] pub enum RunnerConfigVariant { Serverless 0, Normal 1, } impl RunnerConfigVariant { pub fn parse(v: str) - OptionSelf { match v { serverless Some(RunnerConfigVariant::Serverless), normal Some(RunnerConfigVariant::Normal), _ None, } } }从源码结构可以提炼出三个关键点整数判别值Serverless 0、Normal 1这是内部存储与比较时使用的表示字符串解析入口parse()方法只接受serverless与normal两个字符串其余输入一律返回None。这意味着任何请求方传入其他字符串都会解析失败属于严格的取值校验序列化规则#[serde(rename_all snake_case)]确保序列化时输出与枚举同名的小写下划线形式本枚举均为单次小写单词即serverless/normal与 RunnerConfigVariant.md 表格中的 Value 列完全一致。各语言 SDK 中的实现形态Rivet Actors 通过代码生成器OpenAPI Generator / Fern为不同语言产出了对应的类型定义它们均保持与后端枚举完全一致的取值语义。Rust SDKRust 完整版 SDK 的生成代码位于 engine/sdks/rust/api-full/rust/src/models/runner_config_variant.rs#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Serialize, Deserialize)] pub enum RunnerConfigVariant { #[serde(rename serverless)] Serverless, #[serde(rename normal)] Normal, }该生成类型包含三个值得注意的行为Display实现serverless/normal两个变体在to_string()时输出与传输值完全一致的字符串便于直接拼接进 URL 查询参数或日志Default实现Default返回Serverless。也就是说当构造请求时不显式指定 variantRust 类型的默认值就是serverless——这一点与文档表格中 Serverless 排在第一位的顺序一致Hash Ord派生支持将该枚举用作HashMap/HashSet的键或进行排序比较适用于客户端本地缓存 Runner 配置的场景。TypeScript SDKTypeScript SDK 中的定义有两种形态运行时常量对象与纯类型。运行时定义在 engine/sdks/typescript/api-full/src/api/types/RunnerConfigVariant.tsexport type RunnerConfigVariant serverless | normal; export const RunnerConfigVariant { Serverless: serverless, Normal: normal, } as const;而序列化层Fern 生成的 Schema在 engine/sdks/typescript/api-full/src/serialization/types/RunnerConfigVariant.tsexport const RunnerConfigVariant: core.serialization.Schema serializers.RunnerConfigVariant.Raw, Rivet.RunnerConfigVariant core.serialization.enum_([serverless, normal]);序列化层通过enum_([serverless, normal])在运行时校验取值任何不在白名单内的字符串在反序列化阶段就会被拒绝与 Rust 侧parse()的行为保持一致。Go SDKGo SDK 同样包含该枚举的字符串常量定义engine/sdks/go/api-full/types.go各语言 SDK 共享同一份 OpenAPI 规范engine/artifacts/openapi.json生成因此取值与语义在 Rust、TypeScript、Go 之间完全对齐。两种变体的配置结构差异RunnerConfigVariant枚举本身只负责“标识类型”真正体现两种模式差异的是与之配套的RunnerConfig对象。根据 RunnerConfig.md一个完整的 Runner 配置包含两个互斥的分支字段字段类型说明normalRunnerConfigKindOneOfNormal常驻normal模式的配置体serverlessRunnerConfigKindOneOf1Serverless按需serverless模式的配置体drain_on_version_upgradeOptionbool已废弃DeprecatedmetadataOptionserde_json::Value可选附加元数据通过 RunnerConfigKind.md 可知normal与serverless分别对应RunnerConfigKindOneOf和RunnerConfigKindOneOf1两个封闭的分支结构二者字段集合截然不同。serverless 模式的配置字段根据 RunnerConfigKindOneOf1Serverless.mdserverless 模式下的配置项如下字段类型默认/必填说明urlString必填Runner 服务的入口地址request_lifespani32必填请求生命周期上限单位秒max_concurrent_actorsOptioni64可选单个 Runner 上最大并发 Actor 数actor_eviction_delayOptioni32可选Actor 驱逐延迟单位秒actor_eviction_periodOptioni32可选Actor 驱逐周期单位秒actor_eviction_rateOptionf32可选Actor 驱逐速率单位个/秒drain_grace_periodOptioni32可选排空drain宽限期单位秒headersOptionHashMapString, String可选附加 HTTP 请求头metadata_poll_intervalOptioni64可选元数据轮询间隔毫秒未设置时使用全局默认值drain_on_version_upgradeOptionbool可选版本升级时是否排空min_runners/max_runners/runners_margin/slots_per_runnerOptioni32可选已废弃Deprecated从字段组合可以推断serverless 模式是一套“按需拉起、自动驱逐、受控并发”的弹性调度模型url与request_lifespan是必填项说明该模式下 Runner 以临时请求request-driven方式被唤醒actor_eviction_delay / period / rate三件套共同控制空闲 Actor 的回收节奏延迟多久开始、每隔多久检查、每秒回收多少metadata_poll_interval控制对元数据的轮询频率弃用的min_runners / max_runners / runners_margin / slots_per_runner表明该模式早期曾借鉴常驻模式的固定槽位slot模型现已转向纯事件驱动调度。normal 模式的配置字段相比之下根据 RunnerConfigKindOneOfNormal.mdnormal 模式的配置体非常精简字段类型默认/必填说明actor_eviction_delayOptioni32可选Actor 驱逐延迟单位秒actor_eviction_periodOptioni32可选Actor 驱逐周期单位秒actor_eviction_rateOptionf32可选Actor 驱逐速率单位个/秒drain_on_version_upgradeOptionbool可选版本升级时是否排空normal 模式没有url、request_lifespan、max_concurrent_actors等字段说明它代表的是长期常驻的 Runner不需要按请求临时拉起也没有并发上限约束仅保留驱逐策略与升级排空行为作为资源治理手段。两模式对比小结维度serverlessnormal调度模型按需request-driven弹性拉起常驻运行必填字段url、request_lifespan无并发控制max_concurrent_actors无驱逐策略actor_eviction_delay/period/rate同左元数据轮询metadata_poll_interval无附加请求头headers无历史字段min/max_runners、runners_margin、slots_per_runner已废弃无在 API 中的实际用法RunnerConfigVariant最直接的消费场景是Runner 配置列表接口。根据 RunnerConfigsListApi.md该接口定义如下GET /runner-configs其查询参数中明确包含variant取值即RunnerConfigVariant的两种字符串值之一参数类型必填说明namespaceString是命名空间variantRunnerConfigVariant否按运行模式过滤serverless或normallimiti32否分页大小cursorString否分页游标runner_namesString否已废弃Deprecatedrunner_nameVecString否按 Runner 名称过滤服务端对查询参数的解析定义在 engine/packages/api-types/src/runner_configs/list.rs#[derive(Debug, Serialize, Deserialize, Clone, IntoParams)] #[serde(deny_unknown_fields)] #[into_params(parameter_in Query)] pub struct ListQuery { pub namespace: String, pub limit: Optionusize, pub cursor: OptionString, pub variant: Optionrivet_types::keys::namespace::runner_config::RunnerConfigVariant, /// Deprecated. #[serde(default)] pub runner_names: OptionString, #[serde(default)] pub runner_name: VecString, }这里的variant字段直接复用rivet_types::keys::namespace::runner_config::RunnerConfigVariant类型因此serverless与normal之外的取值会被parse()拒绝。一个只查询 serverless 模式配置的请求示例GET /runner-configs?namespacemy-namespacevariantserverless Authorization: Bearer token Accept: application/json响应体RunnerConfigsListResponse定义见 RunnerConfigsListResponse.md会返回一个以 Runner 配置名为键的HashMapString, RunnerConfigResponse以及分页信息其中每个RunnerConfigResponse内部就通过normal/serverless分支字段携带对应模式的具体配置。相关资源与延伸阅读枚举文档RunnerConfigVariant.md配置结构文档RunnerConfig.md、RunnerConfigKind.md、RunnerConfigKindOneOf1Serverless.md、RunnerConfigKindOneOfNormal.md接口文档RunnerConfigsListApi.md后端核心类型engine/packages/types/src/keys/namespace/runner_config.rs请求参数定义engine/packages/api-types/src/runner_configs/list.rsRust SDK 生成代码engine/sdks/rust/api-full/rust/src/models/runner_config_variant.rs相关接口测试engine/packages/engine/tests/runner/api_runner_configs_list.rs若需深入理解 serverless 模式的完整设计背景可进一步阅读 docs-internal/engine/SERVERLESS.md小结RunnerConfigVariant虽然只是一个双值枚举却是理解 Rivet Actors Runner 调度模型的钥匙serverless代表按需弹性、具备驱逐与并发控制机制的轻量运行模式normal代表常驻型运行模式。在多语言 SDK 中它的取值严格统一为serverless/normal并作为GET /runner-configs接口的variant查询参数参与过滤结合 RunnerConfigKindOneOf1Serverless.md 与 RunnerConfigKindOneOfNormal.md 中的字段差异即可为不同负载特征的应用选择并配置合适的 Runner 运行形态。【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Rivet Actors RunnerConfigVariant 详解：serverless 与 normal 两种 Runner 配置模式
Rivet Actors RunnerConfigVariant 详解serverless 与 normal 两种 Runner 配置模式【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actorsRunnerConfigVariant是 Rivet Actors 中用于标识Runner 配置类型的枚举它区分了两种完全不同的资源调度与运行形态serverless按需弹性伸缩与normal常驻运行。本文以 RunnerConfigVariant.md 为骨架结合仓库内 Rust / TypeScript / Go 多语言 SDK 的生成代码与后端核心类型定义完整讲解该枚举的序列化值、各语言实现形态、配套的RunnerConfig配置结构差异以及在GET /runner-configs接口中的实际用法帮助你准确理解并正确配置 Rivet Actors 的 Runner 运行模式。枚举定义与序列化值RunnerConfigVariant是一个仅有两种取值的简单枚举其序列化wire format值定义如下NameValueServerlessserverlessNormalnormal需要注意的是这里的 Value 是字符串形式的 JSON 序列化值而不是整数索引。该枚举在 HTTP API 中作为查询参数、以及在RunnerConfig对象中作为判别字段discriminator出现均使用上述字符串值进行传输。后端核心类型的权威定义该枚举在服务端最底层的定义位于 engine/packages/types/src/keys/namespace/runner_config.rs它同时给出了整数表示存储/内部使用与字符串表示传输/外部使用两套形态#[derive(Clone, Copy, Debug, Serialize, Deserialize, strum::FromRepr, ToSchema)] #[serde(rename_all snake_case)] pub enum RunnerConfigVariant { Serverless 0, Normal 1, } impl RunnerConfigVariant { pub fn parse(v: str) - OptionSelf { match v { serverless Some(RunnerConfigVariant::Serverless), normal Some(RunnerConfigVariant::Normal), _ None, } } }从源码结构可以提炼出三个关键点整数判别值Serverless 0、Normal 1这是内部存储与比较时使用的表示字符串解析入口parse()方法只接受serverless与normal两个字符串其余输入一律返回None。这意味着任何请求方传入其他字符串都会解析失败属于严格的取值校验序列化规则#[serde(rename_all snake_case)]确保序列化时输出与枚举同名的小写下划线形式本枚举均为单次小写单词即serverless/normal与 RunnerConfigVariant.md 表格中的 Value 列完全一致。各语言 SDK 中的实现形态Rivet Actors 通过代码生成器OpenAPI Generator / Fern为不同语言产出了对应的类型定义它们均保持与后端枚举完全一致的取值语义。Rust SDKRust 完整版 SDK 的生成代码位于 engine/sdks/rust/api-full/rust/src/models/runner_config_variant.rs#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Serialize, Deserialize)] pub enum RunnerConfigVariant { #[serde(rename serverless)] Serverless, #[serde(rename normal)] Normal, }该生成类型包含三个值得注意的行为Display实现serverless/normal两个变体在to_string()时输出与传输值完全一致的字符串便于直接拼接进 URL 查询参数或日志Default实现Default返回Serverless。也就是说当构造请求时不显式指定 variantRust 类型的默认值就是serverless——这一点与文档表格中 Serverless 排在第一位的顺序一致Hash Ord派生支持将该枚举用作HashMap/HashSet的键或进行排序比较适用于客户端本地缓存 Runner 配置的场景。TypeScript SDKTypeScript SDK 中的定义有两种形态运行时常量对象与纯类型。运行时定义在 engine/sdks/typescript/api-full/src/api/types/RunnerConfigVariant.tsexport type RunnerConfigVariant serverless | normal; export const RunnerConfigVariant { Serverless: serverless, Normal: normal, } as const;而序列化层Fern 生成的 Schema在 engine/sdks/typescript/api-full/src/serialization/types/RunnerConfigVariant.tsexport const RunnerConfigVariant: core.serialization.Schema serializers.RunnerConfigVariant.Raw, Rivet.RunnerConfigVariant core.serialization.enum_([serverless, normal]);序列化层通过enum_([serverless, normal])在运行时校验取值任何不在白名单内的字符串在反序列化阶段就会被拒绝与 Rust 侧parse()的行为保持一致。Go SDKGo SDK 同样包含该枚举的字符串常量定义engine/sdks/go/api-full/types.go各语言 SDK 共享同一份 OpenAPI 规范engine/artifacts/openapi.json生成因此取值与语义在 Rust、TypeScript、Go 之间完全对齐。两种变体的配置结构差异RunnerConfigVariant枚举本身只负责“标识类型”真正体现两种模式差异的是与之配套的RunnerConfig对象。根据 RunnerConfig.md一个完整的 Runner 配置包含两个互斥的分支字段字段类型说明normalRunnerConfigKindOneOfNormal常驻normal模式的配置体serverlessRunnerConfigKindOneOf1Serverless按需serverless模式的配置体drain_on_version_upgradeOptionbool已废弃DeprecatedmetadataOptionserde_json::Value可选附加元数据通过 RunnerConfigKind.md 可知normal与serverless分别对应RunnerConfigKindOneOf和RunnerConfigKindOneOf1两个封闭的分支结构二者字段集合截然不同。serverless 模式的配置字段根据 RunnerConfigKindOneOf1Serverless.mdserverless 模式下的配置项如下字段类型默认/必填说明urlString必填Runner 服务的入口地址request_lifespani32必填请求生命周期上限单位秒max_concurrent_actorsOptioni64可选单个 Runner 上最大并发 Actor 数actor_eviction_delayOptioni32可选Actor 驱逐延迟单位秒actor_eviction_periodOptioni32可选Actor 驱逐周期单位秒actor_eviction_rateOptionf32可选Actor 驱逐速率单位个/秒drain_grace_periodOptioni32可选排空drain宽限期单位秒headersOptionHashMapString, String可选附加 HTTP 请求头metadata_poll_intervalOptioni64可选元数据轮询间隔毫秒未设置时使用全局默认值drain_on_version_upgradeOptionbool可选版本升级时是否排空min_runners/max_runners/runners_margin/slots_per_runnerOptioni32可选已废弃Deprecated从字段组合可以推断serverless 模式是一套“按需拉起、自动驱逐、受控并发”的弹性调度模型url与request_lifespan是必填项说明该模式下 Runner 以临时请求request-driven方式被唤醒actor_eviction_delay / period / rate三件套共同控制空闲 Actor 的回收节奏延迟多久开始、每隔多久检查、每秒回收多少metadata_poll_interval控制对元数据的轮询频率弃用的min_runners / max_runners / runners_margin / slots_per_runner表明该模式早期曾借鉴常驻模式的固定槽位slot模型现已转向纯事件驱动调度。normal 模式的配置字段相比之下根据 RunnerConfigKindOneOfNormal.mdnormal 模式的配置体非常精简字段类型默认/必填说明actor_eviction_delayOptioni32可选Actor 驱逐延迟单位秒actor_eviction_periodOptioni32可选Actor 驱逐周期单位秒actor_eviction_rateOptionf32可选Actor 驱逐速率单位个/秒drain_on_version_upgradeOptionbool可选版本升级时是否排空normal 模式没有url、request_lifespan、max_concurrent_actors等字段说明它代表的是长期常驻的 Runner不需要按请求临时拉起也没有并发上限约束仅保留驱逐策略与升级排空行为作为资源治理手段。两模式对比小结维度serverlessnormal调度模型按需request-driven弹性拉起常驻运行必填字段url、request_lifespan无并发控制max_concurrent_actors无驱逐策略actor_eviction_delay/period/rate同左元数据轮询metadata_poll_interval无附加请求头headers无历史字段min/max_runners、runners_margin、slots_per_runner已废弃无在 API 中的实际用法RunnerConfigVariant最直接的消费场景是Runner 配置列表接口。根据 RunnerConfigsListApi.md该接口定义如下GET /runner-configs其查询参数中明确包含variant取值即RunnerConfigVariant的两种字符串值之一参数类型必填说明namespaceString是命名空间variantRunnerConfigVariant否按运行模式过滤serverless或normallimiti32否分页大小cursorString否分页游标runner_namesString否已废弃Deprecatedrunner_nameVecString否按 Runner 名称过滤服务端对查询参数的解析定义在 engine/packages/api-types/src/runner_configs/list.rs#[derive(Debug, Serialize, Deserialize, Clone, IntoParams)] #[serde(deny_unknown_fields)] #[into_params(parameter_in Query)] pub struct ListQuery { pub namespace: String, pub limit: Optionusize, pub cursor: OptionString, pub variant: Optionrivet_types::keys::namespace::runner_config::RunnerConfigVariant, /// Deprecated. #[serde(default)] pub runner_names: OptionString, #[serde(default)] pub runner_name: VecString, }这里的variant字段直接复用rivet_types::keys::namespace::runner_config::RunnerConfigVariant类型因此serverless与normal之外的取值会被parse()拒绝。一个只查询 serverless 模式配置的请求示例GET /runner-configs?namespacemy-namespacevariantserverless Authorization: Bearer token Accept: application/json响应体RunnerConfigsListResponse定义见 RunnerConfigsListResponse.md会返回一个以 Runner 配置名为键的HashMapString, RunnerConfigResponse以及分页信息其中每个RunnerConfigResponse内部就通过normal/serverless分支字段携带对应模式的具体配置。相关资源与延伸阅读枚举文档RunnerConfigVariant.md配置结构文档RunnerConfig.md、RunnerConfigKind.md、RunnerConfigKindOneOf1Serverless.md、RunnerConfigKindOneOfNormal.md接口文档RunnerConfigsListApi.md后端核心类型engine/packages/types/src/keys/namespace/runner_config.rs请求参数定义engine/packages/api-types/src/runner_configs/list.rsRust SDK 生成代码engine/sdks/rust/api-full/rust/src/models/runner_config_variant.rs相关接口测试engine/packages/engine/tests/runner/api_runner_configs_list.rs若需深入理解 serverless 模式的完整设计背景可进一步阅读 docs-internal/engine/SERVERLESS.md小结RunnerConfigVariant虽然只是一个双值枚举却是理解 Rivet Actors Runner 调度模型的钥匙serverless代表按需弹性、具备驱逐与并发控制机制的轻量运行模式normal代表常驻型运行模式。在多语言 SDK 中它的取值严格统一为serverless/normal并作为GET /runner-configs接口的variant查询参数参与过滤结合 RunnerConfigKindOneOf1Serverless.md 与 RunnerConfigKindOneOfNormal.md 中的字段差异即可为不同负载特征的应用选择并配置合适的 Runner 运行形态。【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考