---
name: python-env-yashu
description: 本机 Python 解释器与虚拟环境的权威清单。激活条件：用户消息须包含以下关键词之一：`python环境`、`虚拟环境`、`venv`、`解释器`、`interpreter`、`装依赖`、`安装包`、`pip install`、`uv pip`、`用哪个python`、`python版本`、`环境共享`、`共享环境`、`GPU环境`、`numba`、`cupy`、`CUDA环境`。
agent_created: true
title: python-env-yashu
canonical_url: https://skilld.dev/gh/steelan9199/wechat-publisher/python-env-yashu
last_updated: 2026-11-03T03:15:05.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install steelan9199/wechat-publisher/python-env-yashu`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/python-env-yashu`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/steelan9199/wechat-publisher/python-env-yashu) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/python-env-yashu`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/python-env-yashu --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/python-env-yashu --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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）

```powershell
$py = "D:\software\uv\envs\py312-gpu\Scripts\python.exe"    # 或 py314-cpu
uv pip install --python $py <包名>
```

### 跑脚本

**输出一律重定向到文件再读**（本机 stdout 常不回传，看着像卡死，判断成败看副作用）：

```powershell
& $py "脚本.py" *> "D:\software\workBuddyWorkspace\_out.txt"
"exit=$LASTEXITCODE" *>> "D:\software\workBuddyWorkspace\_out.txt"
```

然后用 Read 读 `_out.txt`。

### 新建环境（沿用命名规范）

```powershell
# 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 **支持目录重命名**（内部用相对定位）。改名前后都要验证：

```powershell
Rename-Item "D:\software\uv\envs\<旧名>" "<新名>"
& "D:\software\uv\envs\<新名>\Scripts\python.exe" -c "import numpy; print(numpy.__version__)"
```

---

## GPU 编程要点

```python
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。
```python
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`：
```python
while i < 0 or i >= n:
    if i < 0: i = -i - 1
    else:      i = 2 * n - 1 - i
```
用**线性 ramp 数据验证不出来**（几种约定结果相同），**必须用非对称数据测**。

### 坑 12：`gaussian_filter1d` 的权重公式

```python
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` 复验。
