API返回DataFrame字典时触发ValueError：浮点数超出JSON兼容范围

核心原因 #

JSON规范不支持NaN、inf、-inf这类特殊浮点数类型，但Pandas计算均值时可能生成这些值：

• 当指定填充的列全为缺失值时，df[col].mean()会返回NaN
• 若列中存在极端数值（如超大数除以0），计算出的均值可能为inf/-inf

在Colab中直接输出字典时，Python会默认显示这些特殊值，但FastAPI返回响应时会尝试将字典序列化为JSON，此时就会触发ValueError。错误溯源到result[operation] = [{i:result7}]，说明result7正是这类JSON不兼容的特殊浮点数。

解决方法 #

1. 局部处理特殊值（推荐，更灵活） #

在赋值前检查并替换result7中的特殊值，替换为JSON兼容的内容（如None或业务允许的默认值）：

import pandas as pd
import numpy as np

# 假设你的计算逻辑之后得到了result7
# 处理特殊浮点数
if pd.isna(result7) or not np.isfinite(result7):
    processed_value = None  # 或根据业务需求换成0、"N/A"等
else:
    processed_value = result7

# 再赋值到结果字典中
result[operation] = [{i: processed_value}]

2. 全局配置FastAPI的JSON编码器 #

如果多个接口都存在类似问题，可以自定义JSON编码器，全局处理Pandas的特殊数值：

from fastapi import FastAPI
from fastapi.encoders import jsonable_encoder
from starlette.responses import JSONResponse
import pandas as pd
import numpy as np

def custom_encoder(obj):
    if isinstance(obj, float):
        # 替换NaN、inf、-inf为None
        if pd.isna(obj) or not np.isfinite(obj):
            return None
    # 其他类型沿用默认编码逻辑
    return jsonable_encoder(obj)

app = FastAPI()

@app.get("/fill-missing")
def fill_missing_values():
    # 你的业务逻辑：加载数据、计算均值填充、生成result字典
    # ...
    return JSONResponse(content=custom_encoder(result))

验证步骤 #

1. 在FastAPI接口中添加打印语句，输出result7的具体值，确认是否为NaN/inf
2. 在Colab中模拟目标列全缺失的测试场景，生成结果字典后尝试用json.dumps()序列化：

   import json
   # 假设result是你的输出字典
   json.dumps(result)
   

   若触发同样的ValueError，则可100%确认是特殊浮点数导致的序列化问题。

内容的提问来源于stack exchange，提问作者Apoorva