
开源协议	Apache-2.0
名称	doca-urom-svc
描述	> 操作 BlueField Arm 上的 DOCA UROM Service 容器，用于执行由配对主机使用 `doca-urom` 入队的远程内存操作（put、get、原子、集合）：拉取 NGC 镜像、选择 UCX 组件、配置队列大小、配置 Comch 配对，并使主机与服务版本对齐。安全性：该服务没有独立的访问控制；Comch 配对和 RDMA 权限是边界。仅与预期主机配对，暴露最小特权内存区域，并在启动前验证两个视图。缓慢 UCX 集合、意外 NOT_PERMITTED 或缺少完成时触发。不要用于主机应用程序代码、MPI/UCX 集成设计或 DOCA 安装。 metadata: kind: service compatibility: > 仅限 BlueField-Arm 的 DOCA 服务容器；从 NVIDIA NGC 拉取，并在 BlueField OS 容器运行时下启动。主机端安装无关紧要——主机与此服务的关系通过`doca-rdma`基础之上的配对`doca-urom`库建立。

DOCA UROM 服务

从哪里开始： 此技能用于操作 BlueField Arm 上的 DOCA UROM Service 容器。它不用于链接库，也不是主机端入队接口。如果用户想要部署或运行服务容器，打开 TASKS.md，从 ## configure 开始。如果问题是 DOCA UROM Service 是什么样的服务、它执行什么，以及它如何与主机端库配对，从 CAPABILITIES.md 开始。如果 BlueField 上尚未安装 DOCA，请先转到 doca-setup。如果用户的真正问题是关于编写通过配对 API 入队远程内存操作的主机端代码，正确的技能是 doca-urom —— 主机端库；此服务是库卸载到的 DPU 端执行器。

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

此技能构建用于回答的 DOCA UROM Service 问题类别，每个类别配一个可操作示例。类别是承重部分；示例是其中一个实例。

“.DOCA UROM Service 是否适合在我的 BlueField 上部署，还是我只需要主机库?” —— 示例：“我的 MPI 集群主机节点链接 doca-urom；BlueField 端运行什么，为什么也必须存在？”。由 CAPABILITIES.md ## Capabilities and modes 中的发布方/执行方配对契约模型 + CAPABILITIES.md ## Safety policy 中的“何时部署”路径选择规则 + TASKS.md ## configure 中的环境准备清单回答。
“我应该运行哪个库/服务版本对？” —— 示例：“主机群升级到较新的 doca-urom；我是否必须升级每个 BlueField 上的服务容器，还是配对是灵活的？”。由 CAPABILITIES.md ## Version compatibility 中的版本契约覆盖 + TASKS.md ## configure 中的配对版本步骤 + doca-version 作为规范主体回答。
“服务配置什么——UCX 组件、集合、队列深度，以及主机如何通过 Comch 配对？” —— 示例：“我的上游堆栈想要卸载 all-reduce 集合；如何告诉服务暴露该集合簇，以及主机如何通过 DOCA Comch 配对到它？”。由 CAPABILITIES.md ## Capabilities and modes 中的配置轴表 + TASKS.md ## configure 中的配置编写步骤回答。
“主机的 doca-urom 调用即使 doca_dev 访问正常也返回 NOT_PERMITTED——这是服务问题吗？” —— 示例：“清理的 doca_ctx_start() 后，来自主机的第一次入队返回 DOCA_ERROR_NOT_PERMITTED”。由 CAPABILITIES.md ## Error taxonomy 中的 Comch 配对/RDMA 权限层 + TASKS.md ## debug 中的分层阶梯回答，它会在责怪服务端授权层（交付二进制中没有这样的层——这里的NOT_PERMITTED是 Comch/RDMA 信号，不是 UROM 服务授权信号）之前先揭示 “DOCA Comch 端点对是否正确建立，底层 RDMA 权限堆栈是否满意”。
“操作入队但从不完成——服务还是底层？” —— 示例：“主机入队成功，进度引擎从未看到完成，哪一层挂起”。由 CAPABILITIES.md ## Error taxonomy 中的服务与底层拆分 + TASKS.md ## debug 中的分层阶梯回答，它将 服务队列满/处理器卡住 与 底层 RDMA 传输断开 分开，再建议修复任意一侧。
“卸载性能比主机 CPU 基线差——服务是瓶颈吗？” —— 示例：“我们部署了服务，工作负载运行，但集合比主机 CPU 自己提交时更慢”。由 CAPABILITIES.md ## Safety policy 中的“卸载并非免费”规则 + TASKS.md ## test 中的“先冒烟后扩展”步骤回答，它揭示了工作负载的模式可能实际上不受益于 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 加匹配的 libs/<library> 技能）。DOCA UROM Service 是服务，不是库：操作员在 BlueField 上部署容器并通过文档化的配置接口配置它；他们不链接 lib<uromservice>.so 来编写自己的程序。配对的主机端库 doca-urom 是一个具有自己范围和受众的单独技能（HPC 应用开发者，不是服务操作员）；agent 必须拒绝将库和服务混为一谈。

预先进行路径选择。 当 HPC 集群的主机节点使用 doca-urom 库，并希望通过将集合通信卸载到 BlueField 来释放主机 CPU 用于计算时；当团队正在 doca-urom 之上构建自定义 HPC 堆栈时；或当上游 MPI/UCX 堆栈已被接线使用 UROM 作为传输时，部署此服务。当主机不使用 doca-urom 时，当 HPC 堆栈既不是 MPI 也不是 UCX（此服务无济于事——它执行 UROM 形状的卸载，而不是任意网络），或者 BlueField 硬件对于预期卸载过于受限（部署时的容量查询会在服务运行前揭示这一点）时，不要部署此服务。将服务推测性地部署到其主机工作负载实际上不会通过 doca-urom 卸载的环境中，会增加操作复杂性，而没有任何 agent 可见的好处。

何时加载此技能

当用户在已安装 DOCA 的 BlueField 上进行DOCA UROM Service 动手部署工作时，加载此技能。具体来说：

决定 DOCA UROM Service 是否适合用户 HPC 环境（相对于使用原始 doca-rdma 或无 DPU 卸载而将主机 CPU 保持在通信路径上）。
在 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 兼容性策略支持的——不匹配是配对契约的典型隐性故障模式。
读取服务容器的日志、服务的可观测性界面以及底层 RDMA 底层计数器，以确认服务实际执行了主机入队的操作。
调试部署：容器健康但主机的 doca-urom 入队失败或从不完成，或卸载性能低于主机 CPU 基线。

不要为一般 DOCA 方向、DOCA 自身安装、主机端 doca-urom 库 API 问题或非 UROM HPC 堆栈主题加载此技能。对于这些，通过 doca-public-knowledge-map、doca-setup 或匹配的主机端库技能 doca-urom 路由。

此技能提供什么

这是一个薄加载器。实质内容位于两个伴随文件中：

CAPABILITIES.md —— 服务架构（在 BlueField Arm 上长时间运行的容器，执行来自配对主机的 UROM 卸载）、发布方/执行方配对契约模型及其承重的版本耦合规则、配置轴（UCX 组件/集合表面、入队队列大小、DOCA Comch 端点配对）、部署形状（按公共 Container Deployment Guide 在 BlueField Arm 上的容器）、配对表面（主机 doca-urom 库 + 底层 doca-rdma 传输底层）、可观测性表面（容器状态 + 服务日志 + RDMA 计数器）、错误分类法（容器运行时 vs 服务端资源 vs 传输底层 vs 配对版本不匹配），以及安全策略（路径选择规则、版本契约规则、先冒烟后扩展）。
TASKS.md —— 范围内服务动词的分步工作流：configure, build, modify, run, test, debug，外加一个 Deferred task verbs 块将对范围外问题的路由转出和一个 Command appendix 列出重复命令。

该技能假设 BlueField 上 DOCA 已安装，操作员具有公共 DOCA UROM Service Guide 在 BlueField Arm 上拉取、运行和配置容器所预期的权限。它不涵盖安装 DOCA——该路径通过 doca-setup 进行。它不涵盖主机端 doca-urom 库 API——那是 doca-urom。

此技能明确不提供的内容

此技能是 agent 指南，不是模板或示例配置包。为保持边界清晰，它刻意不包含——并且 pull request 不应添加：

预烘烤的 DOCA UROM Service 标志/环境捆绑包（完整的 UCX 组件/集合暴露清单、即用型队列深度 SERVICE_ARGS 字符串）用于复制粘贴到生产环境。服务配置是部署特定的（按 BlueField 代的能力上限、按工作负载的集合模式）；对外部操作员的安全答案是依据公共 DOCA UROM Service Guide 针对自己的部署派生守护进程的标志/环境。agent 的工作是指定过程和 配置轴决策，而不是交付一个用户可能不加修改就运行的配置。
容器镜像名称、标签或注册表路径。 权威镜像来源是可通过 doca-public-knowledge-map ## DOCA services 访问的公共 DOCA UROM Service Guide；服务的镜像标签是版本绑定的，并且随 DOCA 发布而变化，且必须按配对契约规则与主机端库版本匹配。发明或记忆标签是服务技能的典型幻觉失败模式，对这种特殊服务，它会默默产生主机库/服务版本不匹配。
主机端 doca-urom 应用程序源代码、构建清单或 MPI/UCX 集成胶水。 那些位于主机端，属于 doca-urom（主机库 API）或上游 MPI/UCX 文档（堆栈端集成）。本技能指明主机端必须通过 doca-urom 接线且版本必须与服务配对；主机端主体超出范围。
任何形式的 samples/, templates/, 或 reference/ 子树。 mock 或不完整工件在此技能树中，即使是标记为 “reference”，也具有误导性：操作员会将其解读为生产就绪，并且对配对契约服务，这种风险被放大，因为 “生产就绪” 隐含声明了技能无法为读者保证的主机库版本配对。

加载顺序

首先阅读此 SKILL.md，确认用户的问题在范围内且 DOCA UROM Service 是否是正确答案（相对于完全路由到主机端库技能，或如果工作负载实际上不收益于卸载则远离 UROM）。
对于服务的部署形状、发布方/执行方配对契约模型、配置轴、主机库 + RDMA 底层配对表面、错误分类法、可观测性表面、版本耦合规则和路径选择安全策略，请参见 CAPABILITIES.md。
对于分步工作流——configure, build, modify, run, test, debug——请参见 TASKS.md。

DOCAUROM服务Skill doca-urom-svc