ValueError: `py_limited_api=’cp39’` not supported. `Py_LIMITED_API` is currently incompatible with `Py_GIL_DISABLED`. See https://github.com/python/cpython/issues/111506.

快速结论：该报错通常出现在使用 free-threaded（NO-GIL）Python 3.14t 构建 xFormers 时。优先排查 Python 解释器是否为 3.14t 版本，并考虑使用 xFormers 0.0.35 或更新的预编译 wheel。

问题场景

用户在构建 xFormers 时，使用了一个 free-threaded（无 GIL）的 Python 解释器（如 Python 3.14t），并执行 python3 setup.py bdist_wheel 命令触发构建。问题发生在 setuptools 处理 py_limited_api="cp39" 配置项时。

报错原文

ValueError: `py_limited_api='cp39'` not supported. `Py_LIMITED_API` is currently incompatible with `Py_GIL_DISABLED`. See https://github.com/python/cpython/issues/111506.

原因分析

可能原因：CPython 3.14t 启用了 free-threaded（无 GIL）模式，该模式与 Py_LIMITED_API 不兼容。当 setuptools 检测到解释器是被 --disable-gil 编译的（即带有 t 后缀，如 3.14t），它不允许同时设置 py_limited_api。这是 CPython 上游设计的限制。

环境排查

Python 解释器版本：确认是否为 3.14t（含 t 后缀的 free-threaded 版本）
xFormers 版本：确认是否低于 0.0.35
构建命令：检查 setup.py 中是否使用了 py_limited_api="cp39"

解决步骤

升级 xFormers 到 0.0.35 或更高版本：根据 Issue 评论，该问题已在版本 0.0.35 中通过 commit 1297aae5a36 解决。升级后，PyPI 上的 py39-none wheel 应可在 free-threaded 解释器上安装。
使用预编译 wheel：优先从 PyPI 安装 xFormers 0.0.35 的预编译 wheel，而不是从源码构建。
（备选）切换为普通 Python 解释器：如果必须从源码构建，可考虑使用非 free-threaded 的 Python（如 3.14 不带 t 后缀）。
（可优先尝试）等待上游 CPython 支持：根据 Issue 讨论，PyTorch 2.10 将支持 3.14t（包括 torch.compile），但 xFormers 的 free-threaded 支持目前是设计限制，短期内无更新计划。

验证方法

成功构建或安装后，运行 import xformers 并确认无 ImportError。也可以尝试在 free-threaded 解释器下运行一个依赖 xFormers 的简单注意力示例（如 from xformers.ops import memory_efficient_attention）。