跳转至

DescribeImage 视觉多模态大模型图像理解与结构化反推节点

节点核心功能 (What is it?)

DescribeImage 节点通过调用具备视觉多模态（Vision）感知能力的顶级大模型，对输入的静态图像进行深度解析并生成自然语言描述或结构化 JSON 数据。它既可以作为图像转文字、视觉问答（VQA）的感知终端，也可通过精准的定向指令作为扩散模型反向提示词（Reverse Prompt Engineering）的推导引擎。

典型适用场景 (When would I use it?)

在以下情况下使用该节点：

  • 生成图像的深度自然语言文本描述或无障碍替代文本（Alt Text）；
  • 从照片、设计图、架构图或图表中抽取关键事实与文字信息；
  • 自动化反推参考图的布光、色调、艺术风格与微观主体特征；
  • 将视觉资产转化为结构化 JSON 数据供下游业务系统存储与检索；
  • 为自主智能体（Agent）赋予“视觉眼睛”以辅助做出行动决策。

使用指南 (How to use it)

基础配置流程 (Basic Setup)

  1. 在画布中添加 DescribeImage 节点。
  2. 将待理解的图像资产接入 image 输入插槽。
  3. 在 prompt 字段中根据期望的分析侧重给出具体的分析指令（默认 "Describe the image"）。
  4. 运行节点即可在 output 获得详细分析文本。

精准指令的重要性 (Be Specific About What You Want)

在编写 prompt 提示词时，明确具体关注的元素能让模型给出极高品质的反馈：

  • 色彩与光影：尝试 "Describe the color palette, the color of light and shadow, the saturation and value"（详细描述其配色方案、明暗光影色彩、饱和度与明度）；
  • 角色与构图：尝试 "Describe the character's gender, age, clothing, posture, demeanor, and actions"（详细描述人物的性别、年龄、服装材质、站姿体态与动作）。

指令越精准具体，模型产出的输出质量就越契合预期。

参数输入插槽 (Parameters)

  • image（必需）：待分析理解的目标图像工件（接受 ImageArtifact 或 ImageUrlArtifact）。
  • prompt（字符串，默认 "Describe the image"）：指导模型如何观察与描述画面的自然语言指令。
  • agent（可选）：传入已有的专属 Agent 配置实例；若接入，则覆盖当前模型的独立配置。
  • model：选择所调用的多模态模型（支持直选或接入 Prompt Model Config 配置引脚）。
  • description_only（布尔值）：若开启，则只纯粹返回图像描述文本，剥离一切多余的对话包装客套词。
  • output_schema（可选）：用于强约束输出格式的 JSON Schema。接受 JSON Schema 对象或合法 JSON 字符串。一旦连入，输出引脚自动切换为结构化 JSON 模式。

输出引脚 (Outputs)

  • output：生成的图像分析结果。默认输出纯文本 text，当配置了 output_schema 时输出严格校验通过的 JSON 数据。
  • agent：在本次图像理解任务中实例化的智能体对象，可继续传递给下游节点复用上下文。

典型工作流示例 (Example)

自然语言风景反推

  1. 添加 DescribeImage 节点至画布。
  2. 将生图节点或外部导入图像接入 image 参数。
  3. 在 prompt 字段填入："Describe this landscape in detail, including colors, features, and mood"。
  4. 运行节点，在 output 即可提取该风景画面的光影与意境描述，直接供给其他生图节点作为 Prompt。

结构化数据提取 (JSON 契约约束)

若需要模型严格按照固定 JSON 模板输出：

  1. 添加 CreateAgentSchema 节点，输入样例 JSON 结构（例如包含 {"style": "", "palette": [], "main_subject": ""}）。
  2. 将 CreateAgentSchema.schema 引脚连接至 DescribeImage.output_schema。
  3. 运行 DescribeImage 节点。
  4. 节点的 output 将输出 100% 契合该 Schema 规范的结构化 JSON 数据（若校验失败引擎会自动抛出重试拦截）。

关键技术特性 (Important Notes)

  • 云端鉴权凭证：默认使用 Griptape Cloud 网关时，需确保环境变量中存在有效的 GT_CLOUD_API_KEY。
  • 默认模型选型：在未接入外部驱动时，节点默认采用能力极强的通用多模态模型（如 gpt-5.2 等）进行高精语义识别。
  • 缺失防御：若上游未提供图像，节点将优雅输出 "No image provided" 而杜绝引发系统崩溃。

常见问题与排查 (Common Issues)

  • API 报错或鉴权失败：确认环境变量中的 GT_CLOUD_API_KEY 是否有效。
  • 描述内容泛化空洞：在 prompt 中增加限定词（如“逐项罗列”、“指出三处细节矛盾”等），避免使用空泛的默认指令。