 参数与环境变量精确定制运行时)
Taichi 全局设置完整指南：用 ti.init() 参数与环境变量精确定制运行时
【免费下载链接】taichiProductive, portable, and performant GPU programming in Python.项目地址: https://gitcode.com/GitHub_Trending/ta/taichi
Taichi 程序的统一入口是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(arch=cuda)后，Taichi 选择 CUDA 作为后端，并忽略对应的环境变量TI_ARCH； - 其次读取环境变量：若未传
arch参数但设置了export TI_ARCH=cuda，Taichi 仍会选择 CUDA 作为后端； - 最后使用默认配置：若参数和环境变量都未设置，则采用默认后端
arch=ti.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）
| 参数 | 取值 | 说明 | 默认值 |
|---|---|---|---|
arch | ti.cpu、ti.gpu、ti.cuda、ti.vulkan等 | 指定使用的计算架构（后端）。ti.gpu会自动探测可用的 GPU 后端；ti.init()还带有enable_fallback（默认True），探测失败时回退 | 当前主机架构host_arch() |
device_memory_GB | float | 为 CUDA（以及 AMDGPU）预分配的显存大小，单位 GB | 1（即默认预分配 1 GB 显存） |
device_memory_GB在 taichi/program/compile_config.h#L70-L72 中归类为 "CUDA/AMDGPU backend options"，测试基础设施中也会用到，例如 tests/python/conftest.py#L30-L32 在初始化时传入device_memory_GB=1。
编译选项（Compilation Options）
| 参数 | 取值 | 说明 | 默认值 |
|---|---|---|---|
advanced_optimization | bool | 启用/禁用高级优化。关闭可缩短编译时间并降低出错概率 | True |
fast_math | bool | 启用/禁用快速数学运算。关闭可避免潜在的未定义数学行为（如某些函数在 CUDA 上的精度损失） | True |
print_ir | bool | 打印编译过程中生成的中间表示（IR），用于排查内核编译问题 | False |
运行时选项（Runtime Options）
| 参数 | 取值 | 说明 | 默认值 |
|---|---|---|---|
cpu_max_num_threads | int | 设置 CPU 线程池使用的线程数 | std::thread::hardware_concurrency()（硬件并发数） |
debug | bool | 以调试模式运行，Taichi 会做更多检查（如越界检查、自动求导校验等） | False |
default_cpu_block_dim | int | 设置 CPU 上每个 block 的线程数 | 32 |
default_gpu_block_dim | int | 设置 GPU 上每个 block 的线程数 | 128 |
default_fp | ti.f32、ti.f64 | 设置 Taichi 作用域内浮点数的默认精度 | ti.f32 |
default_ip | ti.i32、ti.i64 | 设置 Taichi 作用域内整数的默认精度 | ti.i32 |
kernel_profiler | bool | 开启/关闭内核性能剖析（见 Profiler 文档） | False |
offline_cache | bool | 开启/关闭编译后内核的离线缓存 | 前端默认开启（见下文） |
offline_cache_file_path | str | 设置离线缓存文件的存放目录 | get_repo_dir() + "ticache" |
random_seed | int | 为随机数生成器设置自定义种子（影响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_level | ti.INFO、ti.TRACE、ti.WARN、ti.ERROR、ti.CRITICAL、ti.DEBUG | 设置日志级别 | ti.INFO |
verbose | bool | 开启/关闭冗长输出。例如ti.init(verbose=False)可屏蔽多余的启动信息 | True |
开发者选项（Develop Options）
| 参数 | 取值 | 说明 | 默认值 |
|---|---|---|---|
gdb_trigger | bool | 崩溃时是否触发 GDB 调试器。例如ti.init(gdb_trigger=True)启用 GDB | False |
log_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 使用哪块 GPU：export CUDA_VISIBLE_DEVICES=[gpuid] |
TI_ARCH | 指定程序运行的后端，例如export TI_ARCH=cuda表示选用 CUDA |
TI_ENABLE_[CUDA/OPENGL/...] | 启动时禁用某个后端。例如export TI_ENABLE_CUDA=0禁用 CUDA 后端 |
TI_VISIBLE_DEVICE | 指定 Vulkan 使用哪块 GPU：export TI_VISIBLE_DEVICES=[gpuid] |
运行时选项（Runtime Options）
| 环境变量 | 说明 |
|---|---|
TI_DEBUG | 开关调试模式。例如export TI_DEBUG=1激活调试模式 |
TI_ENABLE_TORCH | 启动时是否导入 torch。例如export TI_ENABLE_TORCH=0禁止使用 torch。默认值为 1 |
TI_ENABLE_PADDLE | 启动时是否导入 paddle。例如export TI_ENABLE_PADDLE=0禁止使用 paddle。默认值为 1 |
TI_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_BITCODE=1启用缓存，可缩短启动时间；关闭则可节省磁盘占用 |
TI_TEST_THREADS | 指定跑测试用的线程数。例如export TI_TEST_THREADS=4分配 4 个线程；等价写法是python tests/run_tests.py -t4 |
日志选项（Logging Options）
| 环境变量 | 说明 |
|---|---|
TI_LOG_LEVEL | 设置日志级别。例如export TI_LOG_LEVEL=trace开启 TRACE 级别 |
后端（Backends）实战
- 指定后端架构：
ti.init(arch=ti.cuda)选用 CUDA，与环境变量TI_ARCH等价； - 指定 CUDA 预分配显存：
ti.init(device_memory_GB=0.5)预分配 0.5 GB 显存； - 指定 CUDA 使用哪块 GPU：
export CUDA_VISIBLE_DEVICES=[gpuid]； - 指定 Vulkan 使用哪块 GPU：
export TI_VISIBLE_DEVICE=[gpuid]； - 启动时禁用后端：
export TI_ENABLE_CUDA=0可禁用 CUDA（同理适用于METAL、OPENGL等）。
多 GPU 注意事项：如果要在多卡机器上同时使用 CUDA 与 Taichi 的 GGUI 系统，必须确保
CUDA_VISIBLE_DEVICES与TI_VISIBLE_DEVICE指向同一块 GPU（原则上应按 UUID 匹配）。可用nvidia-smi -L查看本机 GPU 设备详情，避免出现渲染后端与计算后端落在不同显卡上的问题。
编译（Compilation）实战
- 关闭高级优化：
ti.init(advanced_optimization=False)，可缩短编译时间并减少潜在错误； - 关闭快速数学：
ti.init(fast_math=False)，可避免潜在的未定义数学行为； - 打印中间 IR：
ti.init(print_ir=True)。注意编译好的内核默认会走离线缓存（见 离线缓存一节），如果希望强制重新编译并输出 IR，需要同时关闭缓存：ti.init(print_ir=True, offline_cache=False)。
运行时（Runtime）实战
- 重启整个 Taichi 系统（清除所有 field 与 kernel）：
ti.reset()。其底层实现在 python/taichi/lang/impl.py#L509-L516：清空已注册内核、重建PyTaichi对象并调用_ti_core.reset_default_compile_config()恢复默认编译配置； - 以调试模式启动：
ti.init(debug=True)，也可设置环境变量TI_DEBUG，或通过命令行ti debug your_script.py运行； - 禁止启动时导入 torch：
export TI_ENABLE_TORCH=0； - 禁止启动时导入 paddle：
export TI_ENABLE_PADDLE=0； - 设置随机种子：
ti.init(random_seed=seed)（seed为整数），影响ti.random()的随机序列。常见做法是用当前时间作种子：ti.init(random_seed=int(time.time()))； - 切换默认浮点精度为双精度：
ti.init(default_fp=ti.f64)（官方文档中对应的示例存在笔误，正确取值应为ti.f64而非ti.i64）； - 切换默认整数精度为 64 位：
ti.init(default_ip=ti.i64)（文档示例写作default_ip=ti.i32，注意语义是"整数精度"，对应取值为ti.i32/ti.i64）； - 关闭内核离线缓存：
ti.init(offline_cache=False)，详见 离线缓存说明；若只需自定义缓存目录，可用ti.init(offline_cache_file_path="/path/to/cache")，这也是 tests/python/test_cli.py#L234 的用法； - 允许使用变量作为索引访问 vector/matrix 元素：
ti.init(dynamic_index=True)； - 开启内核性能剖析：
ti.init(kernel_profiler=True)，配合ti.profiler模块分析内核耗时，详见 Profiler 文档。
日志（Logging）实战
- 设置日志级别：
ti.init(log_level=ti.TRACE)或ti.set_logging_level(ti.TRACE)均可开启 TRACE 级别；环境变量TI_LOG_LEVEL起同样作用； - 屏蔽冗长输出：
ti.init(verbose=False)。
开发者（Develop）实战
- 崩溃时触发 GDB：
ti.init(gdb_trigger=True)； - 开发者模式下缓存运行时 bitcode：
export TI_CACHE_RUNTIME_BITCODE=1，可加快启动； - 并行跑测试：
export TI_TEST_THREADS=4，或直接运行python tests/run_tests.py -t4。
多次调用 ti.init() 与 ti.reset() 的陷阱
如果ti.init被调用两次，第一次调用设置的配置会被丢弃。例如：
ti.init(debug=True) 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-L220，reset 后访问旧 field 会直接报错）。
高精度计算：default_fp 与 fast_math 的配合
默认的fast_math=True可能引发难以排查的精度问题。例如ti.sqrt（以及依赖它的ti.norm等函数）在 CUDA 后端上的精度可能低于 CPU 后端。要规避此类问题，推荐将默认浮点精度提升到双精度并关闭快速数学：
ti.init(default_fp=ti.f64, fast_math=False)如果你遇到其他精度损失问题，可以先尝试ti.init(fast_math=False)验证是否为快速数学所致；若仍无法解决，可携带最小复现用例向官方提交 issue。
组合示例：一套稳妥的初始化模板
将上述要点组合起来，可以得到一个兼顾可调试性与确定性的初始化模板：
import taichi as ti import time ti.init( arch=ti.cuda, # 指定后端；也可改用 ti.cpu / ti.vulkan device_memory_GB=0.5, # CUDA 预分配 0.5 GB 显存 debug=True, # 开启越界检查等调试能力 fast_math=False, # 关闭快速数学，保证数值行为确定 default_fp=ti.f64, # 默认浮点双精度 random_seed=int(time.time()), # 随机种子 kernel_profiler=True, # 开启内核剖析 offline_cache=False, # 调试阶段关闭缓存，确保每次都是全新编译 print_ir=False, # 需要排查 IR 时改为 True )该模板的每个开关都有明确的调试或精度动机：调试阶段关闭离线缓存配合print_ir=True可强制复现编译；交付阶段再恢复offline_cache=True（默认）以利用缓存加速后续启动。通过 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），仅供参考
函数（预防僵尸进程))
