doca-flow-tune

DOCA Flow Tune（doca_flow_tune）

示例

• “BlueField 上的 Flow 规则安装速率较低。”——这属于本工具的适用范围。先创建快照，再选择一个调优方向；不要用 flow-perf 基准测试来替代。
• “Tune 可视化步骤为空。”——在更改 Flow 程序之前，先检查 dumper JSON/CSV / analyze JSON。

说明

请遵循下文的加载顺序。打开任务配套文档，了解配置／调优／调试。打开功能配套文档，了解在线与离线模式。不要打开所有配套文件。

命令接口（DOCA 3.5 公共 Flow Tune 指南）。 doca_flow_tune 是一个单一二进制文件，用户选择三个顶层命令之一时，该次调用的角色由所选命令决定——monitor、analyze、visualize（请通过已安装版本的 --help 确认）。3.5 指南中没有 dump、web、import 和 sim_timing；请勿调用它们。计数器转储属于 monitor（使用 --enable-dump，或使用 background 子命令进行不输出到屏幕的转储），而不是独立命令；analyze 接受 export 和 packet-trace 子命令（连字符形式）。monitor 和 analyze 以连接服务的在线模式运行二进制文件，通过 Unix 域套接字连接实时 doca-flow 应用；套接字路径位于随附的 flow_tune_cfg*.json 文件中的 network.server_uds。visualize（以及对先前导出的流水线文件进行离线分析）则以离线／已捕获快照模式运行，处理在线命令之前写入已配置 outputs_directory 的 JSON / CSV 文件。本技能的其余内容（以及功能配套文档／任务配套文档）采用旧式的“服务角色／在线模式／离线模式”表述——此表述与这里的命令接口内部一致：“服务角色”＝连接服务的在线命令（monitor、analyze export／analyze packet-trace）；“在线模式”＝上述任一命令；“离线模式”＝通过已捕获文件运行 visualize。请将命令名称视为主要标识；将“服务端／在线／离线”视为选择子命令后产生的行为结果。

**从这里开始：**这是用于调用统一 DOCA Flow 调优工具 doca_flow_tune 的工具技能。打开任务配套文档，从 ## configure 开始，确定三轴决策（目标 Flow 流水线 × 调优方向 × 测量方式），并选择离线、在线或连接服务模式；接着阅读 ## run，了解“快照 → 分析 → 可视化”循环；然后阅读 ## test，了解批量操作前的冒烟测试覆盖层，该覆盖层会把任何将调优建议应用回 Flow 应用代码的状态变更操作作为关卡。若未安装 DOCA，请先转到 doca-setup/SKILL.md；若用户尚未运行 doca-flow 应用，请转到 doca-flow/SKILL.md——flow-tune 不会创建管道，它只会在库已创建的管道之上进行观测和建议。

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

此技能旨在回答的 doca_flow_tune 问题类别，每类都附有一个完整示例。类别是核心内容；完整示例只是其中一个具体实例。

• “这个问题该用 doca-flow-tune 还是 doca-flow-perf？” — 完整示例：“我的 doca-flow 服务运行在 BlueField-3 上，我认为规则安装速率低于设备可承受的水平；我是应该先测量，还是先调优？”。此问题由功能配套文档中的 调优与性能测试 边界说明回答，并根据测量基线与基于测量基线进行优化的区别，分别指引至 doca-flow-perf/SKILL.md 和本技能。
• “在不触碰数据平面的情况下，捕获实时 doca-flow 流水线的硬件和软件计数器快照。” — 完整示例：“我想针对正在运行的 Flow 端口执行一次无副作用的转储器 / 监控器运行，用于运维速率分析”。此问题由任务配套文档中的快照流程，以及功能配套文档中默认只读的原则回答。
• “根据实际问题，选择合适的调优方向——规则放置、资源提示，还是硬件卸载模式。” — 完整示例：“我的 Flow 管道规则安装速率很低；这是放置问题还是表大小配置问题？”。此问题由功能配套文档中的三轴配置说明，以及任务配套文档中的配置流程回答。
• “在同一个构件中，doca_flow_tune 的服务端角色和客户端 / 消费者角色如何协作？” — 完整示例：“我总是看到关于 Flow Tune 服务端和 Flow Tune 客户端的介绍；我运行的是哪个二进制文件？”。此问题由功能配套文档中的 一个二进制文件，两种角色 说明，以及任务配套文档中的相应指引回答。
• “如何将 flow-tune 推荐的参数更改应用回我的 doca-flow 应用，同时不破坏数据平面？” — 完整示例：“分析步骤建议为我的管道使用不同的表大小配置；我该如何应用？”。此问题由任务配套文档中的 建议 → 对 Flow 程序进行最小差异修改 流程，以及任务配套文档中的先进行冒烟测试再批量操作的规则回答。
• “doca_flow_tune 没有报告结果 / 与 Flow 应用不一致 / 无法附加——这意味着什么？” — 完整示例：“工具可以运行，但可视化步骤生成的 mermaid 图为空”。此问题由功能配套文档中的分层错误分类，以及任务配套文档回答。

受众

本技能面向外部运维人员、性能工程师、DOCA Flow 应用开发者，以及需要了解、评估或改进用户实际安装环境和设备上运行的 doca-flow 管道行为的 AI Agent。 具体包括：

• 希望只读查看现有管道及其硬件／软件计数器变化情况，再据此建议是否进行更改的运维人员。
• 已有 doca-flow-perf 基线、希望将测量转化为优化的性能工程师——选择调优方向，并确定 doca-flow 程序中的哪个参数可以发挥作用。
• 使用离线分析 + 可视化流程、希望在不重新插桩程序的情况下了解管道布局的 Flow 开发者。
• 执行“管道是否按预期运行，以及非变更型调优建议是否有帮助”这一排查步骤的 AI Agent。

本技能不适用于调试 doca_flow_tune 源代码的用户，不能替代 DOCA Flow Tune 公开指南，不用于学习 doca-flow API（参见 doca-flow/SKILL.md），也不用于介绍基线测量方法——这属于 doca-flow-perf/SKILL.md 的内容。

doca_flow_tune 以单一工具形式交付（一个二进制文件，以及配套的分析器／可视化脚本和 JSON 配置模板）——以往的服务端和客户端角色都包含在这一制品中，而不是由两个可执行文件分别承担。它采用与该套件其余部分相同的 kind: tool 三文件结构。

语言范围

本技能规定如何调用 doca_flow_tune、如何解读其输出，以及如何将建议转化为所观察的 DOCA Flow 应用的代码更改。此工具不是编程目标——没有可供链接的公开 API；工作流是配置 JSON、运行、读取输出，并对周边的 doca-flow 程序提出最小差异更改建议。有关建议所针对的 doca-flow API，请参见 doca-flow/SKILL.md； 有关跨语言应用模式，请参见 doca-programming-guide/SKILL.md。

何时加载此技能

当用户需要，或 Agent 需要针对正在运行或计划中的 doca-flow 应用调用 doca_flow_tune，以评估、转储、可视化、分析或调优该管道时，加载此技能。具体包括：

• 选择要使用的角色（基于捕获的配置 + 状态进行离线分析／可视化；针对实时应用运行在线转储器／监控器；或使用连接到应用的服务端角色）。
• 选择要咨询的调优方向（规则放置、资源提示／表大小、硬件卸载模式）。
• 选择要对照的测量指标（规则安装速率、查找延迟、硬件计数器增量）——这些指标不能互换；请使用先前 doca-flow-perf 基线指定的指标。
• 围绕拟议的 Flow 程序更改，记录有据可查的更改前／后对照（JSON 配置路径、命令行、DOCA 版本、设备、环境、未经删减的工具输出）。
• 诊断空会话、退化的可视化图表，或与实时计数器相矛盾的分析建议。

不要在进行通用 DOCA 入门、Flow 程序 API 工作、安装或纯测量方法研究时加载此技能——请转到 doca-public-knowledge-map/SKILL.md、 doca-flow/SKILL.md、 doca-setup/SKILL.md 或 doca-flow-perf/SKILL.md。

此技能提供的内容

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

• capabilities 配套文件 — 说明 doca_flow_tune 会观察和 推荐哪些内容：统一产物的分解（同一个二进制文件中的服务端角色
  • 客户端 / 消费者角色）、三轴配置模型（调优轴 × 测量 × 范围：哪个 pipe / port / app）、已记录的离线 / 在线 / attach 模式、JSON 配置文件结构（公开发布的 flow_tune_cfg_public.json 模板，以及仅硬件和仅软件变体）、转储器 / 监控器 / 分析器 / 可视化工具的输出界面、版本叠加（此工具使用它所观察的 doca-flow 库版本；规范规则位于 doca-version/SKILL.md）、 分层错误分类 （config-syntax / attach-failed / pipe-not-found / measurement-unsound / recommendation-unactionable / version / cross-cutting）、可观测性立场（此工具本身就是 Flow 流水线的 可观测性原语），以及安全策略：由于建议会应用到实时 Flow 状态中， 任何会修改状态的建议应用操作都属于高风险操作。
• tasks 配套文件 — 针对范围内任务动词的分步工作流： install（转至 setup；二进制文件已随附）、 configure（三轴决策 + JSON 配置 + 模式选择）、 build（转至 install；二进制文件已随附）、modify （通过最小差异将建议应用回 Flow 程序）、run （快照 → 分析 → 可视化流程）、test （评估循环 — 预热、稳定状态、前 / 后配对、 客户端 / 服务端 / Flow 版本匹配）、debug（逐层排查错误分类）、 use（Agent 侧消费 flow-tune 输出的工作流），另有 Deferred task verbs 区块和 Command appendix。

该技能假设主机上已安装 DOCA（或正在运行公开的 NGC DOCA 容器）， 并且已按照 doca-flow/SKILL.md 技能创建并验证了 doca-flow 应用。缺少这些前提条件，调优会话就没有可供观察的对象。

此技能有意不包含的内容

此技能是Agent 指南，而非示例或脚本包。 为明确边界，此技能有意不包含以下内容，而且不应在拉取请求中添加：

• **作为契约引用的逐字标志清单、子命令名称、JSON 配置字段 名称或默认端点路径。**公开的 DOCA Flow Tune 指南（可通过 doca-public-knowledge-map ## DOCA tools (doca-public-knowledge-map/SKILL.md#doca-tools)) 访问）与已安装的 --help 共同构成事实依据；随附的 flow_tune_cfg*.json 模板则是 JSON 架构的第二个依据。将这些内容复制到此处， 会因工具演进而过时。
• **预制的示例输出（转储器 CSV 列、分析器 JSON 字段名称、可视化工具的 mermaid 输出）。**输出因安装环境、 设备、固件和版本而异；固定于某个平台的已采集示例会误导其他地方的操作人员。
• 用于消费 flow-tune 输出的包装器、解析器或脚本。 用户安装目录中随附的 scripts/ 目录包含 供应商提供的辅助工具（例如 flow_json_diff.py、 flow_mermaid_diff.py、hw_counters_csv_analyzer.py）；正确的 答案是*"阅读已安装版本随附的脚本"*。
• **预制的调优建议。**建议因安装环境、设备、固件和工作负载而异；Agent 始终会根据用户的实际会话重新推导建议。
• **samples/、templates/ 或 reference/ 子目录。**模拟的 调优方案看起来像可用于生产环境的内容，会造成误导。

加载顺序

1. 首先阅读此技能，确认用户的问题属于适用范围（用户确实想针对 doca-flow 流水线调用 doca_flow_tune，而不是测量基线性能或了解 Flow API）。
2. 关于 doca_flow_tune 的观测内容、单二进制文件／双角色的划分、三轴模型、版本覆盖、错误分类、可观测性界面和安全态势，请参阅能力配套文档。
3. 关于已记录的调用方式，以及快照 → 分析 → 可视化 → 提议 → 冒烟测试工作流（install、configure、build、modify、run、test、debug、use），请参阅任务配套文档。

相关技能

• doca-flow/SKILL.md — 此工具观测和调优的基础库。flow-tune 报告的管道／条目／规则界面由 doca-flow 程序代码创建；建议会通过通用的修改示例工作流返回到该程序。
• doca-flow-perf/SKILL.md — 同系列的测量工具。规则是：doca-flow-perf 测量基线；doca-flow-tune 在此基础上提出优化建议。没有 perf 提供的基线数值就使用 tune 的 Agent 是在盲目优化；没有明确问题就使用 perf 的 Agent 则是在为基准测试而基准测试。
• doca-public-knowledge-map/SKILL.md — 用于导航至 docs.nvidia.com 上的 DOCA Flow Tune 公开页面，以及其他公开 DOCA 文档。
• doca-version/SKILL.md — 规范的版本检测链、四方匹配、NGC 语义，以及“以头文件为准而非文档”的规则。本技能中的 ## Version compatibility 覆盖内容是对其的轻量扩展。
• doca-debug/SKILL.md — 跨领域的调试阶梯。Flow-tune 会呈现自身的错误分类；如果最终发现原因在 DOCA 底层（驱动、固件、NUMA），则由 tune 的错误分类移交给 doca-debug。
• doca-structured-tools-contract/SKILL.md — 此工具包的检测 → 优先使用 → 回退 → 报告契约。任务配套文档中的命令附录遵循该契约。
• doca-setup/SKILL.md — 环境准备、安装验证、大页、NUMA，以及我还没有安装环境时通过公开 NGC DOCA 容器进行操作的路径。
• doca-hardware-safety/SKILL.md — 跨领域的硬件安全元策略，本技能的 ## Safety policy 会在其基础上增加覆盖规则。