FastAPI跨版本Pydantic Tuple字段OpenAPI验证报错解决问询

问题原因 #

FastAPI 0.65.2之后的版本更新了OpenAPI Schema自动生成逻辑，对List[List[Tuple[str, float]]]这种三层嵌套的泛型Tuple类型无法自动生成合法的Schema定义，导致访问Swagger文档时触发OpenAPI结构验证失败。

兼容所有版本的解决方案 #

方案1：保留原有请求结构，手动指定字段Schema #

该方案完全不需要修改上游请求格式和业务逻辑，仅需要给嵌套字段补充Schema定义即可：

from pydantic import BaseModel, Field
from typing import List, Tuple

class ReRankerPayload(BaseModel):
    batch_id: str
    queries: List[str]
    num_items_to_return: int
    # 手动指定该字段的OpenAPI Schema，避免框架自动生成失败
    passage_id_and_score_matrix: List[List[Tuple[str, float]]] = Field(
        ...,
        example=[
            [["16278720_0", 0.8], ["169339_0", 0.6]],
            [["19258753_14", 0.6], ["3270043_12", 0.4]]
        ],
        schema_extra={
            "items": {
                "items": {
                    "type": "array",
                    "items": [
                        {"type": "string"},
                        {"type": "number"}
                    ],
                    "minItems": 2,
                    "maxItems": 2
                }
            }
        }
    )

方案2：使用子模型规范结构（更推荐，长期维护性更好） #

如果可以调整上游请求结构，改用Pydantic子模型定义最内层的数据结构，完全避免嵌套Tuple的兼容问题：

1. 模型定义修改：

from pydantic import BaseModel
from typing import List

# 新增子模型定义
class PassageScoreItem(BaseModel):
    passage_id: str
    score: float

class ReRankerPayload(BaseModel):
    batch_id: str
    queries: List[str]
    num_items_to_return: int
    passage_id_and_score_matrix: List[List[PassageScoreItem]]

2. 对应请求载荷的passage_id_and_score_matrix部分调整为对象格式即可：

[
    [
        {"passage_id": "16278720_0", "score": 0.8},
        {"passage_id": "169339_0", "score": 0.6}
    ],
    [
        {"passage_id": "19258753_14", "score": 0.6},
        {"passage_id": "3270043_12", "score": 0.4}
    ]
]

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