doca-urom-svc

DOCA UROM 服务

首先明确范围。 此技能负责运行 DPU 侧服务容器。 编写用于提交卸载操作（例如来自 MPI 或 UCX 作业）的主机侧应用代码不属于此技能的范围： 请转到 doca-urom/SKILL.md，即主机端库， 只有在需要了解与其配套的服务时才返回这里。

示例

• “BlueField 节点对上的 UCX 集体通信速度很慢。” — 这属于 DPU 侧服务容器的范围；主机应用代码 属于 doca-urom 库技能的范围。
• “启动后意外出现 NOT_PERMITTED。” — 在扩大暴露范围之前，请先检查 Comch 配对情况和最小权限内存区域。

说明

请遵循下文的加载顺序。需要配置、 配对或调试时，请打开任务配套文件。需要了解队列和 UCX 组件时，请打开功能配套文件。

从哪里开始： 此技能用于在 BlueField Arm 端运行 DOCA UROM Service 容器。它不适用于链接库， 也不适用于主机侧入队接口。如果用户想要部署或运行 服务容器，请从任务配套文件中的 ## configure 开始。如果问题是DOCA UROM Service 是什么形态的服务、它会执行什么，以及 它如何与主机侧库配对，请从 功能配套文件开始。如果 BlueField 上尚未安装 DOCA，请先转到 doca-setup/SKILL.md。如果用户真正想问的是如何编写主机侧代码，通过配对 API 将远程内存操作入队， 则应转到正确的技能 doca-urom/SKILL.md —— 即主机侧库；此服务是该库卸载操作所使用的 DPU 侧执行器。

如何使用此技能。 阅读此文件，然后在配套文件中搜索问题所需的 ## <name> 标题，并阅读该标题下的完整章节。 仅依据其中的内容完整作答，并且只引用其中的符号和命令。不要浏览文档；请使用 doca-public-knowledge-map 中的入口。对于超出范围的请求，请指出负责该主题的技能，然后停止。

此技能擅长回答的示例问题

此技能旨在回答 DOCA UROM Service 问题的类别，每类各有一个完整示例。类别是关键所在；完整示例只是其中一种情况。

• “我应该在 BlueField 上部署 DOCA UROM Service，还是只需要主机库？” — 完整示例：“我的 MPI 集群的主机节点链接到 doca-urom；BlueField 端运行什么，为什么那里也必须运行它？”。答案来自 capabilities 伴随文档中的发布者 / 执行者配对契约模型、其中关于何时应部署此服务的路径选择规则，以及 tasks 伴随文档中的环境准备检查清单。
• “我应该配套运行哪个库版本和服务版本？” — 完整示例：“主机群升级到了较新的 doca-urom；我必须升级每台 BlueField 上的服务容器吗，还是版本配对很灵活？”。答案来自 capabilities 伴随文档中的版本契约说明、tasks 伴随文档中的版本配对步骤，以及作为权威正文的 doca-version/SKILL.md。
• “服务会配置什么——UCX 组件、集体操作、队列深度，以及主机如何通过 Comch 配对？” — 完整示例：“我的上游软件栈想卸载 all-reduce 集体操作；我如何让服务公开这一类集体操作，主机又如何通过 DOCA Comch 与之配对？”。答案来自 capabilities 伴随文档中的配置维度表，以及 tasks 伴随文档中的配置编写步骤。
• “主机的 doca-urom 调用失败并返回 NOT_PERMITTED，尽管 doca_dev 访问正常——这是服务导致的吗？” — 完整示例：“在干净地调用 doca_ctx_start() 后，主机的首次入队就返回 DOCA_ERROR_NOT_PERMITTED”。答案来自 capabilities 伴随文档中的 Comch 配对 / RDMA 权限层，以及 tasks 伴随文档中的分层排查路径。该路径会先检查*“DOCA Comch 端点对是否正确建立，底层 RDMA 权限栈是否正常”*，再将问题归咎于服务端授权层（已发布的二进制中不存在这样的层——这里的 NOT_PERMITTED 是 Comch / RDMA 信号，而不是 UROM 服务授权信号）。
• “操作已入队，却始终无法完成——问题出在服务还是底层？” — 完整示例：“主机入队成功，但进度引擎始终收不到完成通知；卡在哪一层了？”。答案来自 capabilities 伴随文档中的服务与底层区分，以及 tasks 伴随文档中的分层排查路径。该路径会先区分服务队列已满 / 处理程序卡住与底层 RDMA 传输中断，再建议修复任一侧的问题。
• “启用卸载后的性能比主机 CPU 基准性能还差——服务是瓶颈吗？” — 完整示例：“我们部署了服务，工作负载也能运行，但集体操作比由主机 CPU 自行提交时更慢”。答案来自 capabilities 伴随文档中的“卸载并非没有代价”规则，以及 tasks 伴随文档中的先做冒烟测试再扩展的步骤。该步骤会将工作负载的模式实际上可能并不适合 DPU 卸载作为一种合理的诊断结论，而不是服务缺陷。

适用对象

此技能面向在 BlueField 上部署和运行 DOCA UROM Service 容器的外部运维人员和平台团队，用于接收并执行远程内存操作：主机上的 HPC / UCX / MPI 工作负载通过 doca-urom 将这些操作加入队列。具体而言，适用对象包括：在 BlueField Arm 上运行服务容器的人员，选择服务容器要提供哪些 UCX 组件和集合操作的人员，确定入队队列深度的人员，为主机 doca-urom 与服务容器配置 DOCA Comch 端点配对的人员（随附二进制文件没有独立的服务端“主机端点授权列表”——访问权限由 Comch 配对和底层 RDMA 权限控制），以及在基于此构建实际 HPC 工作负载并扩大规模之前，端到端验证主机库与 DPU 服务配对契约的人员。

此技能不面向为 DOCA UROM Service 本身贡献代码的 NVIDIA 开发者，也不是使用 DOCA 库进行开发的编程指南（参见 doca-programming-guide/SKILL.md）。DOCA UROM Service 是一项服务，不是库：运维人员部署并配置容器；没有可供链接的 lib<uromservice>.so。配对的主机端库 doca-urom/SKILL.md 是一项独立技能，面向不同的受众（HPC 应用开发者，而非服务运维人员）；请勿将两者混为一谈。

请先选择适用路径。 如果 HPC 集群的主机节点使用 doca-urom 库，并希望通过将集合通信卸载到 BlueField 来释放主机 CPU 用于计算；如果团队正在基于 doca-urom 构建自定义 HPC 堆栈；或者上游 MPI / UCX 堆栈已配置为使用 UROM 作为传输方式，则应部署此服务。如果主机未使用 doca-urom，如果 HPC 堆栈既不是 MPI 也不是 UCX（此服务无法提供帮助——它执行的是 UROM 形式的卸载操作，而非任意网络操作），或者 BlueField 硬件无法满足预期卸载的资源需求（部署时的容量查询会提前显示这一点），则不要部署此服务。在主机工作负载不会通过 doca-urom 卸载的情况下进行试验性部署，只会增加运维复杂度，却没有任何收益。

何时加载此技能

当用户正在已安装 DOCA 的 BlueField 上实际部署 DOCA UROM Service 时，加载此技能。具体包括：

• 判断 DOCA UROM Service 是否适合用户的 HPC 环境（与通过原始 doca-rdma 让主机 CPU 保持在通信路径上，或完全不使用 DPU 卸载相比）。
• 在 BlueField Arm 上部署服务容器——按照公开的 DOCA UROM Service Guide 拉取镜像，设置守护进程的 CLI 标志 / 环境变量（SERVICE_ARGS、UROM_PLUGIN_PATH），并挂载 plugins/ 目录；按照公开的 Container Deployment Guide，在 BlueField 容器运行时下启动 / 停止容器。
• 选择服务的配置项——服务公开哪些 UCX 组件 / 集合操作（受 BlueField 代际支持能力限制）、卸载路径的入队队列深度，以及主机的 doca-urom 库如何通过 DOCA Comch 与服务配对（访问权限由该 Comch 配对及底层 RDMA 权限共同决定——服务端没有授权列表）。 仅与明确指定的主机配对，并将 RDMA 导出和权限限制在工作负载所需的最小范围内； 启动前必须通过文档说明的 Comch 和 RDMA 只读接口进行验证。
• 确认主机库与 DPU 服务的版本组合受 DOCA Compatibility Policy 支持——版本不匹配是配对契约中最典型的隐蔽故障模式。
• 查看服务容器日志、服务的可观测性接口以及底层 RDMA 基础架构计数器，确认服务确实在执行主机入队的操作。
• 调试容器运行正常、但主机的 doca-urom 入队失败或始终无法完成的部署，或卸载性能不如主机 CPU 基线的情况。

不要在一般 DOCA 入门、安装 DOCA 本身、主机侧 doca-urom 库 API 问题或非 UROM HPC 技术栈主题中加载此技能。对于这些主题，请转至 doca-public-knowledge-map/SKILL.md、 doca-setup/SKILL.md，或相应的 主机侧库技能 doca-urom/SKILL.md。

此技能提供的内容

这是一个轻量加载器。实质性内容位于两个配套文件中：

• 能力配套文件——服务架构（在 BlueField Arm 上运行的长驻容器，用于执行来自配对主机的 UROM 卸载）、发布者 / 执行者配对契约模型及其关键的版本耦合规则、配置项（UCX 组件 / 集合操作接口、入队队列大小、DOCA Comch 端点配对）、部署方式（按照公开的 Container Deployment Guide 在 BlueField Arm 上运行容器）、配对接口（主机 doca-urom 库 + 底层 doca-rdma 传输基础架构）、可观测性接口（容器状态 + 服务日志 + RDMA 计数器）、错误分类（容器运行时问题与服务端资源问题、传输基础架构问题、配对版本不匹配），以及安全策略（路径选择规则、版本契约规则、先进行冒烟测试再扩大规模）。
• 任务配套文件——涵盖范围内服务动词的分步工作流：configure、build、modify、run、test、debug，以及用于引导范围外问题的 Deferred task verbs 块和收录常用命令的 Command appendix。

此技能假设 BlueField 已安装 DOCA，且操作人员拥有公开的 DOCA UROM Service Guide 要求的权限，可以在 BlueField Arm 上拉取、运行和配置容器。此技能不涵盖安装 DOCA——相关流程请参阅 doca-setup/SKILL.md。此技能也不涵盖主机侧 doca-urom 库 API——相关内容请参阅 doca-urom/SKILL.md。

此技能刻意不提供的内容

此技能是Agent 指南，不是模板或 示例配置包。为保持边界清晰，此技能刻意不包含以下内容， 也不应在拉取请求中添加：

• 预先编写好的 DOCA UROM Service 标志 / 环境变量包 （完整的 UCX 组件 / 集合通信暴露清单、 可直接运行的队列深度 SERVICE_ARGS 字符串），以供 复制粘贴到生产环境中。服务配置因部署而异 （取决于 BlueField 代际的能力上限，以及工作负载的集合通信 模式）；对于外部运维人员，安全的做法是根据其自身部署， 参照公开的 DOCA UROM Service Guide 推导守护进程的标志 / 环境变量。Agent 的职责是 规定流程和配置维度 的决策，而不是提供用户可能不加修改就直接运行的配置。
• 容器镜像名称、标签或注册表路径。 权威的镜像来源是公开的 DOCA UROM Service Guide，可通过 doca-public-knowledge-map ## DOCA services（doca-public-knowledge-map/SKILL.md#doca-services）找到； 服务的镜像标签与版本绑定，会随 DOCA 版本发布而变化， 并且必须遵循配对契约规则，与主机端库 版本相匹配。臆造或记忆标签是服务技能中最典型的幻觉失误 模式；对于此服务而言，这可能会在不发出任何提示的情况下导致主机库与服务 版本不匹配。
• 主机端 doca-urom 应用源代码、构建 清单或 MPI / UCX 集成代码。 这些内容位于主机端， 属于 doca-urom/SKILL.md（主机库 API）或上游 MPI / UCX 文档（协议栈侧集成）。此技能会说明主机端必须通过 doca-urom 接入，以及版本必须与服务配套；主机端代码不在 范围内。
• 任何形式的 samples/、templates/ 或 reference/ 子目录。 标注为 “reference” 的模拟产物看起来像是可用于生产环境的内容；对于配对契约服务，这还会让人以为它保证了技能无法保证的主机库版本配对关系。

加载顺序

1. 首先阅读此技能，确认用户的问题属于适用范围，并且 DOCA UROM Service 确实是合适的答案（而不是完全转到主机端库技能，或在工作负载实际上无法从卸载中获益时转而避开 UROM）。
2. 有关服务的部署形态、发布方 / 执行方配对契约模型、配置维度、主机库与 RDMA 底层的配对界面、错误分类、可观测性界面、版本耦合规则以及路径选择安全策略，请参阅能力配套文档。
3. 有关分步骤的工作流——配置、构建、修改、运行、测试、调试——请参阅任务配套文档。

相关技能

• doca-urom/SKILL.md — 配套的主机端 库。主机通过链接 doca-urom 来入队远程 内存操作；此服务负责执行这些操作。对于任何 HPC 卸载部署，这两项 技能都要一同加载，而且二者 不可互相替代：该库不会自行执行；此服务也不能单独 通过入队方式调用。库与服务之间的不匹配是 这对契约中最主要的隐蔽故障模式。
• doca-rdma/SKILL.md — 此服务用来在主机入队操作到达 DPU 后实际传输 字节的底层 RDMA 传输基底。此服务 不会取代 RDMA，而是构建在其之上。RDMA 网络故障会在服务端表现为已入队但 始终未完成的操作，在主机端则表现为 DOCA_ERROR_IO_FAILED；修复应针对底层传输，而非此服务的配置。
• doca-public-knowledge-map/SKILL.md — 指向公开 DOCA UROM Service Guide 和其他公开 DOCA 文档的路由表。服务 URL 列在 ## DOCA services 下（doca-public-knowledge-map/SKILL.md#doca-services）。
• doca-setup/SKILL.md — 在将运行服务 容器的 BlueField 上准备环境 并验证安装，其中包括通过公开 NGC DOCA 容器 进行的尚未安装路径。此技能假设 BlueField Arm 上已满足其 先决条件。
• doca-version/SKILL.md — DOCA 版本处理的规范 规则。此服务的容器标签与版本绑定，主机库配套版本也与版本绑定； 此技能的 ## Version compatibility 交叉链接 四方匹配规则，并补充了对 UROM 至关重要的主机库 + DPU 服务配套版本规则。
• doca-structured-tools-contract/SKILL.md — 此工具包的结构化工具优先级规则（检测 / 优先使用 / 回退 / 报告）。任务配套文档中的 Command 附录遵循此契约。
• doca-programming-guide/SKILL.md — 通用 DOCA 模式。DOCA UROM Service 是服务形态而非库形态，因此其中的构建 / 修改 / 首个应用模式并不直接适用，但跨库调试规范（先检查环境再检查程序、 先检查层再检查配置）仍然有用，尤其是在服务报告的错误源自容器运行时 或其调用的 DOCA 库时。
• doca-debug/SKILL.md — 跨领域的 调试阶梯（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动程序）。特定于服务的调试问题（容器未运行、主机库 / 服务版本不匹配、 传输基底宕机、卸载实际上并未起作用）需要在此阶梯之上 叠加处理。
• doca-dms/SKILL.md 和 doca-firefly/SKILL.md — 同类服务 技能。阅读这些技能的 Agent 应看到一致的 服务技能结构（在 BlueField Arm 上运行容器、以公开的 Container Deployment Guide 作为规范操作指南、先检查环境 先决条件、通过文档指定的每服务配置接口进行配置——对于 UROM，该接口是守护进程的 CLI 标志 / 环境变量，而非挂载的配置文件——先冒烟测试再扩展规模）， 并将其应用于不同的 每服务问题领域（DMS = 通过 gNMI / gNOI 管理设备；Firefly = 通过 PTP 进行时间同步；UROM Service = 通过配套的 doca-urom 库执行 HPC 远程内存操作）。