[Bug] 群聊上下文图片理解对 GIF 动图未进行多帧处理，导致仅能获得静态帧描述

[fanfan8899333-bit]

问题描述

在启用「群聊上下文感知 -> 自动理解图片（image_caption）」后，如果群成员发送 GIF 动图/QQ 动画表情，AstrBot 的图片转述功能不会对 GIF 进行抽帧或多帧处理，而是将整个 GIF 作为单个 image 输入直接交给配置的视觉模型。

部分视觉模型/API 虽然能够接收 image/gif，但实际只会按照其中某一静态画面进行描述，因此最终写入 group_chat_context 的内容只有静态图片信息，无法理解 GIF 中的动作、表情变化和前后过程。

经确认，该问题并不是 QQ 协议端将 GIF 转为了 JPEG。

以本次测试的 QQ 动画表情为例，SnowLuma 协议层获得：

fileId: "3ED4FA690934062E8BE1DA2AF9575B9E.jpg"
fileSize: 783068
width: 240
height: 240
picFormat: 2000
subType: 1
summary: "[动画表情]"

其中 picFormat=2000 明确表示真实图片格式为 GIF。虽然 QQ 的 fileId 后缀为 .jpg，但实际媒体格式仍为 GIF。

AstrBot 收到的 OneBot 消息段为：

file: "3ED4FA690934062E8BE1DA2AF9575B9E.jpg"
sub_type: 1
summary: "[动画表情]"
url: "https://multimedia.nt.qq.com.cn/download?..."

AstrBot 的 group_chat_context 会优先使用 comp.url，并调用图片描述 Provider，但当前 get_image_caption() 仅传入：

image_urls=[image_url]

没有对 GIF 的 n_frames 进行检测，也没有进行抽帧后以多张图片传递给视觉模型。

因此当前实际流程为：

QQ GIF
→ AstrBot group_chat_context
→ 单个 GIF image
→ 图片转述模型
→ 获得静态画面描述
→ [Image: 静态描述]
→ 写入群聊上下文

实际测试 MiniMax-M3 时，GIF 最终只被描述成角色的头发、眼睛、兽耳等静态特征，没有描述 GIF 中的动作变化。

希望 AstrBot 内置的群聊图片转述功能能够对 GIF/APNG/Animated WebP 等动画图片进行多帧处理，而不是完全依赖 Provider 是否原生支持动画图片。

可能的改进方案

建议在 group_chat_context.get_image_caption() 调用 Provider 前增加动画图片预处理：

1. 获取图片到本地后，根据实际 MIME / Pillow 判断是否为动画图片，而不是根据文件后缀判断；
2. 如果检测到 GIF 且 n_frames > 1：
   • 均匀抽取 4~6 个代表帧；
   • 将帧转换为 JPEG/PNG；
   • 通过 image_urls=[frame1, frame2, ...] 一次性传递给图片转述 Provider；
3. 在 image_caption_prompt 中附加提示，例如：
   “以下多张图片按照时间顺序来自同一个 GIF 动图，请综合各帧描述动作和表情变化。”
4. 静态 JPEG/PNG 保持当前行为不变。

目前已有第三方 GIF Vision Helper 插件采用类似方案，可以证明这种处理方式能够兼容不原生支持 GIF 时序理解的多模态 Provider。

如何复现？

1. 使用 OneBot v11 接入 QQ。
2. 开启 AstrBot 的「群聊上下文感知」。
3. 开启「自动理解图片」，并配置一个支持图片输入的视觉模型作为图片转述模型。
4. 禁用所有第三方插件，避免插件影响测试。
5. 在 QQ 群中发送一个动作变化明显的 GIF 动图，例如：
   • 第一阶段人物闭眼
   • 中间人物睁眼
   • 最后人物挥手
6. 查看 AstrBot Debug 日志中的 group_chat_context 图片转述结果。
7. 可以发现模型只描述其中的静态画面，没有获得 GIF 多帧中的动作变化。
8. 对照协议端 Debug 日志，可以确认收到的原始图片实际为 GIF（picFormat=2000），并非 JPEG。

AstrBot 版本

v4.27.4

操作系统

Linux

部署方式

Docker

使用的消息平台适配器

OneBot v11（aiocqhttp，SnowLuma）

错误日志

SnowLuma：

event_input ... elements:[{
    type:"image",
    fileId:"3ED4FA690934062E8BE1DA2AF9575B9E.jpg",
    fileSize:783068,
    width:240,
    height:240,
    picFormat:2000,
    subType:1,
    summary:"[动画表情]"
}]

OneBot 转换后：

message:[{
    type:"image",
    data:{
        url:"https://multimedia.nt.qq.com.cn/download?...",
        file:"3ED4FA690934062E8BE1DA2AF9575B9E.jpg",
        sub_type:1,
        summary:"[动画表情]"
    }
}]

AstrBot：

[sources.anthropic_source] model='MiniMax-M3'

模型返回静态描述：
“这是一个动漫风格的可爱角色……
头发：青绿色长发……
眼睛：紫红色眼睛……
耳朵：一对尖尖的兽耳……
头上趴着一只小小的黑色猫咪……”

随后：

[astrbot.group_chat_context]
[Image: 这是一个动漫风格的可爱角色……]

辅助信息

No response

检查清单

• 我已在 Issue 列表中搜索过相关问题仍无法解决，或该问题从未被报告过。
• 我已尝试过禁用所有插件，排除了可能是因插件导致的问题。
• 我报告的问题与 AstrBot 本体相关，而非在报告某一插件的问题。
• 我已阅读并同意本项目的贡献者行为准则。
• (可选)我愿意提交 PR 以帮助修复该问题。

[dosubot]

Hi @fanfan8899333-bit! I'm Dosu and I'm helping the AstrBotTeam team.

我确认了你描述的行为，代码层面可以印证：

get_image_caption() 目前的实现

GroupChatContext.get_image_caption() 只是把单个 image_url 原样传给视觉 Provider（通过 image_urls=[image_url]），没有做任何抽帧/多帧处理 [1]。上游 _format_message() 遇到 Image 组件时也只是把 comp.url 或 comp.file 直接交给 get_image_caption() [2]，完全没有区分 GIF/静态图。一个动画 GIF 在这里就是被当成"一张图"发给模型，是否能得到动作变化描述完全取决于 Provider 本身对 GIF 时序的支持——这与你的分析一致。

相关的历史修复

此前另一位用户报告过更上游的问题：v4.26 引入的 ensure_jpeg() 曾把所有非 JPEG 图片（包括 GIF）无差别转码为单帧 JPEG，导致动画信息在管道最前端就被永久破坏 [3]。这个问题已在提交 c6b2c65b 中修复：ensure_jpeg() 现在会检测 is_animated/n_frames > 1，动图跳过转码、保留原始格式 [4]。也就是说 GIF 原始数据目前不会在管道前端丢失，但 get_image_caption 这一层仍然没有针对动图做抽帧。

正在推进的相关 PR

值得关注的是，目前有一个 open 状态的 PR #9703 正在为 Provider 层引入动画图片处理策略（first_frame / multi_frame），包括均匀抽帧、最大帧数配置（1–16）、以及格式适配和本地转换缓存 [5]。不过该 PR 的改动目标是 外发图片的 Provider 上下文组装（assemble_context() 层），而不是群聊上下文中 get_image_caption 的图片转述流程。如果该 PR 合并，其中新增的 resolve_image_ref_to_images() 工具函数和抽帧逻辑理论上可以被 get_image_caption 复用来实现你提出的方案。

总结来看，你反馈的 get_image_caption 缺乏动图多帧处理确实是一个独立的功能缺口，目前代码中不存在相关处理。

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[piexian]

#9703 合并后把转述提供商的动图策略设为多帧抽取即可获得多帧转述。剩余两点（转述场景默认值/时序提示）作为后续小 PR 单独提，复用这个 PR 的 resolve_image_ref_to_images() 即可，改动量很小。前提是合的话.......