TVM 目标描述与代码生成模块 `tvm.target` 完全指南：Target 字符串、TargetKind 与设备检测

• 编译器
• 深度学习
• 模型优化

导读

tvm.target是 TVM 中描述"为谁生成代码"的核心 Python 模块：编译一个模型到 CPU、GPU 或专用加速器之前，必须先用它构造一个目标（Target）对象，把目标架构、交叉编译三元组、CPU 特性、外部库等编译期信息封装起来。本篇文章以 docs/reference/api/python/target.rst 所挂载的tvm.target模块为主体，完整讲解 Target 字符串语法与全部选项、Target/TargetKind的构造与能力、常用设备辅助构造函数、Target 上下文管理、标签注册、设备自动检测与 GenericFunc 目标分派，并结合 python/tvm/target 下的源码与 tests/python/target 中的测试用例给出可复现的实战示例。读完本文，你将能够为任意目标设备写出正确、可维护的 TVM Target 配置，并理解其底层如何映射到代码生成后端。

tvm.target模块是什么

tvm.target是 TVM Python 前端中的"Target description and codgen module"，负责目标的描述与代码生成入口。它并非一个简单的字符串常量，而是一组与 C++ 运行时通过 FFI 绑定的对象与工具函数，核心包括：

• Target：目标设备信息对象，可由目标字符串、配置字典或标签创建；
• TargetKind：编译目标的种类（如llvm、cuda、opencl），每种 Kind 维护一份可用选项表；
• VirtualDevice：编译期描述"数据存放在哪、代码如何编译"的表示；
• GenericFunc：可按当前目标进行特化分派的通用函数机制；
• 一系列便捷构造函数：cuda()、rocm()、mali()、arm_cpu()、hexagon()、riscv_cpu()、stm32()、vta()等；
• 目标标签（tag）注册与列表、从物理设备自动检测目标的工具函数。

模块的导出与组织方式见 python/tvm/target/init.py：它从target.py导出Target、create、TargetKind及各类设备构造函数，从virtual_device.py导出VirtualDevice，从compilation_config.py导出make_compilation_config，从tag.py导出list_tags，从generic_func.py导出GenericFunc与三个装饰器，并整体引入datatype与codegen子模块。

Target 字符串语法与完整选项列表

模块的模块级 docstring（见 python/tvm/target/init.py）给出了 TVM 目标字符串的权威格式：

<target_kind> [-option=value]...

即：以目标种类开头，后面跟零个或多个以空格分隔的-选项=值键值对。TVM 用同一个字符串同时表达"后端种类"与"该后端的详细配置"。

选项一览表

需要注意：-mattr中的+表示启用该特性，-表示禁用；多个特性用逗号分隔。-mcpu、-mtriple、-mabi等选项最终会传递给 LLVM 后端参与代码生成决策。

字典形式配置

除了字符串，Target构造函数还接受配置字典或 JSON 字符串。字典形式下各字段与字符串选项一一对应（详见 python/tvm/target/target.py 的 docstring）：

此外，Target构造函数还支持host位置参数（第二个参数），其取值形式与 target 相同，用于同时指定"目标设备 + 运行该设备驱动的宿主机"。

字符串与字典的等价示例

import tvm # 字符串形式 t1 = tvm.target.Target("cuda -arch=sm_80 -libs=cublas,cudnn") # 字典形式（等价） t2 = tvm.target.Target({ "kind": "cuda", "arch": "sm_80", "libs": ["cublas", "cudnn"], }) # 同时指定 host t3 = tvm.target.Target("cuda", host="llvm -mtriple=x86_64-linux-gnu")

tests/python/target/test_target_target.py中的test_target_string_parse与test_target_string_with_spaces分别验证了cuda -model=unknown -libs=cublas,cudnn这类字符串解析以及含空格的 target 往返序列化（str(target)后再次构造）的正确性。

TargetKind：目标种类与其选项注册表

TargetKind是"编译目标的种类"，由@tvm._ffi.register_object注册为 TVM Object（见 python/tvm/target/target.py）。它有两个静态/实例方法：

• TargetKind.options：返回当前 kind 可用选项名到类型的字典；
• TargetKind.options_from_name(kind_name)：按名称（字符串）获取某 kind 的选项字典。

C++ 侧在 src/target/target_kind.cc 通过TVM_REGISTER_TARGET_KIND注册了全部内置种类，每个种类关联一个 DLPack 设备类型常量：

Target.list_kinds()会返回当前 TVM 构建中所有可用种类名称的列表，tests/python/target/test_target_target.py中的test_target_dispatch等用例会遍历它逐一构造 Target 来验证所有种类都能被正确解析。

Target 对象：构造、属性与规范化工具

三种构造方式

按 python/tvm/target/target.py，Target(target, host=None)可以从三类输入构造：

1. 原始目标字符串：如"cuda"、"llvm -mtriple=aarch64-linux-gnu"；
2. 配置字典：如上文的字典字段表；
3. 目标标签：预注册或自定义的标签名（见下文"目标标签"小节）。

构造时会先经过convert把 str/dict 转成 TVM 内部Map/String表示，再由_ffi_api.Target构造底层对象；传入非法类型会抛出ValueError("target has to be a string or dictionary.")。若host非空，则用Target(target)与Target(host)两个子对象一起构造。

常用属性

Target提供了一系列属性用于查询目标特性（见 python/tvm/target/target.py）：

• arch：CUDA 架构字符串（如sm_80），取自attrs["arch"]；
• max_num_threads/max_block_size_x/max_block_size_y/thread_warp_size/max_shared_memory_per_block：线程与共享内存限制；
• max_function_args：最大函数参数个数；
• vtcm_capacity：Hexagon VTCM 容量（字节），0 表示无限制；
• device_name：设备名；
• model：设备型号（默认"unknown"）；
• mcpu/mattr：CPU 型号与特性列表；
• libs：外部库列表；
• supports_integer_dot_product：是否支持整数点积。对 CUDA，当sm_version >= 61时返回 True（即 Pascal 之后支持dp4a等指令）；
• supports_cooperative_matrix：是否支持协作矩阵（cooperative matrix）；
• l2_cache_size_bytes：L2 缓存大小；
• features：TargetFeatures对象，可用target.features.<name>查询 LLVM 特性支持情况（见tests/python/target/test_llvm_features_info.py的test_target_features）。

这些属性在调度（schedule）与代码生成时被用来决定线程束大小、共享内存预算、向量宽度等关键参数。

规范化（canonicalization）静态方法

Target还提供一组静态方法，把各种"目标类对象"统一成规范形式，是编译入口的公共基础设施：

• Target.canon_target(target)：把None、既有Target、字符串（如"cuda -arch=sm_80"）或字典（如{"kind": "cuda", "arch": "sm_80"}）统一转成Target；
• Target.canon_target_and_host(target, target_host=None)：同时规范目标与宿主机，若target_host非空会警告其即将弃用并建议改用tvm.target.Target(target, host=target_host)；
• Target.canon_multi_target(multi_targets)：把一个目标类对象、目标列表/Array 或"设备类型到目标"的字典（遗留的异构目标表示，键被忽略）转成Target数组；
• Target.canon_multi_target_and_host(target, target_host=None)：多目标 + host 的规范化；
• Target.canon_target_map_and_host(target_map, target_host=None)：把"目标 → IRModule"映射的键规范化，并把 host 固化到每个键中；
• Target.target_or_current(target)：若传入None，则取当前上下文目标（Target.current()），仍为空则抛ValueError。

另外Target.from_device(device)会从物理设备反查出对应 Target（见"设备自动检测"小节）。

序列化与宿主设置

• Target.export()：导出目标的 JSON 字符串表示；
• Target.with_host(host=None)：返回带指定宿主机的新 Target 对象；
• Target.current(allow_none=True)：返回当前上下文中的目标（配合with使用），allow_none=False时未设置会抛异常。

设备便捷构造函数：从辅助函数到完整 Target

tvm.target提供了一系列"语义化"构造函数，比手写 Target 字符串更不易出错。这些函数都通过_merge_opts合并用户附加选项后构造Target（tvm.target.create()已标记弃用，请直接使用Target构造器，见 python/tvm/target/target.py）。

GPU 相关

CUDA 的arch参数例如sm_61（对应 GTX 1080 Ti 等 Pascal 卡）；cuda()函数在 python/tvm/target/target.py 中实现，tests/python/target/test_target_target.py的test_target_string_parse验证了cuda -model=unknown -libs=cublas,cudnn的解析。

CPU 相关

arm_cpu(model="unknown", options=None)内置了常见开发板/手机型号到完整选项的映射表（python/tvm/target/target.py）：

最终统一生成llvm -keys=arm_cpu,cpu -device=arm_cpu ...形式的目标。rasp(options)已弃用，应改调arm_cpu("rasp3b")。

riscv_cpu(model="sifive-u54", options=None)内置 SiFive 系列配置（python/tvm/target/target.py）：sifive-e31（riscv32-unknown-linux-gnu+-mabi=ilp32）、sifive-e76（同上）、sifive-u54（riscv64-unknown-linux-gnu+-mabi=lp64d，默认）、sifive-u74（同上）。这些 ABI 与 GCC 的-march=rv64gc -mabi=lp64d惯例对应。

stm32(series="unknown", options=None)面向 STM32 全系列 MCU（python/tvm/target/target.py），STM32_SUPPORTED_SERIES覆盖高性能（H7xx/F7xx/F4xx/F2xx）、主流（G0xx/F0xx/F1xx/G4xx/F3xx）与低功耗（U5xx/L5xx/L4xx/L1xx/L0xx）系列，映射到c -keys=arm_cpu,cpu -device=arm_cpu -mcpu=cortex-mX形式的 C 代码生成目标。

专用设备

• hexagon(cpu_ver="v68", **kwargs)：Qualcomm Hexagon DSP 目标（python/tvm/target/target.py），合法 CPU 版本为v65/v66/v67/v67t/v68/v69/v71/v73/v75。关键字参数包括hvx（HVX 向量字节数，默认 128，0 禁用 HVX 代码生成，合法值[0, 64, 128]）、llvm_options、use_qfloat（默认 v68 及以上为 True，即启用 HVX QFloat 指令）、use_ieee_fp（默认 False）、num_cores（默认 4，meta scheduler 需要）、vtcm_capacity（默认按版本取 0.25MB~8MB）。例如生成的 LLVM 目标串形如-mtriple=hexagon -mcpu=hexagonv68 -mattr=+hvxv68,+hvx-length128b；v68 还会默认附加-force-hvx-float以支持自动向量化。注意：HVX 浮点支持需要 LLVM 14+。
• micro(model="unknown", options=None)：microTVM 目标，MICRO_SUPPORTED_MODELS覆盖atsamd51、esp32、imxrt10xx、mps2_an521、mps3_an547、nrf52840、nrf5340dk、rp2040、sam3x8e、stm32f746xx、stm32h7xx、stm32l4r5zi、stm32u5xx、zynq_mp_r5等板卡，生成c -mcpu=... -model=...形式目标；未知型号直接抛ValueError。
• vta(model="unknown", options=None)：VTA 加速器，生成ext_dev -device=vta -keys=vta,cpu -model=...。

这些构造函数在 python/tvm/target/init.py 中被集中导出，是日常使用最频繁的入口。

Target 上下文管理：with与Target.current()

Target实现了上下文管理器协议（python/tvm/target/target.py）：

with tvm.target.Target("cuda"): print(tvm.target.Target.current()) # 进入作用域后即为 cuda 目标

进入with块时调用_ffi_api.TargetEnterScope，退出时调用TargetExitScope。这一机制让 Relay/Relax 编译、GenericFunc 分派、算子策略选择等在"当前目标"上下文中自动读取目标信息。tests/python/target/test_target_target.py的test_target_dispatch与test_target_temp_strategy验证了作用域内切换目标时行为一致且可嵌套回退。

在编译接口中，Target.target_or_current(target)则是"显式传入优先，否则取当前上下文"的便捷入口。

设备自动检测：从物理设备到 Target

Target.from_device(device)调用 python/tvm/target/detect_target.py 中的detect_target_from_device，把运行时的物理设备对象反查为 Target。支持的设备类型为["cuda", "metal", "rocm", "vulkan", "opencl", "cpu"]（SUPPORT_DEVICE字典，python/tvm/target/detect_target.py）。

各设备的检测策略：

• CUDA（_detect_cuda）：读取设备的max_shared_memory_per_block、max_threads_per_block、warp_size，并把compute_version（如8.0）转换为arch: "sm_80"；
• Metal：max_shared_memory_per_block固定 32768，其余从设备读取；
• ROCm：mtriple: "amdgcn-amd-amdhsa-hcc"，其余从设备读取；
• OpenCL：从设备读取三个容量字段；
• Vulkan：通过device_api.vulkan.get_target_property查询supports_float16、supports_int8、supports_int16、supports_int64、supports_8bit_buffer、supports_16bit_buffer、supports_storage_buffer_storage_class等能力并写入 Target 属性；
• CPU：通过tvm.codegen.llvm.GetDefaultTargetTriple与tvm.codegen.llvm.GetHostCPUName获取宿主机的默认三元组与 CPU 名。

若设备类型不支持自动检测或设备不存在（驱动未装、TVM 未编译对应驱动），会分别抛出带明确提示的ValueError。

import tvm # 假设本机有可用的 CUDA 设备 # target = tvm.target.Target.from_device(tvm.device("cuda", 0)) # 或在已持有 device 对象时直接反查

目标标签（Target Tag）：复用预定义目标

标签机制让用户用简短名称引用预定义目标（python/tvm/target/tag.py）：

import tvm from tvm.target.tag import register_tag, list_tags # 注册自定义标签 register_tag("nvidia/gtx1080ti", config={ "kind": "cuda", "arch": "sm_61", }) # 查看全部标签 tags = list_tags() # 返回 {名称: Target} target = tvm.target.Target("nvidia/gtx1080ti")

register_tag(name, config, override=False)把名称映射到配置字典；override=False时重复注册同名标签会抛异常。模块加载时已预注册nvidia/gtx1080ti（cuda + sm_61），并在加载期调用list_tags()校验所有标签的正确性。C++ 侧实现见 src/target/tag.cc 的target.TargetTagAddTag与target.TargetTagListTags，标签注册表刻意维护在 C++ 侧以支持纯 C++ 使用场景，Python API 仅用于快速原型。list_tags()在 runtime-only 构建下返回None。

GenericFunc：按目标分派的通用函数

GenericFunc是 TVM 的"目标感知"函数机制：同一个函数名可根据当前目标上下文分派到不同实现（python/tvm/target/generic_func.py）。

@tvm.target.generic_func装饰器

import tvm @tvm.target.generic_func def my_func(a): return a + 1 @my_func.register("cuda") def my_func_cuda(a): return a + 2 print(my_func(2)) # 3：默认实现 with tvm.target.cuda(): print(my_func(2)) # 4：分派到 cuda 特化

其分派逻辑为：取Target.current()，若为None则调用默认函数；否则按target.keys的顺序在分派字典中查找匹配键，命中即调用特化实现，未命中回退默认实现。register(key, func=None, override=False)支持传入字符串或字符串列表作为分派键，override=False时重复注册抛ValueError。装饰后的函数还暴露get_packed_func()返回当前目标下的分派函数。

@tvm.target.override_native_generic_func

用于覆盖 C++ 侧已注册的 GenericFunc 默认实现：

@tvm.target.override_native_generic_func("my_func") def my_func(a): return a + 1 @my_func.register("cuda") def my_func_cuda(a): return a + 2

C++ 侧通过generic_func.cc的注册表保存全局 GenericFunc，Python 侧get_native_generic_func(name)获取（不存在则新建），然后set_default(fdefault, allow_override=True)覆盖默认实现，register(key, func, override=True)注册分派特化。注意调用 generic_func 时不支持关键字参数（会抛RuntimeError）。

这一机制是tvm.target中算子/内建函数按设备特化的关键基础设施：例如tir内建函数在不同后端上有不同实现时，会通过 GenericFunc 注册到cuda、opencl、vulkan等键下。

关联对象：VirtualDevice 与 CompilationConfig

VirtualDevice（python/tvm/target/virtual_device.py）是编译期的"数据放置 + 编译方式"表示：

from tvm.target import VirtualDevice import tvm # device 为空时使用"无约束"设备（device type 与 id 均为 -1） vd = VirtualDevice(device=tvm.device("cuda", 0), target=None, memory_scope="global") print(vd.device_type)

它由VirtualDevice_ForDeviceTargetAndMemoryScope构造，描述数据在运行时存放在哪个设备、用哪个 target 编译其计算、使用什么内存作用域（memory_scope，如global、shared）。这在异构编译与内存规划场景中用于把算子与设备/存储绑定。

make_compilation_config(ctxt, target, target_host=None)（python/tvm/target/compilation_config.py）则通过Target.canon_multi_target_and_host规范化目标后构造CompilationConfig，主要用于单元测试，模拟标准编译接口的表示约定。

综合实战：为真实模型配置目标并编译

下面组合前述知识，演示一个完整的 Relay 编译流程（以tests/python/target/test_target_target.py的用例风格为参考）：

import tvm from tvm import relay # 1. 构造目标：CUDA 指定架构 + 外部库 target = tvm.target.Target("cuda -arch=sm_80 -libs=cublas,cudnn") print(target.kind.name) # cuda print(target.arch) # sm_80 print(target.libs) # ['cublas', 'cudnn'] # 2. 用便捷函数构造 ARM 交叉编译目标 arm_target = tvm.target.arm_cpu("rasp4b") print(arm_target) # llvm -keys=arm_cpu,cpu -device=arm_cpu -model=bcm2711 ... # 3. 编译时使用 Target（显式传入；省略时可用 with 上下文） mod, params = relay.testing.synthetic.get_workload() with tvm.transform.PassContext(opt_level=3): lib = relay.build(mod, target=target, params=params) # 4. 从物理设备自动反查目标（需设备可用） # detected = tvm.target.Target.from_device(tvm.device("cuda", 0)) # 5. 运行时按目标分派 generic func with tvm.target.Target("cuda"): lib.export_library("model.so")

要点回顾：

• 始终显式指定关键选项：CUDA 务必给arch=sm_xx，否则会收到警告且生成的 kernel 可能不是最优；
• 交叉编译三件套：-mtriple、-mcpu、-mattr决定生成代码的指令集，-mabi/-mfloat-abi决定 ABI 兼容性；
• 优先用便捷构造函数：arm_cpu("rasp4b")、riscv_cpu("sifive-u54")、stm32("stm32F4xx")等自带经过验证的默认配置，比手写字符串更可靠；
• host 与 target 分离：异构场景用Target(target, host=...)明确"谁在算、谁在管"。

测试与验证线索

本模块的行为在 tests/python/target 下有系统性覆盖，可作为进一步研究入口：

• test_target_target.py：字符串解析、含空格目标往返、LLVM-cl-opt与-jit选项、list_kinds()、目标分派与临时策略、create弃用警告等；
• test_llvm_features_info.py：target.features查询 LLVM 特性支持（含-mcpu=dummy这类非法 CPU 的错误路径）；
• test_arm_target.py：ARM 目标在with tvm.target.Target(arm_target)上下文中的行为；
• test_target_parser_mprofile.py：Cortex-M 系列-mcpu=cortex-m55/m7/m3的解析与-mattr=+nomve等特性覆盖。

结语

tvm.target是 TVM 编译栈的"目标总入口"：从<target_kind> [-option=value]...的字符串语法、Target/TargetKind对象与属性，到覆盖 CUDA/ROCm/OpenCL/ARM/RISC-V/Hexagon/STM32/microTVM 的便捷构造函数，再到上下文管理、标签复用、设备自动检测与 GenericFunc 目标分派，它把"为谁生成代码"这一编译问题完整地封装为可组合、可验证的 Python API。掌握本文所述的字符串与字典两种配置方式、常用选项语义及规范化工具，你就能在 TVM 中为任何目标设备写出正确且高效的编译配置。

• 编译器
• 深度学习
• 模型优化