Index of every page on this site: llms.txt
All skills
steelan9199 avatar

/python-env-yashu

@9e01957
Run it yourself

本机 Python 解释器与虚拟环境的权威清单。激活条件:用户消息须包含以下关键词之一:`python环境`、`虚拟环境`、`venv`、`解释器`、`interpreter`、`装依赖`、`安装包`、`pip install`、`uv pip`、`用哪个python`、`python版本`、`环境共享`、`共享环境`、`GPU环境`、`numba`、`cupy`、`CUDA环境`。

  • 1 file
  • 12.5 KB
  • Updated 3 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/steelan9199/wechat-publisher/python-env-yashu

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈95 tokens for metadata: the name and description. ≈3.1k when used: this file.

Description uses 2.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈212 characters, or 2.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 9e01957. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 weeks ago.

Activeupdated 3 weeks ago
agent_created
true

README badge

README badge for steelan9199/wechat-publisher/python-env-yashu