Skip to content

knowledge-architecture.md

Latest commit

 

History

History
110 lines (81 loc) · 14.8 KB

knowledge-architecture.md

File metadata and controls

110 lines (81 loc) · 14.8 KB
Raw

HCU-TrainFlow-Wiki 与任务档案

TrainFlow 的共享 Wiki 保存在工程 knowledge/，随 Git 提交、克隆和更新。只收录官方资料、跨项目有借鉴意义的通用环境经验，以及模型最终优化里程碑的总结和关键数据。任务 Store 保存完整实验过程；有记录、有测量或一次局部测试通过，都不自动构成共享收录条件。

内容 位置 保存范围
官方引擎、依赖与参考工程 knowledge/projects/<project>/knowledgebase/ 项目内区分上游原文与作者知识，包含教程、PR/review、调用链、优化机制及限制
HCU 仓库知识 HCU-Knowledge；本仓仅保存 knowledge/catalog/external/ 联查入口 不复制 HCU 仓库 Wiki、源码文档、PR 或整套版本证据
工作流方法说明 docs/practices/ 环境发现、配方核对、调参、验证与交付的方法；属于使用文档，不混入知识检索
跨项目环境经验 knowledge/sites/<site-id>/ 经验证、有明确适用条件的硬件/软件/拓扑、环境配方、单测参考与通用排障经验；说明其他项目如何借鉴
模型最终优化里程碑 knowledge/experiments/<case-id>/ 已结束优化阶段的最终基线/结果、关键改动、性能/显存/loss、适用边界和必要证据；不持续追加中间候选
当前任务档案 TRAINFLOW_WORKSPACE 完整日志、trace、checkpoint、数据、开发 checkout、控制状态、看板、事件和任务 experience/reference

站点配置和实测数据可以进入本仓 Wiki；这是 TrainFlow 的知识归属规则。外部 Cookbook/目标项目 PR 的发布要求单独处理，不能用它来阻止本站点知识沉淀。凭据、私钥、访问 token 不属于知识内容，始终不入仓。完整海量数据/模型权重也无需复制进知识库。

任务中的维护时机

共享库统一由 $hcu-trainflow-wiki-search 检索、$hcu-trainflow-wiki-skill-update 维护；后者也维护受资料/源码变化影响的流程、Skill、命令和解析器。主控与独立阶段入口都遵守以下时机，不要求用户另行提醒，不另建周期性全库更新服务。

时机 Agent 应做的事 完成边界
任务初期，已确认模型、环境及实际执行分支后 读取相关官方来源的 observed/reviewed 记录，核对当前版本/接口及所需 PR。已有证据仍适用则复用；过时、缺失或待复核才定向采集和交叉复核 需要该事实的命令/决策前解决关键缺口；无关补采延后，不以全量 Wiki 更新阻挡实验
环境验收后 筛选新发现的通用站点配置、有效配方、实测参考或排障结论，更新 sites/；同时确认实际软件版本是否改变初期判断 记录身份、条件、单位和证据，不能将一次现场成功推广为通用默认
优化阶段完成验收后 提炼最终方案、冻结基线、关键改动、性能/显存、阶段 loss、限制与证据到 experiments/；其后仍可继续扩 DP 和长训 未通过约定数值验收的候选留任务档案；总结限定已验证模型/规模，不把优化结束写成长训已完成
当前请求最终完成、交付前 回看上述处理结果，补充尚未沉淀的可复用经验及最终模型总结，更新已交付 PR/Cookbook 的状态和链接，检查共享页可脱离任务目录阅读和检索 仅环境检查、分析、诊断、交付任务只整理自身实际证据；没有最终优化结果就不创建最终模型总结，没有可共享知识就记录原因
中断恢复、版本/接口发生变化 复用已有处理记录，仅复查变化涉及的来源、页面和用法；取消任务保留私有证据及未完成项 不因轮询、换 Agent 或恢复会话而重复刷新；取消不生成成功总结

flow-start 与 flow-next 在相关边界返回非阻塞的 knowledge_followup，给出更新 Skill、阶段、范围和 disposition_key。它是执行提示，不会自行联网、运行模型或写共享 Wiki，也不改变训练验收状态。Agent 在现有任务计划/看板记录该 key 与 checked-current、updated、deferred（理由及后续时机）或 no-shareable-knowledge；重复看到同一提示时先读处理记录。直接交付模式没有持久 flow，由负责阶段主动执行本表的收尾筛选。

普通问题查询用搜索 Skill，不因此启动更新。官方维护使用来源采集/复核命令；经验提炼由 Agent 阅读实际结果并编写或修订共享页。两条路径都按下文筛选、补齐必要证据、更新导航/索引、运行知识验证与实际检索，涉及工作流变化再做相应回归和本机安装同步。report、flow-advance、experience-sync 只保存私有任务档案，不能视为共享知识已完成更新。权限、限流或待现场验证项如实留待办；不擅自更新 HCU-Knowledge，不替换活动训练依赖。

目录和证据

knowledge/
  projects/<project>/
    README.md                # 项目统一入口，由 wiki-catalog 更新导航
    knowledgebase/
      upstream/
        docs/<source>/       # 官方文档原文，保持上游内容
        prs/<owner--repo>/    # PR 描述、评论、review 与固定代码入口
        source-map/          # 自动生成的完整源码路径
      local/
        overview/            # 工程定位与解释性代码地图
        guides/              # 安装、运行与测试
        topics/              # 机制与调用链
        cases/               # 重大或高价值优化案例
        changes/             # 版本差异、发布入口与维护说明
  evidence/prs/              # PR 原始 JSON，按内容哈希保存，不重复正文
  catalog/                   # 全库来源目录、增量游标、外部联查及旧路径迁移
  sites/
    <site-id>/
      README.md              # 身份、能力、局限、导航和复用入口
      environment.json       # 已观测的环境事实，带时间和来源
      communication.md       # 有效配方与实测解释，可继续增加专题
      evidence/<revision>/   # 本页声明的精选原件，不依赖旧 workspace
      manifest.json          # 入仓证据相对路径、字节数、SHA256、来源/处理方式
  experiments/<case-id>/     # 最终优化里程碑；尚未定案的项目留在 workspace
docs/practices/              # 工作流方法说明，不进入 wiki-search

sources.json 的 knowledge_project 决定资料所属项目，多个关联来源可以共享一个项目（如 MindSpeed 与 MindSpeed-LLM、代码仓与网站教程）。Bridge、Energon 有独立入口，与 Megatron 互相链接。无内容的分类无需空建。upstream 是来源，local 是解释；evidence 是核验原件，不是另一份 Wiki。Release/roadmap 以官方入口和必要的版本解释保留，不单建全量发布页快照目录。

目录迁移保留原页面 ID；旧 ID 中含历史目录名是稳定标识，不是文件路径。catalog/path-migrations.json 供维护程序解析旧记录，旧正文哈希不会因此被重新批准；内容变化仍须复核。重新 wiki-index 即可搜索新位置，不需要重新下载上游或模型。

HCU 仓库知识的分工

HCU 源码、构建运行、PR/MR、优化案例与版本知识由 HCU-Knowledge 维护。TrainFlow 先用 $hcu-knowledge-search 查实际项目/分支/依赖；证据不足再读真实源码与帮助，临时原件留任务缓存。不得因局部 Wiki 更新而重复采集 HCU 仓或顺带更新大库。明确要求修订 HCU 仓库知识时，交给它自己的 update Skill。

TrainFlow 仍负责自身怎样使用这些工具：catalog/external-knowledge.json 登记外部项目、查询入口、需要关注的接口和受影响文件；wiki-routes PROJECT 可列出这些关联。更新 Skill 依据当前大库或实际源码检查接口、输出、参数及副作用，修订本仓 docs/Skills/解析器，记录检查依据及待验证项。可复用使用经验按现有规范进 sites/，通用方法进 docs，临时排查留 workspace。外部登记不承诺后台自动扫描。

HCU TraceLens 是本仓实际集成的定制工具：官方 AMD Wiki 与 HCU 接口文档分开。其 fork 的锁与集成文档通过 thirdparty/manifest.json 的 integration_contracts 关联；依赖 commit 变化会要求复核契约，不再靠复制 fork 的整套来源/Wiki 做绑定。校验不代替接口回归，也不假设 HCU-Knowledge 已覆盖该 fork。

专题页必须有唯一 id、标题、阶段、知识类型、观测/复核日期与验证边界。原命令与最终执行命令、固定源码/镜像/库身份、关键参数、结果、正确性、因果边界、复用前检查和失效触发都应写清。标称值、历史值、本次实测分别表达；“脚本跑完”不能写成环境达标。某站点的 NIC/GID/TC/固定端口等不能成为所有 HCU 集群默认值。

正文使用仓内相对链接；复制所引用的关键原件或注明为选摘及完整来源哈希。完整归档仍可保留在任务 workspace，但仓内页不能只有 objects/<hash> 或任务绝对路径，导致另一个用户无法理解或核验主要结论。manifest.json 校验已经声明的证据，并不证明文字推理正确。两个实证目录在 .gitattributes 中关闭换行归一化，避免 Windows/Linux checkout 改变原件哈希；提交前也应检查 Git 索引中的字节与清单一致。

自动更新时的内容筛选

每次新增或修订共享页，先回答“其他训练任务会在什么问题下复用它”，再决定归属。官方资料按训练、适配、性能、数值、恢复及其依赖关系选择；不能因来自官方或匹配目录通配符就默认全部收录。具体 bug/PR 可揭示通用的生命周期、调度或精度问题，不能仅因粒度细就丢弃。

  • 正文保留：可复用结论、触发条件、适用版本、有效配置、关键数据、证据入口和限制。实际测量节点、镜像、库与命令参数属于复现条件，可继续保留。
  • 过程归档：用户何时同意继续、等待答复或权限、当时谁占卡、临时端口/容器的创建回收、逐次尝试与下一步待办放任务档案。正文需要连接命令时参数化，不把某次任务的设施变成站点固定入口。支撑结论的原始回执保留真实身份，不为精简改写原件。
  • 文档范围：knowledge/sources.json 用 document_globs 发现文档，用带理由的 document_exclusions 排除已审查的低相关内容；可用 document_scope 说明该源与训练的关系。保留完整源码目录，排除全文不妨碍之后按问题查 PR/源码，也不表示上游已删除。新用途成立时重新审查排除规则。
  • 收尾复核：同时检查同站点/同工程总览、专题与案例。精简正文不改变观测日期、验证级别或证据哈希；仍有效的历史结论不因版本旧而自动删除。不要把“安排复核”写成已经存在的后台定时任务。
  • 案例筛选：仅对重大或高价值优化项整理详细案例，优先完善已有案例；小修改更新原有章节、PR 摘要和证据即可，不凑案例。全量及自主更新都遵守 案例选择规则，正常采集与受影响内容复核照常进行。

范围调整涉及已收录文档时，检查作者页链接与固定证据引用，再移除明确排除的生成页及文档 ledger 记录，刷新目录和索引。自动同步不会擅自删除既有页；发现排除规则与保留记录冲突会报出待整理项。程序校验能检查已登记排除规则和文件一致性，正文是否具有复用价值仍由更新 Agent 阅读判断。

统一检索，直接复用现有 CLI

hcu-trainflow --workspace NEW_TASK wiki-search "RCCL RoCE alltoall" --project TRAINFLOW_PROJECT --online-pr off
hcu-trainflow --workspace NEW_TASK wiki-read sites/cfs-roce-bw1000/communication --project TRAINFLOW_PROJECT

wiki-search 索引整个 knowledge/**/*.md，因此必须在写入前筛选内容，不能靠标题里的“实验”“待验证”降低噪声。官方页、可复用环境经验和最终模型里程碑可搜；中间试验不放在 knowledge 下。站点事实不一定属于某个引擎；先按问题跨引擎搜索，再定向过滤，避免 --engine megatron 把通信现场记录排除。JSON/日志/图像由命中文章链接打开，未把所有原件全文自动索引的内容冒充可搜。重点术语、别名、变量名和数值解释须出现在 Markdown。

任务内细节仍用 experience-search、experience-read、reference-query。它们搜索所选 Store，不自动搜索所有 workspace。普通检索不改上游、不重新测量、不执行配方；知识命中也不是健康/性能门槛通过。

里程碑更新协议

  1. 保存完整任务证据和现有 experience/reference，准确记录真实观测时间与上下文。
  2. 先判断收录资格：官方事实按来源规则维护；环境经验必须说明跨项目复用价值、已验证条件及失效边界；模型总结须是当前明确优化阶段的最终里程碑，写清初始基线、最终选择、关键数据、数值验收结果和未达目标。未完成阶段 loss 的性能候选不能写成最终优化成果。
  3. 临时错误、单次调参、未验候选、逐算子中间报告、诊断 trace、命令流水和一次性站点细节只进 workspace/看板/experience。未达到收录条件不创建占位 Wiki。最终总结仅保留理解最终选择所必需的失败/回退边界，不复制所有尝试。Cookbook 交付关联最终总结；草稿和投递过程留任务记录。
  4. 选择支撑总结的最少充分证据，复制到仓内并登记哈希；将原始文件与衍生摘要分开，摘要说明转换与完整原件哈希。新增测量保留版本，当前入口链接到最新适用记录。重新阅读不刷新测量日期。
  5. 与同站点总览、专题、相关模型总结及 Skill 交叉复核。配置/驱动/镜像/库/网络策略改变时标记受影响结论待复核，不能仅刷新数字或目录日期。正文无通用价值时归回任务档案，不为保留页面而强写通用结论。
  6. python scripts/validate_knowledge.py 核对页 ID 和证据。用全新 Store 搜索、打开正文与关键证据，确认主要结论不依赖原任务目录；也复查旧 Store 会更新索引、不再命中已移出的中间页。结构校验不能替代收录价值及事实复核。

官方上游变化继续使用现有 Wiki update 协议；站点记录根据新观测/里程碑维护，不虚构远程自动采集。工作流可自主维护这些局部知识；普通任务不更新 HCU 大领域知识库，也不自动替换活动训练依赖。