Taichi 全局设置完整指南：用 ti.init() 参数与环境变量精确定制运行时

Taichi 全局设置完整指南用 ti.init() 参数与环境变量精确定制运行时【免费下载链接】taichiProductive, portable, and performant GPU programming in Python.项目地址: https://gitcode.com/GitHub_Trending/ta/taichiTaichi 程序的统一入口是ti.init()它负责完成运行时初始化包括选择后端backend、配置编译策略、设定数值精度与日志级别等。本指南以docs/lang/articles/reference/global_settings.md为骨架系统讲解ti.init()的全部常用参数、等价的环境变量、两者的优先级规则并结合本仓库源码如 python/taichi/lang/misc.py、taichi/program/compile_config.h揭示默认值与底层实现。读完本文你将能够针对 CPU/CUDA/Vulkan 等多种后端、调试、性能剖析、离线缓存、高精度计算等场景精准写出可复现、可维护的 Taichi 启动配置。配置生效的优先级参数 环境变量 默认值每个ti.init()参数或环境变量都只控制 Taichi 运行时的一个具体行为例如参数arch指定后端参数debug决定是否以调试模式运行。以arch为例Taichi 的解析顺序是优先读取ti.init()传入的参数执行ti.init(archcuda)后Taichi 选择 CUDA 作为后端并忽略对应的环境变量TI_ARCH其次读取环境变量若未传arch参数但设置了export TI_ARCHcudaTaichi 仍会选择 CUDA 作为后端最后使用默认配置若参数和环境变量都未设置则采用默认后端archti.cpu。这一优先级规则有源码级佐证。在 python/taichi/lang/misc.py#L225-L257 中_EnvironmentConfigurator.add()的实现逻辑是若某个 key 同时出现在ti.init的 kwargs 与环境变量中则采用 kwargs 中的值并打印警告Environment variable TI_... overridden by ti.init argument ...仅当参数缺失时才读取环境变量TI_ 参数名大写。arch的特例处理位于 python/taichi/lang/misc.py#L444-L449若设置了TI_ARCH则通过_ti_core.arch_from_name将其转换为架构枚举。另外TI_DEFAULT_FP/TI_DEFAULT_IP也遵循同样的参数覆盖环境变量规则见 python/taichi/lang/misc.py#L384-L408。值得一提的是ti.init()对未知参数会直接抛出KeyError: Unrecognized keyword argument(s) for ti.init见 python/taichi/lang/misc.py#L431-L434因此写错参数名会立即暴露而不是静默忽略。通过 ti.init() 参数定制运行时下表完整覆盖了官方文档列出的常用参数并补充了从 taichi/program/compile_config.cpp#L9-L65 与 taichi/program/compile_config.h 中确认的默认值。后端选项Backend Options参数取值说明默认值archti.cpu、ti.gpu、ti.cuda、ti.vulkan等指定使用的计算架构后端。ti.gpu会自动探测可用的 GPU 后端ti.init()还带有enable_fallback默认True探测失败时回退当前主机架构host_arch()device_memory_GBfloat为 CUDA以及 AMDGPU预分配的显存大小单位 GB1即默认预分配 1 GB 显存device_memory_GB在 taichi/program/compile_config.h#L70-L72 中归类为 CUDA/AMDGPU backend options测试基础设施中也会用到例如 tests/python/conftest.py#L30-L32 在初始化时传入device_memory_GB1。编译选项Compilation Options参数取值说明默认值advanced_optimizationbool启用/禁用高级优化。关闭可缩短编译时间并降低出错概率Truefast_mathbool启用/禁用快速数学运算。关闭可避免潜在的未定义数学行为如某些函数在 CUDA 上的精度损失Trueprint_irbool打印编译过程中生成的中间表示IR用于排查内核编译问题False运行时选项Runtime Options参数取值说明默认值cpu_max_num_threadsint设置 CPU 线程池使用的线程数std::thread::hardware_concurrency()硬件并发数debugbool以调试模式运行Taichi 会做更多检查如越界检查、自动求导校验等Falsedefault_cpu_block_dimint设置 CPU 上每个 block 的线程数32default_gpu_block_dimint设置 GPU 上每个 block 的线程数128default_fpti.f32、ti.f64设置 Taichi 作用域内浮点数的默认精度ti.f32default_ipti.i32、ti.i64设置 Taichi 作用域内整数的默认精度ti.i32kernel_profilerbool开启/关闭内核性能剖析见 Profiler 文档Falseoffline_cachebool开启/关闭编译后内核的离线缓存前端默认开启见下文offline_cache_file_pathstr设置离线缓存文件的存放目录get_repo_dir() ticacherandom_seedint为随机数生成器设置自定义种子影响ti.random()0关于default_fp/default_ip需要注意两点详见 python/taichi/lang/misc.py#L365-L366一是不能直接设置default_up它会始终跟随default_ip的无符号版本二是若同时设置了环境变量TI_DEFAULT_FP取值为32或64参数会覆盖环境变量并打印警告。离线缓存除了路径外还有一整套清理策略见 taichi/program/compile_config.h#L91-L98默认清理策略为lru另有never/version/fifo可选缓存文件总大小上限默认 100 MB清理因子默认0.25。虽然 C 侧offline_cache默认是false但 python/taichi/lang/misc.py#L376 在 Python 前端会将其强制置为True因此对 Python 用户而言缓存默认开启。日志选项Logging Options参数取值说明默认值log_levelti.INFO、ti.TRACE、ti.WARN、ti.ERROR、ti.CRITICAL、ti.DEBUG设置日志级别ti.INFOverbosebool开启/关闭冗长输出。例如ti.init(verboseFalse)可屏蔽多余的启动信息True开发者选项Develop Options参数取值说明默认值gdb_triggerbool崩溃时是否触发 GDB 调试器。例如ti.init(gdb_triggerTrue)启用 GDBFalselog_level与gdb_trigger在 python/taichi/lang/misc.py#L260-L267 的_SpecialConfig中维护其默认值分别为info与False最终在 python/taichi/lang/misc.py#L437-L442 被派发到对应的运行时模块。通过环境变量定制运行时环境变量适合在部署、CI 与容器场景下不改代码地调整行为。文档列出的环境变量如下其中部分如TI_ARCH与ti.init()参数一一对应但并非全部如此——有些环境变量没有参数等价物反之亦然。后端选项Backend Options环境变量说明CUDA_VISIBLE_DEVICES指定 CUDA 使用哪块 GPUexport CUDA_VISIBLE_DEVICES[gpuid]TI_ARCH指定程序运行的后端例如export TI_ARCHcuda表示选用 CUDATI_ENABLE_[CUDA/OPENGL/...]启动时禁用某个后端。例如export TI_ENABLE_CUDA0禁用 CUDA 后端TI_VISIBLE_DEVICE指定 Vulkan 使用哪块 GPUexport TI_VISIBLE_DEVICES[gpuid]运行时选项Runtime Options环境变量说明TI_DEBUG开关调试模式。例如export TI_DEBUG1激活调试模式TI_ENABLE_TORCH启动时是否导入 torch。例如export TI_ENABLE_TORCH0禁止使用 torch。默认值为 1TI_ENABLE_PADDLE启动时是否导入 paddle。例如export TI_ENABLE_PADDLE0禁止使用 paddle。默认值为 1TI_ENABLE_TORCH与TI_ENABLE_PADDLE的默认行为在 python/taichi/lang/util.py#L34-L56 中有直接体现两处均通过os.environ.get(TI_ENABLE_TORCH, 1)/os.environ.get(TI_ENABLE_PADDLE, 1)读取默认值为1值为0时跳过导入尝试——这也是为什么在不安装 PyTorch/Paddle 的环境中程序仍能正常启动。开发者选项Develop Options环境变量说明TI_CACHE_RUNTIME_BITCODE开发者模式下是否缓存编译后的运行时 bitcode。例如export TI_CACHE_RUNTIME_BITCODE1启用缓存可缩短启动时间关闭则可节省磁盘占用TI_TEST_THREADS指定跑测试用的线程数。例如export TI_TEST_THREADS4分配 4 个线程等价写法是python tests/run_tests.py -t4日志选项Logging Options环境变量说明TI_LOG_LEVEL设置日志级别。例如export TI_LOG_LEVELtrace开启 TRACE 级别后端Backends实战指定后端架构ti.init(archti.cuda)选用 CUDA与环境变量TI_ARCH等价指定 CUDA 预分配显存ti.init(device_memory_GB0.5)预分配 0.5 GB 显存指定 CUDA 使用哪块 GPUexport CUDA_VISIBLE_DEVICES[gpuid]指定 Vulkan 使用哪块 GPUexport TI_VISIBLE_DEVICE[gpuid]启动时禁用后端export TI_ENABLE_CUDA0可禁用 CUDA同理适用于METAL、OPENGL等。多 GPU 注意事项如果要在多卡机器上同时使用 CUDA 与 Taichi 的 GGUI 系统必须确保CUDA_VISIBLE_DEVICES与TI_VISIBLE_DEVICE指向同一块 GPU原则上应按 UUID 匹配。可用nvidia-smi -L查看本机 GPU 设备详情避免出现渲染后端与计算后端落在不同显卡上的问题。编译Compilation实战关闭高级优化ti.init(advanced_optimizationFalse)可缩短编译时间并减少潜在错误关闭快速数学ti.init(fast_mathFalse)可避免潜在的未定义数学行为打印中间 IRti.init(print_irTrue)。注意编译好的内核默认会走离线缓存见 离线缓存一节如果希望强制重新编译并输出 IR需要同时关闭缓存ti.init(print_irTrue, offline_cacheFalse)。运行时Runtime实战重启整个 Taichi 系统清除所有 field 与 kernelti.reset()。其底层实现在 python/taichi/lang/impl.py#L509-L516清空已注册内核、重建PyTaichi对象并调用_ti_core.reset_default_compile_config()恢复默认编译配置以调试模式启动ti.init(debugTrue)也可设置环境变量TI_DEBUG或通过命令行ti debug your_script.py运行禁止启动时导入 torchexport TI_ENABLE_TORCH0禁止启动时导入 paddleexport TI_ENABLE_PADDLE0设置随机种子ti.init(random_seedseed)seed为整数影响ti.random()的随机序列。常见做法是用当前时间作种子ti.init(random_seedint(time.time()))切换默认浮点精度为双精度ti.init(default_fpti.f64)官方文档中对应的示例存在笔误正确取值应为ti.f64而非ti.i64切换默认整数精度为 64 位ti.init(default_ipti.i64)文档示例写作default_ipti.i32注意语义是整数精度对应取值为ti.i32/ti.i64关闭内核离线缓存ti.init(offline_cacheFalse)详见 离线缓存说明若只需自定义缓存目录可用ti.init(offline_cache_file_path/path/to/cache)这也是 tests/python/test_cli.py#L234 的用法允许使用变量作为索引访问 vector/matrix 元素ti.init(dynamic_indexTrue)开启内核性能剖析ti.init(kernel_profilerTrue)配合ti.profiler模块分析内核耗时详见 Profiler 文档。日志Logging实战设置日志级别ti.init(log_levelti.TRACE)或ti.set_logging_level(ti.TRACE)均可开启 TRACE 级别环境变量TI_LOG_LEVEL起同样作用屏蔽冗长输出ti.init(verboseFalse)。开发者Develop实战崩溃时触发 GDBti.init(gdb_triggerTrue)开发者模式下缓存运行时 bitcodeexport TI_CACHE_RUNTIME_BITCODE1可加快启动并行跑测试export TI_TEST_THREADS4或直接运行python tests/run_tests.py -t4。多次调用 ti.init() 与 ti.reset() 的陷阱如果ti.init被调用两次第一次调用设置的配置会被丢弃。例如ti.init(debugTrue) print(ti.cfg.debug) # True ti.init() print(ti.cfg.debug) # False这是因为 python/taichi/lang/misc.py#L373 在init()内部会先调用reset()再重新构建默认配置。因此若需动态修改配置请以最后一次ti.init()为准若想中途彻底清空所有 field 与 kernel 并回到初始状态可显式调用ti.reset()官方文档示例见 python/taichi/lang/misc.py#L204-L220reset 后访问旧 field 会直接报错。高精度计算default_fp 与 fast_math 的配合默认的fast_mathTrue可能引发难以排查的精度问题。例如ti.sqrt以及依赖它的ti.norm等函数在 CUDA 后端上的精度可能低于 CPU 后端。要规避此类问题推荐将默认浮点精度提升到双精度并关闭快速数学ti.init(default_fpti.f64, fast_mathFalse)如果你遇到其他精度损失问题可以先尝试ti.init(fast_mathFalse)验证是否为快速数学所致若仍无法解决可携带最小复现用例向官方提交 issue。组合示例一套稳妥的初始化模板将上述要点组合起来可以得到一个兼顾可调试性与确定性的初始化模板import taichi as ti import time ti.init( archti.cuda, # 指定后端也可改用 ti.cpu / ti.vulkan device_memory_GB0.5, # CUDA 预分配 0.5 GB 显存 debugTrue, # 开启越界检查等调试能力 fast_mathFalse, # 关闭快速数学保证数值行为确定 default_fpti.f64, # 默认浮点双精度 random_seedint(time.time()), # 随机种子 kernel_profilerTrue, # 开启内核剖析 offline_cacheFalse, # 调试阶段关闭缓存确保每次都是全新编译 print_irFalse, # 需要排查 IR 时改为 True )该模板的每个开关都有明确的调试或精度动机调试阶段关闭离线缓存配合print_irTrue可强制复现编译交付阶段再恢复offline_cacheTrue默认以利用缓存加速后续启动。通过 taichi/program/compile_config.h 与 python/taichi/lang/misc.py 两份核心文件你可以随时核对任意配置项的默认值与生效路径让 Taichi 运行时始终处于可控状态。【免费下载链接】taichiProductive, portable, and performant GPU programming in Python.项目地址: https://gitcode.com/GitHub_Trending/ta/taichi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考