SAGE 工具文档: `ImageCaptioner`¶

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

1. 功能概述¶

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

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

2. 参数详解¶

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

输入参数¶

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

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

输出格式¶

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

3. 使用示例¶

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

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

```python title="基础用法示例"
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. 内部实现逻辑¶

???+ info "执行流程详解 (点击展开)" ImageCaptioner 的 execute 方法遵循以下步骤来完成任务：

1.  **模型检查**:
    * 首先检查 `self.model_name` 是否已设置。如果未设置，则抛出 `ValueError` 异常，提示用户必须先设置模型名称。

2.  **构造请求**:
    * 创建一个符合 OpenAI 格式的消息列表 `messages`。其中包含一个 `system` 角色的消息，用于设定助手的身份，以及一个 `user` 角色的消息，内容为“为位于路径 {image_path} 的图片生成标题”。

3.  **初始化客户端**:
    * 使用当前工具设置的 `model_name` 和一个固定的 `seed` (42) 来初始化 `OpenAIClient`。

4.  **带重试机制的调用**:
    * 进入一个最多 **5** 次的重试循环。
    * 在循环中，调用 `client.generate()` 方法并传入 `messages`。
    * 如果调用成功，立即返回获取到的 `response`。
    * 如果捕获到 `ConnectionError`（连接错误），则打印错误信息，并等待 **3** 秒后再次尝试。
    * 如果重试 5 次后仍然失败，则将最后一次的异常向上抛出。

5.  **通用异常处理**:
    * 整个过程被包裹在一个 `try...except` 块中。如果发生除连接错误外的任何其他异常，将打印错误信息并返回 `None`。

5. 依赖项与要求¶

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

6. 限制与注意事项¶

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

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

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

SAGE 工具文档: ImageCaptioner¶