FastAPI返回Pandas DataFrame时遇Pydantic验证错误的求助

错误原因 #

你遇到的ValidationError核心是类型不匹配：df.to_dict(orient="records")返回的是列表（List）（每个元素对应一行数据的字典），但你的Response模型里把df定义成了Dict类型，Pydantic无法通过类型校验。

可行解决方案 #

方案1：修正Response模型的类型（推荐） #

直接把df的类型改成List[Dict]，完全匹配to_dict(orient="records")的返回结构：

from typing import List, Dict
from pydantic import BaseModel

class Response(BaseModel):
    df: List[Dict]
    date: str

修改后原返回代码无需调整，前端拿到的是结构化JSON数组，处理起来直接且高效。

方案2：调整DataFrame转字典的参数 #

如果业务需要返回字典结构的df，可以修改orient参数，比如用orient="dict"（返回{列名: {索引: 值}}）或orient="index"（返回{索引: {列名: 值}}），此时模型里的Dict类型就能匹配：

return Response(
    df=df.to_dict(orient="dict"),
    date=f"{df.index.mean():%Y-%m-%d}",
)

注意：这种方式返回的数据结构和records模式不同，需要确认前端是否适配。

方案3：绕开Pydantic模型直接返回JSON #

如果不需要Pydantic的校验逻辑，可以用jsonable_encoder和JSONResponse直接构造响应：

from fastapi.encoders import jsonable_encoder
from fastapi.responses import JSONResponse

# 业务函数内
data = {
    "df": df.to_dict(orient="records"),
    "date": f"{df.index.mean():%Y-%m-%d}"
}
return JSONResponse(content=jsonable_encoder(data))

总结 #

后端修正Response模型的类型为List[Dict]是最简洁的修复方式，前端拿到结构化数据后无需额外解析字符串，比字符串化的方案高效得多。

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