AI AgentAgent 框架RAG后端【免费下载链接】rig⚙️ Build modular and scalable LLM Applications in Rust项目地址https://gitcode.com/GitHub_Trending/rig2/rig点击查看免费下载导读本文基于仓库中 crates/rig-vertexai/CHANGELOG.md 的版本演进脉络结合 rig-vertexai crate 的源码、示例与测试系统讲解如何在 Rig 生态中把 Google Cloud Vertex AI含托管的 Gemini 系列模型作为模型提供方接入 Rust 应用。读完本文你将掌握 rig-vertexai 的客户端构建与凭证管理ADC 与自定义 PredictionService、Completion 请求/响应在 Rig 规范化消息与 Vertex 线格式之间的双向映射、Token 用量与思维链reasoning溯源、工具调用function calling配置以及 0.2.x 至 0.43.0 各版本的关键破坏性变更与迁移要点。一、rig-vertexai 是什么一个专注于 Vertex AI 线格式的 Companion Craterig-vertexai 是 Rig 工作区monorepo见 Cargo.toml中的一个 companion crate职责非常聚焦把 Google Cloud Vertex AI 的GenerateContentRPC 桥接到 Rig 统一的 Completion 抽象上。它的模块划分清晰地体现了这一边界src/lib.rs导出VertexAi、VertexAiBuilder以及一个用于从规范化文本块中取回 Vertex 附加字段如thoughtSignature的常量VERTEX_TEXT_EXTRAS_KEYsrc/client.rs客户端与凭证构建逻辑src/completion.rsGenerateContent这一 Completion wire 的定义、模型标识常量与传输Transport实现src/types/completion_request.rs请求→Vertex 请求的映射、completion_response.rsVertex 响应→Rig 事件流的解码、message.rs消息内容→VertexContent/Part的双向转换。从 crate 文档注释看它强调一个关键设计事实这是一个单次 RPC集成——即使调用方请求流式streaming模式底层仍然发送一元unaryGenerateContentRPC并把完整响应作为单个事件重新发出详见 src/completion.rs 中对Transport的注释 Both modes send the unary RPC; a streamed call re-emits its reply。这一点在 ecs_host_model.rs 示例中也以注释形式再次强调stream: false, // Vertex streaming is explicitly unsupported。依赖上该 crate 直接构建于google-cloud-aiplatform-v1官方 SDK 客户端与google-cloud-auth凭证之上并以rig-core为唯一的上游 Rig 依赖见 Cargo.toml。二、快速上手依赖、凭证与第一个 Completion2.1 添加依赖官方 READMEcrates/rig-vertexai/README.md给出的用法是同时引入 companion crate 与 rig-core[dependencies] rig-vertexai 0.42.0 rig-core 0.42.0也可以直接运行cargo add rig-vertexai rig-core自动添加最新版本。当前工作区中 rig-vertexai 与 rig-core 均为 0.43.0见 Cargo.toml 中version 0.43.0的依赖声明因此建议以 0.43.0 为基线阅读本文。2.2 配置 Google Cloud 凭证按照 README 的 Setup 一节需要先配置 Google Cloud 凭证最常用的方式是应用默认凭证ADCgcloud auth application-default loginVertexAi::from_env()会依次读取三个环境变量见 src/client.rs 中VertexAi::from_env/new的文档环境变量作用是否必填缺省行为GOOGLE_CLOUD_PROJECT指定 GCP 项目 ID必填缺失时build()返回MissingProject错误GOOGLE_CLOUD_LOCATION指定区域location可选缺省为global源码常量DEFAULT_LOCATIONGOOGLE_CLOUD_SERVICE_ACCOUNT服务账号模拟impersonation可选设置后基于 ADC 源凭证构建 impersonated 凭证注意这些环境变量的命名刻意对齐了 Google 官方 genai 客户端源码注释明确引用了 python-genai 的Client文档降低跨语言迁移成本。2.3 最小可运行示例crates/rig-vertexai/examples/completion_vertexai.rs 是完整的单文件示例use anyhow::Context; use rig_core::completion::CompletionRequest; use rig_vertexai::{VertexAi, completion::GEMINI_2_5_FLASH_LITE}; #[tokio::main] async fn main() - Result(), anyhow::Error { tracing_subscriber::fmt().with_target(false).init(); // Uses ADC credentials and expects GOOGLE_CLOUD_PROJECT to be set. let model VertexAi::from_env()?.completion(GEMINI_2_5_FLASH_LITE); let request CompletionRequest::new(What is the capital of France?).max_tokens(1024); let response model .call(request) .await .context(Failed to get completion)?; let mut response_text String::new(); for content in response.choice.iter() { if let rig_core::message::AssistantContent::Text(rig_core::message::Text { text, .. }) content { response_text.push_str(text); } } println!(Response: {response_text}); Ok(()) }要点VertexAi::from_env()?返回客户端completion(model)用 src/completion.rs 中导出的模型常量如GEMINI_2_5_FLASH_LITE、GEMINI_2_5_FLASH、GEMINI_2_5_PRO、GEMINI_1_5_PRO等构造一个ModelGenerateContent, VertexAiCompletionRequest::new(...).max_tokens(...)走的是 Rig 的类型化请求表面typed request surface其取值在发送前会被映射为 Vertex 的maxOutputTokens。三、客户端构建的三种形态与凭证生命周期src/client.rs 中VertexAiBuilder提供了三种渐进式构建方式理解它们的差异是正确使用本 crate 的关键。3.1 形态一VertexAi::from_env()/VertexAi::new()直接基于环境变量构建等价于VertexAiBuilder::new().build()。它会在构建时立即解析凭证除非显式传入。最重要的运行时约束ADC 解析会构建google-cloud-auth的 token 缓存而该缓存会在当前 Tokio runtime 上下文中派生一个刷新任务refresh task。因此必须在 Tokio runtime 上下文内调用否则返回RuntimeRequired错误错误文案为 construct Vertex ADC credentials inside a Tokio runtime context; the host must retain and drive that runtime该 runtime 必须在客户端整个生命周期内保持存活并被驱动drive因为刷新任务属于 runtime 而非某一次 completion。build_credentials的逻辑见 src/client.rs在解析 ADC 前会先通过tokio::runtime::Handle::try_current()探测 runtime 是否存在不存在则直接拒绝避免在无 runtime 时读取任何凭证源。3.2 形态二Builder 显式凭证let client rig_vertexai::VertexAi::builder() .with_project(my-project) .with_location(us-central1) .with_credentials(credentials) // google_cloud_auth::credentials::Credentials .build()?;with_credentials(...)会跳过 ADC 解析流程使用你给定的Credentials。project/location若未显式设置仍会回退到环境变量。3.3 形态三宿主自建 PredictionService推荐给需要完全掌控连接的主机对于希望自己管理连接与凭证生命周期的宿主README 提供了交出连接的模式use google_cloud_aiplatform_v1::client::PredictionService; let service PredictionService::builder() .with_endpoint(https://us-central1-aiplatform.googleapis.com) .build() .await?; let client rig_vertexai::VertexAi::builder() .with_project(my-project) .with_location(us-central1) .with_prediction_service(service) .build()?;此模式下 Rig 会原样接管SDK 客户端的 endpoint、凭证、传输、重试策略与 universe domain从不重建客户端、不读取 ADC。project与location仍然必须在 Rig 客户端配置显式或环境变量因为它们是请求中模型资源的命名见下方 model path 格式与连接无关。冲突校验同时传入with_prediction_service(...)与with_credentials(...)会在build()时返回ConflictingCredentials——因为自带的 PredictionService 已经固定了自身的凭证。3.4 延迟初始化与错误缓存未提供 PredictionService 时SDK 客户端采用PredictionServiceSource::Deferred策略凭证在build()时解析而PredictionService通过tokio::sync::OnceCell在首次使用时VertexAi::inner()懒构建。该 OnceCell 保存的是ResultPredictionService, VertexAiClientError——初始化失败也会被缓存并共享给所有 clone修正配置的唯一办法是重新构建客户端。构建成功与否都不验证连通性也不代表鉴权通过见PredictionServiceSource注释。四、请求映射从 Rig CompletionRequest 到 Vertex GenerateContentsrc/types/completion_request.rs 中的VertexCompletionRequest负责把 Rig 的规范化CompletionRequest翻译成 Vertex 的请求结构。4.1 System 消息与对话历史contents()遍历chat_history跳过System消息其余逐条调用content_from_message转成 VertexContentsystem_instruction()把所有System消息内容以\n\n拼接封装为角色为user的Content作为system_instruction发送——注意这是 Vertex 的惯例system_instruction里 role 用userSystem 消息不能出现在contents里src/types/message.rs 会直接拒绝Message::System进入 contents 路径。4.2 工具Tools与工具选择ToolChoicetools()把 Rig 的工具定义映射为 Vertex 的FunctionDeclarationname、description、parameters_json_schema全部塞进一个Tool。tool_config()则把tool_choice映射为FunctionCallingConfigRigToolChoiceVertexModeallowed_function_namesAuto或None未设置AUTO空RequiredANY空NoneNONE空Specific { function_names }ANY指定的函数名列表4.3 GenerationConfig类型化字段优先generation_config()是映射中最复杂的部分遵循一个总原则Rig 类型化请求表面typed request surface优先于 provider-specific 的附加参数。若请求带max_tokens则先清空 provider 附加参数里的max_output_tokens避免双重转换与范围校验冲突再用类型化值覆盖若请求带temperature同样先清空 provider 附加参数里的temperature固定设置candidate_count 1因为 Rig 的规范化响应只保留一个候选见 src/types/completion_response.rs 中assistant_content只取candidates.first()请求端必须同步避免生成会被静默丢弃的候选。同时提供若干防御性校验max_output_tokens超出 Vertex 的 i32 范围会返回ProviderError::request(max_output_tokens exceeds Vertex AIs i32 range)temperature/top_p/top_k等必须有限且落在 f32 范围内vertex_f32校验responseSchema不能与responseJsonSchema/_responseJsonSchema混用responseJsonSchema与_responseJsonSchema也不能同时设置thinking_budget与thinking_level不能同时设置vertex_thinking_config校验ThinkingLevel支持Minimal/Low/Medium/Highresponse_modalities中的AUDIO被明确拒绝Rig 无法表示 assistant 音频响应仅支持Text与Imageimage_config支持aspect_ratio与image_size。五、响应解码从 GenerateContentResponse 到 Rig 事件流src/types/completion_response.rs 定义了VertexDecoder与PROVIDER_NAME vertexai。5.1 解码流程Decoder::decode按顺序做四件事把整个GenerateContentResponse序列化为serde_json::Value存入out.raw(...)——这就是 README 中raw 响应可无需再次 RPC 直接恢复的来源解析第一个候选candidates.first()的 content parts逐 part 产出AssistantContent通过map_finish_reason把 Vertex 的finishReason映射到 Rig 的规范化FinishReason——未映射的值会以其 wire 形式SCREAMING_SNAKE如MALFORMED_FUNCTION_CALL原样透传这样 Vertex 未来新增的 reason 不会被误读成自然停止产出Finish携带 usage、reason、model_version作为 model、response_id。5.2 各类 Part 的规范化对候选 content 中的每个 partfunction_callVertex 的函数调用不带调用 IDRig 为每一次调用铸造自己的 handleToolCall::from_wire(, ...)并保留签名text若part.thought true映射为AssistantContent::Reasoning思维链否则映射为AssistantContent::Textinline_data图片仅支持 JPEG/PNG/WEBP/HEIC/HEIF且thought标记的内部思考图会被跳过助手历史无法表达该标志带thought_signature的 inline 图片会被拒绝无法表示的签名 part 只发tracing::warn!告警并丢弃不暴露签名内容。签名thoughtSignature机制是本 crate 相对其他 provider 的一大特色Vertex 会在带签名的答案 part 上附带不透明字节。这些字节以 base64 编码后文本签名放在Text.additional_params的VERTEX_TEXT_EXTRAS_KEY值vertexai键下推理签名则随Reasoning的 signature 保存src/types/message.rs 在反向映射回放时将其解码回set_thought_signature(bytes)实现签名只在 Vertex 之间往返的闭环相关演进见下文 0.40.0 的 preserve signed thought text parts 与 0.43.0 的 reasoning provenance 系列改动。5.3 Token 用量映射usage()函数把 Vertex 的usage_metadata映射为 Rig 的Usage口径代码注释明确说明input prompt_token_count tool_use_prompt_tokenssum over 各 modalityoutput candidates_token_count thoughts_token_counttotal input output即 Vertex 的totalTokenCountcached_input_tokens cached_content_token_count已包含在 prompt_token_count 中cache_creation_input_tokens NoneVertex 不报告 cache 写入计数tool_use_prompt_tokens与reasoning_tokens thoughts_token_count单独给出。注意Usage的字段在 0.43.0 起全部是Optionu64Usage counters are Option — an absent counter is representable映射不到的计数如实为None而不是编造 0。5.4 恢复原始响应README 给出了从规范化响应中无损取回 SDK 原始类型的代码use google_cloud_aiplatform_v1::model::GenerateContentResponse; use rig_core::{completion::CompletionResponse, serde_json}; fn recover(response: CompletionResponse) - ResultGenerateContentResponse, serde_json::Error { serde_json::from_value(response.raw) }5.5 消息内容双向映射src/types/message.rsUser → Vertex文本映射为Part::set_textToolResult映射为FunctionResponse——JSON/文本内容聚合到{output: ...}结构图片则通过rig_tool_result_image_N这样的 display-name 引用放入response_parts以$ref保留规范块顺序函数响应按名字而非调用 ID 关联工具结果图片仅支持 JPEG/PNG/WEBP且支持 base64、Raw 与 URL 三种数据源Assistant → Vertex角色为model只回放本 provider 签发的 reasoningISSUER机制reasoning.open(ISSUER)其他服务签发的 reasoning 被过滤并在显式要求回放时报错文本/工具调用/图片/推理 part 均尽力恢复 thought_signaturebase64 解码失败只告警不拒绝整轮。六、传输层模型资源路径与错误语义VertexAi的TransportGenerateContent实现src/completion.rs展示了请求如何被组装为 SDK 调用let model_path format!( projects/{}/locations/{}/publishers/google/models/{model}, self.project(), self.location() );即模型资源路径形如projects/{project}/locations/{location}/publishers/google/models/{model}——这正是project/location必须配置在 Rig 客户端上的原因它们命名的是资源而非连接。错误处理方面rpc_error会保留 SDK 错误的展示文本、HTTP 状态码、RPC code 与重试提示UNAVAILABLE、RESOURCE_EXHAUSTED、DEADLINE_EXCEEDED、ABORTED被判定为瞬时transient错误SDK 的 transport/IO/timeout/connect 分类在无 RPC code 时也提供瞬时提示供上层重试策略决策。七、在 ECS 宿主中托管 Vertex 客户端实战进阶crates/rig-vertexai/examples/ecs_host_model.rs 展示了与 rig-ecs 的集成模式核心是运行时归属runtime ownership先创建专用 Tokio runtime在runtime.enter()上下文中构建VertexAi::from_env()满足 ADC 对 runtime 上下文的要求runtime.block_on(client.inner())预先完成 SDK 客户端构建Complete SDK preparation before borrowing the execution world实现Servetrait每次 poll包括 ECS worker 的 poll都runtime.enter()后poll操作 future不派生 detached 任务结束时按序drop(app)→drop(client)→drop(runtime)保证先停收新工作、再释放共享客户端、最后释放其 runtime的关闭顺序。该示例注明运行会触发真实可能计费调用仅编译不构成鉴权或服务测试。工作区另有 tests/ecs_runtime.rs 等测试验证相关生命周期。八、用工具调用构建 Agentcrates/rig-vertexai/examples/tool_vertexai.rs 展示如何把 Vertex 模型与 rig-agent 的工具系统结合let model VertexAi::from_env()?.completion(GEMINI_2_5_FLASH_LITE); let calculator_agent AgentBuilder::new(model) .tool(Adder) .max_tokens(1024) .build(); let answer calculator_agent.prompt(Calculate 15 27).await?.output;其中Adder实现Tooltraitparameters()用schemars::schema_for!生成 JSON Schema——该 schema 最终会经set_parameters_json_schema成为 Vertex 的FunctionDeclaration。这验证了第三节中工具映射的完整链路Rig 工具定义 → JSON Schema → Vertex 函数声明 → 模型调用 →FunctionResponse回填。九、版本演进解读从 CHANGELOG 看 0.2.x → 0.43.0 的架构变迁crates/rig-vertexai/CHANGELOG.md 记录了自 0.2.02025-12-01以来的全部版本。下面按主题归纳便于读者理解为什么现在的 API 长这样。9.1 版本时间线与里程碑版本日期与本 crate 最相关的变更0.2.02025-12-01Consolidate provider clients[#1050]修复 model/agent 初始化方法不一致[#1069]0.2.1 / 0.2.3 / 0.2.4 / 0.2.5 / 0.3.1 / 0.3.42025-12 ~ 2026-04跟随 rig-core 本地包更新0.2.22025-12-15ToolCall Signature 与附加参数[#1154]crate 重组[#1145]0.2.62026-02-17结构化输出structured outputs[#1382]跨 provider 推理轨迹往返[#1396]CompletionRequest可选模型覆盖[#1374]0.3.22026-03-17preamble 内部改为 system message[#1527]0.3.32026-03-29OTel GenAI semconv 修复 Anthropic 自动 prompt caching[#1572]0.3.52026-04-28全工作区 clippy no-panic lints[#1663]0.3.62026-05-13Gemini Token usage 正确性修复面向 posthog llm analytics[#1761]创建 rig crate 的项目重组[#1699]0.3.72026-06-02暴露流式响应元数据[#1790]Anthropic 文档引用支持[#1778]0.38.12026-06-02统一工作区 crate 版本[#1853]0.39.02026-06-19sans-IOAgentRun状态机两条 agent 循环变为薄驱动[#1899][breaking]0.40.02026-07-10vertexai 专项修复映射 generation config 并保留图片历史[#2086]、保留带签名的思考文本 part[#2052]Flatten Tool metadata API[#2029]工作区级 provider 错误响应检查拓宽[#1944][breaking]0.41.02026-07-28rig-core 与 rig-agent 拆分到 rig facade 之后[#2197][breaking]敏感 span 内容改为 opt-in[#2151]简化工具执行与 hook API[#2132]0.42.02026-08-16OneOrManyT→VecT[#2273][breaking]流式 part 成为实体[#2262]provider 边界规范化 completion 响应并抹去 agent 构造时的模型类型[#2257]behavior空转换响应以CompletionError::ResponseError拒绝共用message::require_non_empty_responseLOC 精简净减约 4,777 行0.43.02026-09-30Usage计数器全部Optionu64[#2535]所有 provider 的 Usage 语义统一[#2631][breaking]effect-bus 关键路径重做[#2443]统一的 typed decoder 与每 wire 一个 fold[#2617]provider 客户端自持 transport[#2611]driver 独占写入 provider/request id/raw[#2626]NonEmptyT→VecT[#2640][breaking]Gemini 显式上下文缓存及三个 usage 映射修复[#2375]reasoning provenance 与签名槽[#2578][#2580][breaking]说明CHANGELOG 中[**breaking**]标记的变更大多来自 rig-core / rig-agent 的重构但它们通过rig-core依赖直接传导到本 crate 的 API 面如Usage字段类型、request 结构、run 类型等升级时需一并关注。9.2 四条演进主线主线 Aprovider 客户端的收敛与统一。从 0.2.0 的 Consolidate provider clients、0.2.2 的 crate 重组到 0.38.1 统一工作区版本、0.41.0 的 rig-core/rig-agent 拆分再到 0.43.0 的 provider clients own their transport 与 collapse the client machinery to Provider Has*[#2441]客户端职责不断内聚连接与凭证归 provider 所有Rig 只负责规范化请求/响应。本文第三、四、五节的源码结构正是这条主线的最终形态。主线 B消息与线格式的规范化。0.3.2 的 preamble→system message、0.42.0 的OneOrManyT→VecT与 normalize completion responses at the provider boundary、0.43.0 的 one typed decoder and one fold per wire层层收敛到本文第四、五节描述的双向映射——尤其是 0.42.0 引入的空响应拒绝语义message::require_non_empty_response对应 src/types/completion_response.rs 末尾的require_non_empty_response(assistant_contents)调用。主线 CToken 用量口径的统一。0.3.6 修复 Gemini token usageposthog 分析场景、0.43.0 的Optionu64化与 one meaning for Usage on every provider[#2631]最终落到本文 5.3 节usage()的精确口径与缺失计数为None的语义。crate 内专门有 vertex_usage_mapping_tests.rs 对映射进行逐项验证。主线 D推理reasoning溯源与签名。0.2.6 的跨 provider 推理轨迹往返、0.40.0 的 preserve signed thought text parts、0.43.0 的 signature slots, upstream reasoning provenance 与 stateful handle round-trips and reasoning provenance[#2578][#2580]构成了本文 5.2 节的ISSUER/VERTEX_TEXT_EXTRAS_KEY/thought_signature 机制——Vertex 的签名只在 Vertex 之间往返其他 provider 签发的推理不会被回放。9.3 破坏性变更速查升级到 0.43.0 时需要重点检查Usage字段变为Optionu64所有计数读写都要处理None如cached_input_tokens、cache_creation_input_tokens在 Vertex 侧天然缺失消息内容容器VecT化OneOrMany/NonEmpty假类型被移除空轮次的校验移到请求边界run 类型与 driver 职责收敛provider/request id/raw 由 driver 独占写入provider 不再各自为政工具执行与 hook API 简化0.41.0、Tool metadata 扁平化0.40.0自定义工具定义与 hook 回调签名需按新 API 调整无 streaming RPC 的语义不变流式调用仍然重放一元响应勿期待增量事件。十、测试矩阵如何验证一个 Vertex 集成rig-vertexai 的测试分层tests/ 与各模块内tests.rs是理解集成契约的好入口tests/sdk_boundary.rs验证与google-cloud-aiplatform-v1SDK 的边界如原始响应恢复tests/raw_api.rs覆盖 raw 响应与线格式往返tests/runtime_ownership.rs 与 tests/ecs_runtime.rs验证第三、七节描述的 runtime 归属与关闭顺序src/types/completion_response/vertex_usage_mapping_tests.rsusage 口径专项验证src/types/completion_request/tests.rs、src/types/completion_response/tests.rs、src/types/message/tests.rs请求/响应/消息映射的单元测试。同时crate 根 lib.rs 与 completion.rs 内嵌的no_rundoctest 本身就是最小可编译用例可作为 API 快速验证模板。结语rig-vertexai 是薄而严谨的 provider 集成范本外部依赖官方 SDK 负责连接与传输内部用一套精心设计的类型映射请求编码、响应解码、消息双向转换、usage 与 finish reason 规范化把 Vertex AI 的GenerateContent无缝纳入 Rig 的 Completion/Agent/ECS 体系。理解它的客户端构建形态ADC vs 自建 PredictionService、runtime 归属约束、签名与 usage 口径以及 CHANGELOG 所呈现的四条演进主线就能在升级与排障时游刃有余。进一步实践可参考 examples/ 下的四个示例completion、tool、ECS host、no_rig_vertexai以及仓库根目录 README.md 中关于 Rig 生态的整体介绍。赞分享AI AgentAgent 框架RAG后端【免费下载链接】rig⚙️ Build modular and scalable LLM Applications in Rust项目地址https://gitcode.com/GitHub_Trending/rig2/rig点击查看免费下载相关推荐FoldCraftLauncher故障排除手册解决崩溃闪退与性能问题终极指南FoldCraftLauncher故障排除手册解决崩溃闪退与性能问题终极指南 FoldCraftLauncher是一款功能强大的Android平台Minecr移动开发游戏开发使用 rig-helixdb 在 Rust 中构建 HelixDB 向量检索RAG应用使用 rig helixdb 在 Rust 中构建 HelixDB 向量检索RAG应用 本篇技术指南聚焦 Rig 生态中的 rig helixdb 向量存储AI AgentAgent 框架RAG后端在 Rig 中使用 ScyllaDB 构建向量存储与相似度检索rig-scylladb 集成指南在 Rig 中使用 ScyllaDB 构建向量存储与相似度检索rig scylladb 集成指南 导读 本文围绕 Rig 官方集成 crate rig scyAI AgentAgent 框架RAG后端上一篇Terraform AWS Provider 6.23.0 深度解析S3 桶 ABAC 标签治理、ECS Express Gateway 等新资源与关键增强下一篇用 Watermill Forwarder 组件实现 Outbox 模式在数据库事务中原子化发布消息创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
AI AgentAgent 框架RAG后端【免费下载链接】rig⚙️ Build modular and scalable LLM Applications in Rust项目地址https://gitcode.com/GitHub_Trending/rig2/rig点击查看免费下载导读本文基于仓库中 crates/rig-vertexai/CHANGELOG.md 的版本演进脉络结合 rig-vertexai crate 的源码、示例与测试系统讲解如何在 Rig 生态中把 Google Cloud Vertex AI含托管的 Gemini 系列模型作为模型提供方接入 Rust 应用。读完本文你将掌握 rig-vertexai 的客户端构建与凭证管理ADC 与自定义 PredictionService、Completion 请求/响应在 Rig 规范化消息与 Vertex 线格式之间的双向映射、Token 用量与思维链reasoning溯源、工具调用function calling配置以及 0.2.x 至 0.43.0 各版本的关键破坏性变更与迁移要点。一、rig-vertexai 是什么一个专注于 Vertex AI 线格式的 Companion Craterig-vertexai 是 Rig 工作区monorepo见 Cargo.toml中的一个 companion crate职责非常聚焦把 Google Cloud Vertex AI 的GenerateContentRPC 桥接到 Rig 统一的 Completion 抽象上。它的模块划分清晰地体现了这一边界src/lib.rs导出VertexAi、VertexAiBuilder以及一个用于从规范化文本块中取回 Vertex 附加字段如thoughtSignature的常量VERTEX_TEXT_EXTRAS_KEYsrc/client.rs客户端与凭证构建逻辑src/completion.rsGenerateContent这一 Completion wire 的定义、模型标识常量与传输Transport实现src/types/completion_request.rs请求→Vertex 请求的映射、completion_response.rsVertex 响应→Rig 事件流的解码、message.rs消息内容→VertexContent/Part的双向转换。从 crate 文档注释看它强调一个关键设计事实这是一个单次 RPC集成——即使调用方请求流式streaming模式底层仍然发送一元unaryGenerateContentRPC并把完整响应作为单个事件重新发出详见 src/completion.rs 中对Transport的注释 Both modes send the unary RPC; a streamed call re-emits its reply。这一点在 ecs_host_model.rs 示例中也以注释形式再次强调stream: false, // Vertex streaming is explicitly unsupported。依赖上该 crate 直接构建于google-cloud-aiplatform-v1官方 SDK 客户端与google-cloud-auth凭证之上并以rig-core为唯一的上游 Rig 依赖见 Cargo.toml。二、快速上手依赖、凭证与第一个 Completion2.1 添加依赖官方 READMEcrates/rig-vertexai/README.md给出的用法是同时引入 companion crate 与 rig-core[dependencies] rig-vertexai 0.42.0 rig-core 0.42.0也可以直接运行cargo add rig-vertexai rig-core自动添加最新版本。当前工作区中 rig-vertexai 与 rig-core 均为 0.43.0见 Cargo.toml 中version 0.43.0的依赖声明因此建议以 0.43.0 为基线阅读本文。2.2 配置 Google Cloud 凭证按照 README 的 Setup 一节需要先配置 Google Cloud 凭证最常用的方式是应用默认凭证ADCgcloud auth application-default loginVertexAi::from_env()会依次读取三个环境变量见 src/client.rs 中VertexAi::from_env/new的文档环境变量作用是否必填缺省行为GOOGLE_CLOUD_PROJECT指定 GCP 项目 ID必填缺失时build()返回MissingProject错误GOOGLE_CLOUD_LOCATION指定区域location可选缺省为global源码常量DEFAULT_LOCATIONGOOGLE_CLOUD_SERVICE_ACCOUNT服务账号模拟impersonation可选设置后基于 ADC 源凭证构建 impersonated 凭证注意这些环境变量的命名刻意对齐了 Google 官方 genai 客户端源码注释明确引用了 python-genai 的Client文档降低跨语言迁移成本。2.3 最小可运行示例crates/rig-vertexai/examples/completion_vertexai.rs 是完整的单文件示例use anyhow::Context; use rig_core::completion::CompletionRequest; use rig_vertexai::{VertexAi, completion::GEMINI_2_5_FLASH_LITE}; #[tokio::main] async fn main() - Result(), anyhow::Error { tracing_subscriber::fmt().with_target(false).init(); // Uses ADC credentials and expects GOOGLE_CLOUD_PROJECT to be set. let model VertexAi::from_env()?.completion(GEMINI_2_5_FLASH_LITE); let request CompletionRequest::new(What is the capital of France?).max_tokens(1024); let response model .call(request) .await .context(Failed to get completion)?; let mut response_text String::new(); for content in response.choice.iter() { if let rig_core::message::AssistantContent::Text(rig_core::message::Text { text, .. }) content { response_text.push_str(text); } } println!(Response: {response_text}); Ok(()) }要点VertexAi::from_env()?返回客户端completion(model)用 src/completion.rs 中导出的模型常量如GEMINI_2_5_FLASH_LITE、GEMINI_2_5_FLASH、GEMINI_2_5_PRO、GEMINI_1_5_PRO等构造一个ModelGenerateContent, VertexAiCompletionRequest::new(...).max_tokens(...)走的是 Rig 的类型化请求表面typed request surface其取值在发送前会被映射为 Vertex 的maxOutputTokens。三、客户端构建的三种形态与凭证生命周期src/client.rs 中VertexAiBuilder提供了三种渐进式构建方式理解它们的差异是正确使用本 crate 的关键。3.1 形态一VertexAi::from_env()/VertexAi::new()直接基于环境变量构建等价于VertexAiBuilder::new().build()。它会在构建时立即解析凭证除非显式传入。最重要的运行时约束ADC 解析会构建google-cloud-auth的 token 缓存而该缓存会在当前 Tokio runtime 上下文中派生一个刷新任务refresh task。因此必须在 Tokio runtime 上下文内调用否则返回RuntimeRequired错误错误文案为 construct Vertex ADC credentials inside a Tokio runtime context; the host must retain and drive that runtime该 runtime 必须在客户端整个生命周期内保持存活并被驱动drive因为刷新任务属于 runtime 而非某一次 completion。build_credentials的逻辑见 src/client.rs在解析 ADC 前会先通过tokio::runtime::Handle::try_current()探测 runtime 是否存在不存在则直接拒绝避免在无 runtime 时读取任何凭证源。3.2 形态二Builder 显式凭证let client rig_vertexai::VertexAi::builder() .with_project(my-project) .with_location(us-central1) .with_credentials(credentials) // google_cloud_auth::credentials::Credentials .build()?;with_credentials(...)会跳过 ADC 解析流程使用你给定的Credentials。project/location若未显式设置仍会回退到环境变量。3.3 形态三宿主自建 PredictionService推荐给需要完全掌控连接的主机对于希望自己管理连接与凭证生命周期的宿主README 提供了交出连接的模式use google_cloud_aiplatform_v1::client::PredictionService; let service PredictionService::builder() .with_endpoint(https://us-central1-aiplatform.googleapis.com) .build() .await?; let client rig_vertexai::VertexAi::builder() .with_project(my-project) .with_location(us-central1) .with_prediction_service(service) .build()?;此模式下 Rig 会原样接管SDK 客户端的 endpoint、凭证、传输、重试策略与 universe domain从不重建客户端、不读取 ADC。project与location仍然必须在 Rig 客户端配置显式或环境变量因为它们是请求中模型资源的命名见下方 model path 格式与连接无关。冲突校验同时传入with_prediction_service(...)与with_credentials(...)会在build()时返回ConflictingCredentials——因为自带的 PredictionService 已经固定了自身的凭证。3.4 延迟初始化与错误缓存未提供 PredictionService 时SDK 客户端采用PredictionServiceSource::Deferred策略凭证在build()时解析而PredictionService通过tokio::sync::OnceCell在首次使用时VertexAi::inner()懒构建。该 OnceCell 保存的是ResultPredictionService, VertexAiClientError——初始化失败也会被缓存并共享给所有 clone修正配置的唯一办法是重新构建客户端。构建成功与否都不验证连通性也不代表鉴权通过见PredictionServiceSource注释。四、请求映射从 Rig CompletionRequest 到 Vertex GenerateContentsrc/types/completion_request.rs 中的VertexCompletionRequest负责把 Rig 的规范化CompletionRequest翻译成 Vertex 的请求结构。4.1 System 消息与对话历史contents()遍历chat_history跳过System消息其余逐条调用content_from_message转成 VertexContentsystem_instruction()把所有System消息内容以\n\n拼接封装为角色为user的Content作为system_instruction发送——注意这是 Vertex 的惯例system_instruction里 role 用userSystem 消息不能出现在contents里src/types/message.rs 会直接拒绝Message::System进入 contents 路径。4.2 工具Tools与工具选择ToolChoicetools()把 Rig 的工具定义映射为 Vertex 的FunctionDeclarationname、description、parameters_json_schema全部塞进一个Tool。tool_config()则把tool_choice映射为FunctionCallingConfigRigToolChoiceVertexModeallowed_function_namesAuto或None未设置AUTO空RequiredANY空NoneNONE空Specific { function_names }ANY指定的函数名列表4.3 GenerationConfig类型化字段优先generation_config()是映射中最复杂的部分遵循一个总原则Rig 类型化请求表面typed request surface优先于 provider-specific 的附加参数。若请求带max_tokens则先清空 provider 附加参数里的max_output_tokens避免双重转换与范围校验冲突再用类型化值覆盖若请求带temperature同样先清空 provider 附加参数里的temperature固定设置candidate_count 1因为 Rig 的规范化响应只保留一个候选见 src/types/completion_response.rs 中assistant_content只取candidates.first()请求端必须同步避免生成会被静默丢弃的候选。同时提供若干防御性校验max_output_tokens超出 Vertex 的 i32 范围会返回ProviderError::request(max_output_tokens exceeds Vertex AIs i32 range)temperature/top_p/top_k等必须有限且落在 f32 范围内vertex_f32校验responseSchema不能与responseJsonSchema/_responseJsonSchema混用responseJsonSchema与_responseJsonSchema也不能同时设置thinking_budget与thinking_level不能同时设置vertex_thinking_config校验ThinkingLevel支持Minimal/Low/Medium/Highresponse_modalities中的AUDIO被明确拒绝Rig 无法表示 assistant 音频响应仅支持Text与Imageimage_config支持aspect_ratio与image_size。五、响应解码从 GenerateContentResponse 到 Rig 事件流src/types/completion_response.rs 定义了VertexDecoder与PROVIDER_NAME vertexai。5.1 解码流程Decoder::decode按顺序做四件事把整个GenerateContentResponse序列化为serde_json::Value存入out.raw(...)——这就是 README 中raw 响应可无需再次 RPC 直接恢复的来源解析第一个候选candidates.first()的 content parts逐 part 产出AssistantContent通过map_finish_reason把 Vertex 的finishReason映射到 Rig 的规范化FinishReason——未映射的值会以其 wire 形式SCREAMING_SNAKE如MALFORMED_FUNCTION_CALL原样透传这样 Vertex 未来新增的 reason 不会被误读成自然停止产出Finish携带 usage、reason、model_version作为 model、response_id。5.2 各类 Part 的规范化对候选 content 中的每个 partfunction_callVertex 的函数调用不带调用 IDRig 为每一次调用铸造自己的 handleToolCall::from_wire(, ...)并保留签名text若part.thought true映射为AssistantContent::Reasoning思维链否则映射为AssistantContent::Textinline_data图片仅支持 JPEG/PNG/WEBP/HEIC/HEIF且thought标记的内部思考图会被跳过助手历史无法表达该标志带thought_signature的 inline 图片会被拒绝无法表示的签名 part 只发tracing::warn!告警并丢弃不暴露签名内容。签名thoughtSignature机制是本 crate 相对其他 provider 的一大特色Vertex 会在带签名的答案 part 上附带不透明字节。这些字节以 base64 编码后文本签名放在Text.additional_params的VERTEX_TEXT_EXTRAS_KEY值vertexai键下推理签名则随Reasoning的 signature 保存src/types/message.rs 在反向映射回放时将其解码回set_thought_signature(bytes)实现签名只在 Vertex 之间往返的闭环相关演进见下文 0.40.0 的 preserve signed thought text parts 与 0.43.0 的 reasoning provenance 系列改动。5.3 Token 用量映射usage()函数把 Vertex 的usage_metadata映射为 Rig 的Usage口径代码注释明确说明input prompt_token_count tool_use_prompt_tokenssum over 各 modalityoutput candidates_token_count thoughts_token_counttotal input output即 Vertex 的totalTokenCountcached_input_tokens cached_content_token_count已包含在 prompt_token_count 中cache_creation_input_tokens NoneVertex 不报告 cache 写入计数tool_use_prompt_tokens与reasoning_tokens thoughts_token_count单独给出。注意Usage的字段在 0.43.0 起全部是Optionu64Usage counters are Option — an absent counter is representable映射不到的计数如实为None而不是编造 0。5.4 恢复原始响应README 给出了从规范化响应中无损取回 SDK 原始类型的代码use google_cloud_aiplatform_v1::model::GenerateContentResponse; use rig_core::{completion::CompletionResponse, serde_json}; fn recover(response: CompletionResponse) - ResultGenerateContentResponse, serde_json::Error { serde_json::from_value(response.raw) }5.5 消息内容双向映射src/types/message.rsUser → Vertex文本映射为Part::set_textToolResult映射为FunctionResponse——JSON/文本内容聚合到{output: ...}结构图片则通过rig_tool_result_image_N这样的 display-name 引用放入response_parts以$ref保留规范块顺序函数响应按名字而非调用 ID 关联工具结果图片仅支持 JPEG/PNG/WEBP且支持 base64、Raw 与 URL 三种数据源Assistant → Vertex角色为model只回放本 provider 签发的 reasoningISSUER机制reasoning.open(ISSUER)其他服务签发的 reasoning 被过滤并在显式要求回放时报错文本/工具调用/图片/推理 part 均尽力恢复 thought_signaturebase64 解码失败只告警不拒绝整轮。六、传输层模型资源路径与错误语义VertexAi的TransportGenerateContent实现src/completion.rs展示了请求如何被组装为 SDK 调用let model_path format!( projects/{}/locations/{}/publishers/google/models/{model}, self.project(), self.location() );即模型资源路径形如projects/{project}/locations/{location}/publishers/google/models/{model}——这正是project/location必须配置在 Rig 客户端上的原因它们命名的是资源而非连接。错误处理方面rpc_error会保留 SDK 错误的展示文本、HTTP 状态码、RPC code 与重试提示UNAVAILABLE、RESOURCE_EXHAUSTED、DEADLINE_EXCEEDED、ABORTED被判定为瞬时transient错误SDK 的 transport/IO/timeout/connect 分类在无 RPC code 时也提供瞬时提示供上层重试策略决策。七、在 ECS 宿主中托管 Vertex 客户端实战进阶crates/rig-vertexai/examples/ecs_host_model.rs 展示了与 rig-ecs 的集成模式核心是运行时归属runtime ownership先创建专用 Tokio runtime在runtime.enter()上下文中构建VertexAi::from_env()满足 ADC 对 runtime 上下文的要求runtime.block_on(client.inner())预先完成 SDK 客户端构建Complete SDK preparation before borrowing the execution world实现Servetrait每次 poll包括 ECS worker 的 poll都runtime.enter()后poll操作 future不派生 detached 任务结束时按序drop(app)→drop(client)→drop(runtime)保证先停收新工作、再释放共享客户端、最后释放其 runtime的关闭顺序。该示例注明运行会触发真实可能计费调用仅编译不构成鉴权或服务测试。工作区另有 tests/ecs_runtime.rs 等测试验证相关生命周期。八、用工具调用构建 Agentcrates/rig-vertexai/examples/tool_vertexai.rs 展示如何把 Vertex 模型与 rig-agent 的工具系统结合let model VertexAi::from_env()?.completion(GEMINI_2_5_FLASH_LITE); let calculator_agent AgentBuilder::new(model) .tool(Adder) .max_tokens(1024) .build(); let answer calculator_agent.prompt(Calculate 15 27).await?.output;其中Adder实现Tooltraitparameters()用schemars::schema_for!生成 JSON Schema——该 schema 最终会经set_parameters_json_schema成为 Vertex 的FunctionDeclaration。这验证了第三节中工具映射的完整链路Rig 工具定义 → JSON Schema → Vertex 函数声明 → 模型调用 →FunctionResponse回填。九、版本演进解读从 CHANGELOG 看 0.2.x → 0.43.0 的架构变迁crates/rig-vertexai/CHANGELOG.md 记录了自 0.2.02025-12-01以来的全部版本。下面按主题归纳便于读者理解为什么现在的 API 长这样。9.1 版本时间线与里程碑版本日期与本 crate 最相关的变更0.2.02025-12-01Consolidate provider clients[#1050]修复 model/agent 初始化方法不一致[#1069]0.2.1 / 0.2.3 / 0.2.4 / 0.2.5 / 0.3.1 / 0.3.42025-12 ~ 2026-04跟随 rig-core 本地包更新0.2.22025-12-15ToolCall Signature 与附加参数[#1154]crate 重组[#1145]0.2.62026-02-17结构化输出structured outputs[#1382]跨 provider 推理轨迹往返[#1396]CompletionRequest可选模型覆盖[#1374]0.3.22026-03-17preamble 内部改为 system message[#1527]0.3.32026-03-29OTel GenAI semconv 修复 Anthropic 自动 prompt caching[#1572]0.3.52026-04-28全工作区 clippy no-panic lints[#1663]0.3.62026-05-13Gemini Token usage 正确性修复面向 posthog llm analytics[#1761]创建 rig crate 的项目重组[#1699]0.3.72026-06-02暴露流式响应元数据[#1790]Anthropic 文档引用支持[#1778]0.38.12026-06-02统一工作区 crate 版本[#1853]0.39.02026-06-19sans-IOAgentRun状态机两条 agent 循环变为薄驱动[#1899][breaking]0.40.02026-07-10vertexai 专项修复映射 generation config 并保留图片历史[#2086]、保留带签名的思考文本 part[#2052]Flatten Tool metadata API[#2029]工作区级 provider 错误响应检查拓宽[#1944][breaking]0.41.02026-07-28rig-core 与 rig-agent 拆分到 rig facade 之后[#2197][breaking]敏感 span 内容改为 opt-in[#2151]简化工具执行与 hook API[#2132]0.42.02026-08-16OneOrManyT→VecT[#2273][breaking]流式 part 成为实体[#2262]provider 边界规范化 completion 响应并抹去 agent 构造时的模型类型[#2257]behavior空转换响应以CompletionError::ResponseError拒绝共用message::require_non_empty_responseLOC 精简净减约 4,777 行0.43.02026-09-30Usage计数器全部Optionu64[#2535]所有 provider 的 Usage 语义统一[#2631][breaking]effect-bus 关键路径重做[#2443]统一的 typed decoder 与每 wire 一个 fold[#2617]provider 客户端自持 transport[#2611]driver 独占写入 provider/request id/raw[#2626]NonEmptyT→VecT[#2640][breaking]Gemini 显式上下文缓存及三个 usage 映射修复[#2375]reasoning provenance 与签名槽[#2578][#2580][breaking]说明CHANGELOG 中[**breaking**]标记的变更大多来自 rig-core / rig-agent 的重构但它们通过rig-core依赖直接传导到本 crate 的 API 面如Usage字段类型、request 结构、run 类型等升级时需一并关注。9.2 四条演进主线主线 Aprovider 客户端的收敛与统一。从 0.2.0 的 Consolidate provider clients、0.2.2 的 crate 重组到 0.38.1 统一工作区版本、0.41.0 的 rig-core/rig-agent 拆分再到 0.43.0 的 provider clients own their transport 与 collapse the client machinery to Provider Has*[#2441]客户端职责不断内聚连接与凭证归 provider 所有Rig 只负责规范化请求/响应。本文第三、四、五节的源码结构正是这条主线的最终形态。主线 B消息与线格式的规范化。0.3.2 的 preamble→system message、0.42.0 的OneOrManyT→VecT与 normalize completion responses at the provider boundary、0.43.0 的 one typed decoder and one fold per wire层层收敛到本文第四、五节描述的双向映射——尤其是 0.42.0 引入的空响应拒绝语义message::require_non_empty_response对应 src/types/completion_response.rs 末尾的require_non_empty_response(assistant_contents)调用。主线 CToken 用量口径的统一。0.3.6 修复 Gemini token usageposthog 分析场景、0.43.0 的Optionu64化与 one meaning for Usage on every provider[#2631]最终落到本文 5.3 节usage()的精确口径与缺失计数为None的语义。crate 内专门有 vertex_usage_mapping_tests.rs 对映射进行逐项验证。主线 D推理reasoning溯源与签名。0.2.6 的跨 provider 推理轨迹往返、0.40.0 的 preserve signed thought text parts、0.43.0 的 signature slots, upstream reasoning provenance 与 stateful handle round-trips and reasoning provenance[#2578][#2580]构成了本文 5.2 节的ISSUER/VERTEX_TEXT_EXTRAS_KEY/thought_signature 机制——Vertex 的签名只在 Vertex 之间往返其他 provider 签发的推理不会被回放。9.3 破坏性变更速查升级到 0.43.0 时需要重点检查Usage字段变为Optionu64所有计数读写都要处理None如cached_input_tokens、cache_creation_input_tokens在 Vertex 侧天然缺失消息内容容器VecT化OneOrMany/NonEmpty假类型被移除空轮次的校验移到请求边界run 类型与 driver 职责收敛provider/request id/raw 由 driver 独占写入provider 不再各自为政工具执行与 hook API 简化0.41.0、Tool metadata 扁平化0.40.0自定义工具定义与 hook 回调签名需按新 API 调整无 streaming RPC 的语义不变流式调用仍然重放一元响应勿期待增量事件。十、测试矩阵如何验证一个 Vertex 集成rig-vertexai 的测试分层tests/ 与各模块内tests.rs是理解集成契约的好入口tests/sdk_boundary.rs验证与google-cloud-aiplatform-v1SDK 的边界如原始响应恢复tests/raw_api.rs覆盖 raw 响应与线格式往返tests/runtime_ownership.rs 与 tests/ecs_runtime.rs验证第三、七节描述的 runtime 归属与关闭顺序src/types/completion_response/vertex_usage_mapping_tests.rsusage 口径专项验证src/types/completion_request/tests.rs、src/types/completion_response/tests.rs、src/types/message/tests.rs请求/响应/消息映射的单元测试。同时crate 根 lib.rs 与 completion.rs 内嵌的no_rundoctest 本身就是最小可编译用例可作为 API 快速验证模板。结语rig-vertexai 是薄而严谨的 provider 集成范本外部依赖官方 SDK 负责连接与传输内部用一套精心设计的类型映射请求编码、响应解码、消息双向转换、usage 与 finish reason 规范化把 Vertex AI 的GenerateContent无缝纳入 Rig 的 Completion/Agent/ECS 体系。理解它的客户端构建形态ADC vs 自建 PredictionService、runtime 归属约束、签名与 usage 口径以及 CHANGELOG 所呈现的四条演进主线就能在升级与排障时游刃有余。进一步实践可参考 examples/ 下的四个示例completion、tool、ECS host、no_rig_vertexai以及仓库根目录 README.md 中关于 Rig 生态的整体介绍。赞分享AI AgentAgent 框架RAG后端【免费下载链接】rig⚙️ Build modular and scalable LLM Applications in Rust项目地址https://gitcode.com/GitHub_Trending/rig2/rig点击查看免费下载相关推荐FoldCraftLauncher故障排除手册解决崩溃闪退与性能问题终极指南FoldCraftLauncher故障排除手册解决崩溃闪退与性能问题终极指南 FoldCraftLauncher是一款功能强大的Android平台Minecr移动开发游戏开发使用 rig-helixdb 在 Rust 中构建 HelixDB 向量检索RAG应用使用 rig helixdb 在 Rust 中构建 HelixDB 向量检索RAG应用 本篇技术指南聚焦 Rig 生态中的 rig helixdb 向量存储AI AgentAgent 框架RAG后端在 Rig 中使用 ScyllaDB 构建向量存储与相似度检索rig-scylladb 集成指南在 Rig 中使用 ScyllaDB 构建向量存储与相似度检索rig scylladb 集成指南 导读 本文围绕 Rig 官方集成 crate rig scyAI AgentAgent 框架RAG后端上一篇Terraform AWS Provider 6.23.0 深度解析S3 桶 ABAC 标签治理、ECS Express Gateway 等新资源与关键增强下一篇用 Watermill Forwarder 组件实现 Outbox 模式在数据库事务中原子化发布消息创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
