4. Team 查询与属性：深入理解你的通信团队

各位同学，今天我们聊聊 Team 的查询与属性。说白了，就是搞清楚你手里的这个通信团队到底长什么样——有多少人、谁是谁、拓扑结构如何。

我个人习惯，在写任何集合通信代码之前，都会先做一轮 Team 属性查询。为什么？因为你得知道你的队友是谁，才能决定怎么跟他们配合。我在项目中遇到过好几次，因为没搞清楚 PE 映射关系，结果数据发错了目标，调试了一整天。

4.1 nvshmem_team_get_config：获取 Team 的配置信息

这个接口就像 Team 的身份证。它能告诉你这个 Team 的基本参数，比如包含多少个 PE、用的是哪个通信后端。

nvshmem_team_config_t config;
nvshmem_team_get_config(NVSHMEM_TEAM_WORLD, &config);

printf("Team 包含 %d 个 PE\n", config.num_pe);
printf("通信后端: %d\n", config.transport);

嗯，这里要注意：nvshmem_team_config_t 结构体里还有不少字段，但最常用的就是 num_pe。我刚开始用的时候，总以为这个接口能返回 Team 的上下文句柄，其实不是——它只返回创建 Team 时传入的配置参数。

4.2 nvshmem_team_translate_pe：跨 Team 的 PE 映射

这个接口，说实话，是我觉得最容易被忽略但极其有用的一个。它解决了一个核心问题：同一个 GPU 在不同 Team 里的编号可能不一样。

举个例子：

• 在 NVSHMEM_TEAM_WORLD 里，你的 PE 编号是 3
• 在一个只有 4 个 PE 的子 Team 里，你的 PE 编号可能是 1

这时候就需要 translate_pe 来帮你做映射。

int world_pe = 3;
int sub_team_pe = nvshmem_team_translate_pe(
    world_pe, 
    NVSHMEM_TEAM_WORLD, 
    my_sub_team
);

printf("World PE %d 在子 Team 中的编号是 %d\n", world_pe, sub_team_pe);

我曾经在一个多节点项目中，需要把数据从某个特定 GPU 广播到子 Team 的所有成员。如果不做 PE 映射，你根本不知道目标 PE 在子 Team 里是谁。那次调试让我深刻体会到：跨 Team 通信，映射是第一步。

4.3 Team 拓扑信息获取

NVSHMEM 支持多种 Team 拓扑，比如一维环形、二维网格等。获取拓扑信息，能帮你理解数据在物理上的流动路径。

常用的拓扑查询接口：

• nvshmem_team_get_info：获取 Team 的详细信息，包括拓扑类型
• nvshmem_team_get_ring_info：获取环形拓扑的邻居信息
• nvshmem_team_get_2dgrid_info：获取二维网格拓扑的行列信息

nvshmem_team_ring_info_t ring_info;
nvshmem_team_get_ring_info(my_ring_team, &ring_info);

printf("当前 PE 在环中的前驱: %d\n", ring_info.prev);
printf("当前 PE 在环中的后继: %d\n", ring_info.next);

你想想看，如果你在做环形归约，知道前驱和后继是谁，就能直接点对点通信，不用走集合通信接口。这在某些场景下能省不少开销。

4.4 实战：组合查询，摸清 Team 底细

我一般会写一个辅助函数，把 Team 的所有属性一次性打印出来，方便调试：

void print_team_info(nvshmem_team_t team, const char* name) {
    int my_pe = nvshmem_team_my_pe(team);
    int n_pes = nvshmem_team_n_pes(team);
    
    nvshmem_team_config_t config;
    nvshmem_team_get_config(team, &config);
    
    printf("[%s] 当前 PE: %d, 总 PE 数: %d\n", name, my_pe, n_pes);
    printf("[%s] 配置参数: num_pe=%d, transport=%d\n", 
           name, config.num_pe, config.transport);
    
    // 如果是环形拓扑，打印邻居
    nvshmem_team_ring_info_t ring;
    if (nvshmem_team_get_ring_info(team, &ring) == 0) {
        printf("[%s] 环形拓扑: prev=%d, next=%d\n", 
               name, ring.prev, ring.next);
    }
}

这个函数我几乎每个项目都会用。尤其是在调试多 Team 通信时，它能帮你快速定位问题——比如某个 Team 的 PE 数量不对，或者拓扑结构不是你期望的那样。

4.5 知识体系总览

下面这张图，是我自己总结的 Team 查询与属性的知识结构，你可以对照着看：

说白了，这三个方面——配置查询、PE 映射、拓扑信息——就是你在使用 Team 时必须掌握的基本功。配置查询让你知道 Team 的规模，PE 映射让你能在不同 Team 之间正确寻址，拓扑信息则帮你设计高效的通信策略。

我个人建议，在写任何集合通信代码之前，先花 5 分钟把这些信息打印出来看看。这 5 分钟，往往能帮你省下后面 5 小时的调试时间。

---