Agenta项目中JSON差异评估器的零除问题分析与修复

问题背景

在Agenta项目的后端服务中，开发团队实现了一个用于比较JSON数据的差异评估器(auto_json_diff)。该评估器的主要功能是对比预测结果与标准答案之间的JSON结构差异，并计算相似度分数。然而，在实际使用过程中，评估器在某些情况下会抛出"float division by zero"的异常，导致评估过程失败。

问题现象

当评估器处理以下JSON数据时出现了异常：

标准答案(ground truth):

{
  "CCI_edits": ["CCI 1", "CCI 3"],
  "E_M": "99214",
  "HCC": ["HCC19", "HCC59"],
  "ICD_10": ["I10", "E11.9", "Z87.891"],
  "CPT_HCPCS": ["99213", "96372", "85610", "84443"]
}

预测结果(prediction):

{
  "CCI_edits": [],
  "E_M": "99214",
  "HCC": ["HCC3", "HCC19"],
  "ICD_10": ["J45.909", "E11.9", "I10", "Z79.84"],
  "CPT_HCPCS": ["99214", "94640", "99213", "85018"]
}

评估器配置使用了默认参数：

{
    "predict_keys": false,
    "correct_answer_key": "correct_answer",
    "compare_schema_only": false,
    "case_insensitive_keys": false
}

问题分析

通过查看错误堆栈，问题发生在计算平均分数时：

average_score = cumulated_score / no_of_keys

这里出现了零除错误，说明no_of_keys变量在某些情况下可能为零。深入分析评估器逻辑，发现当配置中predict_keys参数为false时，评估器会忽略预测结果中的键，仅使用标准答案中的键进行比较。然而，在某些边缘情况下，标准答案可能为空或评估器未能正确识别有效键，导致键计数为零。

解决方案

修复此问题需要考虑以下几个方面：

1. 输入验证：在计算分数前，应验证输入JSON的有效性，确保至少存在一个有效键。

2. 默认值处理：当键计数为零时，应提供合理的默认值或明确的错误提示，而不是直接进行除法运算。

3. 配置参数检查：确保评估器配置参数能够正确处理各种边界情况。

4. 错误处理机制：实现健壮的错误处理，为开发者提供清晰的错误信息，便于问题定位。

技术实现

修复后的代码应该包含以下改进：

def compare_jsons(ground_truth, prediction, config):
    # 验证输入JSON非空
    if not ground_truth or not isinstance(ground_truth, dict):
        raise ValueError("无效的标准答案JSON")
    
    # 获取要比较的键集合
    if config.get("predict_keys", False):
        keys = set(prediction.keys()) if prediction else set()
    else:
        keys = set(ground_truth.keys())
    
    # 处理无有效键的情况
    if not keys:
        return 0.0  # 或者根据业务需求返回特定值/抛出异常
    
    # 正常比较逻辑
    cumulated_score = 0.0
    for key in keys:
        # 键比较和值比较逻辑
        ...
    
    # 计算平均分数
    return cumulated_score / len(keys)

经验总结

1. 边界条件处理：在开发数据处理组件时，必须充分考虑各种边界条件，特别是当输入数据可能为空或结构异常时。

2. 防御性编程：关键计算步骤前应添加必要的验证逻辑，防止运行时错误。

3. 配置参数影响：评估器的行为高度依赖配置参数，需要仔细考虑每个参数可能带来的影响。

4. 错误信息友好性：当问题发生时，应提供足够的信息帮助用户理解问题原因，而不仅仅是抛出技术性异常。

这个问题提醒我们在开发数据比较工具时，需要全面考虑各种可能的输入情况，并实现相应的保护机制，确保系统的健壮性。