TypeError: Image.__init__() got an unexpected keyword argument ‘alt_text’

问题场景

用户在使用 Gradio 构建应用时，将 gr.Image 作为输出组件展示模型生成的图片。通过查询页面上的 <img> 标签发现，Gradio 自身的四个装饰性图标（Logo、停止录制、设置等）均有正确的 alt 文本，而用户实际生成的输出图片的 alt 属性为空字符串，屏幕阅读器会完全跳过该图片。尝试在 Python 中通过 gr.Image(alt_text="...") 设置替代文本时，直接抛出 TypeError 异常。

报错原文

TypeError: Image.__init__() got an unexpected keyword argument 'alt_text'

原因分析

问题的根源在于 Gradio 的输出渲染链路缺少对 alt 文本的支持。具体来说：

1. 前端硬编码：js/image/shared/ImagePreview.svelte 中硬编码了 alt: ""，且没有读取任何来自后端的替代文本字段。Gradio 自身的图标都带有合适的 alt 文本，但用户的输出图片被硬编码为空字符串，被辅助技术视为“装饰性图片”而跳过。

2. 数据模型缺失：ImageData 数据模型中没有定义承载 alt_text 的字段，即使前端尝试读取也无法获取。虽然 TypeScript 的 FileData 类型已经声明了 alt_text?: string，但 Python 端从未填充该字段。

3. Python API 不完善：Image.__init__() 方法不接受 alt_text 参数，导致用户无法从 Python 侧设置替代文本。

可能原因：这不是使用错误，而是 Gradio 6.22.0 版本的功能缺失。gr.Gallery 和 gr.Chatbot 都已支持替代文本（前者从单条说明派生，后者端到端传递 alt_text），唯独 gr.Image 被遗漏。

环境排查

• Gradio 版本：确认是否为 6.22.0（Issue 中已验证的版本，且在该版本中 gr.Image(alt_text="...") 会抛出 TypeError）。
• Python：确认 gr.Image 调用时是否传入 alt_text 参数（传入后应触发报错）。
• 数据模型：检查 ImageData.model_fields 是否只包含 ['path', 'url', 'size', 'orig_name', 'mime_type', 'is_stream', 'meta']（Issue 中已确认，没有 alt_text 字段）。

解决步骤

以下步骤基于 Issue 评论中提出的实现细节整理，为可优先尝试的修复方向：

1. 在 Python 数据类中增加字段：在 gradio/data_classes.py 的 ImageData 类中添加 alt_text: str | None = Field(default=None, description="Alt text describing the image")。
2. 增加组件参数：在 gradio/components/image.py 的 Image.__init__ 中添加关键字参数 alt_text: str | None = None，并将其赋值给 self.alt_text。
3. 传递参数到后处理函数：在 gradio/image_utils.py 中为 postprocess_image 函数签名添加 alt_text: str | None = None，并在两个 ImageData(...) 构造点（SVG 分支和普通分支）都传入该字段。
4. 更新组件调用：在 gradio/components/image.py 调用 postprocess_image(...) 时传入 alt_text=self.alt_text。
5. 修改前端渲染：将 js/image/shared/ImagePreview.svelte 中的硬编码 alt: "" 改为 alt: value.alt_text ?? ""。
6. 如为 base64 流式传输：注意 Base64ImageData 只包含 url 字段，streaming="base64" 路径可能需要单独处理或暂时排除在修复范围外。

验证方法

完成代码修改后，可通过以下方式确认问题已解决：

1. 在 Python 中调用 gr.Image(alt_text="a photo of a cat") 不再抛出 TypeError。

2. 在应用中输出图片后，在浏览器开发者工具中查询 <img> 标签，确认生成的图片 alt 属性值即设置的 alt_text 文本。

3. 使用屏幕阅读器（如 NVDA、VoiceOver）访问页面，确认输出图片能够被朗读出替代文本，而不再被跳过。

参考来源

gradio-app/gradio #13731

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。