AI AgentAgent 框架RAG后端【免费下载链接】rig⚙️ Build modular and scalable LLM Applications in Rust项目地址https://gitcode.com/GitHub_Trending/rig2/rig点击查看免费下载本文聚焦 Rig 生态中的 companion crate——rig-vertexai讲解如何将 Google Cloud Vertex AI含 Gemini 托管模型接入 Rig覆盖依赖安装、Application Default CredentialsADC认证、环境变量与 Builder 配置、Tokio 运行时所有权陷阱、自定义 PredictionService 注入、原始响应恢复、生成参数与工具调用映射以及 ECS 宿主场景下的生命周期管理。读完本文你将能在 Rust 中完成从「一条 gcloud 命令拿到认证」到「生产级托管 SDK Client」的完整落地。rig-vertexai 是什么rig-vertexai是 Rig 官方维护的 companion crate将 Google Cloud Vertex AI托管模型包括 Gemini 系列作为模型提供商接入 Rig 的模型抽象层。它不做重复造轮子而是把google-cloud-aiplatform-v1SDK 的GenerateContent能力封装成 Rig 的Completion操作crates/rig-vertexai/src/lib.rs让开发者用与 Rig 其他提供商一致的Model、AgentBuilder接口完成调用同时保留对底层 SDK 客户端、凭据与传输层的完全控制权。整个 crate 由三部分组成client模块VertexAi客户端与VertexAiBuilder负责项目/区域/凭据/预测服务的装配crates/rig-vertexai/src/client.rscompletion模块GenerateContent的 wire 实现与模型标识常量crates/rig-vertexai/src/completion.rstypes模块请求/响应/消息与 Vertex AI SDK 类型之间的编解码映射crates/rig-vertexai/src/types/completion_request.rs、crates/rig-vertexai/src/types/completion_response.rs。快速开始安装与首次调用在Cargo.toml中加入rig-vertexai与rig-core两个依赖[dependencies] rig-vertexai 0.42.0 rig-core 0.42.0也可以直接执行cargo add rig-vertexai rig-core让 Cargo 自动解析并添加当前最新版本。需要注意的是当前仓库工作区的版本已推进到0.43.xcrates/rig-vertexai/Cargo.toml 中rig-core依赖为0.43.0README 中给出的0.42.0是文档写作时的版本推荐以cargo add的结果为准。认证环节使用 Google Cloud 的 Application Default Credentials一条命令即可完成gcloud auth application-default login之后参考 completion_vertexai.rs一个最小可运行的调用如下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(); // 使用 ADC 凭据并期望 GOOGLE_CLOUD_PROJECT 已设置 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?; 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)得到ModelGenerateContent, VertexAi随后即可像使用 Rig 其他提供商一样执行call、构建 Agent 或对接 ECS。环境变量与 Builder配置项全景VertexAiBuilder提供四个核心配置入口crates/rig-vertexai/src/client.rsBuilder 方法作用未设置时的回退with_project(project)显式指定 Google Cloud 项目 ID回退到环境变量GOOGLE_CLOUD_PROJECT必需否则返回MissingProject错误with_location(location)显式指定区域location回退到GOOGLE_CLOUD_LOCATION再回退到默认值global见DEFAULT_LOCATION常量with_credentials(credentials)显式提供google-cloud-auth的Credentials回退到 ADC并支持服务账号模拟见下with_prediction_service(service)注入宿主编好的 SDKPredictionService回退到懒构建的 SDK 客户端完整的配置解析逻辑在build()中项目 ID 缺省时读GOOGLE_CLOUD_PROJECT环境变量并报MissingProject区域缺省时读GOOGLE_CLOUD_LOCATION或取常量DEFAULT_LOCATION值为global凭据的解析集中在build_credentials()中。凭据解析有一个值得注意的细节当环境变量GOOGLE_CLOUD_SERVICE_ACCOUNT被设置时Rig 会基于 ADC 源凭据构建**服务账号模拟impersonation**凭据即以该服务账号为目标 principal未设置时直接使用 ADC 源凭据。也就是说通过一个环境变量即可切换到提权调用场景。另一个关键行为是懒初始化当没有注入 PredictionService 时build()只解析凭据SDK 客户端本身存放在ArcOnceCell中在VertexAi::inner()首次使用时才真正构建PredictionServiceSource::Deferred分支。初始化结果包括错误会被缓存并共享给所有 clone因此如果初始化失败需要修正配置应当重新构建客户端而不是复用旧实例。这一点在inner()的文档注释中明确说明。from_env()与new()等价二者都只是VertexAiBuilder::new().build()的便捷封装完整读取以下环境变量GOOGLE_CLOUD_PROJECT必需指定项目 IDGOOGLE_CLOUD_LOCATION可选默认globalGOOGLE_CLOUD_SERVICE_ACCOUNT可选启用服务账号模拟。运行时所有权ADC 与 Tokio Runtime 的绑定关系这是rig-vertexai最容易踩坑、也最需要理解的一点。VertexAi::from_env()以及未显式提供凭据或 PredictionService 的VertexAi::builder()会解析 Application Default Credentials而google-cloud-auth的凭据构建会在当前的 Tokio runtime 上派生一个凭据刷新任务refresh task必须在 Tokio runtime 上下文中调用from_env()/build()否则直接返回RuntimeRequired错误——源码在读取任何凭据源之前就通过tokio::runtime::Handle::try_current()做了前置校验该刷新任务属于 runtime 而非某一次 completion因此只要客户端还在使用就必须让该 runtime 保持存活并被持续驱动alive and driven如果 runtime 被提前 drop 或停止驱动凭据将无法按期刷新后续请求可能因令牌过期而失败。这也是VertexAiClientError::RuntimeRequired错误消息的原话construct Vertex ADC credentials inside a Tokio runtime context; the host must retain and drive that runtime。对常规的#[tokio::main]程序来说这通常没有影响主 runtime 天然存活但在以下场景必须显式处理在非 async 的 main 函数中手动创建tokio::runtime::Runtime再进入block_on在 ECS / Bevy 应用等宿主环境中操作 future 可能在不同线程上被 poll而凭据任务绑定在创建它的 runtime 上程序退出时需要控制关闭顺序见下文 ECS 章节。供给自有 SDK Client把连接与凭据生命周期握在自己手里如果一个宿主希望完全掌控连接与凭据生命周期可以自己构建 Google SDK 客户端并交给 Rig。此时 Rig 会原样采信传入的 endpoint、凭据、传输层、重试策略与 universe domain既不重建客户端也不读取 ADCuse google_cloud_aiplatform_v1::client::PredictionService; async fn example() - anyhow::Result() { 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()?; let _ client; Ok(()) }这段代码正是 rig-vertexai README 与with_prediction_service的 doc 示例crates/rig-vertexai/src/client.rs。这里有两个容易混淆的点project 与 location 仍然配置在 Rig 客户端上。它们命名的是请求中的模型资源而不是连接本身——请求会组装成projects/{project}/locations/{location}/publishers/google/models/{model}形式的模型路径见 crates/rig-vertexai/src/completion.rs。因此即使注入自定义服务也必须提供这两个值显式或通过环境变量。同时传入 PredictionService 与with_credentials(...)会在构建期被拒绝。因为注入的 SDK 客户端已经固化了自身的凭据二者语义冲突build()直接返回ConflictingCredentials错误。注入方式对应PredictionServiceSource::Supplied分支客户端由宿主持有取消某一次 completion 不会触碰它而默认的Deferred分支中SDK 客户端在首次使用时构建并共享。Raw 响应不发起第二次 RPC 即可恢复 SDK 原始结构每个 Rig 归一化响应上都保留了raw字段其中存放的是 Vertex AI SDK 的GenerateContentResponse的序列化 JSON。即使 Rig 已经把响应解码为归一化的消息流你仍可以随时把它还原为 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) }在解码侧crates/rig-vertexai/src/types/completion_response.rsVertexDecoder会在将响应消费进归一化内容之前先把完整响应写入out.raw(...)因此 raw 是「提供商原始文档」的忠实快照。此外该模块还暴露了VERTEX_TEXT_EXTRAS_KEY常量用于在文本块的附加参数中携带 Vertex 特有的thoughtSignature数据。支持的模型与生成参数映射内置模型常量completion.rs 预置了常用 Gemini 模型标识常量模型标识GEMINI_1_5_PRO/GEMINI_1_5_FLASHgemini-1.5-pro/gemini-1.5-flashGEMINI_1_5_PRO_LATEST/GEMINI_1_5_FLASH_LATESTgemini-1.5-pro-latest/gemini-1.5-flash-latestGEMINI_2_0_FLASH_EXPgemini-2.0-flash-expGEMINI_2_5_FLASH_LITEgemini-2.5-flash-liteGEMINI_2_5_FLASHgemini-2.5-flashGEMINI_2_5_PROgemini-2.5-procompletion()接受任何impl IntoString因此也可以直接传入字符串模型名。生成参数与配置映射Rig 的类型化请求面max_tokens、temperature等与提供商扩展参数additional_params会被统一映射为 Vertex 的GenerationConfigcrates/rig-vertexai/src/types/completion_request.rs映射规则包括类型化参数优先若请求设置了max_tokens则清除 provider 扩展中的max_output_tokens后由类型化值覆盖temperature同理绕过 provider 侧的转换与范围校验直接生效范围校验max_output_tokens不得超过 Vertex 的i32范围超限报 request 错误temperature、top_p等 f32 字段必须是有限值且落在 Vertex 的 f32 范围内强制candidate_count 1因为 Rig 的归一化响应只保留一个候选请求不能要求 Vertex 生成会被静默丢弃的多个候选扩展参数映射stop_sequences、response_mime_type、response_schema/response_json_schema二者互斥同时设置会报错、top_p、top_k、presence_penalty、frequency_penalty、response_logprobs、logprobs、thinking_config、response_modalities、image_config均可透传映射Thinking 配置thinking_budget与thinking_level互斥thinking_level支持Minimal/Low/Medium/High四档响应模态支持Text与ImageAudio会被拒绝因为 Rig 无法表示助手的音频响应。流式调用的行为需要特别注意该集成没有流式 RPC。Transport::send对两种模式unary 与 stream都发送同一个 unary RPC流式调用会把该回复重放为一个单元素流crates/rig-vertexai/src/completion.rs 模块注释与实现。因此stream: true并不会带来真正的增量输出。错误映射与重试提示rpc_error()会把 SDK 错误保留为 provider-body 表示并附带 HTTP 状态、RPC code 与重试提示。其中UNAVAILABLE、RESOURCE_EXHAUSTED、DEADLINE_EXCEEDED、ABORTED被视为瞬时错误transient当没有 RPC code 时SDK 的传输层分类transport / io / timeout / connect也会提供重试提示。这为 Rig 的自动重试与截断重试机制提供了判定依据。工具调用Function Callingtool_vertexai.rs 展示了 Agent 加工具的标准用法——只需把VertexAi的模型交给AgentBuilderuse rig_agent::prelude::*; use rig_agent::tool::ToolContext; use rig_vertexai::{VertexAi, completion::GEMINI_2_5_FLASH_LITE}; let model VertexAi::from_env()?.completion(GEMINI_2_5_FLASH_LITE); let calculator_agent AgentBuilder::new(model) .tool(Adder) // 自定义 Tooladd .max_tokens(1024) .build(); let answer calculator_agent.prompt(Calculate 15 27).await?.output; println!(Vertex AI Calculator Agent: {answer});请求侧的映射规则在 completion_request.rs 中Rig 的Tool定义被转换为 Vertex 的FunctionDeclarationname / description / JSON schema 参数ToolChoice则映射为FunctionCallingConfig的模式Rig 的ToolChoiceVertex 的 ModeAuto或未设置AUTORequiredANYNoneNONESpecific { function_names }ANYallowed_function_names响应侧的解析在 completion_response.rsVertex 的函数调用不带调用 IDRig 会为响应中的第index个调用自行铸造 handle保证同一轮内的多次调用不会共享 IDthoughtSignature会以 base64 编码保留用于精确回放。与纯 SDK 调用对比理解 Rig 的价值crates/rig-vertexai/examples/no_rig_vertexai.rs 用纯 SDK 实现了同样的「提问」逻辑手动读GOOGLE_CLOUD_PROJECT、构建PredictionService、拼模型路径projects/{project}/locations/global/publishers/google/models/{model}、构造Part/Content/GenerationConfig、send()后手动从candidates[0].content.parts中取出文本。对比可见 Rig 集成主要替你完成了四件事模型路径拼接与凭据装配from_env()一行搞定归一化的请求/响应消息模型与CompletionRequest类型化参数thought/thoughtSignature、工具调用 ID 等细节的语义化处理与 Rig 的 Agent、工具、ECS、可观测等生态无缝衔接。ECS 宿主场景显式关闭顺序与每轮 poll 的 runtime 进入ecs_host_model.rs 展示了在 Rig ECSrig-ecs中托管 Vertex 完成操作的正确姿势其要点正是上文「运行时所有权」章节在生产环境的具体化先完成 SDK 准备再借用执行世界在runtime.enter()上下文内调用VertexAi::from_env()构建客户端再用runtime.block_on(client.inner())提前完成 PredictionService 的懒初始化每轮 poll 都进入 runtime自定义Hosted适配器持有tokio::runtime::Handle在serve()中通过runtime.enter()包裹操作 future 的每次poll因为 ECS worker 可能在任意线程上 poll而凭据刷新任务绑定在创建它的 runtime 上显式关闭顺序先drop(app)停止接纳工作并丢弃世界/操作再drop(client)释放共享客户端最后drop(runtime)——取消无法撤销已被远端接受的请求因此顺序必须是「停工作 → 释放客户端 → 释放 runtime」。示例注释同时提醒运行该示例会产生真实、可能计费的调用仅编译并不构成认证或服务测试这也是所有 live 示例的共同前提。测试与验证crate 内置了tests/目录下的集成测试crates/rig-vertexai/tests覆盖了本文讨论的几大主题runtime_ownership.rs验证 ADC 构造对 Tokio runtime 的要求以及 runtime 存活与客户端生命周期之间的绑定关系sdk_boundary.rs验证 SDK 客户端边界的契约——注入自有 PredictionService 后 Rig 不再重建客户端或读取 ADCraw_api.rs验证raw字段携带完整GenerateContentResponse并可恢复ecs_runtime.rs验证 ECS 宿主场景下每轮 poll 的 runtime 进入与关闭顺序。单元测试则分布在 src/types/completion_request/tests.rs、src/types/completion_response/tests.rs 与 src/completion/tests.rs其中 usage 映射prompt tool-use 求和为输入、candidates thoughts 求和为输出还有专门的 vertex_usage_mapping_tests.rs 做边界验证。小结rig-vertexai的设计核心可以概括为三句话默认路径足够顺滑ADC 环境变量即可跑通高级路径完全开放可注入自有 PredictionService 掌控连接与凭据所有权边界清晰ADC 的刷新任务属于创建它的 Tokio runtime宿主必须负责其生命周期。无论你是想快速试用 Gemini还是需要在 ECS / Bevy 这类自定义运行时中托管 Vertex 调用理解本文的运行时所有权与关闭顺序就能避免绝大多数集成期的隐蔽故障。赞分享AI AgentAgent 框架RAG后端【免费下载链接】rig⚙️ Build modular and scalable LLM Applications in Rust项目地址https://gitcode.com/GitHub_Trending/rig2/rig点击查看免费下载相关推荐LangChain.js Google Vertex AI Web 集成指南langchain/google-vertexai-web 从认证到版本管理LangChain.js Google Vertex AI Web 集成指南langchain/google vertexai web 从认证到版本管理 人工智能大模型AI AgentAI 应用RAG工具调用AI SDK 与 MCP 集成实战从 SSE、stdio 到认证与 Elicitation 的完整示例指南AI SDK 与 MCP 集成实战从 SSE、stdio 到认证与 Elicitation 的完整示例指南 AI SDK 的 MCP 支持让你可以把 Mode人工智能AI 应用AI Agent工具调用MCP Clientsopencodex 接入 Google Vertex AI扩展 google 适配器的 GCP ADC 认证与流式 Gemini 路由实战opencodex 接入 Google Vertex AI扩展 google 适配器的 GCP ADC 认证与流式 Gemini 路由实战 本文以 openc上一篇CPUDoc免费解锁电脑隐藏性能的终极指南让你的CPU跑得更快更省电下一篇如何在5分钟内免费搭建浏览器SVG编辑器SVG-Edit完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考