Python 环境(Yashu)
Overview
本机 Python 相关的解释器与虚拟环境有两套,统一放在 D:\software\uv\envs\,用途不同,不要混用。
| 用途 | 环境名 | 解释器路径 | Python |
|---|---|---|---|
| CPU 通用环境 | py314-cpu |
D:\software\uv\envs\py314-cpu\Scripts\python.exe |
3.14.7 |
| GPU 渲染环境 | py312-gpu |
D:\software\uv\envs\py312-gpu\Scripts\python.exe |
3.12.13 |
命名规则:py<版本>-<用途>。新增环境请沿用此规范,让目录名一眼看出 Python 版本和用途。
⚠️ 不要把虚拟环境建在
D:\software\workBuddyWorkspace里 —— 那是工作区,老板会随时清理。 所有环境一律放D:\software\uv\envs\。
系统里由 uv 托管的裸解释器(不直接用,仅 uv venv --python 3.12 拉环境时用到):
D:\software\uv\python3.12.exe、D:\software\uv\python3.14.exe。
图像处理 / OpenCV 首选解释器
| 用途 | 解释器 | Python | cv2 |
|---|---|---|---|
| 图像处理首选 | D:\github\battleofballs\.venv\Scripts\python.exe |
3.12.13 | 5.0.0(完整版,GUI: WIN32UI,imshow 可用) |
- 固定方式:
$env:OPENCV_PYTHON = "D:\github\battleofballs\.venv\Scripts\python.exe"(兼容CV_PYTHON)。 - 备选(干净隔离):
D:\software\uv\envs\py312-mir\Scripts\python.exe,需先uv pip install opencv-python(该 wheel 为 abi3,覆盖 3.11–3.14)。 - 铁律:不要在 battleofballs 那个 venv 里执行任何
pip/uv install opencv*—— 该环境同时存在 GUI 与 headless 两份 opencv dist-info,一装就可能把cv2.pyd换成 headless 版,imshow立即失效;该环境也没有 pip。 opencv-toolkit-yashu技能自带解释器探测链(OPENCV_PYTHON→ 当前解释器 →VIRTUAL_ENV→.venv→ PATH →py -0p→uv python find,命中即止),不设变量时自动探测;本表只记录本机的事实偏好,两者不互相依赖。
关键铁律:GPU 只能用 Python 3.12
不要为了装 numba / numba-cuda / cupy 去降级或重建 py314-cpu。
已实测(2026-10-05,RTX 4060 Ti / CC 8.9 / 驱动 591.86 / CUDA Toolkit 12.6):
| 组合 | 结果 |
|---|---|
numba-cuda-mlir + Python 3.12 |
✅ 正常,raymarch 实测 117x 加速 |
numba-cuda-mlir + Python 3.14 |
❌ 编译 kernel 触发 compiler bug |
numba-cuda + Python 3.14 |
❌ numpy 2.5 删了 np.row_stack,import 即崩 |
cupy-cuda12x + Python 3.12 |
❌ kernel 启动硬崩(无 traceback) |
cupy-cuda12x + Python 3.14 |
⚠️ 可跑,但不如 mlir 稳定,不推荐 |
numba-cuda 已被官方标记为维护模式,继任者是 numba-cuda-mlir——直接用 mlir,不要碰 numba-cuda。
怎么用
装包(这两个 venv 都没有 pip,必须用 uv)
$py = "D:\software\uv\envs\py312-gpu\Scripts\python.exe" # 或 py314-cpu
uv pip install --python $py <包名>跑脚本
输出一律重定向到文件再读(本机 stdout 常不回传,看着像卡死,判断成败看副作用):
& $py "脚本.py" *> "D:\software\workBuddyWorkspace\_out.txt"
"exit=$LASTEXITCODE" *>> "D:\software\workBuddyWorkspace\_out.txt"然后用 Read 读 _out.txt。
新建环境(沿用命名规范)
# GPU 环境
uv venv --python 3.12 "D:\software\uv\envs\py312-gpu"
uv pip install --python "D:\software\uv\envs\py312-gpu\Scripts\python.exe" "numba-cuda-mlir[cu12]" numpy scipy pillow[cu12] 后缀必须带,它会拉入 cuda-bindings 12.x / cuda-core / nvidia-cuda-* 运行时,缺了就崩。
环境可以重命名
uv venv 支持目录重命名(内部用相对定位)。改名前后都要验证:
Rename-Item "D:\software\uv\envs\<旧名>" "<新名>"
& "D:\software\uv\envs\<新名>\Scripts\python.exe" -c "import numpy; print(numpy.__version__)"GPU 编程要点
from numba_cuda_mlir import cuda
@cuda.jit(device=True) # 场函数用 device=True
def fld(x, y, z):
return cuda.libdevice.sin(x) * cuda.libdevice.cos(y)
@cuda.jit # kernel 里用 cuda.grid(1)
def kern(out, n):
i = cuda.grid(1)
if i < n:
out[i] = fld(i, 0.0, 0.0)- 数学函数用
math.*或cuda.libdevice.*,不是np.*。 - kernel 内不能调任何 Python 函数。想传场函数,就写成
device=True的 device function,或传标量参数。 - 传 numpy 数组会触发
NumbaPerformanceWarning(host→device 拷贝开销);正式代码用cuda.to_device显式搬到显存。 - 每个线程负责一个像素,从像素编号现算光线方向,不要预先物化光线数组——省显存也省带宽。
- 全程用 float32。float64 会让显存占用和带宽需求翻倍,加速比直接砍半。
- kernel 首次编译约 1~2 秒,之后热启动毫秒级;批量渲染时同一 kernel 只编译一次。
⚠️ numba-cuda-mlir 编译器的真实坑(2026-10-05 实测,14 条)
这些全是跑起来才暴露的,文档里查不到。每条都是「症状 → 原因 → 解法」。
能用 / 不能用
| 写法 | 结果 |
|---|---|
math.sin/cos/tan/sqrt/exp/log/atan2/floor/ceil/fabs/copysign/pow/acos/asin/atan/tanh |
✅ 17 个全可用,优先级高于 libdevice |
math.isnan / math.isinf |
✅ 可用 |
cuda.libdevice.isnan/isinf/sign/abs2 |
❌ 不存在,属性访问直接 AttributeError |
libdevice 其余(sin/cos/fmax/fmin/max/min/...) |
✅ 存在(共 324 个) |
np.clip(v,a,b) / np.sin / np.sqrt / np.minimum |
❌ TypingError |
float(bool) / int(bool) |
❌ float 不行(float() only support for numbers);int 可以 |
min(max(v,a),b) |
✅ 替代 np.clip |
嵌套 if/else、bool 局部变量、for+break、while、tuple 返回、模块级 numpy 常量被 device fn 引用 |
✅ 全部正常 |
动态循环边界(for _ in range(n),n 为 kernel 参数) |
✅ 正常 |
坑 1:3D 数组不能传进 device function
作为 kernel 参数可以,作为 device function 的参数会报
input and output rank must be > 0。
解法:网格传扁平 1D float32 + 手工算stride。
b = (i0 * ny + j0) * nz + k0 # 而不是 g[i0, j0, k0]坑 2:import math 必须放文件顶部
放文件末尾时,@cuda.jit(device=True) 装饰器已在import 阶段执行,device function 里引用 math 会失败。
坑 3:hasattr / try-except 不能出现在 device function 里
hasattr 报 Untyped global name 'hasattr': Cannot determine Numba type;
try 报 mark_try_block。写device function 时不要用任何运行时反射/异常处理。
坑 4:设备数组统一用扁平 1D
(n, 3) 的二维数组当flat buffer 索引(out[i*3])会在类型推断期报
Cannot unify float64 and array(float64, 1d, C)。
所有 device buffer 一律 np.zeros(n*3) + 手动 *3 索引,不要用二维。
坑 5:x != x 检测 NaN 会被编译器优化掉
实测对 nan 返回 False(恒等于"不是 nan")。要用 math.isnan(x)。
坑 6:kernel 数组参数个数不是问题
23 个参数的 kernel 实测正常。所有标量参数打包成一个 float32 device 数组传,签名只留 4 个,是可行且推荐的做法。
坑 7:carray 的签名反直觉
carray(arr, shape) 缺 shape 报错;传 numpy 数组报 expected a ctypes pointer。
直接用 cuda.to_device(arr),别用 carray。
坑 8:MAX_THREADS_PER_BLOCK = 1024,但 64/128/256/512 实测差异在噪声内
小网格(<16 block)会触发 NumbaPerformanceWarning: Grid size N will likely result in GPU under-utilization。
这是警告不是错误,忽略即可。
坑 9:真实性能参考(RTX 4060 Ti)
| 操作 | 耗时 |
|---|---|
| 1720×1720 光线步进 300 步 | 0.022 s |
| 296 MB(420³ f32)host→device | 0.053 s |
| 860×860 ss=2 全流程(kernel+bloom+tonemap) | 0.096 s |
| kernel 首次编译(本机,含 mlir 编译) | 12~13 s |
kernel 编译要 12秒(比文档说的 1~2 秒慢一个量级),批量渲染时一次即可摊销。
坑 10:scipy 的 gaussian_filter 标量 sigma 会连颜色轴一起模糊
gaussian_filter(img, 3.0) 作用在 (H,W,3) 上时,三个轴都被平滑。
复现到 GPU 时必须补一个 3×3 颜色混合矩阵(按 sigma 生成,独立一趟 kernel),
否则 max diff 差 0.30。
坑 11:scipy 边界模式 = numpy symmetric
索引映射 -1→0, -2→1, n→n-1:
while i < 0 or i >= n:
if i < 0: i = -i - 1
else: i = 2 * n - 1 - i用线性 ramp 数据验证不出来(几种约定结果相同),必须用非对称数据测。
坑 12:gaussian_filter1d 的权重公式
r = int(4.0 * sigma + 0.5) # truncate=4.0
x = np.arange(-r, r + 1)
w = np.exp(-0.5 * (x / sigma) ** 2)
w /= w.sum()按此生成可与 scipy 达到 5e-8(float32 精度极限)一致。
坑 13:验证渲染结果别用"线性数据"测边界
线性渐变下所有边界约定结果相同 → 会得出"我的实现是对的"这个错误结论。 本项目因此浪费了两轮:先是用 9×11 小图测(r=5 时每个像素都在反射区,无解), 后是用线性 ramp 测1D 映射(假通过)。用delta 图 + 非对称随机数据 + 大图内区才能定位。
坑 14:GPU 后处理里累加器不能和输入同一 buffer
acc += f(blur) 若 acc is blur,则累加器初值变成 blur 本身,且多档 sigma 会互相覆盖。
必须三个独立 buffer:base / blur / acc。
已装包速查
py314-cpu(3.14.7,705 MB):numpy 2.5.3、scipy 1.18.1、matplotlib 3.11.2、pillow 12.3.0、numba 0.68.0、llvmlite 0.50.0,另有 manim / mcp / moderngl / playwright / av 等。
py312-gpu(3.12.13,~700 MB):numba-cuda-mlir 0.5.4、numpy 2.5.3、scipy 1.18.1、pillow 12.3.0、matplotlib 3.11.2(2026-10-05 为做 CPU/GPU 对照补装)、cuda-bindings 12.9.9、cuda-core 1.2.1、cuda-toolkit 12.9.2.0、nvidia-cuda-* 12.9.86。
已从 py314-cpu 清理(2026-10-05):numba-cuda、numba-cuda-mlir、cupy-cuda12x、cuda-*、nvidia-cuda-* 共 11 个包。numba 本体保留(纯 CPU JIT 可用)。
环境迁移记录(2026-10-05):原 envs\geo → 重命名为 envs\py314-cpu;原 workBuddyWorkspace\math3d\.venv-gpu → 重建为 envs\py312-gpu。重命名后已验证解释器与全部包正常(uv venv 支持重定位)。
硬件事实
- GPU:NVIDIA GeForce RTX 4060 Ti,8188 MiB,compute capability 8.9
- 驱动:591.86(支持 CUDA 13.x)
- CUDA Toolkit:v12.6 已装于
C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.6,nvcc在 PATH - CPU:12th Gen Intel Core i5-12600KF,10 核 16 线程
- 内存:31.8 GB
- MSVC
cl.exe未安装。用预编译 wheel 就不需要它;只有要编译 C++ 扩展才需装 Build Tools。
Notes
- 两个环境隔离,py314-cpu 保持 3.14 不动,GPU 相关的一律进
py312-gpu。 - 虚拟环境不要建在工作区(
D:\software\workBuddyWorkspace),一律放D:\software\uv\envs\。 numba装在 py314-cpu 里可用于纯 CPU JIT 加速(典型 5~15x),例如把 numpy 的逐步循环改成@njit。这与 GPU 无关,可按需使用。- 并行跑多个进程前设
OMP_NUM_THREADS=1、OPENBLAS_NUM_THREADS=1、MKL_NUM_THREADS=1,并用multiprocessing的spawn方式(Windows 必须),否则可能撞0xC0000004。
已验证的参考实现
D:\software\workBuddyWorkspace\math3d\render3d_gpu.py(1235 行)是一份完整可跑的
GPU 光线步进渲染器,覆盖 march / 软阴影 / AO / 体积发光 / bloom / filmic 调色,
三条路径均与 CPU 版逐像素一致(IoU 1.0)。写新 kernel 时照它的模式抄最省事。
配套探测脚本在 math3d\_probes\(14 个),是本文档各条坑的**可复现证据**,
改编译器版本后应重跑 _verify_paths.py 复验。