Understanding response serialization/deserialization performance in FastAPI with Pydantic 2

[jhamman]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the FastAPI documentation, with the integrated search.
• I already searched in Google "How to X in FastAPI" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to FastAPI but to Pydantic.
• I already checked if it is not related to FastAPI but to Swagger UI.
• I already checked if it is not related to FastAPI but to ReDoc.

Commit to Help

• I commit to help with one of those options 👆

Example Code

from fastapi import FastAPI, Response
from pydantic import BaseModel, TypeAdapter

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str
    number: int

models = [Item(name=f"Foo-{i}", description=f"A very nice Item-{i}", number=i) for i in range(1000)]
ta = TypeAdapter(list[Item])


@app.get("/a", response_model=list[Item])
async def a() -> list[Item]:
    return models

# > hey -z 30s -c 5 http://127.0.0.1:8000/a
# Average: 0.0045 secs (out of 33147 requests)


@app.get("/b")
async def b() -> Response:
    return Response(content=ta.dump_json(models))

# > hey -z 30s -c 5 http://127.0.0.1:8000/b
# Average: 0.0019 secs (out of 33147 requests)

Description

I would like to better understand how to optimize JSON serialization when using FastAPI with Pydantic 2. My particular application is often sending and/or receiving somewhat large JSON objects and we've observed that serializing and deserializing these objects can be a significant bottleneck. We were therefore excited to take advantage of Pydantic 2 improved performance in model validation and JSON serialization. That said, we're not observing the speed ups we expected and so we'd like to understand how to optimize things a bit.

The example above highlights a few things:

• The use of Pydantic 2's TypeAdapter for serializing a collection of BaseModels. In our testing, we've found this to be an important tool for accelerating JSON serialization (details below).
• The added performance when using a custom response relative to the default JSONResponse. This may be expected but I would have assume FastAPI is following a similar code path (albeit longer).

I assume the main reason for the performance gap here is that in route /a, data is flowing BaseModel->Dict->JSON whereas in route /b, Pydantic is able to go straight from BaseModel-JSON.

Questions:

1. Does my diagnosis sound right?
2. Are there established patterns to take advantage Pydantic's improved serialization performance?

---

Details comparing json.dumps to TypeAdapter.dump_json:

%timeit json.dumps([m.dict() for m in models])  # pydantic 1
114 µs ± 184 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)

%timeit json.dumps([m.model_dump() for m in models])  # pydantic 2
28.6 µs ± 37.9 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)

%timeit  ta.dump_json(models)  # pydantic 2 + type adapter
7.14 µs ± 1.25 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)

Operating System

Linux, macOS

Operating System Details

Test above was run on macOS but our production systems are all Linux/Docker

FastAPI Version

0.108.0

Pydantic Version

2.5.3

Python Version

Python 3.11.7

Additional Context

Related issues/docs:

• FastAPI response_model when returning Pydantic models pydantic/pydantic#5921
• FastAPI with Pydantic v2 #9709
• https://fastapi.tiangolo.com/advanced/custom-response/?h=#response
• https://docs.pydantic.dev/latest/api/type_adapter/

[Pierre-Alexandre35]

I have the exact same question.