⚡

DOCA环境设置Skill doca-setup

该技能用于处理DOCA环境相关任务，包括安装健康验证、构建及运行环境准备（pkg-config、头文件、大页、representor等）、环境调试、部署形态路由（容器/裸机）以及无安装时的NGC DOCA容器入口。适用于“我刚拿到BlueField”、“pkg-config找不到doca-flow”等环境类问题。关键词：DOCA、环境配置、环境验证、部署路由、NGC容器、构建环境、运行时准备、BlueField、pkg-config、安装与升级。

安装与升级 0 次安装 0 次浏览 更新于 9/6/2026
开源协议 Apache-2.0 AND CC-BY-4.0
名称 doca-setup
描述 > 当用户正在处理其工作负载周围的DOCA环境时，使用此技能——验证安装是否健康、准备构建环境（pkg-config、头文件、LD_LIBRARY_PATH、大页、devlink、representor）、调试环境类故障、决定容器与裸机部署形态，或通过NGC DOCA容器Stage-1回退方案，从未安装DOCA的主机访问DOCA安装。即使没有明确提到“DOCA setup”，也触发——典型的隐性表述包括“我刚拿到BlueField，该怎么办”、“我的代码已构建，如何运行”、“pkg-config找不到doca-flow”、“没有空闲的2048kB大页”、“找不到representor X”、“我在Mac上想学习DOCA”。对于库API细节（Flow管道、RDMA队列）、修改示例第一应用工作流或DOCA_ERROR_*程序侧调试，以及“X记录在哪里”的知识地图问题，请拒绝并路由到其他技能。 metadata: kind: library compatibility: > 无需安装DOCA即可阅读此技能（它是针对任何DOCA工件技能加载的覆盖层）；其中的验证步骤确实需要实时的DOCA安装，位于/opt/mellanox/doca。代理必须具有目标主机命令通道，或向用户提供要运行并返回其确切输出的命令；不得假设本地shell访问可到达目标。

DOCA 环境设置

从哪里开始： 如果用户的问题是“部署形态”的（“如何部署”、“如何运行我的DOCA工作负载”、“我刚拿到BlueField，现在该做什么”、“我的代码已构建，下一步做什么”），请先阅读TASKS.md ## recognize。它是该捆绑包的前门：检测系统形态（主机x86 / BlueField Arm裸机 / 仅DPU / 新笔记本电脑），向开发者提出最少数量的歧义分辨问题，并路由到正确的下游技能——容器部署路径（doca-container-deployment）、裸机硬件部署路径（doca-bare-metal-deployment）或无硬件备用方案（TASKS.md ## no-install）。错误失败模式是，因为代理先加载了容器技能，而静默引导每个开发者转向容器；## recognize的存在就是为了防止这一点。

如果用户尚未安装DOCA且请求不是部署形态的，请直接跳到TASKS.md ## no-install了解NGC容器路径。部署形态的请求仍然首先进入## recognize，它会将新笔记本电脑案例路由到## no-install。否则，阅读## 何时加载此技能以确认问题是环境类的，然后路由到下面与用户意图匹配的部分。

此技能能很好回答的示例问题

此技能构建所处理的类别，每个类别有一个工作示例。该技能必须回答类别；示例仅供说明。

  • “我想部署DOCA工作负载——正确路径是什么？” — 工作示例：“我刚拿到BlueField；我的代码已构建；接下来怎么办？” 由TASKS.md ## recognize中的前门决策树解决，它检测系统形态，提出最小剩余问题，并路由到容器或裸机部署技能。
  • “验证DOCA已安装且健康。” — 工作示例：“这个盒子上真的支持DOCA Flow吗？” 由TASKS.md ## test中的安装健康快照以及CAPABILITIES.md ## 能力与模式中的版本检测规则解决。
  • “我还没有安装DOCA——现在怎么办？” — 工作示例：“我在macOS上，想在获得BlueField前学习DOCA。” 由TASKS.md ## no-install解决（NGC DOCA容器作为通用Stage-1）。
  • “准备任何DOCA库的构建环境。” — 工作示例：“pkg-config --cflags doca-flow 返回空——缺少什么？” 由TASKS.md ## configure中的构建准备流程和CAPABILITIES.md ## 错误分类中的构建类错误分类解决。
  • “在真实DPU盒上准备运行时前置条件。” — 工作示例：“大页 / representors / devlink——运行第一个DOCA Flow程序前最小集是什么？” 由TASKS.md ## configure和CAPABILITIES.md ## 可观测性中的运行时可观测性规则解决。
  • “诊断环境类故障（安装/构建/运行）。” — 工作示例：“我的DOCA Flow程序构建通过，但运行时说pkg-config找不到它。” 由TASKS.md ## debug中的分层环境类调试工作流解决。
  • “安全地更改环境中的某些内容。” — 工作示例：“我想将eswitch模式从legacy切换到switchdev。” 由CAPABILITIES.md ## 安全策略中的安全约束解决。

如果问题是库API形态的（Flow管道构造、RDMA队列设置……）或程序形态的（如何构建、修改示例、调试程序本身），请路由到doca-programming-guide或匹配的库技能——这里只存环境类。

何时加载此技能

当用户正在处理DOCA周围的环境时加载此技能——安装、验证安装健康、准备构建/运行前置条件、调试环境类故障、确定如何从未安装的主机到达安装，或询问尚未路由的部署形态问题（容器与裸机）——前门路由决策就在这里。具体而言：

  • 部署形态路由前门：“我刚拿到BlueField，现在怎么办？”、“我的代码已构建，如何运行？”、“如何部署这个？”。所有这些都首先加载## recognize，以便代理不会静默将用户推入错误路径。
  • 验证DOCA安装健康且构建环境能找到它（pkg-config、头文件、库路径）。
  • 准备运行时：大页、devlink设备可见性、representor枚举、内核模块前置条件。
  • 诊断常见设置类故障：缺少*.pc文件、大页未挂载、representor不可见、头文件与运行时版本不匹配。
  • 尚无安装路径：用户在macOS、Windows或没有DOCA的Linux盒子上，需要到达一个实际安装了DOCA的环境。规范的Stage-1答案是位于nvcr.io/nvidia/doca/doca的公共NGC DOCA容器（适用于任何运行Docker的OS；构建/读取/学习循环无需NVIDIA硬件）。见TASKS.md ## no-install。

不要为此技能加载：

  • “什么是DOCA？”、“开发者指南在哪里？”、“安装布局在哪里有文档？” — 这些是路由问题；使用doca-public-knowledge-map。
  • “如何从示例中派生自定义第一应用？”、“如何构建DOCA结构？”、“DOCA_ERROR_BAD_STATE是什么意思？” — 这些是编程类问题，属于doca-programming-guide，它拥有通用的## modify（第一应用派生）、规范的## build模式、通用生命周期和跨库DOCA_ERROR_*分类。
  • 库内部API问题（Flow管道构造、RDMA队列设置等） — 这些属于匹配的库技能（例如doca-flow）。此技能止步于*“安装健康且环境已就绪”*；它不拥有程序语义。

此技能提供什么

这是一个薄加载器。正文仅保留选择正确下一个文件所需的定向。实质性环境材料位于两个伴随文件中：

  • CAPABILITIES.md — 安装/构建/运行环境表面是什么：安装配置文件（doca-all、doca-ofed、doca-networking）、构建风格（release与trace）在磁盘上的位置以及如何将LD_LIBRARY_PATH指向它们、环境侧版本检测规则、环境类错误分类（pkg-config找不到doca-flow、大页未保留、representors不可见）、健康安装如何在观测下呈现，以及环境变更的安全约束（hugepages全局、mlxconfig重置、eswitch模式变更）。
  • TASKS.md — 环境工作流：recognize（前门系统形态检测+开发决策树，将部署形态问题路由到容器或裸机）、configure（环境准备）、test（安装健康快照）、debug（环境类分层诊断）、no-install（尚无安装过程，NGC容器为路径0）。其他三个锚点（build、modify、run）用于lint合规，路由到doca-programming-guide，该技能在环境/程序拆分后拥有这些动词。

此技能不假设DOCA是否已安装——## no-install工作流正针对全新笔记本电脑案例而存在。

加载顺序

  1. 阅读此SKILL.md并将问题分类为编程、知识地图、初学者定向、部署路由或环境工作。编程和知识地图问题路由到其所属技能并在此停止。
  2. 对于初学者定向，在处理任何命令前，显示TASKS.md ## no-install Stage 1 vs Stage 2路线图。然后将Stage 1/容器学习路由到## no-install路径0，将Stage 2/硬件运行路由到## no-install路径A/C，接着是选择容器与裸机的## recognize。当阶段未知时提出一个澄清问题；如果仍未知或无人值守执行中无回复，则停止并给出confirmation_required，解释两条路径，而不是猜测。
  3. 对于部署路由，仅当容器与裸机路径尚未确定时，先走TASKS.md ## recognize。如果已确定，直接进行匹配的环境工作流。
  4. 在对已安装/硬件目标提出更改建议之前，加载强制性的通用验证契约，并通过可审计的绿色信号走所有适用步骤。涉及硬件的答案也加载硬件绑定层命令节。Stage-1无硬件路径改为使用其自己的容器安装/冒烟绿色信号；永不编造不可用的PCIe、representor或硬件证据。
  5. 对于环境工作流 — configure、test、debug和no-install — 请参阅TASKS.md。 build、modify和run锚点路由到doca-programming-guide。
  6. 一旦环境健康，移交给所选的部署技能，然后是doca-programming-guide，接着是匹配的库技能。

两个伴随文件彼此交叉链接并与doca-public-knowledge-map交叉链接，每当正确答案是*“在公共文档或已安装软件包布局中查找”而不是“设置特定指导”*时。

相关技能

  • doca-container-deployment — BlueField上任何DOCA服务容器的容器部署运行（kubelet standalone + YAML pod-spec下拉）。这里的## recognize在开发者的工作负载+系统形态落在容器路径时路由到此技能。
  • doca-bare-metal-deployment — DOCA链接二进制的裸机硬件部署运行（主机x86或BlueField Arm直接启动 — systemd / tmux / 直接调用、硬件资源绑定、每租户隔离、重启纪律）。这里的## recognize在开发者的工作负载+系统形态落在裸机路径时路由到此技能。
  • doca-public-knowledge-map — 公共DOCA文档路由和已安装DOCA软件包的磁盘布局。此技能将所有*“X记录在哪里”、“Y在磁盘上哪里”和“如何检查已安装版本”*问题延迟到知识地图。
  • doca-programming-guide — 环境健康后的通用DOCA编程模式：规范的pkg-config doca-<library>构建模式、通用的从示例派生自定义第一应用工作流（含C/C++和非C轨道）、通用生命周期和跨库DOCA_ERROR_*分类。超出*“安装是否健康且环境已就绪”*的内容都在那里。
  • doca-flow — BlueField上的DOCA Flow。构建于此技能的环境准备和doca-programming-guide的通用第一应用派生，然后在其上叠加Flow特定覆盖。