@baimingtao/lbs-agent 1.0.0

package/extensions/skills/optional/mlops/pinecone/SKILL.md

@@ -0,0 +1,360 @@
+---
+name: pinecone
+description: 用于生产级 AI 应用的托管型向量数据库。全托管、自动扩缩容，支持混合搜索（dense + sparse）、metadata 过滤和 namespaces。低延迟（<100ms p95）。适用于生产级 RAG、推荐系统或大规模语义搜索。最适合 serverless、托管型基础设施。
+version: 1.0.0
+author: Orchestra Research
+license: MIT
+dependencies: [pinecone-client]
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [RAG, Pinecone, Vector Database, Managed Service, Serverless, Hybrid Search, Production, Auto-Scaling, Low Latency, Recommendations]
+
+---
+
+# Pinecone - 托管型向量数据库
+
+面向生产级 AI 应用的向量数据库。
+
+## 何时使用 Pinecone
+
+**适用于:**
+- 需要托管型、serverless 向量数据库
+- 生产级 RAG 应用
+- 需要自动扩缩容
+- 关键的低延迟要求（<100ms）
+- 不希望自行管理基础设施
+- 需要混合搜索（dense + sparse 向量）
+
+**Metrics**:
+- 完全托管的 SaaS
+- 可自动扩容至数十亿条向量
+- **p95 延迟 <100ms**
+- 99.9% 的正常运行时间 SLA
+
+**可使用的替代方案**:
+- **Chroma**: 自托管、开源
+- **FAISS**: 离线、纯相似度搜索
+- **Weaviate**: 具有更多功能的自托管方案
+
+## 快速 start
+
+### 安装
+
+```bash
+pip install pinecone-client
+```
+
+### 基础 usage
+
+```python
+from pinecone import Pinecone, ServerlessSpec
+
+# Initialize
+pc = Pinecone(api_key="your-api-key")
+
+# Create index
+pc.create_index(
+    name="my-index",
+    dimension=1536,  # Must match embedding dimension
+    metric="cosine",  # or "euclidean", "dotproduct"
+    spec=ServerlessSpec(cloud="aws", region="us-east-1")
+)
+
+# Connect to index
+index = pc.Index("my-index")
+
+# Upsert vectors
+index.upsert(vectors=[
+    {"id": "vec1", "values": [0.1, 0.2, ...], "metadata": {"category": "A"}},
+    {"id": "vec2", "values": [0.3, 0.4, ...], "metadata": {"category": "B"}}
+])
+
+# Query
+results = index.query(
+    vector=[0.1, 0.2, ...],
+    top_k=5,
+    include_metadata=True
+)
+
+print(results["matches"])
+```
+
+## 核心操作
+
+### 创建 index
+
+```python
+# Serverless (recommended)
+pc.create_index(
+    name="my-index",
+    dimension=1536,
+    metric="cosine",
+    spec=ServerlessSpec(
+        cloud="aws",         # or "gcp", "azure"
+        region="us-east-1"
+    )
+)
+
+# Pod-based (for consistent performance)
+from pinecone import PodSpec
+
+pc.create_index(
+    name="my-index",
+    dimension=1536,
+    metric="cosine",
+    spec=PodSpec(
+        environment="us-east1-gcp",
+        pod_type="p1.x1"
+    )
+)
+```
+
+### 插入 (Upsert) 向量
+
+```python
+# Single upsert
+index.upsert(vectors=[
+    {
+        "id": "doc1",
+        "values": [0.1, 0.2, ...],  # 1536 dimensions
+        "metadata": {
+            "text": "Document content",
+            "category": "tutorial",
+            "timestamp": "2025-01-01"
+        }
+    }
+])
+
+# Batch upsert (recommended)
+vectors = [
+    {"id": f"vec{i}", "values": embedding, "metadata": metadata}
+    for i, (embedding, metadata) in enumerate(zip(embeddings, metadatas))
+]
+
+index.upsert(vectors=vectors, batch_size=100)
+```
+
+### 查询向量
+
+```python
+# Basic query
+results = index.query(
+    vector=[0.1, 0.2, ...],
+    top_k=10,
+    include_metadata=True,
+    include_values=False
+)
+
+# With metadata filtering
+results = index.query(
+    vector=[0.1, 0.2, ...],
+    top_k=5,
+    filter={"category": {"$eq": "tutorial"}}
+)
+
+# Namespace query
+results = index.query(
+    vector=[0.1, 0.2, ...],
+    top_k=5,
+    namespace="production"
+)
+
+# Access results
+for match in results["matches"]:
+    print(f"ID: {match['id']}")
+    print(f"Score: {match['score']}")
+    print(f"Metadata: {match['metadata']}")
+```
+
+### Metadata 过滤
+
+```python
+# Exact match
+filter = {"category": "tutorial"}
+
+# Comparison
+filter = {"price": {"$gte": 100}}  # $gt, $gte, $lt, $lte, $ne
+
+# Logical operators
+filter = {
+    "$and": [
+        {"category": "tutorial"},
+        {"difficulty": {"$lte": 3}}
+    ]
+}  # Also: $or
+
+# In operator
+filter = {"tags": {"$in": ["python", "ml"]}}
+```
+
+## Namespaces
+
+```python
+# Partition data by namespace
+index.upsert(
+    vectors=[{"id": "vec1", "values": [...]}],
+    namespace="user-123"
+)
+
+# Query specific namespace
+results = index.query(
+    vector=[...],
+    namespace="user-123",
+    top_k=5
+)
+
+# List namespaces
+stats = index.describe_index_stats()
+print(stats['namespaces'])
+```
+
+## 混合搜索 (dense + sparse)
+
+```python
+# Upsert with sparse vectors
+index.upsert(vectors=[
+    {
+        "id": "doc1",
+        "values": [0.1, 0.2, ...],  # Dense vector
+        "sparse_values": {
+            "indices": [10, 45, 123],  # Token IDs
+            "values": [0.5, 0.3, 0.8]   # TF-IDF scores
+        },
+        "metadata": {"text": "..."}
+    }
+])
+
+# Hybrid query
+results = index.query(
+    vector=[0.1, 0.2, ...],
+    sparse_vector={
+        "indices": [10, 45],
+        "values": [0.5, 0.3]
+    },
+    top_k=5,
+    alpha=0.5  # 0=sparse, 1=dense, 0.5=hybrid
+)
+```
+
+## LangChain 集成
+
+```python
+from langchain_pinecone import PineconeVectorStore
+from langchain_openai import OpenAIEmbeddings
+
+# Create vector store
+vectorstore = PineconeVectorStore.from_documents(
+    documents=docs,
+    embedding=OpenAIEmbeddings(),
+    index_name="my-index"
+)
+
+# Query
+results = vectorstore.similarity_search("query", k=5)
+
+# With metadata filter
+results = vectorstore.similarity_search(
+    "query",
+    k=5,
+    filter={"category": "tutorial"}
+)
+
+# As retriever
+retriever = vectorstore.as_retriever(search_kwargs={"k": 10})
+```
+
+## LlamaIndex 集成
+
+```python
+from llama_index.vector_stores.pinecone import PineconeVectorStore
+
+# Connect to Pinecone
+pc = Pinecone(api_key="your-key")
+pinecone_index = pc.Index("my-index")
+
+# Create vector store
+vector_store = PineconeVectorStore(pinecone_index=pinecone_index)
+
+# Use in LlamaIndex
+from llama_index.core import StorageContext, VectorStoreIndex
+
+storage_context = StorageContext.from_defaults(vector_store=vector_store)
+index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)
+```
+
+## Index 管理
+
+```python
+# List indices
+indexes = pc.list_indexes()
+
+# Describe index
+index_info = pc.describe_index("my-index")
+print(index_info)
+
+# Get index stats
+stats = index.describe_index_stats()
+print(f"Total vectors: {stats['total_vector_count']}")
+print(f"Namespaces: {stats['namespaces']}")
+
+# Delete index
+pc.delete_index("my-index")
+```
+
+## 删除向量
+
+```python
+# Delete by ID
+index.delete(ids=["vec1", "vec2"])
+
+# Delete by filter
+index.delete(filter={"category": "old"})
+
+# Delete all in namespace
+index.delete(delete_all=True, namespace="test")
+
+# Delete entire index
+index.delete(delete_all=True)
+```
+
+## 最佳实践
+
+1. **使用 serverless** - 自动扩缩容，性价比高
+2. **批量 upsert** - 效率更高（每批 100-200 条）
+3. **添加 metadata** - 启用过滤功能
+4. **使用 namespaces** - 按用户/租户隔离数据
+5. **监控使用情况** - 查看 Pinecone dashboard
+6. **优化过滤器** - 为频繁过滤的字段建立 index
+7. **使用免费额度进行测试** - 免费 1 个 index、10 万条向量
+8. **使用混合搜索** - 提升质量
+9. **设置合适的维度** - 需与 embedding 模型相匹配
+10. **定期备份** - 导出重要数据
+
+## 性能
+
+| Operation | Latency | 说明 |
+|-----------|---------|-------|
+| Upsert | ~50-100ms | 按批次计 |
+| Query (p50) | ~50ms | 取决于 index 大小 |
+| Query (p95) | ~100ms | SLA 目标 |
+| Metadata filter | ~+10-20ms | 额外开销 |
+
+## 定价 (截至 2025 年)
+
+**Serverless**:
+- 每 100 万个 read units $0.096
+- 每 100 万个 write units $0.06
+- 每 GB 存储/月 $0.06
+
+**免费额度**:
+- 1 个 serverless index
+- 10 万条向量（1536 维）
+- 非常适合原型设计
+
+## 资源
+
+- **Website**: https://www.pinecone.io
+- **Docs**: https://docs.pinecone.io
+- **Console**: https://app.pinecone.io
+- **Pricing**: https://www.pinecone.io/pricing

package/extensions/skills/optional/mlops/pinecone/references/deployment.md

@@ -0,0 +1,181 @@
+# Pinecone 部署指南
+
+Pinecone 的生产环境部署模式。
+
+## Serverless 与 Pod-based 对比
+
+### Serverless（推荐）
+
+```python
+from pinecone import Pinecone, ServerlessSpec
+
+pc = Pinecone(api_key="your-key")
+
+# Create serverless index
+pc.create_index(
+    name="my-index",
+    dimension=1536,
+    metric="cosine",
+    spec=ServerlessSpec(
+        cloud="aws",  # or "gcp", "azure"
+        region="us-east-1"
+    )
+)
+```
+
+**优势：**
+- 自动扩缩容
+- 按用量付费
+- 无需基础设施管理
+- 对于负载波动较大的场景具有成本效益
+
+**适用场景：**
+- 流量不稳定
+- 注重成本优化
+- 不需要一致的延迟
+
+### Pod-based
+
+```python
+from pinecone import PodSpec
+
+pc.create_index(
+    name="my-index",
+    dimension=1536,
+    metric="cosine",
+    spec=PodSpec(
+        environment="us-east1-gcp",
+        pod_type="p1.x1",  # or p1.x2, p1.x4, p1.x8
+        pods=2,  # Number of pods
+        replicas=2  # High availability
+    )
+)
+```
+
+**优势：**
+- 稳定的性能
+- 可预测的延迟
+- 更高的吞吐量
+- 专用资源
+
+**适用场景：**
+- 生产环境工作负载
+- 需要一致的 p95 延迟
+- 需要高吞吐量
+
+## 混合搜索
+
+### Dense + Sparse vectors
+
+```python
+# Upsert with both dense and sparse vectors
+index.upsert(vectors=[
+    {
+        "id": "doc1",
+        "values": [0.1, 0.2, ...],  # Dense (semantic)
+        "sparse_values": {
+            "indices": [10, 45, 123],  # Token IDs
+            "values": [0.5, 0.3, 0.8]   # TF-IDF/BM25 scores
+        },
+        "metadata": {"text": "..."}
+    }
+])
+
+# Hybrid query
+results = index.query(
+    vector=[0.1, 0.2, ...],  # Dense query
+    sparse_vector={
+        "indices": [10, 45],
+        "values": [0.5, 0.3]
+    },
+    top_k=10,
+    alpha=0.5  # 0=sparse only, 1=dense only, 0.5=balanced
+)
+```
+
+**优势：**
+- 结合两者的优点
+- 语义 + 关键词匹配
+- 比单一搜索具有更好的召回率
+
+## 用于多租户的 Namespaces
+
+```python
+# Separate data by user/tenant
+index.upsert(
+    vectors=[{"id": "doc1", "values": [...]}],
+    namespace="user-123"
+)
+
+# Query specific namespace
+results = index.query(
+    vector=[...],
+    namespace="user-123",
+    top_k=5
+)
+
+# List namespaces
+stats = index.describe_index_stats()
+print(stats['namespaces'])
+```
+
+**用例：**
+- 多租户 SaaS
+- 针对特定用户的数据隔离
+- A/B 测试（prod/staging namespaces）
+
+## Metadata 过滤
+
+### 精确匹配
+
+```python
+results = index.query(
+    vector=[...],
+    filter={"category": "tutorial"},
+    top_k=5
+)
+```
+
+### 范围查询
+
+```python
+results = index.query(
+    vector=[...],
+    filter={"price": {"$gte": 100, "$lte": 500}},
+    top_k=5
+)
+```
+
+### 复杂过滤器
+
+```python
+results = index.query(
+    vector=[...],
+    filter={
+        "$and": [
+            {"category": {"$in": ["tutorial", "guide"]}},
+            {"difficulty": {"$lte": 3}},
+            {"published": {"$gte": "2024-01-01"}}
+        ]
+    },
+    top_k=5
+)
+```
+
+## 最佳实践
+
+1. **在开发环境中使用 serverless** - 具有成本效益
+2. **在生产环境中切换为 pods** - 性能稳定
+3. **实现 namespaces** - 用于多租户管理
+4. **策略性地添加 metadata** - 启用过滤功能
+5. **使用混合搜索** - 提升质量
+6. **批量 upserts** - 每批 100-200 个 vectors
+7. **监控使用情况** - 查看 Pinecone dashboard
+8. **设置警报** - 针对使用量/成本阈值
+9. **定期备份** - 导出重要数据
+10. **测试过滤器** - 验证性能
+
+## 资源
+
+- **Docs**: https://docs.pinecone.io
+- **Console**: https://app.pinecone.io

package/extensions/skills/optional/mlops/pytorch-fsdp/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: pytorch-fsdp
+description: 关于使用 PyTorch FSDP 进行完全分片数据并行训练的专家指南 - 参数分片、混合精度、CPU 卸载、FSDP2
+version: 1.0.0
+author: Orchestra Research
+license: MIT
+dependencies: [torch>=2.0, transformers]
+platforms: [linux, macos]
+metadata:
+  hermes:
+    tags: [分布式训练, PyTorch, FSDP, 数据并行, 分片, 混合精度, CPU 卸载, FSDP2, 大规模训练]
+
+---
+
+# Pytorch-Fsdp 技能
+
+提供关于 pytorch-fsdp 开发的全面协助，内容根据官方文档生成。
+
+## 何时使用此技能
+
+在以下情况下应触发此技能：
+- 使用 pytorch-fsdp
+- 询问关于 pytorch-fsdp 的特性或 API
+- 实施 pytorch-fsdp 解决方案
+- 调试 pytorch-fsdp 代码
+- 学习 pytorch-fsdp 最佳实践
+
+## 快速参考
+
+### 常见模式
+
+**模式 1：** 通用 Join 上下文管理器 # 创建于：2025年6月6日 | 最后更新于：2025年6月6日 通用 join（加入）上下文管理器促进了在不均匀输入上的分布式训练。本页概述了相关类的 API：`Join`、`Joinable` 和 `JoinHook`。如需教程，请参阅《使用 Join 上下文管理器处理不均匀输入的分布式训练》。 class torch.distributed.algorithms.Join(joinables, enable=True, throw_on_early_termination=False, **kwargs)[source]# 该类定义了通用的 join 上下文管理器，它允许在一个进程加入后调用自定义的钩子。这些钩子应当模拟（或者说“掩护”）未加入进程的集合通信，以防止挂起和报错，并确保算法的正确性。有关钩子定义的详细信息，请参阅 `JoinHook`。 警告 上下文管理器要求每个参与的 `Joinable` 在其自身每次迭代的集合通信之前调用 `notify_join_context()` 方法以确保正确性。 警告 上下文管理器要求 `JoinHook` 对象中的所有 `process_group` 属性必须相同。如果有多个 `JoinHook` 对象，则使用第一个对象的设备。进程组和设备信息用于检查是否有未加入的进程，并在启用了 `throw_on_early_termination` 时通过 all-reduce 通知进程抛出异常。 参数 joinables (List[Joinable]) – 参与的 `Joinable` 列表；它们的钩子将按给定顺序被遍历。 enable (bool) – 启用不均匀输入检测的标志；设置为 `False` 将禁用上下文管理器的功能，并且仅当用户知道输入不会不均匀时才应设置（默认：`True`）。 throw_on_early_termination (bool) – 控制在检测到不均匀输入时是否抛出异常的标志（默认：`False`）。 示例： >>> import os >>> import torch >>> import torch.distributed as dist >>> import torch.multiprocessing as mp >>> import torch.nn.parallel.DistributedDataParallel as DDP >>> import torch.distributed.optim.ZeroRedundancyOptimizer as ZeRO >>> from torch.distributed.algorithms.join import Join >>> >>> # 在每个生成的工作进程上 >>> def worker(rank): >>> dist.init_process_group("nccl", rank=rank, world_size=2) >>> model = DDP(torch.nn.Linear(1, 1).to(rank), device_ids=[rank]) >>> optim = ZeRO(model.parameters(), torch.optim.Adam, lr=0.01) >>> # Rank 1 比 rank 0 多获取一个输入 >>> inputs = [torch.tensor([1.]).to(rank) for _ in range(10 + rank)] >>> with Join([model, optim]): >>> for input in inputs: >>> loss = model(input).sum() >>> loss.backward() >>> optim.step() >>> # 所有 rank 都能到达这里而不会挂起/报错 static notify_join_context(joinable)[source]# 通知 join 上下文管理器调用此方法的进程尚未加入。然后，如果 `throw_on_early_termination=True`，则检查是否检测到了不均匀输入（即是否已有进程加入），如果是则抛出异常。此方法应在 `Joinable` 对象进行其每次迭代的集合通信之前被调用。例如，这应该在 `DistributedDataParallel` 的前向传播开始时被调用。只有传递给上下文管理器的第一个 `Joinable` 对象会在此方法中执行集合通信，而对于其他对象，此方法是空操作。 参数 joinable (Joinable) – 调用此方法的 `Joinable` 对象。 返回 如果 `joinable` 是传入上下文管理器的第一个对象，则返回用于通知上下文管理器该进程尚未加入的 all-reduce 异步工作句柄；否则返回 `None`。 class torch.distributed.algorithms.Joinable[source]# 这定义了可加入类的抽象基类。一个可加入的类（继承自 `Joinable`）应该实现 `join_hook()`，返回一个 `JoinHook` 实例，此外还要实现分别返回设备和进程组信息的 `join_device()` 和 `join_process_group()`。 abstract property join_device: device# 返回执行 join 上下文管理器所需集合通信的设备。 abstract join_hook(**kwargs)[source]# 为给定的 `Joinable` 返回一个 `JoinHook` 实例。 参数 kwargs (dict) – 一个包含任意关键字参数的字典，用于在运行时修改加入钩子的行为；所有共享相同 join 上下文管理器的 `Joinable` 实例都会接收到相同的 `kwargs` 值。 返回类型 JoinHook abstract property join_process_group: Any# 返回 join 上下文管理器本身所需集合通信的进程组。 class torch.distributed.algorithms.JoinHook[source]# 这定义了一个加入钩子，它在 join 上下文管理器中提供了两个入口点。 入口点：一个是主钩子，只要存在未加入的进程，它就会被重复调用；另一个是后置钩子，当所有进程都加入后，它会被调用一次。要为通用的 join 上下文管理器实现加入钩子，请定义一个继承自 `JoinHook` 的类，并视情况重写 `main_hook()` 和 `post_hook()`。 main_hook()[source]# 只要存在未加入的进程，就调用此钩子以模拟训练迭代中的集合通信。训练迭代，即在一次前向传播、反向传播和优化器步骤中。 post_hook(is_last_joiner)[source]# 当所有进程都加入后调用此钩子。它被传递了一个额外的布尔参数 `is_last_joiner`，指示该 rank 是否是最后加入的进程之一。 参数 is_last_joiner (bool) – 如果该 rank 是最后加入的之一则为 `True`；否则为 `False`。
+
+```
+Join
+```
+
+**模式 2：** 分布式通信包 - torch.distributed # 创建于：2017年7月12日 | 最后更新于：2025年9月4日 注释 请参阅《PyTorch 分布式概述》，以简要了解所有与分布式训练相关的特性。 后端# torch.distributed 支持四个内置后端，每个后端具有不同的功能。下表显示了每个后端可用于 CPU 或 GPU 的函数。对于 NCCL，GPU 指的是 CUDA GPU，而对于 XCCL 指的是 XPU GPU。仅当用于构建 PyTorch 的实现支持时，MPI 才支持 CUDA。 后端 gloo mpi nccl xccl 设备 CPU GPU CPU GPU CPU GPU CPU GPU 发送 ✓ ✘ ✓ ? ✘ ✓ ✘ ✓ 接收 ✓ ✘ ✓ ? ✘ ✓ ✘ ✓ 广播 ✓ ✓ ✓ ? ✘ ✓ ✘ ✓ 全局规约 ✓ ✓ ✓ ? ✘ ✓ ✘ ✓ 规约 ✓ ✓ ✓ ? ✘ ✓ ✘ ✓ 全局聚集 ✓ ✓ ✓ ? ✘ ✓ ✘ ✓ 聚集 ✓ ✓ ✓ ? ✘ ✓ ✘ ✓ 散射 ✓ ✓ ✓ ? ✘ ✓ ✘ ✓ 规约散射 ✓ ✓ ✘ ✘ ✘ ✓ ✘ ✓ 全互联 ✓ ✓ ✓ ? ✘ ✓ ✘ ✓ 同步屏障 ✓ ✘ ✓ ? ✘ ✓ ✘ ✓ PyTorch 附带的后端# PyTorch 分布式包支持 Linux（稳定版）、MacOS（稳定版）和 Windows（原型版）。对于 Linux，默认情况下，Gloo 和 NCCL 后端会被构建并包含在 PyTorch 分布式中（NCCL 仅在使用 CUDA 构建时包含）。MPI 是一个可选后端，只有从源代码构建 PyTorch 时才能包含。（例如，在安装了 MPI 的主机上构建 PyTorch。） 注释 从 PyTorch v1.8 开始，Windows 支持除 NCCL 外的所有集合通信后端。如果 `init_process_group()` 的 `init_method` 参数指向一个文件，它必须遵守以下架构： 本地文件系统，`init_method="file:///d:/tmp/some_file"` 共享文件系统，`init_method="file://////{machine_name}/{share_folder_name}/some_file"` 与 Linux 平台相同，您可以通过设置环境变量 `MASTER_ADDR` 和 `MASTER_PORT` 来启用 `TcpStore`。 应该使用哪个后端？# 过去，我们经常被问到：“我应该使用哪个后端？”。 经验法则 对于使用 CUDA GPU 的分布式训练，请使用 NCCL 后端。 对于使用 XPU GPU 的分布式训练，请使用 XCCL 后端。 对于使用 CPU 的分布式训练，请使用 Gloo 后端。 带有 InfiniBand 互连的 GPU 主机 使用 NCCL，因为它是目前唯一支持 InfiniBand 和 GPUDirect 的后端。 带有以太网互连的 GPU 主机 使用 NCCL，因为它目前为分布式 GPU 训练提供了最佳性能，尤其是对于多进程单节点或多节点的分布式训练。如果您在使用 NCCL 时遇到任何问题，请使用 Gloo 作为备选方案。（请注意，目前对于 GPU，Gloo 的运行速度比 NCCL 慢。） 带有 InfiniBand 互连的 CPU 主机 如果您的 InfiniBand 启用了 IP over IB，请使用 Gloo，否则请使用 MPI。我们计划在即将发布的版本中为 Gloo 添加 InfiniBand 支持。 带有以太网互连的 CPU 主机 使用 Gloo，除非您有特定理由使用 MPI。 常用环境变量# 选择要使用的网络接口# 默认情况下，NCCL 和 Gloo 后端都会尝试自动寻找合适的网络接口来使用。如果自动检测到的接口不正确，您可以使用以下环境变量覆盖它（适用于相应的后端）： `NCCL_SOCKET_IFNAME`，例如 `export NCCL_SOCKET_IFNAME=eth0` `GLOO_SOCKET_IFNAME`，例如 `export GLOO_SOCKET_IFNAME=eth0` 如果您使用 Gloo 后端，可以通过逗号分隔指定多个接口，例如：`export GLOO_SOCKET_IFNAME=eth0,eth1,eth2,eth3`。后端将以轮询（round-robin）方式在这些接口上分发操作。所有进程必须在此变量中指定相同数量的接口，这一点至关重要。 其他 NCCL 环境变量# 调试 - 如果发生 NCCL 故障，您可以设置 `NCCL_DEBUG=INFO` 来打印显式的警告信息以及基本的 NCCL 初始化信息。您还可以使用 `NCCL_DEBUG_SUBSYS` 获取有关 NCCL 特定方面的更多详细信息。例如，`NCCL_DEBUG_SUBSYS=COLL` 会打印集合调用的日志，这在调试挂起问题（尤其是由集合类型或消息大小不匹配引起的问题）时非常有用。如果拓扑检测失败，设置 `NCCL_DEBUG_SUBSYS=GRAPH` 来检查详细的检测结果并作为参考保存，以便后续向 NCCL 团队寻求进一步帮助，将会很有帮助。 性能调优 - NCCL 会根据其拓扑检测结果进行自动调优，以节省用户的调优精力。在某些基于 socket 的系统上，用户仍可尝试调整 `NCCL_SOCKET_NTHREADS` 和 `NCCL_NSOCKS_PERTHREAD` 来增加 socket 网络带宽。NCCL 已经针对一些云提供商（如 AWS 或 GCP）预调优了这两个环境变量。有关 NCCL 环境变量的完整列表，请参阅 NVIDIA NCCL 的官方文档 您还可以使用 `torch.distributed.ProcessGroupNCCL.NCCLConfig` 和 `torch.distributed.ProcessGroupNCCL.Options` 进一步调整 NCCL 通信器。在解释器中使用 `help` 了解有关它们的更多信息（例如 `help(torch.distributed.ProcessGroupNCCL.NCCLConfig)`）。 基础# torch.distributed 包为在一台或多台机器上运行的多个计算节点之间的多进程并行提供了 PyTorch 支持和通信原语。`torch.nn.parallel.DistributedDataParallel()` 类在此功能的基础上构建，作为任何 PyTorch 模型的包装器，提供同步分布式训练。这与 Multiprocessing 包 - torch.multiprocessing 和 torch.nn.DataParallel() 提供的并行方式不同，因为它支持多台网络连接的机器，并且用户必须为每个进程显式启动主训练脚本的单独副本。在单机同步的情况下，torch.distributed 或 `torch.nn.parallel.DistributedDataParallel()` 包装器相比于其他数据并行方法（包括 `torch.nn.DataParallel()`）可能仍然具有优势： 每个进程都会维护自己的优化器，并在每次迭代中执行完整的优化步骤。虽然这看起来可能是冗余的，因为梯度已经被收集在一起并在各进程间求平均，因此对于每个进程来说梯度都是相同的，但这意味着不需要参数广播步骤，从而减少了在节点之间传输张量所花费的时间。 每个进程都包含一个独立的 Python 解释器，消除了从单个 Python 进程驱动多个执行线程、模型副本或 GPU 所带来的额外解释器开销和“GIL 抖动”。这对于大量使用 Python 运行时的模型（包括具有循环层或许多小组件的模型）尤为重要。 初始化# 在调用任何其他方法之前，需要使用 `torch.distributed.init_process_group()` 或 `torch.distributed.device_mesh.init_device_mesh()` 函数对该包进行初始化。两者都会阻塞，直到所有进程都加入。 警告 初始化不是线程安全的。进程组的创建应该在单个线程中执行，以防止各个 rank 之间 'UUID' 分配不一致，并防止初始化期间发生可能导致挂起的竞争条件。 torch.distributed.is_available()[source]# 如果分布式包可用，则返回 `True`。否则，`torch.distributed` 不会暴露任何其他 API。目前，`torch.distributed` 在 Linux、MacOS 和 Windows 上可用。在从源代码构建 PyTorch 时，设置 `USE_DISTRIBUTED=1` 可启用它。目前，Linux 和 Windows 的默认值为 `USE_DISTRIBUTED=1`，MacOS 的默认值为 `USE_DISTRIBUTED=0`。 返回类型 bool torch.distributed.init_process_group(backend=None, init_method=None, timeout=None, world_size=-1, rank=-1, store=None, group_name='', pg_options=None, device_id=None)[source]# 初始化默认的分布式进程组。这也会初始化分布式包。有两种主要的方法可以初始化进程组： 1. 显式指定 `store`、`rank` 和 `world_size`。 2. 指定 `init_method`（一个 URL 字符串），指示在哪里/如何发现对等节点。可选择指定 `rank` 和 `world_size`，或者将所有需要的参数编码在 URL 中并省略它们。 如果两者都未指定，则 `init_method` 假定为 “env://”。 参数 backend (str 或 Backend, 可选) – 要使用的后端。根据构建时的配置，有效值包括 `mpi`、`gloo`、`nccl`、`ucc`、`xccl` 或者由第三方插件注册的后端。从 2.6 版本开始，如果未提供 `backend`，c10d 将使用为 `device_id` 关键字参数（如果提供）指示的设备类型注册的后端。目前已知的默认注册有：`cuda` 对应 `nccl`，`cpu` 对应 `gloo`，`xpu` 对应 `xccl`。如果 `backend` 和 `device_id` 均未提供，c10d 将检测运行时机器上的加速器，并使用为检测到的加速器（或 cpu）注册的后端。此字段可以以小写字符串形式给出（例如 `"gloo"`），也可以通过 `Backend` 属性访问（例如 `Backend.GLOO`）。如果在每台机器上使用多个进程并采用 nccl 后端，则每个进程必须对其使用的每个 GPU 具有独占访问权，因为进程之间共享 GPU 可能会导致死锁或 NCCL 的无效用法。`ucc` 后端是实验性的。可以使用 `get_default_backend_for_device()` 查询设备的默认后端。 init_method (str, 可选) – 指定如何初始化进程组的 URL。如果未指定 `init_method` 或 `store`，则默认为 “env://”。与 `store` 互斥。 world_size (int, 可选) – 参与作业的进程数。如果指定了 `store` 则为必需项。 rank (int, 可选) – 当前进程的 rank（它必须是 0 到 `world_size-1` 之间的数字）。如果指定了 `store` 则为必需项。 store (Store, 可选) – 所有工作进程均可访问的键/值存储，用于交换连接/地址信息。与 `init_method` 互斥。 timeout (timedelta, 可选) – 针对进程组执行操作的超时时间。NCCL 的默认值为 10 分钟，其他后端的默认值为 30 分钟。这是集合通信将被异步中止并且进程将崩溃的持续时间。这样做是因为 CUDA 执行是异步的，由于失败的异步 NCCL 操作可能导致随后的 CUDA 操作在损坏的数据上运行，此时继续执行用户代码不再安全。当设置了 `TORCH_NCCL_BLOCKING_WAIT` 时，进程将阻塞并等待此超时时间。 group_name (str, 可选, 已弃用) – 组名。该参数将被忽略 pg_options (ProcessGroupOptions, 可选) – 进程组选项，指定在构造特定进程组期间需要传入的附加选项。目前，我们仅支持用于 nccl 后端的 `ProcessGroupNCCL.Options`，可以指定 `is_high_priority_stream`，以便在有计算内核等待时，nccl 后端可以获取高优先级的 CUDA 流。有关配置 nccl 的其他可用选项，请参阅 https://docs.nvidia.com/deeplearning/nccl/user-guide/docs/api/types.html#ncclconfig-t device_id (torch.device | int, 可选) – 此进程将处理的单个特定设备，允许进行特定于后端的优化。目前这有两种效果，仅在 NCCL 下：通信器会立即形成（立即调用 `ncclCommInit*`，而不是通常的延迟调用），并且子组将在可能的情况下使用 `ncclCommSplit` 以避免组创建的不必要开销。如果您想尽早了解 NCCL 初始化错误，也可以使用此字段。如果提供的是 int，API 将假定使用编译时的加速器类型。 注释 要启用 `backend == Backend.MPI`，必须在支持 MPI 的系统上从源代码构建 PyTorch。 注释 对多后端的支持是实验性的。目前，当未指定后端时，将同时创建 gloo 和 nccl 后端。gloo 后端将用于带有 CPU 张量的集合通信，而 nccl 后端将用于带有 CUDA 张量的集合通信。可以通过传入格式为 “<device_type>:<backend_name>,<device_type>:<backend_name>” 的字符串来指定自定义后端，例如 “cpu:gloo,cuda:custom_backend”。 torch.distributed.device_mesh.init_device_mesh(device_type, mesh_shape, *, mesh_dim_names=None, backend_override=None)[source]# 根据 `device_type`、`mesh_shape` 和 `mesh_dim_names` 参数初始化一个 `DeviceMesh`。这将创建一个具有 n 维数组布局的 `DeviceMesh`，其中 n 是 `mesh_shape` 的长度。如果提供了 `mesh_dim_names`，则每个维度将被标记为 `mesh_dim_names[i]`。 注释 `init_device_mesh` 遵循 SPMD 编程模型，这意味着相同的 PyTorch Python 程序在集群中的所有进程/rank 上运行。请确保 `mesh_shape`（描述设备布局的 nD 数组的维度）在所有 rank 上是完全相同的。不一致的 `mesh_shape` 可能会导致挂起。 注释 如果未找到进程组，`init_device_mesh` 将在后台初始化分布式通信所需的分布式进程组。 参数 device_type (str) – 网格的设备类型。目前支持：“cpu”、“cuda/cuda-like”、“xpu”。不允许传入带有 GPU 索引的设备类型，例如 “cuda:0”。 mesh_shape (Tuple[int]) – 定义描述设备布局的多维数组维度的元组。 mesh_dim_names (Tuple[str], 可选) – 分配给描述设备布局的多维数组每个维度的网格维度名称元组。其长度必须与 `mesh_shape` 的长度匹配。`mesh_dim_names` 中的每个字符串必须唯一。 backend_override (Dict[int | str, tuple[str, Options] | str | Options], 可选) – 对将为每个网格维度创建的部分或所有 `ProcessGroup` 的覆盖。每个键可以是维度的索引或其名称（如果提供了 `mesh_dim_names`）。每个值可以是包含后端名称及其选项的元组，或者只是这两个组件之一（在这种情况下，另一个将被设置为其默认值）。 返回 代表设备布局的 `DeviceMesh` 对象。 返回类型 DeviceMesh 示例： >>> from torch.distributed.device_mesh import init_device_mesh >>> >>> mesh_1d = init_device_mesh("cuda", mesh_shape=(8,)) >>> mesh_2d = init_device_mesh("cuda", mesh_shape=(2, 8), mesh_dim_names=("dp", "tp")) torch.distributed.is_initialized()[source]# 检查默认进程组是否已初始化。 返回类型 bool torch.distributed.is_mpi_available()[source]# 检查 MPI 后端是否可用。 返回类型 bool torch.distributed.is_nccl_available()[source]# 检查 NCCL 后端是否可用。 返回类型 bool torch.distributed.is_gloo_available()[source]# 检查 Gloo 后端是否可用。 返回类型 bool torch.distributed.distributed_c10d.is_xccl_available()[source]# 检查 XCCL 后端是否可用。 返回类型 bool torch.distributed.is_torchelastic_launched()[source]# 检查此进程是否由 `torch.distributed.elastic`（也称为 torchelastic）启动。`TORCHELASTIC_RUN_ID` 环境变量的存在被用作确定当前进程是否由 torchelastic 启动的代理。这是一个合理的代理，因为 `TORCHELASTIC_RUN_ID` 映射到 rendezvous id，该 id 始终是一个非空值，用于标识用于对等发现目的的作业 ID。 返回类型 bool torch.distributed.get_default_backend_for_device(device)[source]# 返回给定设备的默认后端。 参数 device (Union[str, torch.device]) – 要获取其默认后端的设备。 返回 给定设备的默认后端，以小写字符串形式返回。 返回类型 str 目前支持三种初始化方法： TCP 初始化# 使用 TCP 初始化有两种方法，两者都要求一个可从所有进程访问的网络地址以及期望的 `world_size`。第一种方法要求指定一个属于 rank 0 进程的地址。这种初始化方法要求所有进程都手动指定 rank。请注意，最新的分布式包中不再支持多播地址。`group_name` 也已被弃用。 import torch.distributed as dist # 使用其中一台机器的地址 dist.init_process_group(backend, init_method='tcp://10.1.1.20:23456', rank=args.rank, world_size=4) 共享文件系统初始化# 另一种初始化方法利用了一个组内所有机器都能看到和共享的文件系统，以及一个期望的 `world_size`。URL 应该以 `file://` 开头，并包含共享文件系统上一个（在现有目录中的）不存在文件的路径。如果文件不存在，文件系统初始化将自动创建该文件，但不会删除该文件。因此，您有责任在下次对同一文件路径/名称调用 `init_process_group()` 之前清理该文件。请注意，最新的分布式包中不再支持自动分配 rank，并且 `group_name` 也已弃用。 警告 此方法假定文件系统支持使用 `fcntl` 进行锁定 - 大多数本地系统和 NFS 都支持它。 警告 此方法将始终创建文件，并尽最大努力在程序结束时清理并删除该文件。换句话说，每次使用文件初始化方法进行初始化时，都需要一个全新的空文件才能使初始化成功。如果再次使用了之前初始化（恰好未被清理）使用的同一个文件，这是非预期的行为，通常会导致死锁和失败。因此，即使此方法会尽最大努力清理文件，如果自动删除碰巧未成功，您也有责任确保在训练结束时删除该文件，以防下次再次重用同一文件。如果您计划在同一文件名上多次调用 `init_process_group()`，这一点尤为重要。换句话说，如果文件未被删除/清理，并且您再次对该文件调用 `init_process_group()`，则很可能会发生失败。这里的经验法则是，每次调用 `init_process_group()` 时，都要确保该文件不存在或为空。 import torch.distributed as dist # 应始终指定 rank dist.init_process_group(backend, init_method='file:///mnt/nfs/sharedfile', world_size=4, rank=args.rank) 环境变量初始化# 此方法将从环境变量中读取配置，允许人们完全自定义信息的获取方式。需要设置的变量有： MASTER_PORT - 必需；必须是 rank 0 机器上的空闲端口 MASTER_ADDR - 必需（rank 0 除外）；rank 0 节点的地址 WORLD_SIZE - 必需；可以在此处设置，也可以在 init 函数调用中设置 RANK - 必需；可以在此处设置，也可以在 init 函数调用中设置 rank 为 0 的机器将用于建立所有连接。这是默认方法，这意味着不必指定 `init_method`（或者可以为 env://）。 改善初始化时间# `TORCH_GLOO_LAZY_INIT` - 按需建立连接，而不是使用全连接网格，这可以大大改善非 all2all 操作的初始化时间。 初始化后# 一旦运行了 `torch.distributed.init_process_group()`，就可以使用以下函数。要检查进程组是否已经初始化，请使用 `torch.distributed.is_initialized()`。 class torch.distributed.Backend(name)[source]# 后端的类似枚举的类。 可用的后端：GLOO、NCCL、UCC、MPI、XCCL 以及其他已注册的后端。此类的值是小写字符串，例如 `"gloo"`。它们可以作为属性访问，例如 `Backend.NCCL`。此类可以被直接调用以解析字符串，例如 `Backend(backend_str)` 将检查 `backend_str` 是否有效，如果有效则返回解析后的小写字符串。它也接受大写字符串，例如 `Backend("GLOO")` 返回 `"gloo"`。 注释 存在 `Backend.UNDEFINED` 条目，但仅用作某些字段的初始值。用户既不应直接使用它，也不应假设它的存在。 classmethod register_backend(name, func, extended_api=False, devices=None)[source]# 使用给定的名称和实例化函数注册一个新的后端。第三方 `ProcessGroup` 扩展使用此类方法来注册新的后端。 参数 name (str) – `ProcessGroup` 扩展的后端名称。它应该与 `init_process_group()` 中的名称一致。 func (函数) – 实例化后端的函数处理程序。该函数应该在后端扩展中实现，并接受四个参数，包括 `store`、`rank`、`world_size` 和 `timeout`。 extended_api (bool, 可选) – 后端是否支持扩展的参数结构。默认值：`False`。如果设置为 `True`，后端将获得一个 `c10d::DistributedBackendOptions` 实例，以及一个由后端实现定义的进程组选项对象。 device (str 或 str 列表, 可选) – 此后端支持的设备类型，例如 “cpu”、“cuda” 等。如果为 `None`，则假定同时支持 “cpu” 和 “cuda”。 注释 对第三方后端的这种支持是实验性的，随时可能更改。 torch.distributed.get_backend(group=None)[source]# 返回给定进程组的后端。 参数 group (ProcessGroup, 可选) – 要操作的进程组。默认为通用的主进程组。如果指定了另一个特定组，则调用进程必须是该组的一部分。 返回 给定进程组的后端，以小写字符串形式返回。 返回类型 Backend torch.distributed.get_rank(group=None)[source]# 返回当前进程在给定组中的 rank，否则返回默认组的 rank。Rank 是分配给分布式进程组内每个进程的唯一标识符。它们始终是范围从 0 到 `world_size` 的连续整数。 参数 group (ProcessGroup, 可选) – 要操作的进程组。如果为 `None`，则将使用默认进程组。 返回 进程组的 rank。如果不属于该组，则为 -1。 返回类型 int torch.distributed.get_world_size(group=None)[source]# 返回当前进程组中的进程数。 参数 group (ProcessGroup, 可选) – 要操作的进程组。如果为 `None`，则将使用默认进程组。 返回 进程组的总规模。如果不属于该组，则为 -1。 返回类型 int 关闭# 在退出时通过调用 `destroy_process_group()` 来清理资源非常重要。最简单的遵循模式是在训练脚本中不再需要通信的时候（通常靠近 `main()` 的末尾），通过使用默认值 `None` 作为 `group` 参数调用 `destroy_process_group()` 来销毁每个进程组和后端。该调用应由每个训练器进程执行一次，而不是在外部的进程启动器层执行。如果在超时持续时间内，进程组中的所有 rank 未全部调用 `destroy_process_group()`（尤其是在应用程序中有多个进程组的情况下，例如用于 N-D 并行），则退出时可能会发生挂起。这是因为 `ProcessGroupNCCL` 的析构函数调用了 `ncclCommAbort`，该函数必须被集体调用，但是如果由 Python 的垃圾回收器 (GC) 调用 `ProcessGroupNCCL` 的析构函数，其调用顺序是不确定的。调用 `destroy_process_group()` 有助于确保在各个 rank 之间以一致的顺序调用 `ncclCommAbort`，并避免在 `ProcessGroupNCCL` 的析构函数中调用 `ncclCommAbort`。 重新初始化# `destroy_process_group` 也可用于销毁单个进程组。一个用例可能是容错训练，在运行期间可能会销毁一个进程组，然后初始化一个新的进程组。在这种情况下，关键是要在调用 destroy 之后并在随后初始化之前，使用 `torch.distributed` 原语以外的某种手段来同步训练器进程。由于实现这种同步很困难，这种行为目前不受支持/未经验证，并被视为一个已知问题。如果这是阻碍您使用的案例，请提交 github issue 或 RFC。 组# 默认情况下，集合通信在默认组（也称为 world）上运行，并要求所有进程都进入分布式函数调用。然而，一些工作负载可以从更细粒度的通信中受益。这就是分布式组发挥作用的地方。`new_group()` 函数可用于创建新组，其中包含所有进程的任意子集。它返回一个不透明的组句柄，可以作为 `group` 参数传递给所有的集合通信（集合通信是在某些众所周知的编程模式中交换信息的分布式函数）。 torch.distributed.new_group(ranks=None, timeout=None, backend=None, pg_options=None, use_local_synchronization=False, group_desc=None, device_id=None)[source]# 创建一个新的分布式组。此函数要求主组（即属于分布式作业一部分的所有进程）中的所有进程都进入此函数，即使它们不打算成为该组的成员。此外，组在所有进程中的创建顺序必须相同。 警告 安全的并发使用：当在 NCCL 后端使用多个进程组时，用户必须确保各个 rank 之间的集合通信具有全局一致的执行顺序。如果一个进程内的多个线程发出集合通信，则必须进行显式同步以确保顺序一致。当使用 `torch.distributed` 通信 API 的异步变体时，会返回一个工作对象，并且通信内核会排入单独的 CUDA 流中，从而允许通信和计算重叠。一旦在一个进程组上发出了一个或多个异步操作，在切换使用另一个进程组之前，必须通过调用 `work.wait()` 将它们与其他 CUDA 流进行同步。有关详细信息，请参阅《并发使用多个 NCCL 通信器》<https://docs.nvidia.com/deeplearning/nccl/user-guide/docs/usage/communicators.html#using-multiple-nccl-communicators-concurrently>。 参数 ranks (list[int]) – 组成员 rank 的列表。如果为 `None`，将被设置为所有 rank。默认值为 `None`。 timeout (timedelta, 可选) – 详细信息和默认值请参见 `init_process_group`。 backend (str 或 Backend, 可选) – 要使用的后端。根据构建时的配置，有效值为 `gloo` 和 `nccl`。默认使用与全局组相同的后端。此字段应以小写字符串形式给出（例如 `"gloo"`），也可以通过 `Backend` 属性访问（例如 `Backend.GLOO`）。如果传入 `None`，将使用与默认进程组对应的后端。默认值为 `None`。 pg_options (ProcessGroupOptions, 可选) – 进程组选项，指定在构造特定进程组期间需要传入的附加选项。例如，对于 nccl 后端，可以指定 `is_high_priority_stream`，以便进程组可以获取高优先级的 CUDA 流。有关配置 nccl 的其他可用选项，请参阅 https://docs.nvidia.com/deeplearning/nccl/user-guide/docs/api/types.html#ncclconfig-t use_local_synchronization (bool, 可选)：在进程组创建结束时执行一个组内的局部屏障。这不同之处在于，非成员 rank 不需要调用该 API 并且不加入屏障。 group_desc (str, 可选) – 描述进程组的字符串。 device_id (torch.device, 可选) – 将此进程“绑定”到的单个特定设备，如果提供了此字段，`new_group` 调用将尝试立即为该设备初始化一个通信后端。 返回 可以传递给集合通信调用的分布式组句柄；如果该 rank 不是 `ranks` 的一部分，则为 `GroupMember.NON_GROUP_MEMBER`。 附注：`use_local_synchronization` 不能与 MPI 一起使用。 附注：虽然对于大型集群和小型进程组，`use_local_synchronization=True` 可以显著加快速度，但由于它会改变集群行为（非成员 rank 不加入组屏障 `barrier()`），因此必须小心。 附注：当每个 rank 创建多个重叠的进程组时，`use_local_synchronization=True` 可能导致死锁。为避免这种情况，请确保所有 rank 遵循相同的全局创建顺序。 torch.distributed.get_group_rank(group, global_rank)[source]# 将全局 rank 转换为组 rank。`global_rank` 必须是 `group` 的一部分，否则将引发 `RuntimeError`。 参数 group (ProcessGroup) – 用于查找相对 rank 的 `ProcessGroup`。 global_rank (int) – 要查询的全局 rank。 返回 相对于 `group` 的 `global_rank` 的组 rank 返回类型 int 附注：在默认进程组上调用此函数返回标识本身。 torch.distributed.get_global_rank(group, group_rank)[source]# 将组 rank 转换为全局 rank。`group_rank` 必须是 `group` 的一部分，否则将引发 `RuntimeError`。 参数 group (ProcessGroup) – 用于查找全局 rank 的 `ProcessGroup`。 group_rank (int) – 要查询的组 rank。 返回 相对于 `group` 的 `group_rank` 的全局 rank 返回类型 int 附注：在默认进程组上调用此函数返回标识本身。 torch.distributed.get_process_group_ranks(group)[source]# 获取与 `group` 关联的所有 rank。 参数 group (Optional[ProcessGroup]) – 要从中获取所有 rank 的 `ProcessGroup`。如果为 `None`，则将使用默认进程组。 返回 按组 rank 排序的全局 rank 列表。 返回类型 list[int] 设备网格# `DeviceMesh` 是管理进程组（或 NCCL 通信器）的更高级别抽象。它允许用户轻松创建节点间和节点内的进程组，而无需担心如何正确地为不同的子进程组设置 rank，并且有助于轻松管理这些分布式进程组。`init_device_mesh()` 函数可用于创建新的 `DeviceMesh`，使用描述设备拓扑的网格形状。 class torch.distributed.device_mesh.DeviceMesh(device_type, mesh, *, mesh_dim_names=None, backend_override=None, _init_backend=True)[source]# `DeviceMesh` 代表一个设备网格，其中设备的布局可以表示为 n-d 维数组，而 n-d 维数组的每个值是默认进程组 rank 的全局 ID。`DeviceMesh` 可用于设置集群间的 N 维设备连接，并管理 N 维并行的 `ProcessGroup`。通信可以分别在 `DeviceMesh` 的每个维度上进行。`DeviceMesh` 尊重用户已经选择的设备（即如果用户在 `DeviceMesh` 初始化之前调用 `torch.cuda.set_device`），并且如果用户事先未设置设备，它将为当前进程选择/设置设备。请注意，手动设备选择应该发生在 `DeviceMesh` 初始化之前。当与 DTensor API 一起使用时，`DeviceMesh` 也可用作上下文管理器。 注释 `DeviceMesh` 遵循 SPMD 编程模型，这意味着相同的 PyTorch Python 程序在集群中的所有进程/rank 上运行。因此，用户需要确保网格数组（描述设备布局）在所有 rank 上是相同的。不一致的网格会导致无声的挂起。 参数 device_type (str) – 网格的设备类型。目前支持：“cpu”、“cuda/cuda-like”。 mesh (ndarray) – 描述设备布局的多维数组或整数张量，其中 ID 是默认进程组的全局 ID。 返回 代表设备布局的 `DeviceMesh` 对象。 返回类型 DeviceMesh 以下程序以 SPMD 方式在每个进程/rank
+
+## 参考文件
+
+此技能包含位于 `references/` 中的综合文档：
+
+- **other.md** - 其他文档
+
+当需要详细信息时，请使用 `view` 阅读特定的参考文件。
+
+## 使用此技能
+
+### 面向初学者
+请从 getting_started 或 tutorials 参考文件开始，以了解基础概念。
+
+### 面向特定特性
+请使用相应的类别参考文件（api、guides 等）以获取详细信息。
+
+### 面向代码示例
+上方的快速参考部分包含了从官方文档中提取的常见模式。
+
+## 资源
+
+### references/
+从官方来源提取的整理好的文档。这些文件包含：
+- 详细说明
+- 带有语言标注的代码示例
+- 原始文档链接
+- 用于快速导航的目录
+
+### scripts/
+在此处为常见的自动化任务添加辅助脚本。
+
+### assets/
+在此处添加模板、样板代码或示例项目。
+
+## 说明
+
+- 此技能根据官方文档自动生成
+- 参考文件保留了源文档的结构和示例
+- 代码示例包含语言检测，以实现更好的语法高亮
+- 快速参考模式是从文档中的常见用法示例中提取的
+
+## 更新
+
+要使用更新的文档刷新此技能：
+1. 使用相同的配置重新运行抓取器
+2. 该技能将使用最新信息重新构建