news 2026/9/25 2:45:42

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

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
RocketRide 的 llm_gemini 节点：在 AI Pipeline 中接入 Google Gemini 模型

【免费下载链接】rocketride-server

High-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.json：

  • protocol:llm_gemini://，是管道端点协议；
  • classType:["llm"]，即它是标准的 LLM 类型节点；
  • capabilities:["invoke"]，表明它可以被 Agent 或其他节点作为 LLM 调用连接使用；
  • register:filter，node:python，path: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 Pro（gemini-3_1-pro-preview），其完整配置见 services.json。

常用 Profile

ProfileModelContext tokensOutput tokens
Gemini 3.1 Pro(默认)models/gemini-3.1-pro-preview1,048,57665,536
Google: Gemini 3.6 Flashmodels/gemini-3.6-flash1,048,57665,536
Google: Gemini 3.5 Flashmodels/gemini-3.5-flash1,048,57665,536
Google: Gemini 3.5 Flash Litemodels/gemini-3.5-flash-lite1,048,57665,536

更多模型（折叠查看）

ProfileModelContext tokensOutput tokens
custom(用户指定)可编辑可编辑
Gemini 3.1 Flash Image Previewmodels/gemini-3.1-flash-image-preview131,07258,982
Gemini 3.1 Flash Litemodels/gemini-3.1-flash-lite-preview1,048,57665,536
Gemini 3 Flash Previewmodels/gemini-3-flash-preview1,048,57665,536
Gemini 3 Pro Image Previewmodels/gemini-3-pro-image-preview65,53632,768
Gemini 2.5 Promodels/gemini-2.5-pro1,048,57665,536
Gemini 2.5 Flashmodels/gemini-2.5-flash1,048,57665,535
Gemini 2.5 Flash Litemodels/gemini-2.5-flash-lite1,048,57665,535
Gemini 2.5 Flash Imagemodels/gemini-2.5-flash-image32,7688,192
Gemini 3 Pro Previewmodels/gemini-3-pro-preview1,048,57665,536
Gemini 3 Pro Imagemodels/gemini-3-pro-image131,07232,768
Gemini 2.0 Flashmodels/gemini-2.0-flash1,048,57665,535
Gemini 2.0 Flash Litemodels/gemini-2.0-flash-lite—65,536
Google: Gemini 2.5 Flash Lite Preview 09-2025models/gemini-2.5-flash-lite-preview-09-20251,048,57665,535
Google: Gemini 2.5 Pro Preview 06-05models/gemini-2.5-pro-preview1,048,57665,536
Google: Gemini 2.5 Pro Preview 05-06models/gemini-2.5-pro-preview-05-061,048,57665,535
Google: Gemini 3.1 Pro Preview Custom Toolsmodels/gemini-3.1-pro-preview-customtools1,048,57665,536
Google Gemini Flash Latestmodels/gemini-flash-latest1,048,57665,536
Google Gemini Pro Latestmodels/gemini-pro-latest1,048,57665,536
Google: Nano Banana 2 (Gemini 3.1 Flash Image)models/gemini-3.1-flash-image131,07232,768
Google: Gemini 3.1 Flash Litemodels/gemini-3.1-flash-lite1,048,57665,536
Google: Nano Banana 2 Lite (Gemini 3.1 Flash Lite Image)models/gemini-3.1-flash-lite-image65,53658,982
models-gemini-2-5-flash-batchmodels/gemini-2.5-flash:batch1,048,57665,535
models-gemini-2-5-flash-lite-batchmodels/gemini-2.5-flash-lite:batch1,048,57665,535
models-gemini-2-5-pro-batchmodels/gemini-2.5-pro:batch1,048,57665,536
models-gemini-3-1-flash-lite-batchmodels/gemini-3.1-flash-lite:batch1,048,57665,536
models-gemini-3-1-pro-preview-batchmodels/gemini-3.1-pro-preview:batch1,048,57665,536
models-gemini-3-5-flash-batchmodels/gemini-3.5-flash:batch1,048,57665,536
models-gemini-3-5-flash-lite-batchmodels/gemini-3.5-flash-lite:batch1,048,57665,536
models-gemini-3-6-flash-batchmodels/gemini-3.6-flash:batch1,048,57665,536
models-gemini-3-7-flashmodels/gemini-3.7-flash1,048,57665,536
models-gemini-3-7-flash-batchmodels/gemini-3.7-flash:batch1,048,57665,536
models-gemini-3-8-flashmodels/gemini-3.8-flash1,048,57665,536
models-gemini-3-8-flash-batchmodels/gemini-3.8-flash:batch1,048,57665,536
models-gemini-3-flash-preview-batchmodels/gemini-3-flash-preview:batch1,048,57665,536

Profile 标题中包含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 的完整字段：title（UI 显示名）、model（模型标识）、modelSource（数据来源，注释标明了manual/openrouter/sync_models.config.json）、modelTotalTokens（上下文总 tokens）、modelOutputTokens（输出上限）、apikey以及可选的deprecated/migration迁移提示。

已废弃的 Profile

以下 Profile 仍可在旧管道中选择，但已标记为废弃，建议迁移：

  • Gemini 3 Pro Preview → 使用gemini-3_1-pro-preview
  • Gemini 3 Pro Image → 使用gemini-3-pro-image-preview
  • Gemini 2.0 Flash → 使用gemini-2_5-flash
  • Gemini 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 Key：Google AI Developer API key
gemini.modelstringModel：Gemini 模型
gemini.modelTotalTokensnumberTotal Tokens：输入 + 输出的最大 token 数
gemini.outputTokensnumberOutput Tokens：最大输出 token 数
gemini.profilestringModel：Gemini 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(vertexai=True, project=..., location=...)也支持 Vertex AI——源码注释中表明，未来重构可能将独立的 Vertex 节点与当前节点统一为一个实现（见 gemini.py）。

底层实现原理

节点的核心实现是 gemini.py 中的Chat类，它继承自ChatBase（packages/ai/src/ai/common/chat.py），但绕过了默认的 LangChain 适配器，直接使用 google-genai 库调用 Gemini API。

调用链路

  1. 客户端初始化：genai.Client(api_key=api_key)（gemini.py）；
  2. 文本生成：client.models.generate_content(model=self._model, contents=prompt)（gemini.py），self._model由父类ChatBase通过validate_model_name校验后注入；
  3. 响应读取：取response.text返回纯文本答案。

由于节点重写了_chat且不设置_llm，它不会进入LangChainAdapter，因此 token 计量需要自行上报——这正是_report_gemini_usage函数存在的原因。

Token 计量：从 usage_metadata 精确上报

_report_gemini_usage（gemini.py）从响应的usage_metadata中读取四个计数：

  • prompt_token_count包含缓存前缀，因此先扣除cached_content_token_count得到"新鲜输入"token；
  • 输出 =candidates_token_count+thoughts_token_count（thoughts_token_count是推理 token，Google 按输出费率计费，需计入输出）；
  • 通过report_llm_tokens（packages/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.py）：GeminiNoTextError被视为不可重试。原因很直接——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.validateConfig（IGlobal.py）会执行一次最小化实时探测：向配置的模型发送单字 promptHi（VALIDATION_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_ARGUMENT"response modalities" 错误的模型，会被视为探测产物而非配置问题而静默放行；
  • 解析失败时有兜底正则（message字段提取、<code> <STATUS>头匹配）与最终 fallback 警告文案Gemini validation setup error. Please check your configuration.。

无密钥测试：Mock google.genai

节点在 services.json 中内置了test块，可针对本地测试服务器运行，无需真实 API Key：

"test": { "profiles": ["gemini-2_5-flash"], "outputs": ["answers"], "cases": [ { "name": "LLM returns mock response", "text": "What is 2+2?", "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、location），client.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 2+2?（Profile 为gemini-2_5-flash），并断言answers通道包含该 Mock 响应。该 mock 同时服务于accessibility_describe节点，是仓库级共享测试设施。

依赖清单

节点运行所需的 Python 依赖声明在 requirements.txt，核心为google-genai，配套 Google 生态依赖：

  • google-genai
  • google-api-core
  • google-auth
  • googleapis-common-protos
  • proto-plus
  • protobuf

小结

llm_gemini节点展示了 RocketRide LLM 节点的典型设计：services.json声明协议、能力与 Profile，IGlobal.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-server

High-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
点击查看免费下载
上一篇：终极OWASP Nettacker风险评估指南：如何量化网络安全威胁等级 🔒
下一篇：Axios 适配器（Adapter）完全指南：内置适配器选择机制与自定义适配器实战

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/25 2:45:09

豆包AI生图去水印全攻略：官方渠道、ComfyUI局部重绘与API批量处理

1. 豆包AI生图的水印到底藏在哪一层先把一个基础事实说清楚&#xff1a;豆包AI生成的图片&#xff0c;水印不是像贴纸一样浮在画面最上层的独立图层。它是在出图阶段由服务端合成进像素里的&#xff0c;位置通常在右下角或左下角&#xff0c;带一个半透明的品牌标识加一行小字。…

作者头像 李华
网站建设 2026/9/25 2:45:00

拼团交易平台系统第2-12节：拼团组队结算统计——支付驱动组队进度与成团判定的实现解析

文档教程后端 【免费下载链接】CodeGuide :books: 本代码库是作者小傅哥多年从事一线互联网 Java 开发的学习历程技术汇总&#xff0c;旨在为大家提供一个清晰详细的学习教程&#xff0c;侧重点更倾向编写Java核心内容。如果本仓库能为您提供帮助&#xff0c;请给予支持(关注、…

作者头像 李华
网站建设 2026/9/25 2:44:20

Cobalt Strike 4.0 zip部署指南：从校验到Beacon上线的完整避坑教程

简介&#xff1a;Cobalt Strike 4.0工具包面向网络安全攻防与红队评估场景&#xff0c;适合获得授权后开展渗透测试、模拟攻击与防御演练的工程师&#xff0c;也可用于企业安全团队验证检测响应能力。压缩包内共54个文件&#xff0c;大小约35.44MB&#xff0c;核心组件为jar主程…

作者头像 李华
网站建设 2026/9/25 2:43:46

Pyro 因果效应推断实战：CEVAE（Causal Effect VAE）从理论到代码

人工智能机器学习深度学习概率编程 【免费下载链接】pyro Deep universal probabilistic programming with Python and PyTorch 项目地址&#xff1a; https://gitcode.com/gh_mirrors/py/pyro 点击查看 免费下载 本篇技术指南围绕 Pyro 官方的 CEVAE 示例教程&#xff08;tut…

作者头像 李华