SAGE 工具文档: `ImageCaptioner`¶

工具状态: 可用

版本: 1.0.0 描述: 一个能够为本地图片文件生成描述性标题（Caption）的工具。

1. 功能概述¶

ImageCaptioner 工具利用大语言模型（LLM）的视觉理解能力，为用户指定的图片生成一段描述性文字。用户只需提供图片的本地路径，该工具便会调用配置好的 LLM 引擎来分析图片并返回生成的标题。

核心依赖

此工具的运行**强依赖**于一个已配置好的大语言模型（LLM）引擎。请确保在执行前，系统已正确设置并能访问该引擎。

2. 参数详解¶

该工具通过 execute 方法接收参数来执行图片标题生成任务。

输入参数¶

参数名 (Parameter)	类型 (Type)	描述
`image_path`	`str`	必需。需要生成标题的本地图片文件的完整路径。

关于 prompt 参数

尽管工具元数据显示了一个 prompt 输入类型，但当前的 execute 方法实现并未直接使用它。工具内部会使用一个固定的模板向模型发起请求。

输出格式¶

execute 方法返回由底层 OpenAIClient 生成的响应。通常这是一个包含模型生成内容的字典，具体结构取决于 LLM 引擎的返回格式。如果执行失败，则返回 None。

3. 使用示例¶

以下是一些演示如何调用 ImageCaptioner 的示例。

基础用法

为一张本地图片生成标题，使用默认的模型。

基础用法示例

import os
from your_module import ImageCaptioner # 请替换为实际的模块路径

# 1. 初始化工具，指定模型
tool = ImageCaptioner(model_name="meta-llama/Llama-2-13b-chat-hf")

# 2. 定义图片路径并执行
# 假设图片与脚本在同一目录下的 examples/ 文件夹中
image_path = os.path.join(os.path.dirname(__file__), "examples/baseball.png")
caption_response = tool.execute(image_path=image_path)

# 3. 打印结果
if caption_response:
    print("生成的标题:")
    print(caption_response)
else:
    print("标题生成失败。")

4. 内部实现逻辑¶

执行流程详解 (点击展开)

ImageCaptioner 的 execute 方法遵循以下步骤来完成任务：

模型检查:
- 首先检查 self.model_name 是否已设置。如果未设置，则抛出 ValueError 异常，提示用户必须先设置模型名称。
构造请求:
- 创建一个符合 OpenAI 格式的消息列表 messages。其中包含一个 system 角色的消息，用于设定助手的身份，以及一个 user 角色的消息，内容为“为位于路径 {image_path} 的图片生成标题”。
初始化客户端:
- 使用当前工具设置的 model_name 和一个固定的 seed (42) 来初始化 OpenAIClient。
带重试机制的调用:
- 进入一个最多 5 次的重试循环。
- 在循环中，调用 client.generate() 方法并传入 messages。
- 如果调用成功，立即返回获取到的 response。
- 如果捕获到 ConnectionError（连接错误），则打印错误信息，并等待 3 秒后再次尝试。
- 如果重试 5 次后仍然失败，则将最后一次的异常向上抛出。
通用异常处理:
- 整个过程被包裹在一个 try...except 块中。如果发生除连接错误外的任何其他异常，将打印错误信息并返回 None。

5. 依赖项与要求¶

核心要求:
- LLM 引擎: 必须能够访问一个兼容 OpenAI API 的大语言模型服务。
Python 库:
- os: 用于处理文件路径。
- time: 用于在重试之间实现延迟。
内部模块:
- sage.lib.tools.base.base_tool.BaseTool: 工具的基类。
- ..utils.openaiclient.OpenAIClient: 用于与 LLM 引擎交互的客户端。

6. 限制与注意事项¶

重要限制

该工具的性能和准确性完全取决于其所依赖的底层大语言模型。元数据中提供了以下详细限制说明：

ImageCaptioner 提供的是通用的图片描述，但存在以下限制： 1. 在处理复杂场景、计数、属性检测和理解物体关系时可能会出错。 2. 可能无法生成全面的标题，特别是对于包含多个物体或抽象概念的图片。 3. 性能会因图片的复杂度而异。 4. 难以处理具有特定文化或专业领域内容的图片。 5. 可能会忽略细节或误解物体间的关系。

建议：为获得精确描述，请考虑将此工具与其他工具结合使用以进行上下文验证，或将其作为精细化处理的第一步。在处理关键信息时，必要时请使用专业工具或人工进行验证。

SAGE 工具文档: ImageCaptioner¶