RocketRide accessibility_describe 节点实战：用 Google Gemini Vision 构建安全导向的无障碍场景描述

【免费下载链接】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点击查看免费下载accessibility_describe是 RocketRide 中一个面向无障碍场景的图像分析节点它把完整接收的图片流交给 Google Gemini 视觉模型生成以安全优先hazards、空间定位clock positions / relative directions、可见文本OCR和导航引导为核心的结构化场景描述供盲人与低视力用户的下游语音播报、智能眼镜等辅助场景消费。读完本文你将掌握该节点的 lanes/profile 结构、四个核心配置项System Instructions、Analysis Prompt、Hazard Priority、Spatial Format的取值与联动方式、API Key 校验规则、重试与错误翻译机制以及它在仓库中的真实实现位置与测试用例可直接在管道中完成无障碍描述环节的搭建与调优。节点定位管道过滤器而非 Agent 工具从services.json的注册信息可以确认其类型归属classType: [image], capabilities: [invoke], register: filter, node: python, lanes: { image: [text] }它被注册为filter类型的 Python 节点输入 lane 为image输出 lane 为text。这意味着它应该被当作管道中的一个完整转换环节来使用当管线的下游消费者需要一段无障碍视角的完整叙述时选择它若下游需要的是裁剪、转码、人脸检测等其他类型的结果则应改用对应节点而非本节点。此外一个重要的边界行为是空的图片流不会产生任何文本输出IInstance.writeImage在 END 动作时若缓冲区为空会直接preventDefault短路返回。工作原理从图片流到textlane 的完整调用链节点的数据处理逻辑位于 IInstance.py核心流程分三步缓冲图片流writeImage按AVI_ACTION.BEGIN / WRITE / END三个动作处理。BEGIN 时初始化bytearray缓冲区WRITE 时追加分块数据END 时才开始真正处理从而保证送入模型的是一张完整的图。编码为 Data URLEND 动作里将字节做 base64 编码并拼装为data:{mimeType};base64,{data}通过question.addContext(...)放入上下文同时把分析提示词通过question.addQuestion(...)一并传入。单次生成请求调用IGlobal.chat.chat(question)由 accessibility_vision.py 中的Chat类把图片字节与分析提示词组合为一次generate_content请求发送给 Gemini随后把返回文本写入textlanecontents [ Content( roleuser, parts[ Part.from_bytes(dataimage_bytes, mime_typemime_type), Part.from_text(textprompt_text), ], ) ] response self._client.models.generate_content( modelself._model, contentscontents, config{ system_instruction: self._system_prompt, temperature: 0.3, max_output_tokens: 1024, }, )注意这里系统指令system_instruction与分析提示词user 文本是分开的系统指令是跨图片生效的持久策略分析提示词是随当前图片发送的逐图请求。Chat类继承自packages/ai/src/ai/common/chat.py中的ChatBase负责 token 管理、配置加载等公共能力并在IGlobal.beginGlobal中作为单例创建、endGlobal中销毁整个生命周期由 IGlobal.py 管理避免每次调用重复初始化客户端。Lanes 一览Lane inLane outDescriptionimagetext分析完整接收的图片流并输出生成的无障碍场景描述模型 Profiles三档 Gemini 视觉模型节点通过preconfig.profiles定义可选模型档位默认档位为Gemini 2.5 Flash - Fast Efficient (1M tokens)gemini-2.5-flash。services.json中每个 profile 都预置了model、modelTotalTokens与空的apikey占位ProfileModelContext limitGemini 2.5 Flash - Fast Efficient (1M tokens)默认gemini-2.5-flash1048576tokensGemini 2.5 Pro - High Quality (1M tokens)gemini-2.5-pro1048576tokensGemini 2.0 Flash - Balanced (1M tokens)gemini-2.0-flash1048576tokens三个 profile 的上下文上限均为1048576tokens。在代码中Chat.__init__通过config.get(model, gemini-2.5-flash)读取模型名modelTotalTokens同样默认1048576accessibility_vision.py中config.get(modelTotalTokens, 1048576)并在getTotalTokens()中暴露给上层做 token 配额管理。切换 profile 后模型名、token 上限与 API Key 都会随 profile 绑定替换。配置详解四个核心参数节点的fields定义了四组与无障碍描述行为直接相关的参数均在services.json的accessibility.*命名空间下并配有生成式参数表Schema。官方建议的起步方式是先用默认 Flash profile填入 API Key保持内置指令与提示词当输出策略需要变化时再逐个调整文本字段并用两个格式化控件Hazard Priority / Spatial Format让输出更易被下游执行。System Instructions系统指令accessibility.systemPrompt这是模型的系统指令默认值为You are an accessibility-focused scene analyzer designed to help blind and visually impaired users understand their surroundings through image descriptions.内置指令accessibility_vision.py中的DEFAULT_SYSTEM_PROMPT明确要求模型安全优先始终先讲潜在危险楼梯、障碍物、车辆、湿滑地面、施工区域、空间定向使用钟点位置与相对距离、逐字读取可见文本、简洁但完整优先可行动信息而非美学细节、上下文丰富识别室内/室外、店铺/街道/办公室等环境类型与地标。修改它适用于需要对每一张图都生效的持久策略例如追加一条站点特定的安全规则而不是针对单张图的提问。需要注意的联动逻辑是留空时先回退到通用的systemPrompt运行时设置再回退到内置指令并且所选 Hazard Priority 与 Spatial Format 会以追加片段的形式拼接到该指令之后见下文源码因此自定义指令应与这两个控件保持兼容不要重复或矛盾地规定空间与排序规则。Analysis Prompt分析提示词accessibility.prompt这是逐图请求。默认提示词要求模型按六个小节组织回答并控制字数Describe this image for a blind person. Include: environment type, hazards with positions, key objects with clock positions, visible text, people, and navigation guidance. Keep under 150 words.源码中的DEFAULT_PROMPT给出了更细的结构ENVIRONMENT环境一句话、HAZARDS危险与障碍清单及位置、KEY OBJECTS关键物体带钟点位置与距离、TEXT可见文本逐字读取、PEOPLE在场人员、大致数量、位置与相关动作、NAVIGATION前进路径是否畅通、有无转弯或障碍总字数控制在 150 词以内并优先安全相关信息。当输出需要匹配特定消费方时修改它例如下游是语音接口、需要快速响应时可要求只输出简短导航信息。留空时同样回退到通用prompt运行时设置再到内置提示词。实现上该文本随图片一起发送系统指令仍作为独立模型设置存在。Hazard Priority危险优先级accessibility.prioritizeHazards该控件向系统提示词追加一条安全排序指令对应源码中的映射表取值追加的指令片段适用建议high默认必须优先讲危险若未发现危险明确说明该区域看起来安全导航导向描述推荐保持highmedium在空间上下文中包含所注意到的危险但不强制置顶描述顺序有其他要求时降低low不追加任何指令需要标准描述顺序时使用Spatial Format空间格式accessibility.spatialFormat该控件向系统提示词追加空间语言风格对应源码中的映射表取值追加的指令片段适用建议clock默认使用钟点位置12 点钟 正前方熟悉钟点方位读法的读者relative使用相对方向left、right、ahead、behind不熟悉钟点方位的读者both同时使用钟点与相对方向冗余定向有价值时它可与 Hazard Priority 协同工作危险描述可以沿用所选的空间约定。Schema 参数总表以下为README.md生成的完整参数表字段路径、类型、默认值均以services.json为准FieldTypeDescriptionDefaultaccessibility.prioritizeHazardsstringHazard Priority危险检测的优先程度highaccessibility.promptstringAnalysis Prompt从图像生成无障碍描述的提示词模板Describe this image for a blind person. Include: environment type, hazards with positions, key objects with clock positions, visible text, people, and navigation guidance. Keep under 150 words.accessibility.spatialFormatstringSpatial Format空间位置的描述方式clockaccessibility.systemPromptstringSystem Instructions定义无障碍描述行为与优先级You are an accessibility-focused scene analyzer designed to help blind and visually impaired users understand their surroundings through image descriptions.accessibility_describe.profilestringVision Model选择用于无障碍描述的 Gemini 视觉模型gemini-2.5-flashmodelstringModelGoogle Gemini 视觉模型由 profile 提供modelTotalTokensnumberTokens最大上下文长度由 profile 提供1048576services.json中的accessibility_describe.profile通过enum: [*preconfig.profiles.*.title]动态枚举三个 profile 标题并用conditional字段在切换模型时联动绑定对应的llm.cloud.apikey与四个accessibility.*属性这也是 UI 上模型与参数随 profile 联动切换的实现基础。认证与 API Key 校验节点要求配置所选 profile 的 Google AI API Key在 Google AI Studio 中创建。Chat.__init__中有两层硬性校验if not api_key: raise ValueError(Missing Google AI API key. Get one at https://aistudio.google.com/apikey) if api_key.startswith(sk-): raise ValueError( Invalid API key format. This appears to be an OpenAI key. Please provide a Google AI API key. )缺失 Key直接抛错节点不会启动sk-前缀拒绝防止把 OpenAI 风格的密钥误发给 Gemini会明确提示用户提供 Google AI API Key。此外客户端初始化失败genai.Client(api_key...)抛异常也会被包装成ValueError向上抛出。在管道 UI 中API Key 通过llm.cloud.apikey属性按 profile 配置。请求参数与失败处理机制生成请求参数一次成功的请求使用如下固定参数accessibility_vision.py的chat()方法参数值说明temperature0.3低随机性保证描述稳定可复现max_output_tokens1024单次输出上限配合默认 150 词约束绰绰有余system_instructionself._system_prompt系统指令含 Hazard/Spatial 追加片段重试策略节点在图片流结束后发起一次初始请求加最多三次重试重试条件由_shouldRetry判定错误消息中包含timeout、connection、HTTP500/502/503/504或internal server error之一即视为可重试。重试等待时间分别为1、2、4 秒delay base_delay * (2 ** attempt)指数退避。错误翻译若全部尝试失败抛出AccessibilityVisionError自定义异常类定义于accessibility_vision.py。错误消息按类型翻译为用户可读文本_format_user_error错误特征用户提示unauthorized / invalid api key / authentication / api_key认证失败请检查 Google AI API Keyrate limit / too many requests / 429 / quota超过速率限制请稍后重试invalid input / bad request / 400输入无效请检查图片格式与提示词model not found / unavailable / not supported模型当前不可用请尝试其他模型timeout / timed out请求超时请重试content policy / safety / blocked图片被安全过滤器拦截请更换图片其他保留原始 Google AI 错误信息前缀Google AI error:请求前的本地校验在发起模型请求之前代码先解析 Data URL 并解码字节image_data.split(,, 1)提取 MIME 类型与 base64 数据base64.b64decode还原字节。缺失图片question.context为空或找不到data:image//data:application/前缀项或Data URL 格式损坏MIME 头缺失、base64 非法都会在请求前抛出ValueError避免无意义地消耗模型调用。注意解析与内容构建被刻意放在重试循环之外——它们是确定性的无需每次重试重建。依赖与运行时节点的唯一 Python 依赖在 requirements.txt 中google-genai1.14.0该依赖由depends(requirements)机制在IGlobal.beginGlobal与accessibility_vision.py模块加载时按需安装/校验。节点运行时由IGlobal单例持有Chat实例实例层IInstance继承自ai.common.llm_base.LLMBase二者通过init.py 导出含getChat()工厂函数遵循 RocketRide 节点标准的 Global/Instance 生命周期模型。内置测试用例services.json的test字段为节点定义了开箱即用的验证用例使用gemini-2.5-flashprofile、输出 lane 为text、超时 30 秒两个用例分别使用仓库testdata/images/下的ocr_test_text.png含文本的场景描述与ocr_test_mixed.png混合内容场景描述断言均为text.notEmpty true即保证带文本图片与混合内容图片都能产出非空的无障碍描述。典型使用场景与最佳实践实时辅助技术services.json的描述中明确提到智能眼镜等实时辅助应用场景——结构化输出危险、空间、文本、人员、导航便于语音合成直接播报。导航导向的管道保持 Hazard Priority 为high、Spatial Format 为clock让播报先讲危险再给方向。快速响应的语音接口把 Analysis Prompt 改为仅输出简短导航信息缩短生成内容与播报延迟。站点特定安全策略在 System Instructions 中追加组织级安全规则如本区域施工统一提示佩戴安全帽让其对每一帧图片生效。成本与质量平衡默认 Flash profile 适合高频场景对细节要求高的场景如复杂文档、密集文字可切到 Gemini 2.5 Pro追求平衡可选 Gemini 2.0 Flash。参考实现路径节点主逻辑accessibility_vision.py图片流处理与实例生命周期IInstance.py单例管理与依赖安装IGlobal.py节点注册与全部配置字段services.json公共聊天基类token 管理、配置加载chat.py赞分享【免费下载链接】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_gemini 节点在 AI Pipeline 中接入 Google Gemini 模型RocketRide 的 llm_gemini 节点在 AI Pipeline 中接入 Google Gemini 模型 RocketRide 是一个以 COpenUSD UsdUI 指南用 Schema 描述节点图、无障碍信息与 UI 呈现提示OpenUSD UsdUI 指南用 Schema 描述节点图、无障碍信息与 UI 呈现提示 UsdUI 是 OpenUSDUniversal Scene D图形学3D渲染RocketRide caption 节点完全指南用 Florence-2 为图像生成自然语言描述RocketRide caption 节点完全指南用 Florence 2 为图像生成自然语言描述 本篇技术指南聚焦 RocketRide 开源仓库中的 ca上一篇深度解析OpenSPG构建企业级智能知识图谱的完整方案下一篇终极指南Livox SDK激光雷达开发实战 - 从环境感知到智能决策的完整解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考