运行Detectron2示例balloon.py出现'regions' KeyError报错是什么原因？

核心原因分析 #

你已经排除了JSON本身结构完全异常的问题，这类KeyError: 'regions'报错几乎都来源于标注格式和代码读取逻辑的隐形不匹配，常见触发场景如下：

• VIA导出设置不匹配：
  即使你用VIA 2.0.0生成标注，如果导出时选择的是「完整项目文件」而非「仅标注（Annotations only）」，JSON外层会多一层项目元数据包裹，你实际遍历的对象是项目配置而非标注条目，自然取不到regions键。
  如果使用VIA 3生成标注，其默认导出的JSON标注默认存放在_via_img_metadata二级字段下，原balloon示例代码默认直接遍历JSON根目录的键，没有做字段适配就会触发报错。
• 键名大小写/拼写不匹配：JSON的键名是大小写敏感的，如果你标注文件里的键是Regions、region等拼写，和代码里的regions不匹配也会触发报错，这类细节在对比结构时很容易被忽略。
• 代码遍历逻辑错误：原balloon示例的标注加载逻辑默认直接取JSON值列表遍历，如果你修改代码时误将values()改为keys()，或者索引层级错误，也会出现取键失败的问题。
• 编码异常导致的解析错误：如果你的标注文件名、标注内容包含特殊字符或中文，JSON加载时可能出现异常解析，原本的字典结构被解析为字符串类型，自然无法通过键名取值。

快速修复步骤 #

1. 首先加校验代码确认解析结果，在JSON加载代码后插入如下片段，确认遍历对象的结构符合预期：

import json
import os

annotations = json.load(open(os.path.join(dataset_dir, "via_region_data.json")))
# 打印首个元素的类型和所有键名，确认是否存在regions键
print(type(annotations), list(annotations.keys())[:5])
if isinstance(annotations, dict):
    first_val = list(annotations.values())[0]
    print(type(first_val), first_val.keys())

2. 适配VIA版本：如果使用VIA 3导出的标注，在加载JSON后新增一行提取标注字段即可：

annotations = json.load(open(json_path))
# 新增VIA3格式适配代码
annotations = annotations["_via_img_metadata"]
# 后续保持原代码逻辑不变
annotations = list(annotations.values())
annotations = [a for a in annotations if a.get("regions")]

3. 替换原代码里的直接取键逻辑为get()方法，避免无标注的图片条目触发报错：将a['regions']替换为a.get("regions", [])，空标注的条目会被自动过滤。

内容的提问来源于stack exchange，提问作者Allie W.