企业官网建设流程全解析

llm_baidu_qianfan是 RocketRide 内置的 LLM 节点，通过千帆（Baidu Qianfan）的 OpenAI 兼容 chat-completions 接口调用 ERNIE 系列大模型，为管道提供基于聊天的文本生成、问答、摘要与中文企业级 AI 工作流能力。本文以该节点的官方文档（nodes/src/nodes/llm_baidu_qianfan/README.md）为骨架，结合节点源码与注册配置，完整讲解数据通路、Profile 模型档位、Base URL 与 API Key 配置、保存时实时校验、运行时错误分类等实战细节，读完后你可以直接在 RocketRide 管道中接入并排障百度千帆 ERNIE 模型。

节点定位：管道中的 ERNIE 对话入口

该节点是一个 RocketRide LLM 节点，核心职责是把管道与百度千帆 ERNIE 大模型连接起来，用于基于聊天的文本生成、问答、摘要以及面向中文场景的企业 AI 工作流。从节点注册文件 services.json 可以看出它的元信息：

• protocol：llm_baidu_qianfan://，协议即节点的唯一标识；
• classType：["llm"]，属于 LLM 类别节点；
• capabilities：["invoke"]，可被管道以函数调用的方式触发；
• register：filter，作为过滤型端点注册进引擎；
• node：python，由 Python 运行时承载，path指向nodes.llm_baidu_qianfan包；
• tile：在 UI 平铺展示时显示Model: ${parameters.llm_baidu_qianfan.profile}，即当前选中的模型档位。

底层实现建立在langchain-openai（ChatOpenAI）之上，通过openaiPython SDK 指向千帆的 OpenAI 兼容端点。这一技术选型意味着节点复用了 RocketRide 对 OpenAI 兼容协议的全部既有能力，同时只暴露千帆特有的配置面。

数据通路：questions 入、answers 出

节点通过一对 lane（管道通道）与外界交互，文档中给出的映射如下：

即：进入questionslane 的问题由配置的 ERNIE 模型作答，生成的回答被写到answerslane 上。在 services.json 中对应"lanes": { "questions": ["answers"] }的定义，并声明了内置测试用例：向节点发送"What is 2+2?"，期望answers输出包含"Mock LLM response"（由 mock 层模拟模型返回，用于无真实凭据时的管道联调）。

从源码结构看，IInstance继承自 packages/ai/src/ai/common/llm_base.py 中的LLMBase，后者是 RocketRide 所有 LLM 节点的公共实例基类：writeQuestions负责把问题交给IGlobal._chat执行并写回answers，还支持通过sendSSE('thinking', ...)把推理过程流式推送到 chat-ui 的 thinking 通道；getContextLength/getOutputLength等可调用函数则把模型的上下文与输出预算暴露给管道。llm_baidu_qianfan的IInstance本身为空实现（pass），即节点完全复用 LLMBase 的通用问答语义，无需任何 provider 特化逻辑。

Profile 模型档位与 token 预算

节点以「档位（profile）」的方式管理模型选择与 token 预算。文档给出的默认档位为ERNIE 4.5 Turbo 128K（ernie-4-5-turbo-128k），完整档位如下：

这些档位在 services.json 的preconfig.profiles中逐一定义，每个档位钉死四类信息：

• model：发送给千帆接口的模型名（如ernie-4.5-turbo-128k）；
• modelTotalTokens：上下文窗口上限（128,000 / 32,768）；
• modelOutputTokens：单次生成的最大输出 token（4,096 / 8,192）；
• modelSource：provider（模型名来自 provider 档位，不可编辑）或manual（custom 档位由用户手填）。

命名档位（三个 ERNIE 档位）只允许编辑 API Key、Base URL 与模型来源，模型名与 token 预算由档位锁定；Custom 档位额外开放model、modelTotalTokens、modelOutputTokens三个字段，用于指向你千帆账号下可用的任意模型。文档特别提示：命名档位已提供模型与 token 预算，多数管道只需一个 API Key 与正确的区域端点即可运行。

配置参数：Schema 全字段说明

节点配置以baidu_qianfan.前缀命名空间组织。README 中由nodes:docs-generate自动生成的 Schema 表格如下：

对照 services.json 的fields定义可以进一步还原字段的语义：

• baidu_qianfan.profile：模型档位下拉选择，枚举值由*>preconfig.profiles.*.title动态生成（即上文四个档位的标题），并通过conditional规则联动展示对应档位的可编辑字段——选择custom时才会浮现model、modelTotalTokens、modelOutputTokens三个手填项；
• baidu_qianfan.serverbase：千帆 OpenAI 兼容端点，默认https://qianfan.baidubce.com/v2，枚举提供了中国大陆与国际两个选项（见下文）；
• llm.cloud.apikey：API Key 字段（在fields的档位对象中作为共享属性引用），节点运行必需；
• llm.cloud.modelSource：模型来源（provider / manual）。

shape中定义了 UI 表单的渲染结构：Pipe 分区下展示baidu_qianfan.profile选择器，其余字段按档位条件展开。

Base URL：区域端点必须与 Key 匹配

千帆按签发地区提供不同端点，文档给出了明确规则：

• 中国大陆签发的 Key：https://qianfan.baidubce.com/v2（默认值）；
• 国际版 Key：https://api.baiduqianfan.ai/v1。

端点与 Key 必须属于同一个千帆环境，混用会导致鉴权失败或请求不可达。源码 qianfan_client.py 中DEFAULT_QIANFAN_BASE_URL = 'https://qianfan.baidubce.com/v2'与文档默认值一致，读取时会对配置值做rstrip('/')归一化，容忍末尾多余的斜杠。

Authentication：API Key 是硬性要求

节点要求提供千帆 API Key（配置字段apikey），没有 Key 节点拒绝启动。源码中对应两条硬校验：

1. 在 IGlobal.py 的validateConfig中，Key 缺失或全空白会立即产生警告Baidu Qianfan API key is required.；
2. 在 qianfan_client.py 的Chat.__init__中，同样的条件会抛出ValueError('Baidu Qianfan API key is required.')，直接阻断节点实例化。

此外 Key 必须拥有所选模型的访问权限。无效或未授权的 Key，在保存校验与运行时都会统一报告为"Baidu Qianfan API key is invalid or unauthorized"——这正是map_exception对AuthenticationError的固定映射文案。

保存时实时校验：一次微型的连通性测试

这是该节点最具特色的能力：保存节点配置时，节点会立即做一次实时校验，向配置的端点发送一条极小的测试请求（prompt 为"Hi"，max_tokens为 8），并根据结果给出针对性警告。实现位于 IGlobal.py 的validateConfig，其中的常量即文档描述的两个数字：

VALIDATION_PROMPT = 'Hi' VALIDATION_MAX_TOKENS = 8

校验流程（对应validateConfig的代码路径）依次检查并给出特定警告：

1. API Key 缺失：Baidu Qianfan API key is required.
2. 模型名为空：Baidu Qianfan model name must not be empty.
3. token 上限非法：modelTotalTokens存在但无法转换为正整数时，警告Token limit must be greater than 0
4. 真实请求探测：使用OpenAI(api_key=..., base_url=...)构造客户端并调用client.chat.completions.create(model=..., messages=[{'role': 'user', 'content': 'Hi'}], max_tokens=8)，按异常类型分类上报：
   • AuthenticationError→Baidu Qianfan API key is invalid or unauthorized.
   • RateLimitError→Baidu Qianfan rate limit exceeded while validating the configuration.
   • APIStatusError→ 解析响应体中的error.type/error.code/error.message（或顶层code/message），拼装成Error <status>: <type> - <message>形式，超过 500 字符会被截断；
   • APIConnectionError→Could not connect to Baidu Qianfan. Check the configured base URL and network access.（文档中的「base URL 不可达」即此分支）；
   • 其他OpenAIError→ 输出格式化后的原始错误文本。

可见文档所述「无效 API Key、空模型名、非正 token 上限、限流、base URL 不可达或其他 API 错误」的每一条警告，都能在validateConfig中找到对应的代码分支，是配置错误的第一道防线。

运行时行为：温度固定为 0，错误按可重试性分流

运行时真正的请求执行器是 qianfan_client.py 中的Chat类，它继承 packages/ai/src/ai/common/chat.py 的ChatBase（RocketRide 所有聊天类驱动的公共基类，负责 token 预算读取、输入校验、token 用量统计与统一的问答接口）。

Chat.__init__构造ChatOpenAI时有三个值得注意的硬编码：

self._llm = ChatOpenAI( model=self._model, api_key=apikey.strip(), base_url=serverbase, temperature=0, max_tokens=self._modelOutputTokens, )

• temperature=0：温度固定为 0，保证输出确定性（文档明确说明）——适合摘要、抽取、问答等对一致性要求高的企业场景；
• max_tokens=self._modelOutputTokens：生成上限由档位（或 custom 手填）的modelOutputTokens决定；
• model来自ChatBase.__init__读取的model配置（命名档位下即 Profile 钉死的模型名）。

同时ChatBase在基类中会为modelTotalTokens提供 16,384 的兜底默认值、为modelOutputTokens提供 4,096 的默认值（见 packages/ai/src/ai/common/chat.py），确保配置缺省时仍有合理的预算。

运行时错误处理遵循「可重试性」二分策略，由is_retryable_error判定：

不可重试的错误会经map_exception转换为面向用户的友好消息，四个分支与文档完全对应：

• AuthenticationError→Baidu Qianfan API key is invalid or unauthorized.
• RateLimitError→Baidu Qianfan rate limit exceeded. Please try again later.
• APIConnectionError→Failed to connect to the Baidu Qianfan API.
• APIError→An error occurred with the Baidu Qianfan API.

结合 packages/ai/src/ai/common/llm_base.py 的LLMBase.writeQuestions可以还原完整调用链：管道把问题写入questionslane →LLMBase._question从IGlobal._chat取出Chat实例调用chat()→ChatBase驱动的ChatOpenAI请求千帆 → 回答经writeAnswers写回answerslane；若调用失败，错误被包装为**LLM error**消息写回 answers，并记录本轮已消耗的 token 供 Trace 展示。

生命周期与依赖

节点生命周期由 IGlobal.py 管理：

• beginGlobal：在端点进入CONFIG之外的打开模式时执行——先_ensure_dependencies()按需安装依赖，再以当前配置构造Chat实例存入endpoint.bag（bag['chat']），供实例侧取用；
• endGlobal：将self._chat置空，释放连接资源；
• 依赖安装采用depends(requirements)动态机制，按需读取节点目录下的 requirements.txt。

节点声明的依赖共四项（与文档的 Dependencies 一节完全一致）：

• openai：OpenAI Python SDK，负责底层 HTTP 调用与异常类型（AuthenticationError、RateLimitError、APIConnectionError、APIError）的抛出；
• langchain/langchain-core：LangChain 核心框架；
• langchain-openai：提供ChatOpenAI，把千帆的 OpenAI 兼容端点包装为标准的 Chat Model 接口。

包入口init.py 导出IGlobal、IInstance与getChat()（延迟导入Chat类），三者共同构成 RocketRide 节点的标准三段式结构，与仓库中其余 LLM 节点（如llm_openai、llm_anthropic）保持一致的注册与加载约定。

快速接入清单

在 RocketRide 管道中接入该节点，按以下步骤即可：

1. 在管道中拖入Baidu Qianfan节点（UI 图标为 baidu-qianfan.svg，平铺标题显示当前模型档位）；
2. 在baidu_qianfan.profile选择模型档位：默认ernie-4-5-turbo-128k，或按需切换ernie-4-5-turbo-32k、ernie-5-0-thinking-preview、custom；
3. 在llm.cloud.apikey填入千帆 API Key，并在baidu_qianfan.serverbase选择与 Key 签发地区一致的端点（中国大陆默认，国际版用https://api.baiduqianfan.ai/v1）；
4. 选择custom档位时，额外填写model、modelTotalTokens、modelOutputTokens；
5. 保存配置——节点会立即发送"Hi"（8 token）的微型探测请求，若有 Key 无效、模型名缺失、token 上限非法、限流、端点不可达等问题，会在保存时就得到针对性警告；
6. 将上游节点接入questionslane，从answerslane 取回答；运行期遇到限流或连接错误会自动重试，鉴权等错误则立即失败并给出用户可读的报错文案。

小结

llm_baidu_qianfan节点以最小的配置面（一个 Key、一个端点、一个档位选择）把千帆 ERNIE 模型接入 RocketRide 管道：temperature=0保证确定性输出，Profile 机制统一管理模型名与 token 预算，保存时的实时探测校验把绝大多数配置错误拦截在运行之前，运行时则用「可重试 / 立即失败」的错误分流保证管道韧性。对于需要中文企业级问答、摘要与生成能力的管道，它是开箱即用的一站式接入方案。

进一步阅读：节点完整注册信息见 services.json，运行时实现见 qianfan_client.py，保存校验与生命周期见 IGlobal.py，公共基类逻辑见 packages/ai/src/ai/common/chat.py 与 packages/ai/src/ai/common/llm_base.py。