RocketRide 的 llm_gemini 节点：在 AI Pipeline 中接入 Google Gemini 模型

【免费下载链接】rocketride-serverHigh-performance AI pipeline engine with a C core and 50 Python-extensible nodes. Build, debug, and scale LLM workflows with 13 model providers, 8 vector databases, and agent orchestration, all from your IDE. Includes VS Code extension, TypeScript/Python SDKs, and Docker deployment.项目地址https://gitcode.com/gh_mirrors/ro/rocketride-server点击查看免费下载RocketRide 是一个以 C 引擎为核心、支持 50 Python 可扩展节点的高性能 AI Pipeline 系统。llm_gemini是其中负责接入 Google Gemini 模型的 LLM 节点它把 Gemini 的文本生成与图像生成能力封装成标准的llm调用接口供 Agent 及其他节点以invoke能力消费也可以直接通过questions/answers两条数据通道Lanes在管道里即插即用。读完本文你将掌握该节点的完整配置方法、全部可用模型 Profile、API Key 认证机制与常见坑点并能理解其基于 google-genai 库的底层实现与无密钥测试方法。节点定位标准的 LLM invoke 连接在 RocketRide 的节点体系中llm_gemini的注册信息定义于 services.jsonprotocol:llm_gemini://是管道端点协议classType:[llm]即它是标准的 LLM 类型节点capabilities:[invoke]表明它可以被 Agent 或其他节点作为 LLM 调用连接使用register:filternode:pythonpath:nodes.llm_gemini引擎会实例化nodes.llm_gemini包中的 Python 实现lanes:{questions: [answers]}定义了数据通道映射。从源码结构看节点由 IGlobal.py全局生命周期管理与配置校验和 gemini.py核心 Chat 实现两部分组成后者继承packages/ai/src/ai/common/chat.py中的ChatBase抽象基类因此天然获得 RocketRide 统一的 token 管理、网络重试、prompt 校验与流式回调能力。数据通道Lanes节点暴露一对数据通道Lane inLane out说明questionsanswers直接发送问题接收模型生成的答案文本到达questions通道后会被发送给配置的模型生成的文本从answers通道发出。这使得即使不经过 Agent 编排也可以把该节点作为管道中的普通节点直接串联使用。模型 Profile 一览节点通过预置的 Profile配置模板来固化模型标识、上下文窗口与输出上限。默认 Profile 为Gemini 3.1 Progemini-3_1-pro-preview其完整配置见 services.json。常用 ProfileProfileModelContext tokensOutput tokensGemini 3.1 Pro(默认)models/gemini-3.1-pro-preview1,048,57665,536Google: Gemini 3.6 Flashmodels/gemini-3.6-flash1,048,57665,536Google: Gemini 3.5 Flashmodels/gemini-3.5-flash1,048,57665,536Google: Gemini 3.5 Flash Litemodels/gemini-3.5-flash-lite1,048,57665,536更多模型折叠查看ProfileModelContext tokensOutput tokenscustom(用户指定)可编辑可编辑Gemini 3.1 Flash Image Previewmodels/gemini-3.1-flash-image-preview131,07258,982Gemini 3.1 Flash Litemodels/gemini-3.1-flash-lite-preview1,048,57665,536Gemini 3 Flash Previewmodels/gemini-3-flash-preview1,048,57665,536Gemini 3 Pro Image Previewmodels/gemini-3-pro-image-preview65,53632,768Gemini 2.5 Promodels/gemini-2.5-pro1,048,57665,536Gemini 2.5 Flashmodels/gemini-2.5-flash1,048,57665,535Gemini 2.5 Flash Litemodels/gemini-2.5-flash-lite1,048,57665,535Gemini 2.5 Flash Imagemodels/gemini-2.5-flash-image32,7688,192Gemini 3 Pro Previewmodels/gemini-3-pro-preview1,048,57665,536Gemini 3 Pro Imagemodels/gemini-3-pro-image131,07232,768Gemini 2.0 Flashmodels/gemini-2.0-flash1,048,57665,535Gemini 2.0 Flash Litemodels/gemini-2.0-flash-lite—65,536Google: Gemini 2.5 Flash Lite Preview 09-2025models/gemini-2.5-flash-lite-preview-09-20251,048,57665,535Google: Gemini 2.5 Pro Preview 06-05models/gemini-2.5-pro-preview1,048,57665,536Google: Gemini 2.5 Pro Preview 05-06models/gemini-2.5-pro-preview-05-061,048,57665,535Google: Gemini 3.1 Pro Preview Custom Toolsmodels/gemini-3.1-pro-preview-customtools1,048,57665,536Google Gemini Flash Latestmodels/gemini-flash-latest1,048,57665,536Google Gemini Pro Latestmodels/gemini-pro-latest1,048,57665,536Google: Nano Banana 2 (Gemini 3.1 Flash Image)models/gemini-3.1-flash-image131,07232,768Google: Gemini 3.1 Flash Litemodels/gemini-3.1-flash-lite1,048,57665,536Google: Nano Banana 2 Lite (Gemini 3.1 Flash Lite Image)models/gemini-3.1-flash-lite-image65,53658,982models-gemini-2-5-flash-batchmodels/gemini-2.5-flash:batch1,048,57665,535models-gemini-2-5-flash-lite-batchmodels/gemini-2.5-flash-lite:batch1,048,57665,535models-gemini-2-5-pro-batchmodels/gemini-2.5-pro:batch1,048,57665,536models-gemini-3-1-flash-lite-batchmodels/gemini-3.1-flash-lite:batch1,048,57665,536models-gemini-3-1-pro-preview-batchmodels/gemini-3.1-pro-preview:batch1,048,57665,536models-gemini-3-5-flash-batchmodels/gemini-3.5-flash:batch1,048,57665,536models-gemini-3-5-flash-lite-batchmodels/gemini-3.5-flash-lite:batch1,048,57665,536models-gemini-3-6-flash-batchmodels/gemini-3.6-flash:batch1,048,57665,536models-gemini-3-7-flashmodels/gemini-3.7-flash1,048,57665,536models-gemini-3-7-flash-batchmodels/gemini-3.7-flash:batch1,048,57665,536models-gemini-3-8-flashmodels/gemini-3.8-flash1,048,57665,536models-gemini-3-8-flash-batchmodels/gemini-3.8-flash:batch1,048,57665,536models-gemini-3-flash-preview-batchmodels/gemini-3-flash-preview:batch1,048,57665,536Profile 标题中包含Image的模型支持图像生成输出如 Gemini 3.1 Flash Image Preview、Gemini 2.5 Flash Image 等。值得注意的还有一批以:batch结尾的批量推理模型Gemini 2.5/3.x 系列 Batch它们通过相同的 Developer API 标识调用适合批量离线任务。在 services.json 的preconfig.profiles中可以看到每个 Profile 的完整字段titleUI 显示名、model模型标识、modelSource数据来源注释标明了manual/openrouter/sync_models.config.json、modelTotalTokens上下文总 tokens、modelOutputTokens输出上限、apikey以及可选的deprecated/migration迁移提示。已废弃的 Profile以下 Profile 仍可在旧管道中选择但已标记为废弃建议迁移Gemini 3 Pro Preview → 使用gemini-3_1-pro-previewGemini 3 Pro Image → 使用gemini-3-pro-image-previewGemini 2.0 Flash → 使用gemini-2_5-flashGemini 2.0 Flash Lite → 使用gemini-2_5-flash-lite在 services.json 中还可以看到这些废弃 Profile 的migration提示字段例如 Gemini 2.5 Pro 的迁移提示为 Please use gemini-3.1-pro-preview instead引擎会在 UI 中据此引导用户更换模型。配置节点配置的核心是选择一个模型 Profile并提供一个 API Key。命名 Profile 已固化模型、上下文窗口和输出上限因此大多数管道无需额外设置。自定义模型选择customProfile 后需要手动填写模型标识Gemini 模型 ID例如models/gemini-2.5-pro总 Token 上限输入 输出custom 默认值为1,114,112输出 Token 上限custom 默认值为65,536。请将这两个值设置为所选择模型的真实限额。custom Profile 的默认值定义于 services.json且 custom 是唯一开放gemini.model、gemini.modelTotalTokens、gemini.outputTokens三个编辑字段的 Profile见fields中gemini.custom的properties列表。配置字段 Schema字段类型说明默认值gemini.apikeystringAPI KeyGoogle AI Developer API keygemini.modelstringModelGemini 模型gemini.modelTotalTokensnumberTotal Tokens输入 输出的最大 token 数gemini.outputTokensnumberOutput Tokens最大输出 token 数gemini.profilestringModelGemini LLM 模型gemini-3_1-pro-preview该 Schema 由nodes:docs-generate脚本自动生成于 README.md字段定义与 UI 行为如gemini.profile的enum下拉、各 Profile 的conditional联动展示、gemini.apikey的ApiKeyWidget安全输入控件均可在 services.json 中查到。认证方式在所选 Profile 的apikey字段中提供 Google AI Developer API Key可在 Google AI Studio 中创建Key 以安全字段secure field存储UI 使用ApiKeyWidget渲染不会明文回显Key 格式校验委托给 google-genai 库完成若缺失 Key管道启动时会以Please enter your Gemini API key.报错——该异常在 gemini.py 中显式抛出。已知坑点Profile 子键回退引擎在存储配置时会从 Profile 名称第一个下划线之后的片段派生子键例如gemini-2_5-pro被存储在5-pro下。节点读取 API Key 时会透明回退到该子键见 gemini.py因此Key 保存在两种布局下都能正常工作。这意味着无论 Key 是通过 UI 保存到标准位置还是历史配置中被存到了子键位置节点都能正确读取。关于 Vertex AI该节点仅面向 Gemini Developer API不使用 Vertex AI。不过 google-genai 客户端本身通过genai.Client(vertexaiTrue, project..., location...)也支持 Vertex AI——源码注释中表明未来重构可能将独立的 Vertex 节点与当前节点统一为一个实现见 gemini.py。底层实现原理节点的核心实现是 gemini.py 中的Chat类它继承自ChatBasepackages/ai/src/ai/common/chat.py但绕过了默认的 LangChain 适配器直接使用 google-genai 库调用 Gemini API。调用链路客户端初始化genai.Client(api_keyapi_key)gemini.py文本生成client.models.generate_content(modelself._model, contentsprompt)gemini.pyself._model由父类ChatBase通过validate_model_name校验后注入响应读取取response.text返回纯文本答案。由于节点重写了_chat且不设置_llm它不会进入LangChainAdapter因此 token 计量需要自行上报——这正是_report_gemini_usage函数存在的原因。Token 计量从 usage_metadata 精确上报_report_gemini_usagegemini.py从响应的usage_metadata中读取四个计数prompt_token_count包含缓存前缀因此先扣除cached_content_token_count得到新鲜输入token输出 candidates_token_countthoughts_token_countthoughts_token_count是推理 tokenGoogle 按输出费率计费需计入输出通过report_llm_tokenspackages/ai/src/ai/common/llm_adapter.py分别写入llm_input_tokens、llm_output_tokens、llm_cache_read_tokens等互不相交的计数器中供 metrics 单例按client_id累计计费。该函数的注释特别强调best-effort它运行在用户已付费的响应上任何计量失败都只记录调试日志debug_usage_failure绝不因计费问题吞掉答案。Token 估算0.75 tokens/word父类默认的getTokens依赖self._llm.get_num_tokens而本节点没有 LangChain LLM 对象因此重写了估算逻辑gemini.py按每个英文单词约 0.75 token 估算即int(word_count / 0.75)。这是一个本地近似值并非模型原生 tokenizer 的精确结果主要用于 prompt 预算校验与截断预警若追求精确计数源码注释建议使用模型的原生计数方式。另外该方法对None输入返回 0——因为无文本部分的响应.text是None而非空字符串token 记账不应成为发现该问题的场所。无文本响应GeminiNoTextError 与重试策略当响应携带空文本时.text为None可能的原因包括安全拦截、token 预算耗尽思考模型可能在输出可见文本前耗尽预算、或只有非文本部分。此时_chat会构造GeminiNoTextError异常[gemini.py](https://link.gitcode.com/i/772e476f4119087f1583b04190e36c1c#L59-L64, L196-L216)并携带finish_reason与block_reason详情。关键在于is_retryable_error的重写gemini.pyGeminiNoTextError被视为不可重试。原因很直接——API 已经给出判定重发相同 prompt 只会得到相同判定而每次重试都会被计费。默认的ChatBase.is_retryable_error对未识别错误采取保守可重试策略若无此重写一次安全拦截会被重发并重复扣费最多CONST_CHAT_MAX_RETRIES次相关重试循环见 packages/ai/src/ai/common/chat.py。管道启动校验beginGlobal中会加载 requirements.txt 声明的依赖并实例化Chat当引擎处于OPEN_MODE.CONFIG配置模式时则跳过加载见 IGlobal.py。保存时配置校验最小实时探针保存节点配置时IGlobal.validateConfigIGlobal.py会执行一次最小化实时探测向配置的模型发送单字 promptHiVALIDATION_PROMPT。其行为要点无 API Key 时跳过探测安全字段在校验时不会被解密因此没有 Key 就直接返回不触发探针Provider 错误以警告呈现捕获BadRequest、Unauthorized、Forbidden、NotFound、TooManyRequests、ServiceUnavailable、InternalServerError、DeadlineExceeded、InvalidArgument等 google-api-core 异常通过_extract_status_message_code解析异常字符串中的 JSON 负载或正则匹配提取HTTP 状态、状态码如INVALID_ARGUMENT与完整消息再经_format_error组装成Error code: STATUS - message形式写入 UI 警告且不截断消息图像模型特例仅支持图像输出、拒绝纯文本探测并报INVALID_ARGUMENTresponse modalities 错误的模型会被视为探测产物而非配置问题而静默放行解析失败时有兜底正则message字段提取、code STATUS头匹配与最终 fallback 警告文案Gemini validation setup error. Please check your configuration.。无密钥测试Mock google.genai节点在 services.json 中内置了test块可针对本地测试服务器运行无需真实 API Keytest: { profiles: [gemini-2_5-flash], outputs: [answers], cases: [ { name: LLM returns mock response, text: What is 22?, expect: { answers: { contains: Mock LLM response } } } ] }运行前提是将环境变量ROCKETRIDE_MOCK指向nodes/test/mocks。此时测试框架通过 nodes/test/mocks/google/genai/init.py 提供的假genai.Client替换真实库它接受与真实 Client 相同的构造参数api_key、vertexai、project、locationclient.models.generate_content()无视任何入参、固定返回文本Mock LLM response. This stub is used when ROCKETRIDE_MOCK is set so tests run without API keys or external services.。测试向questions通道发送What is 22?Profile 为gemini-2_5-flash并断言answers通道包含该 Mock 响应。该 mock 同时服务于accessibility_describe节点是仓库级共享测试设施。依赖清单节点运行所需的 Python 依赖声明在 requirements.txt核心为google-genai配套 Google 生态依赖google-genaigoogle-api-coregoogle-authgoogleapis-common-protosproto-plusprotobuf小结llm_gemini节点展示了 RocketRide LLM 节点的典型设计services.json声明协议、能力与 ProfileIGlobal.py负责生命周期与保存时探针校验gemini.py直接基于 google-genai 实现生成调用并自行接管 token 计量与错误语义。使用时的关键要点可归纳为选对 Profile注意 Image / batch / deprecated 标记、配置 Developer API Key、理解gemini-2_5-pro这类带下划线 Profile 的子键回退机制以及利用ROCKETRIDE_MOCK在无 Key 环境下跑通管道测试。对于以 LLM 为核心的 Agent 管道这个节点提供了把 Gemini 全系模型从 1M 上下文窗口的 Pro 旗舰到 Flash 轻量级与图像生成模型接入 RocketRide 的最短路径。赞分享【免费下载链接】rocketride-serverHigh-performance AI pipeline engine with a C core and 50 Python-extensible nodes. Build, debug, and scale LLM workflows with 13 model providers, 8 vector databases, and agent orchestration, all from your IDE. Includes VS Code extension, TypeScript/Python SDKs, and Docker deployment.项目地址https://gitcode.com/gh_mirrors/ro/rocketride-server点击查看免费下载相关推荐RocketRide llm_mistral 节点完全指南将 Mistral AI 模型接入 AI Pipeline 的配置、调用与容错原理RocketRide llm_mistral 节点完全指南将 Mistral AI 模型接入 AI Pipeline 的配置、调用与容错原理 本篇指南围绕 RRocketRide llm_xai 节点详解用 LangChain ChatXAI 将 xAI Grok 模型接入 AI 流水线RocketRide llm_xai 节点详解用 LangChain ChatXAI 将 xAI Grok 模型接入 AI 流水线 本文基于仓库中的节点文档RocketRide 中的 Qwen LLM 节点基于 DashScope OpenAI 兼容端点的多区域模型接入实战RocketRide 中的 Qwen LLM 节点基于 DashScope OpenAI 兼容端点的多区域模型接入实战 本文以 RocketRide 仓库中的上一篇终极OWASP Nettacker风险评估指南如何量化网络安全威胁等级 下一篇Axios 适配器Adapter完全指南内置适配器选择机制与自定义适配器实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考