报错原文classMyNode(BaseModel):parent:Self|Nonechild:Self|Noneawaitclient.aio.models.generate_content(modelgemini-2.0-flash,contents...,config{response_mime_type:application/json,response_schema:MyNode},)# RecursionError: maximum recursion depth exceededGitHub 真实案例googleapis/python-genai#460 —— Google 官方 GenAI Python SDKGoogle 旗下的 Gemini API 客户端库73 个 和 15 条评论。用户用一个自引用的 Pydantic 模型Self类型引用自身调用 Gemini 的结构化输出 APISDK 在将模型转为 JSON Schema 的过程中掉进了无限递归。具体链路用户定义了一个带Self类型的 Pydantic 模型MyNodeparent: Self | None; child: Self | None将MyNode作为response_schema传给generate_content()SDK 内部调用 Pydantic 的model_json_schema()生成 JSON Schema因为MyNode引用了自身model_json_schema()递归地处理类型的$defs——每次递归都产生一个新的 self-reference永远不会到达叶子节点Python 调用栈在默认 1000 层的递归限制处触发了RecursionError最讽刺的是SDK 代码里没有任何显式的循环引用检查——它假设传入的 Pydantic 模型一定是 DAG有向无环图但Self类型天然就是不满足这个假设的。这不是用户的代码写错了而是 SDK 的 schema 生成器在面对自引用类型时没有一个「终止条件」。根因CPython 的递归限制——不只是个数字sys.setrecursionlimit(1000)是什么意思很多人以为这只是一个「计数器限制」。不对——它背后有三层保护机制全部写在 CPython 的 C 代码里。第一层Python 调用深度计数器ceval.c每次 Python 函数调用CPython 的解释器主循环_PyEval_EvalFrameDefault在执行CALL字节码之前都会调用_Py_EnterRecursiveCall()。这个函数做的事非常简单// Python/ceval.c —— CPython 源码简化表示int_Py_EnterRecursiveCall(constchar*where){PyThreadState*tstate_PyThreadState_GET();if(tstate-py_recursion_remaining0){_PyErr_Format(tstate,PyExc_RecursionError,maximum recursion depth exceeded %s,where);return-1;// ← 返回错误码解释器在 eval frame 里检查到 -1 后抛异常}tstate-py_recursion_remaining--;// ← 每层调用减去 1return0;}关键事实 -py_recursion_remaining是一个线程局部变量PyThreadState的字段初始值 recursion_limit- 每次 Python 函数调用减 1函数返回RETURN_VALUE字节码时调用Py_LeaveRecursiveCall()加回来 - 当计数器降到 0 时不是「触发一个异常」而是在C 层面检查返回值并拒绝执行新的CALL第二层「最后机会」保护limit 50 → Fatal ErrorCPython 在触发RecursionError后会设置tstate-overflowed标志。此时正常的递归限制被临时关闭——这是为了让你的except RecursionError:中的清理代码能正常运行清理代码本身也可能有递归调用。但如果清理代码本身也进入了无限递归递归深度超过limit 50时CPython 会直接Py_FatalError终止进程。这不是 Python 异常而是 C 层面的 abort。// ceval.h 注释原文// * last chance anti-recursion protection is triggered when the recursion// level exceeds current recursion limit 50. By construction, this// protection can only be triggered when the overflowed flag is set. It// means the cleanup code has itself gone into an infinite loop, or the// RecursionError has been mistakenly ignored. When this protection is// triggered, the interpreter aborts with a Fatal Error.第三层C 栈溢出保护Python 3.12这是最容易被人忽略的一层。CPython 的 Python 调用栈和 C 调用栈在实现上是耦合的——每个 Python 函数调用都会在 C 层面新增一个_PyEval_EvalFrameDefault的递归调用。所以把recursion_limit设成 100000 并不能给你 100000 层的 Python 递归——你的 C 栈先爆了。从 Python 3.12 开始CPython 增加了_Py_ReachedRecursionLimitWithMargin检查在每次函数调用前比较当前 C 栈指针和c_stack_soft_limit。如果 C 栈快到上限操作系统分配的栈空间直接抛RecursionError——即使你的 Python 递归计数器还有余额。你的 setrecursionlimit(100000) ↓ CPython 说C 栈还剩 2KB我已经不能再给你一层调用了 ↓ RecursionError和你设多少没关系关键结论RecursionError不是「你递归太深了」而是 CPython 在执行 CALL 字节码之前发现三个条件之一不满足 1. Python 调用深度计数器 ≤ 0 2. 已经触发过 RecursionError 且清理代码仍然在递归50 3. C 栈接近物理上限回到python-genai#460SDK 的process_schema()里没有对Self类型的终止检查导致每处理一次Self就递归调用一次process_schema()直到遍历了 1000 层引用链。这不是算法错误——是schema 生成器缺少「已访问类型集合」的跟踪。任何一个递归图遍历问题都需要一个 visited setSDK 没提供。五种生产级触发场景场景 1Schema 生成器对自引用类型无限递归本次案例的完整模式这是最高频的生产RecursionError来源——不是你的业务代码而是你用的库在处理你的数据模型时触发了递归。# 你的业务代码看起来完全无辜frompydanticimportBaseModelclassCategory(BaseModel):name:strparent:Category | NoneNone# 自引用类型classProduct(BaseModel):categories:list[Category]# 一切正常——直到某个库尝试生成 JSON Schema# ✨ 第三方库内部# def generate_schema(model):# for field_name, field_info in model.model_fields.items():# field_type field_info.annotation# if is_model(field_type):# generate_schema(field_type) # ← 对 Categoryfield_type 还是 Category# # ← 无限递归没有 visited set这种场景的特点你的代码本身没有def f(): return f()这样的显式递归错误发生在你无法控制的库代码内部。orm_mode、json_encoders、schema()、FastAPI 的response_model——所有这些基于类型反射的机制都是潜在的触发点。修复方向# 正确做法库应该维护一个已处理类型的集合defgenerate_schema(model,_visitedNone):if_visitedisNone:_visitedset()ifid(model)in_visited:# ← 关键终止条件return{$ref:f#/$defs/{model.__name__}}_visited.add(id(model))# ... 正常处理字段 ...场景 2__repr__/__str__的循环引用死锁这是最隐蔽的递归场景因为没有显式的递归调用classNode:def__init__(self,parentNone):self.parentparentdef__repr__(self):returnfNode(parent{self.parent})# ← 隐式递归rootNode()childNode(parentroot)print(child)# __repr__ → str(root) → root.__repr__()# RecursionError: maximum recursion depth exceeded while getting the repr of an objectCPython 的角度print(child)触发了child.__repr__()而__repr__里的fNode(parent{self.parent})会让 Python 调用repr(self.parent)→root.__repr__()→ 又去repr(root.parent)也是child→ 无限循环。每次repr()调用在 CPython 层面都是一个CALL字节码递归计数器被消耗。典型触发 - Django 的__str__方法打印关联对象 - SQLAlchemy 的__repr__打印 backref - dataclass 的自动__repr__遇到循环引用修复——处理循环引用def__repr__(self):returnfNode(parent{selfifself.parentisselfelseself.parent})# 或者更通用的方案defsafe_repr(obj,visitedNone):ifvisitedisNone:visitedset()obj_idid(obj)ifobj_idinvisited:returncircularvisited.add(obj_id)# ...场景 3sys.setrecursionlimit调高到 50000 → 生产环境 segmentation faultimportsyssys.setrecursionlimit(50000)defdeep(n):ifn0:return0return1deep(n-1)deep(45000)# 在 Python 3.12 → RecursionErrorC栈检查# 在 Python 3.11 → Segmentation faultC栈炸了OS kill 进程很多人不知道setrecursionlimit不能无脑调大。原因已经在根因分析里解释过了——Python 调用栈和 C 调用栈是耦合的。每层 Python 函数调用在 C 层面大约消耗 1-2KB 的栈空间取决于局部变量和编译器优化。Linux 默认线程栈大小是 8MB8MB/2KBperframe≈4000层实际的物理上限你把recursion_limit设成 50000CPython 的计数器让你跑但 C 栈在第 ~4000 层就撞到了 OS 的保护页→ SEGFAULT。正确做法永远不要在 Python 里靠setrecursionlimit来绕过递归限制。如果算法需要深层递归用迭代改写或用显式栈模拟# 不用递归用显式栈defdeep_iterative(n):stack[n]count0whilestack:ifstack.pop()0:count1else:stack.append(stack[-1]-1ifstackelse0)returncount# 或用尾递归 trampoline 模式deftrampoline(fn,*args):resultfn(*args)whilecallable(result):resultresult()returnresult场景 4asyncio 协程的递归调用——比同步递归更难发现importasyncioasyncdefprocess(item):ifitem.next:awaitprocess(item.next)# ← 协程递归awaititem.handle()# 在 asyncio 里每个 await 一层调用栈# 1000 层的链表 RecursionErrorCPython 的角度await在底层仍然是一个 Python 函数调用——事件循环调用了你的协程的send()方法协程内部的await又调用下一个协程的send()。CPython 看到的仍然是 1000 层嵌套的CALL字节码。更隐蔽的情况asyncdefa():returnawaitb()asyncdefb():returnawaita()# ← 不会报 recursion error因为是 tail-call-like# 但 await c() 后又 await d() 再 await e()...# 1000 层后照样炸修复——用循环替代递归asyncdefprocess(item):currentitemwhilecurrentisnotNone:awaitcurrent.handle()currentcurrent.next场景 5__getattr__/__setattr__的无限递归链classBroken:def__init__(self):self._data{}def__getattr__(self,name):returnself._data[name]# ← _data 不存在时触发 __getattr__ 找 _data# __getattr__ 再 try self._data# 又不存在 → __getattr__ → ... 无限循环objBroken()print(obj.foo)# RecursionError: maximum recursion depth exceeded这是 CPython 的属性查找机制object.__getattribute__→type.__getattr__的 fallback 链导致的。当self._data这个属性本身不存在时Python 会 try__getattr__而__getattr__又引用self._data……在 C 代码层面PyObject_GenericGetAttr(obj,_data)→obj的__dict__里没有_data→检查type(obj).__getattr__→调用我们的__getattr__(_data)→__getattr__里self._data→又调PyObject_GenericGetAttr→无限循环修复在__getattr__里永远通过super().__getattribute__或object.__getattribute__访问实例属性classFixed:def__init__(self):object.__setattr__(self,_data,{})# 绕过 __setattr__def__getattr__(self,name):_dataobject.__getattribute__(self,_data)# 绕过 __getattr__try:return_data[name]exceptKeyError:raiseAttributeError(fno attribute{name})排障流程当你看到RecursionError: maximum recursion depth exceeded按以下顺序排查第一步确认是「显式递归」还是「隐式递归」# 在报错之前插入importtracebacktraceback.print_stack(limit10)# 看最近 10 层调用找到重复出现的函数如果 traceback 里同一个函数反复出现→ 显式递归找到终止条件。如果 traceback 里不同函数交替出现→ 隐式递归__repr__、__getattr__、schema 生成器等。第二步确认递归深度importtracebacktbtraceback.extract_tb(sys.last_traceback)print(f递归深度:{len(tb)}层)# 如果是 1000默认值说明没有正确的终止条件第三步找到「谁在消耗递归栈」python-cimport sys, tracebacksys.settrace(lambda frame, event, arg:print(f{event:6} | {frame.f_code.co_name:30} | {frame.f_code.co_filename}:{frame.f_lineno}))# 然后运行你的代码输出会显示每一次函数调用事件。找到「A 调用 B → B 调用 A → A 调用 B」的模式。第四步验证是不是第三方库的问题# 如果 traceback 最后几层全是 pydantic/pydantic_core/fastapi 的代码# → 不是你的代码在递归是库在处理你的数据时触发了# → 检查你是否传入了自引用类型 / 循环引用的数据第五步不要无脑setrecursionlimitimportsyssys.setrecursionlimit(5000)# ← 你只是推迟了爆炸而且可能把 RecursionError 变成 segfault只在以下情况可以调整 - 你需要处理一个已知深度的数据如 DFS 遍历深度为 3000 的树且你计算过C 栈安全边界 - 处理完立刻调回默认值总结层级理解初级「递归函数要有终止条件或者用sys.setrecursionlimit(50000)调大限制」中级RecursionError不是 Python 抛的异常是 CPython 在ceval.c的_Py_EnterRecursiveCall里检查py_recursion_remaining计数器后拒绝执行下一个CALL字节码。默认 1000 层的限制有三层含义① Python 调用深度计数器② 「最后机会」50 层的 Fatal Error 保护防止 except 块发生二次递归炸进程③ Python 3.12 的 C 栈溢出保护_Py_ReachedRecursionLimitWithMargin让你即使调大 limit 也不会 segmentation fault。生产环境最常见的 RecursionError 根源不是你的代码写了def f(): return f()而是你传给第三方库的数据结构自引用的 Pydantic 模型、循环引用的 ORM 对象、带__repr__的双向关联触发了库内部的无限递归。修复的正确姿势是给递归算法加 visited set或用迭代改写而不是调大限制。记忆锚点RecursionError CPython 在执行 CALL 字节码前发现 Python 调用栈计数器 or C 栈物理空间已经不能安全支持下一层调用了。不是「你的递归写错了」是「某段代码对某个数据结构的遍历没有终止条件」。往回追一层看是谁在遍历你的自引用数据。同类家族RecursionError: maximum recursion depth exceeded while calling a Python object→ Python 函数递归超限RecursionError: maximum recursion depth exceeded in comparison→ 对象比较__eq__/__lt__导致无限递归RecursionError: maximum recursion depth exceeded while getting the repr of an object→__repr__循环引用Fatal Python error: Cannot recover from stack overflow.→ 第二层保护触发limit 50 层的最后防线Segmentation fault (core dumped)→ 你不是在 Python 3.12且把 recursionlimit 调到超过 C 栈物理上限了