RocketRide 管道节点开发指南：Python + services.json + lanes + preconfig 完整参考（附节点测试框架）

RocketRide 管道节点开发指南Python services.json lanes preconfig 完整参考附节点测试框架【免费下载链接】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-serverRocketRide 是一个高性能 AI 管道引擎其核心由 C 编写并内置 50 多个可 Python 扩展的管道节点Pipeline Node。如果你想为它自研一个管道节点——比如接入新的 LLM、向量库或数据源——那么本指南就是你要找的从 Python 实现、services.json声明、lanes数据流定义到preconfig配置档案再到内置的节点测试框架一次讲清楚无需逐行阅读源码。先搞懂一个管道节点长什么样在 RocketRide 中节点是管道的最小组成单元每个节点只做一件事解析文档、调用 LLM、存储向量、转写音频再通过类型化端口串联成完整工作流。一个标准 Python 节点位于nodes/src/nodes/节点名/目录下核心文件只有 4 个文件作用IGlobal.py全局初始化按OPEN_MODE决定是否加载依赖depends(requirements.txt)管理全局资源IInstance.py实例逻辑继承IInstanceBase通过writeText、writeQuestions等方法处理/转发数据services.json节点注册表声明类类型、能力、lanes、preconfig、UI 字段等requirements.txt节点第三方依赖官方节点示例可直接阅读最简节点nodes/src/nodes/question/ —— 纯 Python、零依赖services.json同时演示了 lanes、preconfig 和 test 三大块LLM 节点nodes/src/nodes/llm_openai/services.json带invoke控制的节点nodes/src/nodes/summarization/services.jsonlanes 数据流节点之间如何对得上插头节点之间的数据交换依赖lanes通道。Lane 是一种类型化端口节点在services.json的lanes块中声明消费输入哪些通道、生产输出哪些通道。// question 节点的 lanes 声明消费 text产出 questions lanes: { text: [questions] } 规则上游节点的输出通道类型与下游节点的输入通道类型匹配时两者即可连线。典型的 RAG 数据流为webhook (_source → questions)→embedding_openai (questions → questions)→pinecone (questions → documents)→prompt (documents → questions)→llm_openai (questions → answers)→response (answers → -)完整的通道类型一览摘自 docs/README-nodes.md通道类型含义questions流向模型的查询/提示包answers模型/Agent 的响应documents可分块/可嵌入的文档记录text/table纯文本 / 结构化表格数据image/audio/video媒体负载流式传输BEGIN/WRITE/END 三段式tags附加在记录上的元数据_sourcesource 类节点的入口通道外部触发⚠️ 一个常见误区classType为tool的节点如tool_github、tool_tavily没有数据 lanes它们不处在数据流中而是绑定到 Agent 节点的 tool 通道上由 Agent 按需调用。记住口诀有 lanes 就连线是 tool 就绑定混用会生成非法管道。另外summarization这类节点还有invoke块——它声明需要外接的控制类节点例如必须挂一个 LLM 供其调用与数据 lanes 分属两种连接方式。services.json 逐项详解节点的注册表下面是一份精简版services.json骨架逐项说明哪些必填、哪些可选{ title: My Node, // 必填UI 显示名称 protocol: my_node://, // 必填端点协议 classType: [text], // 必填节点类别llm / text / tool / vectorstore… capabilities: [invoke], // 必填影响引擎行为的标志位 register: filter, // 可选filter管道内/ endpoint node: python, // 可选物理节点类型测试框架要求为 python path: nodes.my_node, // 可选Python 模块导入路径 prefix: my_node, // 必填URL 与路径互转的前缀映射 description: [节点功能描述…], // 可选 icon: my_node.svg, // 可选节点图标SVG 自动发现 lanes: { text: [questions] }, // 可选但关键输入 → 输出通道 preconfig: { default: default, profiles: { default: {} } }, test: { /* 见下文测试框架 */ }, fields: { /* UI 字段定义 */ }, shape: [ /* 画布上分组展示的字段分区 */ ] }几个值得注意的细节icon 自动发现构建流水线会自动扫描nodes/src/nodes/节点名/*.svg无需维护中央注册表。单色 SVG 会被自动改写为currentColor以跟随明暗主题多色 SVG如品牌 Logo原样保留。fieldsshape定义画布上渲染的配置表单支持enum、conditional按 profile 动态显示字段等能力。例如llm_openai的openai.profile字段通过enum: [*preconfig.profiles.*.title]自动把所有 profile 变成下拉选项。preconfig 配置档案一份声明多种预设preconfig是节点的预设系统也是你控制节点行为的最佳位置preconfig: { // 默认 profile其值会被合并进任何非 absolute 的 profile default: openai-5-2, profiles: { custom: { model: , apikey: }, openai-5-4: { title: GPT-5.4, model: gpt-5.4, modelTotalTokens: 1050000, modelOutputTokens: 128000, capabilities: { reasoning: true } } } }工作机制管道中通过profile键选择某个 profile选中的 profile 配置会与default声明的值自动合并除非 profile 标记为absoluteUI 下拉框直接从profiles.*.title生成用户选模型不需要手填参数。以 nodes/src/nodes/llm_openai/services.json 为例它把 40 多个 GPT 模型的 token 上限、推理能力等全部档案化——节点作者在IInstance.py里读到的就是合并后的干净配置。本地原型不动引擎就能调试新节点自研节点不必修改已安装的引擎。把节点放进工作区的local_nodes/文件夹然后启动引擎时指定路径即可my-workspace/ └── local_nodes/ ├── __init__.py # 空文件标记为包 └── my_node/ ├── __init__.py # 必须运行 depends() 并导出 IGlobal/IInstance ├── services.json # path: local_nodes.my_node ├── IGlobal.py ├── IInstance.py └── requirements.txtengine --node_path/path/to/dir-containing-local_nodes ...其节点会被像内置节点一样扫描但导入名为local_nodes.节点绝不与内置nodes包冲突IGlobal会自动安装节点自己的requirements.txt依赖管理与内置节点完全一致。验证通过后将节点移入nodes/src/nodes/节点名/并把path改为nodes.节点即可提交成为 RocketRide 的一部分。节点测试框架写在 services.json 里的自动化测试RocketRide 内置了一套声明式节点测试框架支持node: python的节点——测试用例直接写在services.json的test属性中无需额外编写 pytest 文件。在 services.json 中声明测试question 节点 的官方示例test: { profiles: [default], cases: [ { text: What is the capital of France?, expect: { questions: { equals: What is the capital of France? } } } ] }test块支持的属性属性说明requires依赖的环境变量缺失时用例自动跳过如[ROCKETRIDE_OPENAI_KEY]profiles要测试的 profile每个 profile 独立跑一遍controls挂入管道的控制节点如[llm_openai]chain前置链路*代表被测节点如[preprocessor_langchain, embedding_transformer, *]outputs要捕获的输出通道省略时从expect键自动推断timeout超时秒数默认 60cases测试用例数组输入与断言怎么写文本类通道text / questions / answers / table…直接内联字符串文件类通道image / audio / video / documents填相对testdata/的路径如image: ocr/sample.png测试素材位于 testdata/。expect 断言支持丰富的匹配器内容匹配equals/contains/matches正则/beginsWith/endsWith结构匹配notEmpty/minLength/maxLength/type/hasProperty/noError数值匹配greaterThan/lessThan深层路径property: { path: [0].questions[0].text, contains: capital }以及each数组每项/any任一项已知通道有快捷路径expect: { text: { contains: hello } }会自动定位到该通道的内容字段省去手写路径。两条测试命令契约 集成# 契约测试校验 services*.json 结构必填字段、lane 名、模块存在性无需启动服务器 builder nodes:test # 完整集成测试自动拉起测试服务器把用例放进真实管道跑 builder nodes:test-full # 按名称过滤 builder nodes:test-full --pytest-k question集成测试会自动设置ROCKETRIDE_MOCK环境变量启用外部服务的 mock 实现位于 nodes/test/mocks/因此 CI 中无需真实 API Key 即可运行。框架源码在 nodes/test/framework/详细规范见 docs/README-node-testing.md。把新知识装进你的节点推荐学习路径通读 docs/README-nodes.md118 个节点目录 → 148 个服务的完整目录、lane 类型谁生产谁消费、以及Adding a New Node六步清单对照三个真实节点最简的 question、重型的 llm_openai、带 invoke 的 summarization按本文流程建目录 → 写IGlobal.py/IInstance.py→ 声明lanes与preconfig→ 放iconSVG → 加requirements.txt→ 在test块写用例 →builder nodes:test跑契约测试 →builder nodes:test-full跑集成测试用--node_path做本地原型验证再正式合入nodes/src/nodes/。掌握这套Python services.json lanes preconfig的组合拳后你不仅能在 RocketRide 画布上拖出自己的节点还能让它在 CI 中拥有与其他 148 个内置服务同等质量的自动化测试保障。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考