{
"canonical_name": "noahgolmant/pytorch-hessian-eigenthings",
"compilation_id": "pack_2c4d83945d5a4bb4afbe27117ebc1bc2",
"created_at": "2026-05-16T15:03:26.623322+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install hessian-eigenthings` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install hessian-eigenthings",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_c8dd4b41232f4b80bb1c4448f20b523e"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_60e0f4ffb5f798e55622480bf7cf5501",
"canonical_name": "noahgolmant/pytorch-hessian-eigenthings",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/noahgolmant/pytorch-hessian-eigenthings",
"slug": "pytorch-hessian-eigenthings",
"source_packet_id": "phit_4b0f104cec4d4ab58d90ab1b7f6f7702",
"source_validation_id": "dval_8a294b814b3b4037a843c14c510c47df"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": null,
"github_stars": null,
"one_liner_en": "pytorch-hessian-eigenthings",
"one_liner_zh": "pytorch-hessian-eigenthings",
"primary_category": {
"category_id": "software-development",
"confidence": "medium",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, cli"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "pytorch-hessian-eigenthings",
"title_zh": "pytorch-hessian-eigenthings 能力包",
"visible_tags": [
{
"label_en": "Knowledge Retrieval",
"label_zh": "知识检索",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-knowledge-retrieval",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Automated Workflow",
"label_zh": "自动化工作流",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-automated-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_4b0f104cec4d4ab58d90ab1b7f6f7702",
"page_model": {
"artifacts": {
"artifact_slug": "pytorch-hessian-eigenthings",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install hessian-eigenthings",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/noahgolmant/pytorch-hessian-eigenthings#readme",
"verified": true
}
],
"display_tags": [
"知识检索",
"知识库问答",
"流程自动化",
"自动化工作流",
"评测体系"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "pytorch-hessian-eigenthings"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "仓库名 `pytorch-hessian-eigenthings` 与安装入口 `hessian-eigenthings` 不完全一致。",
"category": "身份坑",
"evidence": [
"identity.distribution | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | repo=pytorch-hessian-eigenthings; install=hessian-eigenthings"
],
"severity": "medium",
"suggested_check": "在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。",
"title": "仓库名和安装名不一致",
"user_impact": "用户照着仓库名搜索包或照着包名找仓库时容易走错入口。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Python Error: the following arguments are required: experimentname",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_24f46464d79f4ae3830f046c077a2574 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/39 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Python Error: the following arguments are required: experimentname",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.0a2 — packaging fix",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_7540a696b30c46cdba07c12f33388567 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a2 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.0.0a2 — packaging fix",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.0a3 — fix lanczos OOM",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_e5e68e2f24e1436cb8f3c2f11cefe326 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a3 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.0.0a3 — fix lanczos OOM",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.0a4 — backend handles CPU-generator + CUDA-tensor combo",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_914b7653aa8b4ef2844a2b4690fab2ad | https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a4 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.0.0a4 — backend handles CPU-generator + CUDA-tensor combo",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.0a5 — comprehensive LLM-scale memory fixes + regression tests",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_509356ab9b68434992d7237219952ba6 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.0.0a5 — comprehensive LLM-scale memory fixes + regression tests",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：RuntimeError: One of the differentiated Tensors appears to not have been used in the graph.",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_f79a3a34cbab435cb3730b7ae17cf492 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/30 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：RuntimeError: One of the differentiated Tensors appears to not have been used in the graph.",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：ValueError: PENet on the Kitti benchmark suite",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_850f8cf0010c4d269ab71d864610097a | https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/41 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：ValueError: PENet on the Kitti benchmark suite",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：AttributeError: 'HVPOperator' object has no attribute 'zero_grad'",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_b515f5c06a5744b19b667bcbc8123348 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/38 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：AttributeError: 'HVPOperator' object has no attribute 'zero_grad'",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 15 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": null,
"forks": null,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": null
},
"source_url": "https://github.com/noahgolmant/pytorch-hessian-eigenthings",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "pytorch-hessian-eigenthings",
"title": "pytorch-hessian-eigenthings 能力包",
"trial_prompt": "# pytorch-hessian-eigenthings - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 pytorch-hessian-eigenthings 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: pytorch-hessian-eigenthings 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-project-intro：项目简介。围绕“项目简介”模拟一次用户任务，不展示安装或运行结果。\n2. page-hessian-basics：Hessian 矩阵基础概念。围绕“Hessian 矩阵基础概念”模拟一次用户任务，不展示安装或运行结果。\n3. page-core-architecture：核心架构设计。围绕“核心架构设计”模拟一次用户任务，不展示安装或运行结果。\n4. page-operators：曲率算子详解。围绕“曲率算子详解”模拟一次用户任务，不展示安装或运行结果。\n5. page-algorithms：特征分解算法。围绕“特征分解算法”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-project-intro\n输入：用户提供的“项目简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-hessian-basics\n输入：用户提供的“Hessian 矩阵基础概念”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-core-architecture\n输入：用户提供的“核心架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-operators\n输入：用户提供的“曲率算子详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-algorithms\n输入：用户提供的“特征分解算法”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-project-intro：Step 1 必须围绕“项目简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-hessian-basics：Step 2 必须围绕“Hessian 矩阵基础概念”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-core-architecture：Step 3 必须围绕“核心架构设计”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-operators：Step 4 必须围绕“曲率算子详解”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-algorithms：Step 5 必须围绕“特征分解算法”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://news.ycombinator.com/item?id=48132232\n- https://github.com/noahgolmant/pytorch-hessian-eigenthings#readme\n- README.md\n- mkdocs.yml\n- pyproject.toml\n- docs/concepts/what-is-the-hessian.md\n- docs/concepts/why-hvp-not-full-h.md\n- hessian_eigenthings/__init__.py\n- hessian_eigenthings/operators/base.py\n- hessian_eigenthings/batching.py\n- hessian_eigenthings/linalg/backend.py\n- hessian_eigenthings/operators/__init__.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 pytorch-hessian-eigenthings 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: ValueError: PENet on the Kitti benchmark suite（https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/41）；github/github_issue: RuntimeError: One of the differentiated Tensors appears to not have been（https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/30）；github/github_issue: AttributeError: 'HVPOperator' object has no attribute 'zero_grad'（https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/38）；github/github_issue: Python Error: the following arguments are required: experimentname（https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/39）；github/github_release: v1.0.0a5 — comprehensive LLM-scale memory fixes + regression tests（https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a5）；github/github_release: v1.0.0a4 — backend handles CPU-generator + CUDA-tensor combo（https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a4）；github/github_release: v1.0.0a3 — fix lanczos OOM（https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a3）；github/github_release: v1.0.0a2 — packaging fix（https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a2）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "ValueError: PENet on the Kitti benchmark suite",
"url": "https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/41"
},
{
"kind": "github_issue",
"source": "github",
"title": "RuntimeError: One of the differentiated Tensors appears to not have been",
"url": "https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/30"
},
{
"kind": "github_issue",
"source": "github",
"title": "AttributeError: 'HVPOperator' object has no attribute 'zero_grad'",
"url": "https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/38"
},
{
"kind": "github_issue",
"source": "github",
"title": "Python Error: the following arguments are required: experimentname",
"url": "https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/39"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.0.0a5 — comprehensive LLM-scale memory fixes + regression tests",
"url": "https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a5"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.0.0a4 — backend handles CPU-generator + CUDA-tensor combo",
"url": "https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a4"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.0.0a3 — fix lanczos OOM",
"url": "https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a3"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.0.0a2 — packaging fix",
"url": "https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a2"
}
],
"status": "已收录 8 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "pytorch-hessian-eigenthings",
"effort": "安装已验证",
"forks": null,
"icon": "code",
"name": "pytorch-hessian-eigenthings 能力包",
"risk": "可发布",
"slug": "pytorch-hessian-eigenthings",
"stars": null,
"tags": [
"知识检索",
"知识库问答",
"流程自动化",
"自动化工作流",
"评测体系"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/noahgolmant/pytorch-hessian-eigenthings 项目说明书\n\n生成时间：2026-05-16 15:01:33 UTC\n\n## 目录\n\n- [项目简介](#page-project-intro)\n- [Hessian 矩阵基础概念](#page-hessian-basics)\n- [核心架构设计](#page-core-architecture)\n- [曲率算子详解](#page-operators)\n- [特征分解算法](#page-algorithms)\n- [参数工具模块](#page-param-utils)\n- [损失函数模块](#page-loss-functions)\n- [HuggingFace 模型集成](#page-huggingface-integration)\n- [分布式训练支持 (DDP)](#page-distributed-ddp)\n- [安装与配置](#page-installation)\n\n\n\n## 项目简介\n\n### 相关页面\n\n相关主题：[Hessian 矩阵基础概念](#page-hessian-basics), [安装与配置](#page-installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/CONTRIBUTING.md)\n- [mkdocs.yml](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/mkdocs.yml)\n- [hessian_eigenthings/algorithms/lanczos.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/lanczos.py)\n- [hessian_eigenthings/operators/hessian.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/hessian.py)\n- [hessian_eigenthings/operators/ggn.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/ggn.py)\n- [hessian_eigenthings/algorithms/trace.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/trace.py)\n- [examples/huggingface_tiny_gpt2.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/examples/huggingface_tiny_gpt2.py)\n \n\n# 项目简介\n\n## 概述\n\npytorch-hessian-eigenthings 是一个专为 PyTorch 模型设计的**Hessian 特征分解高效计算库**。该项目由 UC Berkeley 的 RISELab 开发，旨在为大语言模型（LLM）和深度神经网络的曲率分析提供生产级工具。\n\n资料来源：[README.md:1]()\n\n## 核心定位\n\n该库的核心价值在于解决以下关键问题：\n\n- **Hessian 特征值计算**：在传统方法中，直接计算 Hessian 矩阵的特征分解需要 O(n²) 的存储和 O(n³) 的计算复杂度，对于拥有数十亿参数的现代深度学习模型而言完全不可行\n- **曲率算子抽象**：通过定义统一的 `CurvatureOperator` 接口，允许用户在不显式构造 Hessian 矩阵的情况下进行曲率分析\n- **多种曲率算子支持**：支持 Hessian、广义 Gauss-Newton（GGN）等多种曲率矩阵的特征分解和迹估计\n\n资料来源：[hessian_eigenthings/operators/hessian.py:1-20]()\n\n## 技术架构\n\n### 模块层次结构\n\n```\nhessian_eigenthings/\n├── algorithms/ # 特征分解和迹估计算法\n│ ├── lanczos.py # Lanczos 算法（特征值计算）\n│ └── trace.py # Hutchinson / Hutch++ 算法（迹估计）\n├── operators/ # 曲率算子实现\n│ ├── hessian.py # Hessian 算子\n│ └── ggn.py # 广义 Gauss-Newton 算子\n├── loss_fns/ # 损失函数模块\n│ ├── standard.py # 标准损失函数\n│ ├── huggingface.py # HuggingFace 模型支持\n│ └── _fused_ce_hvp.py # 融合的交叉熵 HVP\n└── backends/ # 线性代数后端\n```\n\n资料来源：[mkdocs.yml:1-20]()\n\n### 设计模式\n\n该项目采用**算子-算法分离**的设计模式：\n\n| 组件 | 职责 | 关键类/函数 |\n|------|------|-------------|\n| **CurvatureOperator** | 定义曲率矩阵接口，实现 matvec 操作 | `HessianOperator`, `GGNOperator` |\n| **LinAlgBackend** | 封装底层向量运算，确保数值稳定性 | `SingleDeviceBackend` |\n| **Algorithm** | 纯算法实现，仅依赖算子接口 | `lanczos()`, `hutchinson()`, `hutch_plus_plus()` |\n\n资料来源：[CONTRIBUTING.md:20-30]()\n\n### 工作流程图\n\n```mermaid\ngraph TD\n A[用户模型 + 数据] --> B[CurvatureOperator]\n B --> C[matvec 操作]\n C --> D{Lanczos 算法 / Hutch++ 算法}\n D --> E[特征值 & 特征向量]\n D --> F[矩阵迹估计]\n \n B --> G[HessianOperator]\n B --> H[GGNOperator]\n \n G --> I[autograd 双反向传播]\n G --> J[有限差分法]\n \n H --> K[分析路径]\n H --> L[autograd 路径]\n```\n\n## 核心算子\n\n### HessianOperator\n\n`HessianOperator` 是最基础的曲率算子，直接计算损失函数关于参数的 Hessian 矩阵与向量的乘积（Hessian-Vector Product, HVP）。\n\n**支持的 HVP 计算方法**：\n\n| 方法 | 描述 | 适用场景 |\n|------|------|----------|\n| `autograd` | 通过 `torch.autograd.grad` 实现精确双反向传播 | 参数规模 ≤ 7B 的单设备分析 |\n| `finite_difference` | 中心差分 `(∇L(θ+εv) − ∇L(θ−εv)) / 2ε` | FSDP/HSDP/TP 等分布式训练场景 |\n\n资料来源：[hessian_eigenthings/operators/hessian.py:10-30]()\n\n### GGNOperator\n\n广义 Gauss-Newton（GGN）算子是一种 **Hessian 的正向近似**，计算量更低且数值更稳定。\n\n**两种 matvec 实现路径**：\n\n| 路径 | 原理 | 内存开销 | 支持场景 |\n|------|------|----------|----------|\n| `analytical`（默认）| 有限差分 JVP + 分析损失 HVP + 单次反向传播 | 匹配单次训练步 | LLM 规模应用 |\n| `autograd` | `torch.func.jvp` + 自动双反向 + `torch.func.vjp` | 随输出规模增长 | 任意损失函数 |\n\n资料来源：[hessian_eigenthings/operators/ggn.py:40-60]()\n\n### 融合 CE HVP 优化\n\n针对大词表语言模型的交叉熵损失，库中实现了高度优化的 HVP 核：\n\n| 后端 | 特点 | 性能提升 |\n|------|------|----------|\n| `triton`（CUDA） | 零中间张量，仅输出缓冲区 | ~3.4x 加速，2x 内存降低 |\n| `torch.compile` | Inductor 核融合 | ~2.6x 加速，2x 内存降低 |\n| `eager` | 朴素 PyTorch 实现 | 基准参考 |\n\n资料来源：[hessian_eigenthings/loss_fns/_fused_ce_hvp.py:1-50]()\n\n## 核心算法\n\n### Lanczos 算法\n\nLanczos 算法是计算 **k 个极端特征值**的标准选方法，特别适合稀疏或结构化矩阵。通过 `lanczos_tridiagonal` 生成三对角矩阵，然后通过特征分解恢复目标特征值。\n\n**支持的特征值选择模式**：\n\n| 模式 | 含义 | 典型用途 |\n|------|------|----------|\n| `LM` | Largest Magnitude | 寻找最大曲率方向 |\n| `LA` | Largest Algebraic | 最大特征值 |\n| `SA` | Smallest Algebraic | 最小特征值（接近零区域） |\n\n资料来源：[hessian_eigenthings/algorithms/lanczos.py:20-40]()\n\n### 迹估计算法\n\nHutchinson 和 Hutch++ 算法通过随机投影估计矩阵迹，适用于计算 **Hessian 矩阵的谱范数/条件数**。\n\n```mermaid\ngraph LR\n A[随机向量 v] --> B[计算 Av]\n B --> C[v^T A v]\n C --> D{重复 m 次}\n D --> E[迹 ≈ (1/m) Σ v_i^T A v_i]\n```\n\n资料来源：[hessian_eigenthings/algorithms/trace.py:10-50]()\n\n## 使用示例\n\n### 基本用法（HuggingFace 模型）\n\n```python\nfrom hessian_eigenthings import HessianOperator, lanczos\nfrom hessian_eigenthings.loss_fns import hf_lm_loss\n\nfull_op = HessianOperator(model=model, dataloader=dataloader, loss_fn=hf_lm_loss())\neig_full = lanczos(full_op, k=3, max_iter=20, tol=1e-3, seed=0)\n```\n\n资料来源：[examples/huggingface_tiny_gpt2.py:40-50]()\n\n### 仅分析注意力层\n\n```python\nattn_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=hf_lm_loss(),\n param_filter=match_names(\"transformer.h.*.attn.*\"),\n)\neig_attn = lanczos(attn_op, k=3, max_iter=20, tol=1e-3, seed=0)\n```\n\n资料来源：[examples/huggingface_tiny_gpt2.py:55-65]()\n\n## 依赖与环境\n\n### 项目依赖\n\n| 依赖类型 | 核心依赖 | 可选依赖 |\n|----------|----------|----------|\n| 必须 | `torch`, `curvlinops` | `transformers`, `transformer-lens` |\n| 开发 | `pytest`, `ruff`, `black`, `mypy` | `triton` (CUDA) |\n\n资料来源：[CONTRIBUTING.md:8-15]()\n\n### 开发环境配置\n\n```bash\ngit clone https://github.com/noahgolmant/pytorch-hessian-eigenthings\ncd pytorch-hessian-eigenthings\nuv sync --group dev --group docs --extra transformers --extra transformer-lens --extra curvlinops\n```\n\n## 致谢与引用\n\n该项目由 Noah Golmant、Zhewei Yao、Amir Gholami、Michael Mahoney 和 Joseph Gonzalez 在 UC Berkeley 的 RISELab 开发完成。\n\n**去膨胀功率迭代**基于 [HessianFlow](https://github.com/amirgholami/HessianFlow)（Z. Yao et al., NeurIPS 2018）实现。**加速随机功率迭代**来自 C. De Sa et al. 的研究成果。\n\n引用格式：\n\n```bibtex\n@misc{hessian-eigenthings,\n author = {Noah Golmant and Zhewei Yao and Amir Gholami and Michael Mahoney and Joseph Gonzalez},\n title = {pytorch-hessian-eigenthings: efficient PyTorch Hessian eigendecomposition},\n month = oct,\n year = 2018,\n version = {1.0},\n url = {https://github.com/noahgolmant/pytorch-hessian-eigenthings}\n}\n```\n\n资料来源：[README.md:10-25]()\n\n## 质量保证\n\n项目在 CI 中运行以下检查确保代码质量：\n\n| 检查项 | 命令 | 说明 |\n|--------|------|------|\n| 代码格式 | `ruff check .` | Python linting |\n| 代码风格 | `black --check .` | PEP 8 格式化 |\n| 类型检查 | `mypy` | 静态类型验证 |\n| 单元测试 | `pytest` | 回归测试 |\n| 文档构建 | `mkdocs build --strict` | 文档验证 |\n\n资料来源：[CONTRIBUTING.md:15-25]()\n\n## 适用场景总结\n\n| 场景 | 推荐算子 | 推荐算法 |\n|------|----------|----------|\n| 小型模型特征分析 | `HessianOperator` | `lanczos()` |\n| LLM 曲率分析 | `GGNOperator` (analytical) | `lanczos()` |\n| 谱范数估计 | 任意算子 | `hutch_plus_plus()` |\n| 分布式训练环境 | `HessianOperator` (finite_difference) | `lanczos()` |\n| HuggingFace 模型 | `GGNOperator` + `hf_lm_loss()` | `lanczos()` + `trace()` |\n\n---\n\n\n\n## Hessian 矩阵基础概念\n\n### 相关页面\n\n相关主题：[项目简介](#page-project-intro), [曲率算子详解](#page-operators), [特征分解算法](#page-algorithms)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [hessian_eigenthings/operators/hessian.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/hessian.py)\n- [hessian_eigenthings/operators/ggn.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/ggn.py)\n- [hessian_eigenthings/algorithms/lanczos.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/lanczos.py)\n- [hessian_eigenthings/algorithms/trace.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/trace.py)\n- [hessian_eigenthings/loss_fns/huggingface.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/loss_fns/huggingface.py)\n- [hessian_eigenthings/loss_fns/_fused_ce_hvp.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/loss_fns/_fused_ce_hvp.py)\n- [README.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/README.md)\n \n\n# Hessian 矩阵基础概念\n\n## 概述\n\nHessian 矩阵（海森矩阵）是损失函数的二阶偏导数矩阵，定义为：\n\n$$H_{ij} = \\frac{\\partial^2 \\mathcal{L}}{\\partial \\theta_i \\partial \\theta_j}$$\n\n在深度学习中，Hessian 矩阵的**特征值和特征向量**与以下关键问题密切相关：\n\n- **泛化特性**：特征值分布可以揭示模型的收敛状态和泛化能力\n- **平坦最小值**：小特征值对应平坦方向，与良好泛化相关\n- **曲率信息**：帮助理解损失函数的局部几何结构\n\n资料来源：[README.md:1-20]()\n\n## Hessian 矩阵的核心性质\n\n### 正定与负定\n\n| 性质 | 条件 | 物理意义 |\n|------|------|----------|\n| 正定 (PSD) | 所有特征值 ≥ 0 | 局部最小值点 |\n| 负定 | 所有特征值 ≤ 0 | 局部最大值点 |\n| 不定 | 特征值有正有负 | 鞍点 |\n\n资料来源：[hessian_eigenthings/operators/ggn.py:1-30]()\n\n### Hessian 与广义高斯-牛顿 (GGN) 的关系\n\n对于机器学习中的损失函数，广义高斯-牛顿矩阵 G 是 Hessian 的良好近似：\n\n$$G = J^T H_{loss} J$$\n\n其中 $J$ 是模型输出的雅可比矩阵。GGN 矩阵具有以下特性：\n\n- **计算效率更高**：避免了 Hessian 的直接计算\n- **始终正定**：Hessian 的近似版本，可用于曲率分析\n- **Fisher 信息矩阵等价性**：对于交叉熵损失 + softmax，GGN 等于 Fisher 信息矩阵\n\n资料来源：[hessian_eigenthings/operators/ggn.py:1-35]()\n\n## 为什么使用 HVP 而非完整 Hessian\n\n### 计算复杂度对比\n\n| 方法 | 空间复杂度 | 时间复杂度 | 适用场景 |\n|------|------------|------------|----------|\n| 完整 Hessian | O(n²) | O(n²) | 小模型 (< 1M 参数) |\n| Hessian 向量积 (HVP) | O(n) | O(k×n) | 大规模模型 |\n\n其中 n 是参数数量，k 是向量积调用次数。\n\n资料来源：[CONTRIBUTING.md:1-30]()\n\n### 两种 HVP 计算方法\n\n```python\nclass HessianOperator:\n \"\"\"支持两种 HVP 计算方法\"\"\"\n \n def __init__(self, ..., method: HvpMethod = \"autograd\"):\n```\n\n| 方法 | 描述 | 精度 | 内存占用 | 适用场景 |\n|------|------|------|----------|----------|\n| `autograd` | 通过 `torch.autograd.grad` 的精确双重反向传播 | 数值精确（舍入精度） | 较高 | 单设备分析至 ~7B 参数 |\n| `finite_difference` | 中心差分 `(∇L(θ+εv) − ∇L(θ−εv)) / 2ε` | O(ε²) 截断误差 | 低 | FSDP/HSDP/TP 分布式训练 |\n\n资料来源：[hessian_eigenthings/operators/hessian.py:1-40]()\n\n## 架构设计\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n A[用户代码] --> B[CurvatureOperator 基类]\n B --> C[HessianOperator]\n B --> D[GGNOperator]\n B --> E[EmpiricalFisherOperator]\n \n F[LinAlgBackend] --> C\n F --> D\n F --> E\n \n G[Lanczos 算法] --> H[特征值分解]\n G --> I[Ritz 向量]\n \n J[Trace 估计] --> K[Hutchinson]\n J --> L[Hutch++]\n \n C --> G\n D --> G\n E --> G\n```\n\n资料来源：[CONTRIBUTING.md:1-25]()\n\n### 算子-算法分离设计\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ 算法层 │\n│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │\n│ │ Lanczos │ │ Trace 估计 │ │ 谱密度估计 │ │\n│ └──────┬──────┘ └──────┬──────┘ └────────┬────────┘ │\n└─────────┼────────────────┼──────────────────┼──────────┘\n │ │ │\n ▼ ▼ ▼\n┌─────────────────────────────────────────────────────────┐\n│ CurvatureOperator │\n│ (抽象基类 - 所有曲率算子的接口) │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ 后端层 │\n│ ┌─────────────────────────────────────────────────────┐│\n│ │ LinAlgBackend ││\n│ │ (统一的向量运算接口) ││\n│ └─────────────────────────────────────────────────────┘│\n└─────────────────────────────────────────────────────────┘\n```\n\n资料来源：[hessian_eigenthings/algorithms/lanczos.py:1-30]()\n\n## Hessian 特征值分解的计算流程\n\n```mermaid\ngraph LR\n A[初始化向量 v₀] --> B[Lanczos 迭代]\n B --> C{收敛判断}\n C -->|未收敛| D[正交化 v]\n D --> B\n C -->|收敛| E[构建三对角矩阵 T]\n E --> F[特征值分解: T = QΛQᵀ]\n F --> G[Ritz 值 ≈ 真实特征值]\n G --> H[Ritz 向量 = VQ]\n```\n\n资料来源：[hessian_eigenthings/algorithms/lanczos.py:1-60]()\n\n## 交叉熵损失 HVP 的融合实现\n\n### 数学推导\n\n对于 softmax 输出的交叉熵损失，Hessian 向量积具有闭式解：\n\n$$H_{loss} @ u = \\left( p \\cdot u - p \\cdot \\langle p, u \\rangle \\right) \\cdot \\frac{mask}{n_{valid}}$$\n\n其中 $p = softmax(logits)$ 是预测概率分布。\n\n资料来源：[hessian_eigenthings/loss_fns/_fused_ce_hvp.py:1-35]()\n\n### 融合策略对比\n\n| 实现方式 | 中间张量数量 | 内存占用 (N=16384, V=50304, fp32) | 加速比 |\n|----------|--------------|-----------------------------------|--------|\n| Eager | ~6 个 (N,V) 张量 | ~19.6 GB | 1x |\n| torch.compile | ~1 个 (N,V) 张量 | ~3.3 GB | ~2.6x |\n| Triton | 0 个中间张量 | ~1.6 GB | ~3.4x |\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py:1-50]()\n\n## 主要 API 接口\n\n### HessianOperator\n\n```python\nclass HessianOperator:\n def __init__(\n self,\n model: nn.Module,\n dataloader: Iterable[Any],\n loss_fn: LossFn,\n *,\n param_filter: ParamFilter | None = None,\n full_dataset: bool = True,\n num_batches: int | None = None,\n method: HvpMethod = \"autograd\",\n fd_eps: float | None = None,\n backend: LinAlgBackend[torch.Tensor] | None = None,\n ) -> None:\n```\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `model` | nn.Module | 必需 | PyTorch 模型 |\n| `dataloader` | Iterable | 必需 | 数据加载器 |\n| `loss_fn` | LossFn | 必需 | 损失函数 |\n| `param_filter` | ParamFilter | None | 参数过滤函数 |\n| `method` | HvpMethod | \"autograd\" | HVP 计算方法 |\n| `full_dataset` | bool | True | 是否使用完整数据集 |\n\n资料来源：[hessian_eigenthings/operators/hessian.py:1-35]()\n\n### GGNOperator\n\n```python\nclass GGNOperator:\n def __init__(\n self,\n model: nn.Module,\n dataloader: Iterable[Any],\n forward_fn: ForwardFn,\n loss_of_output_fn: LossOfOutputFn,\n *,\n loss_hvp: GgnHvpMethod = \"analytical\",\n ):\n```\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `loss_hvp` | GgnHvpMethod | \"analytical\" | GGN HVP 计算方法 |\n\n资料来源：[hessian_eigenthings/operators/ggn.py:1-45]()\n\n## 特征值选择模式\n\nLanczos 算法支持多种特征值选择策略：\n\n| 模式 | 含义 | 用途 |\n|------|------|------|\n| `\"LM\"` | Largest Magnitude | 寻找最大特征值（最尖锐方向） |\n| `\"LA\"` | Largest Algebraic | 寻找最大代数特征值 |\n| `\"SA\"` | Smallest Algebraic | 寻找最小特征值（最平坦方向） |\n\n```python\neig_result = lanczos(operator, k=10, which=\"LM\", max_iter=100)\n```\n\n资料来源：[hessian_eigenthings/algorithms/lanczos.py:1-70]()\n\n## Trace 估计方法\n\n### Hutchinson 方法\n\n通过蒙特卡洛采样估计矩阵的迹：\n\n$$\\text{tr}(A) \\approx \\frac{1}{m} \\sum_{i=1}^{m} v_i^T A v_i$$\n\n其中 $v_i$ 是随机向量（Rademacher 或 Gaussian 分布）。\n\n资料来源：[hessian_eigenthings/algorithms/trace.py:1-40]()\n\n### Hutch++ 方法\n\n改进的采样策略，提供更低的方差估计：\n\n$$\\text{tr}(A) = \\mathbb{E}[v^T A v] - \\mathbb{E}[g^T A g] + \\mathbb{E}[w^T A w]$$\n\n其中 $g$ 和 $w$ 是特殊的偏向采样向量。\n\n| 方法 | 采样数量 | 方差 | 适用场景 |\n|------|----------|------|----------|\n| Hutchinson | O(m) | 较高 | 快速估计 |\n| Hutch++ | O(2m) | 较低 | 精确估计 |\n\n## 使用示例\n\n### 基本特征值计算\n\n```python\nfrom hessian_eigenthings import HessianOperator, lanczos\n\n# 定义模型和数据\nmodel = MyModel()\ndataloader = DataLoader(dataset, batch_size=32)\n\n# 创建 Hessian 算子\nhessian_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=loss_fn,\n)\n\n# 计算 top-k 特征值\neig_result = lanczos(hessian_op, k=10, max_iter=100, seed=42)\n\nprint(f\"Top eigenvalues: {eig_result.eigenvalues}\")\n```\n\n### 注意力机制子空间分析\n\n```python\n# 只计算注意力参数的 Hessian\nattn_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=loss_fn,\n param_filter=match_names(\"blocks.*.attn.*\"),\n)\n\neig_attn = lanczos(attn_op, k=3, max_iter=20)\n```\n\n资料来源：[examples/transformer_lens_attention_only.py:1-45]()\n\n## 与其他工具的集成\n\n| 外部库 | 集成方式 | 用途 |\n|--------|----------|------|\n| FSDP/HSDP | `method=\"finite_difference\"` | 分布式训练中的 Hessian 分析 |\n| DeepSpeed | 通过参数过滤 | 特定参数组的曲率分析 |\n| Transformer-Lens | 自定义 dataloader | Attention-only 分析 |\n| HuggingFace Transformers | `hf_lm_loss()` | 语言模型 Hessian |\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py:1-60]()\n\n## 扩展阅读\n\n- **概念页面**：算法原理、适用场景\n- **操作指南**：具体用户工作流程\n- **参考页面**：自动生成的 API 文档\n\n资料来源：[CONTRIBUTING.md:1-35]()\n\n---\n\n\n\n## 核心架构设计\n\n### 相关页面\n\n相关主题：[曲率算子详解](#page-operators), [特征分解算法](#page-algorithms), [参数工具模块](#page-param-utils)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [hessian_eigenthings/__init__.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/__init__.py)\n- [hessian_eigenthings/operators/base.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/base.py)\n- [hessian_eigenthings/operators/hessian.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/hessian.py)\n- [hessian_eigenthings/operators/ggn.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/ggn.py)\n- [hessian_eigenthings/algorithms/lanczos.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/lanczos.py)\n- [hessian_eigenthings/algorithms/trace.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/trace.py)\n- [hessian_eigenthings/linalg/backend.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/linalg/backend.py)\n- [hessian_eigenthings/batching.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/batching.py)\n \n\n# 核心架构设计\n\n## 概述\n\n`pytorch-hessian-eigenthings` 是一个用于计算 PyTorch 模型 Hessian 矩阵特征分解的高效可扩展库。该项目的核心架构遵循**算子-算法分离**设计模式，通过抽象的曲率算子（Curvature Operator）接口连接不同的曲率矩阵实现与特征分解算法。\n\n架构的核心设计理念：\n\n- **模块化**：曲率矩阵（Hessian、GGN、Fisher）通过统一接口暴露\n- **可扩展性**：新增曲率矩阵只需实现 `CurvatureOperator` 基类\n- **算法无关性**：特征分解算法（Lanczos、Hutchinson、Hutch++）可作用于任意曲率算子\n- **硬件适配**：通过 `LinAlgBackend` 抽象支持多设备（CPU/GPU/MPS）\n\n资料来源：[CONTRIBUTING.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/CONTRIBUTING.md)\n\n## 架构总览\n\n### 系统组件图\n\n```mermaid\ngraph TB\n subgraph \"用户层\"\n U[用户代码]\n end\n \n subgraph \"算法层\"\n LZ[Lanczos 算法]\n HC[Hutchinson 算法]\n HP[Hutch++ 算法]\n SLQ[Stochastic Lanczos Quadrature]\n end\n \n subgraph \"算子层\"\n HO[HessianOperator]\n GGN[GGNOperator]\n EF[EmpiricalFisherOperator]\n end\n \n subgraph \"后端层\"\n BE[LinAlgBackend]\n SD[SingleDeviceBackend]\n MD[MultiDeviceBackend]\n end\n \n U --> LZ\n U --> HC\n U --> HP\n U --> SLQ\n \n LZ --> HO\n HC --> HO\n HP --> HO\n SLQ --> HO\n \n LZ --> GGN\n LZ --> EF\n \n HO --> BE\n GGN --> BE\n EF --> BE\n \n BE --> SD\n BE --> MD\n```\n\n### 核心接口契约\n\n| 组件 | 职责 | 关键方法 |\n|------|------|----------|\n| `CurvatureOperator` | 定义曲率矩阵算子接口 | `matvec(v)` |\n| `LinAlgBackend` | 封装向量运算 | `dot()`, `norm()`, `axpy()` |\n| 算法函数 | 执行特征分解 | `lanczos()`, `hutchinson()`, `hutch_plus_plus()` |\n\n资料来源：[hessian_eigenthings/operators/base.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/base.py)\n\n## CurvatureOperator 基类\n\n### 抽象接口定义\n\n`CurvatureOperator` 是整个库的核心抽象，所有曲率矩阵（Hessian、广义 Gauss-Newton、Fisher 等）都必须继承此类并实现 `matvec(v)` 方法。\n\n```python\nclass CurvatureOperator(ABC):\n @property\n @abstractmethod\n def dtype(self) -> torch.dtype: ...\n \n @property\n @abstractmethod\n def device(self) -> torch.device: ...\n \n @property\n @abstractmethod\n def size(self) -> int: ...\n \n @abstractmethod\n def matvec(self, v: torch.Tensor) -> torch.Tensor: ...\n```\n\n核心方法说明：\n\n| 方法 | 输入 | 输出 | 说明 |\n|------|------|------|------|\n| `matvec(v)` | 维度为 `size` 的向量 | 维度为 `size` 的向量 | 计算曲率矩阵与向量的乘积（矩阵-向量乘积） |\n| `dtype` | - | `torch.dtype` | 算子的数据类型 |\n| `device` | - | `torch.device` | 算子所在设备 |\n| `size` | - | `int` | 参数空间的维度（即模型参数总数） |\n\n### 向量展开与重塑机制\n\n算子内部维护参数列表及其形状信息，用于在扁平向量与原始参数结构之间转换：\n\n```python\nclass CurvatureOperator:\n def _unflatten(self, v: torch.Tensor) -> dict[str, torch.Tensor]:\n offset = 0\n out = {}\n for n, p, sz in zip(self._param_names, self._param_list, self._sizes, strict=True):\n out[n] = v[offset : offset + sz].reshape_as(p)\n offset += sz\n return out\n```\n\n此机制确保算法层始终操作扁平的 1-D 向量，而算子层负责与模型的原始参数结构交互。\n\n资料来源：[hessian_eigenthings/operators/base.py:1-100](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/base.py)\n\n## LinAlgBackend 线性代数后端\n\n### 后端抽象层\n\n`LinAlgBackend` 是一个泛型抽象类，封装了所有向量运算操作。这种设计使得：\n\n1. 单设备场景使用标准 PyTorch 操作\n2. 多设备/分布式场景可注入自定义实现\n3. 测试时可注入模拟后端进行单元测试\n\n```python\nclass LinAlgBackend(ABC, Generic[V]):\n @abstractmethod\n def dot(self, a: V, b: V) -> torch.Tensor: ...\n \n @abstractmethod\n def norm(self, a: V) -> torch.Tensor: ...\n \n @abstractmethod\n def axpy(self, a: torch.Tensor, x: V, y: V) -> V: ...\n \n @abstractmethod\n def zero(self, shape: int) -> V: ...\n```\n\n### 单设备后端实现\n\n`SingleDeviceBackend` 是默认后端实现，直接委托给 PyTorch 张量操作：\n\n| 方法 | 实现 | 说明 |\n|------|------|------|\n| `dot(a, b)` | `torch.dot(a.flatten(), b.flatten())` | 向量点积 |\n| `norm(a)` | `torch.linalg.vector_norm(a)` | L2 范数 |\n| `axpy(a, x, y)` | `a * x + y` | 标量-向量乘加 |\n| `zero(shape)` | `torch.zeros(shape, ...) ` | 创建零向量 |\n\n资料来源：[hessian_eigenthings/linalg/backend.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/linalg/backend.py)\n\n## HessianOperator 实现\n\n### 架构设计\n\n`HessianOperator` 是 Hessian 矩阵的算子实现，支持两种 HVP（Hamiltonian-Vector Product）计算方法：\n\n```mermaid\ngraph LR\n A[输入向量 v] --> B{method 参数}\n B -->|\"autograd\"| C[双反向传播]\n B -->|\"finite_difference\"| D[有限差分]\n \n C --> E[create_graph=True]\n C --> F[梯度 → 二阶导]\n E --> G[H_loss · v]\n \n D --> H[L θ+εv]\n D --> I[L θ-εv]\n H --> J[(∇L₊ - ∇L₋) / 2ε]\n I --> J\n J --> G\n```\n\n### 两种方法的对比\n\n| 特性 | `autograd` | `finite_difference` |\n|------|------------|---------------------|\n| 数值精度 | 精确（浮点舍入内） | O(ε²) 截断误差 |\n| 内存占用 | 较大（需构建反向图） | 较小（仅两次前反向） |\n| FSDP/HSDP/TP 兼容性 | 需特殊处理 | 原生支持 |\n| 适用场景 | 7B 参数以下单机分析 | 大规模分布式训练 |\n\n资料来源：[hessian_eigenthings/operators/hessian.py:1-80](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/hessian.py)\n\n## GGNOperator 实现\n\n### Generalized Gauss-Newton 近似\n\nGGN（广义 Gauss-Newton）矩阵是 Hessian 的正向定矩阵近似，其定义为：\n\n```\nG = J^T · H_loss · J\n```\n\n其中 `J` 是损失函数相对于模型输出的雅可比矩阵，`H_loss` 是损失函数的 Hessian。\n\n### 双路径 HVP 计算\n\nGGNOperator 支持两种 HVP 计算路径：\n\n```python\nif loss_hvp == \"analytical\":\n # 分析路径：有限差分 JVP + 解析 H_loss HVP + 单次反向\n # 内存占用匹配一次正常训练步\nelse:\n # autograd 路径：torch.func.jvp + 双反向 + vjp\n # 数值精确但内存随输出维度扩展\n```\n\n| 路径 | `loss_hvp` 参数 | 内存特性 | 精度 |\n|------|----------------|----------|------|\n| 分析路径 | `\"analytical\"` | 与训练步相同 | 有限差分精度 |\n| 自动微分路径 | `\"autograd\"` | O(vocab_size) | 精确 |\n\n资料来源：[hessian_eigenthings/operators/ggn.py:1-60](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/ggn.py)\n\n## 批处理机制\n\n### Microbatch 支持\n\n对于大数据集场景，算子支持将数据分成多个 microbatch 分别计算后聚合：\n\n```python\nclass HessianOperator:\n def __init__(\n self,\n model: nn.Module,\n dataloader: Iterable[Any],\n loss_fn: LossFn,\n *,\n microbatch_size: int | None = None,\n num_batches: int | None = None,\n ): ...\n```\n\n批处理流程：\n\n```mermaid\ngraph TD\n A[完整数据集] --> B{microbatch_size?}\n B -->|是| C[分割为 N 个 microbatch]\n B -->|否| D[使用完整 dataloader]\n \n C --> E[对每个 microbatch 计算 HVP]\n D --> F[计算 HVP]\n \n E --> G[加权求和]\n F --> G\n```\n\n### 参数过滤\n\n通过 `param_filter` 函数可以选择性地只对模型的部分参数构造算子：\n\n```python\n# 示例：只对注意力层参数构造 Hessian\nattn_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=loss_fn,\n param_filter=match_names(\"transformer.h.*.attn.*\"),\n)\n```\n\n资料来源：[hessian_eigenthings/batching.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/batching.py)\n\n## Lanczos 算法实现\n\n### 算法核心流程\n\nLanczos 算法是计算 Hessian 特征分解的核心算法，该实现具有以下特性：\n\n```mermaid\ngraph LR\n A[初始向量 v₀] --> B[Lanczos 迭代]\n B --> C[生成三对角矩阵 T]\n C --> D[特征分解 T]\n D --> E[Ritz 值 = 特征值近似]\n D --> F[Ritz 向量 = 特征向量近似]\n```\n\n### 特征向量累积优化\n\n代码使用 rank-1 外积更新直接累积 Ritz 向量，避免了临时的大矩阵分配：\n\n```python\n# 直接累积到最终 (k, n) 布局，避免 (n, m) 基底矩阵和转置拷贝\neigenvectors = torch.zeros(sel.shape[0], n, dtype=operator.dtype, device=operator.device)\nfor j, basis_vec in enumerate(td.basis):\n eigenvectors.addr_(s_sel[j], basis_vec)\n```\n\n### 关键参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `k` | int | - | 返回的特征值数量 |\n| `max_iter` | int | - | 最大迭代次数 |\n| `tol` | float | 1e-5 | 收敛阈值 |\n| `which` | str | \"LM\" | 选择策略（LM/LA/SA） |\n| `seed` | int | None | 随机种子 |\n\n`which` 参数说明：\n- `\"LM\"`: Largest Magnitude（绝对值最大）\n- `\"LA\"`: Largest Algebraic（代数最大）\n- `\"SA\"`: Smallest Algebraic（代数最小）\n\n资料来源：[hessian_eigenthings/algorithms/lanczos.py:1-80](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/lanczos.py)\n\n## 追踪估计算法\n\n### Hutchinson 估计器\n\nHutchinson 方法通过随机采样估计矩阵迹：\n\n```\ntr(A) ≈ (1/m) Σ vᵢᵀ A vᵢ\n```\n\n其中 `vᵢ` 是 Rademacher 或 Gaussian 分布的随机向量。\n\n### Hutch++ 改进算法\n\nHutch++ 通过更智能的采样策略降低方差：\n\n| 算法 | 采样数量 | 方差特性 | 适用场景 |\n|------|----------|----------|----------|\n| Hutchinson | m | O(1/√m) | 通用 |\n| Hutch++ | ⌈3m/2⌉ | O(1/m) | 高精度需求 |\n\n资料来源：[hessian_eigenthings/algorithms/trace.py:1-60](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/trace.py)\n\n## 完整调用流程\n\n### 端到端工作流\n\n```mermaid\nsequenceDiagram\n participant User as 用户代码\n participant Op as CurvatureOperator\n participant Algo as 算法函数\n participant Backend as LinAlgBackend\n \n User->>Op: 创建算子实例\n Op->>Backend: 注册后端\n User->>Algo: 调用 lanczos/trac e\n Algo->>Op: 调用 matvec(v)\n Op->>Backend: 执行向量运算\n Backend-->>Op: 返回结果\n Op-->>Algo: 返回 HVP\n Algo-->>User: 返回特征值/向量\n```\n\n### 典型使用示例\n\n```python\n# 1. 创建 Hessian 算子\nhessian_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=loss_fn,\n)\n\n# 2. 调用 Lanczos 算法\nresult = lanczos(hessian_op, k=10, max_iter=50)\n\n# 3. 获取特征值和特征向量\neigenvalues = result.eigenvalues\neigenvectors = result.eigenvectors\n```\n\n资料来源：[examples/huggingface_tiny_gpt2.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/examples/huggingface_tiny_gpt2.py)\n\n## 扩展机制\n\n### 新增曲率算子\n\n要添加新的曲率矩阵（如 Fisher 信息矩阵），只需继承 `CurvatureOperator` 并实现 `matvec` 方法：\n\n```python\nclass MyCurvatureOperator(CurvatureOperator):\n def __init__(self, model, dataloader, ...):\n super().__init__()\n # 初始化参数列表等\n \n @property\n def dtype(self) -> torch.dtype:\n return self._param_list[0].dtype\n \n def matvec(self, v: torch.Tensor) -> torch.Tensor:\n # 实现矩阵-向量乘积\n return ...\n```\n\n### 新增算法\n\n算法通过 `CurvatureOperator` 接口与所有算子兼容，无需修改：\n\n```python\ndef my_algorithm(operator: CurvatureOperator, **kwargs) -> MyResult:\n # operator.matvec(v) 可用于任意曲率算子\n ...\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/CONTRIBUTING.md)\n\n## 总结\n\n`pytorch-hessian-eigenthings` 的核心架构以**算子-算法分离**为核心设计原则，通过抽象的 `CurvatureOperator` 接口连接曲率矩阵实现与特征分解算法。这种设计使得：\n\n1. **代码复用**：不同算法可作用于同一算子\n2. **易于扩展**：新增曲率矩阵或算法无需修改现有代码\n3. **硬件适配**：通过后端抽象支持多设备场景\n4. **内存优化**：不同实现路径（autograd vs analytical）可权衡精度与内存\n\n整个库的架构简洁而高效，核心文件仅包含算子基类、算法实现和后端抽象三个主要层次，配合专门的损失函数模块完成特定任务的优化。\n\n---\n\n\n\n## 曲率算子详解\n\n### 相关页面\n\n相关主题：[核心架构设计](#page-core-architecture), [特征分解算法](#page-algorithms), [分布式训练支持 (DDP)](#page-distributed-ddp)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [hessian_eigenthings/operators/__init__.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/__init__.py)\n- [hessian_eigenthings/operators/hessian.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/hessian.py)\n- [hessian_eigenthings/operators/ggn.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/ggn.py)\n- [hessian_eigenthings/operators/fisher.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/fisher.py)\n- [hessian_eigenthings/operators/distributed/ddp.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/distributed/ddp.py)\n- [docs/reference/operators.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/reference/operators.md)\n \n\n# 曲率算子详解\n\n曲率算子（Curvature Operator）是 pytorch-hessian-eigenthings 项目的核心抽象，封装了对任意 PyTorch 模型进行曲率矩阵（如 Hessian、广义 Gauss-Newton 矩阵、Fisher 信息矩阵）矩阵-向量乘积（matvec）的计算逻辑。通过将曲率矩阵的操作抽象为统一的算子接口，该项目得以支持多种高效的算法（如 Lanczos、随机幂迭代、Hutchinson/Hutch++ 迹估计），而无需关心底层曲率矩阵的具体实现细节。\n\n## 1. 架构概述\n\n曲率算子系统采用**算子模式**（Operator Pattern）设计，所有曲率算子均继承自 `CurvatureOperator` 基类，暴露统一的 `matvec(v)` 接口。算法模块仅依赖此接口，从而实现曲率矩阵计算与特征值分解、迹估计等操作的解耦。\n\n```mermaid\ngraph TD\n subgraph \"用户层\"\n A[\"HessianOperator\"] --> B[\"GGNOperator\"]\n A --> C[\"FisherOperator\"]\n C --> D[\"EmpiricalFisherOperator\"]\n end\n \n subgraph \"抽象基类\"\n E[\"CurvatureOperator
size: int
dtype: dtype
device: device
matvec(v) → Av\"]\n end\n \n subgraph \"算法层\"\n F[\"lanczos()\"]\n G[\"power_iteration()\"]\n H[\"trace()\"]\n I[\"spectral_density()\"]\n end\n \n subgraph \"后端层\"\n J[\"LinAlgBackend
SingleDeviceBackend
DistributedBackend\"]\n end\n \n A --> E\n B --> E\n C --> E\n D --> E\n E --> J\n F --> E\n G --> E\n H --> E\n I --> E\n```\n\n## 2. 基类设计：CurvatureOperator\n\n`CurvatureOperator` 是所有曲率算子的抽象基类，定义了算子的通用接口和属性。\n\n### 2.1 核心属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `size` | `int` | 模型中被纳入计算的参数总数 |\n| `dtype` | `torch.dtype` | 算子的数据类型 |\n| `device` | `torch.device` | 算子所在的设备 |\n\n### 2.2 核心方法\n\n```python\nclass CurvatureOperator(ABC):\n @abstractmethod\n def matvec(self, v: torch.Tensor) -> torch.Tensor:\n \"\"\"计算曲率矩阵与向量 v 的乘积 Av，返回形状与 v 相同\"\"\"\n ...\n```\n\n`matvec` 方法接收一个展平后的参数向量 `v`（形状为 `(size,)`），返回曲率矩阵与 `v` 的乘积结果。该方法内部处理参数重排、梯度计算、重塑等逻辑，对外保持一致的接口。\n\n资料来源：[hessian_eigenthings/operators/__init__.py]()\n\n## 3. HessianOperator\n\n`HessianOperator` 用于计算损失函数关于模型参数的 Hessian 矩阵与向量的乘积。\n\n### 3.1 数学背景\n\nHessian 矩阵定义为损失函数对参数的二阶导数矩阵：\n\n$$H = \\nabla_\\theta^2 \\mathcal{L}(\\theta)$$\n\n对于神经网络，直接构建完整的 Hessian 矩阵成本高昂（参数可达数十亿），因此 `HessianOperator` 仅实现矩阵-向量乘积 `Hv`，支持后续的特征值分解等分析操作。\n\n### 3.2 初始化参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `model` | `nn.Module` | 必选 | 待分析的 PyTorch 模型 |\n| `dataloader` | `Iterable[Any]` | 必选 | 数据加载器，用于迭代数据批次 |\n| `loss_fn` | `LossFn` | 必选 | 损失函数，签名 `Callable[[Tensor, Any], Tensor]` |\n| `param_filter` | `ParamFilter \\| None` | `None` | 参数过滤器，仅对匹配参数计算曲率 |\n| `full_dataset` | `bool` | `True` | 是否对整个数据集求平均 |\n| `num_batches` | `int \\| None` | `None` | 使用的批次数，`None` 表示全部 |\n| `microbatch_size` | `int \\| None` | `None` | 微批次大小 |\n| `microbatch_unsafe` | `bool` | `False` | 是否跳过微批次安全检查 |\n| `method` | `HvpMethod` | `\"autograd\"` | HVP 计算方法 |\n| `fd_eps` | `float \\| None` | `None` | 有限差分方法的步长 |\n| `backend` | `LinAlgBackend \\| None` | `None` | 线性代数后端 |\n\n资料来源：[hessian_eigenthings/operators/hessian.py:19-43]()\n\n### 3.3 HVP 计算方法\n\n`HessianOperator` 支持两种 Hessian 向量积（HVP）的计算方式：\n\n#### 3.3.1 autograd 方法（默认）\n\n通过 `torch.autograd.grad` 进行精确的双反向传播计算：\n\n```python\n# 伪代码实现\ngrad_params = grad(loss, params, create_graph=True)\nhvp = grad(grad_params, params, grad_outputs=v)\n```\n\n该方法数值精确，适合单设备分析场景，参数规模上限约为 70 亿。资料来源：[hessian_eigenthings/operators/hessian.py:20-23]()\n\n#### 3.3.2 finite_difference 方法\n\n采用中心差分公式近似 HVP：\n\n$$\\text{Hv} \\approx \\frac{\\nabla\\mathcal{L}(\\theta + \\epsilon v) - \\nabla\\mathcal{L}(\\theta - \\epsilon v)}{2\\epsilon}$$\n\n该方法每个 HVP 需要两次正常的前向和反向传播，**不涉及任何二阶反向传播图**，天然支持 FSDP/HSDP/张量并行等分布式训练框架。代价是存在 $O(\\epsilon^2)$ 的截断误差。资料来源：[hessian_eigenthings/operators/hessian.py:23-25]()\n\n## 4. GGNOperator（广义 Gauss-Newton 矩阵）\n\n`GGNOperator` 计算广义 Gauss-Newton（GGN）矩阵与向量的乘积。GGN 是 Hessian 的 PSD（半正定）近似，常用于大规模神经网络的曲率分析。\n\n### 4.1 数学背景\n\nGGN 矩阵定义为：\n\n$$G = J^T H_{loss} J$$\n\n其中 $J$ 是模型输出对参数的雅可比矩阵，$H_{loss}$ 是损失函数对模型输出的 Hessian。由于 $H_{loss}$ 被替换为近似 PSD 矩阵，$G$ 必然是 PSD 矩阵。\n\n对于交叉熵损失 + Softmax 分类，GGN 矩阵恰好等于 Fisher 信息矩阵。资料来源：[hessian_eigenthings/operators/ggn.py:45-50]()\n\n### 4.2 两函数 API 设计\n\n`GGNOperator` 采用解耦的双函数接口：\n\n| 函数 | 签名 | 说明 |\n|------|------|------|\n| `forward_fn` | `Callable[..., Tensor]` | 返回模型输出 |\n| `loss_of_output_fn` | `Callable[[Tensor, Any], Tensor]` | 将模型输出和批次转换为标量损失 |\n\n这种设计使得 `GGNOperator` 可以独立计算 $Jv$（雅可比-向量积）、$H_{loss} \\cdot (Jv)$ 和 $J^T \\cdot (H_{loss} \\cdot Jv)$，而不依赖于损失函数的内部实现细节。资料来源：[hessian_eigenthings/operators/ggn.py:52-54]()\n\n### 4.3 matvec 实现方式\n\n| 方式 | 默认 | 说明 |\n|------|------|------|\n| `analytical` | ✅ | 有限差分 JVP + 解析 loss-Hessian-向量积 + 一次正常反向传播应用 $J^T$。内存占用与单次训练步相当，是 LLM 规模使用的首选方案 |\n| `autograd` | - | `torch.func.jvp` + 自动微分双反向传播 + `torch.func.vjp` 路径。数值精确但内存随输出规模快速膨胀，适用于没有解析 `.hvp` 的损失函数 |\n\n资料来源：[hessian_eigenthings/operators/ggn.py:56-66]()\n\n### 4.4 内部结构\n\n```mermaid\ngraph LR\n A[\"参数字典
{name: Tensor}\"] --> B[\"模型前向
forward_fn\"]\n B --> C[\"模型输出
Tensor\"]\n C --> D[\"损失计算
loss_of_output_fn\"]\n D --> E[\"标量损失
loss\"]\n \n F[\"向量 v
(参数空间)\"] --> G[\"JVP
Jv\"]\n G --> H[\"H_loss @ Jv
解析或 autograd\"]\n H --> I[\"VJP
J^T @ (H_loss @ Jv)\"]\n I --> J[\"结果
Av = Gv\"]\n```\n\nGGN matvec 的完整流程包括：\n\n1. 从参数字典中提取参数值和梯度\n2. 计算雅可比-向量积 $u = Jv$\n3. 计算损失 Hessian 对 $u$ 的作用 $w = H_{loss} \\cdot u$\n4. 通过反向传播计算 $J^T \\cdot w$ 资料来源：[hessian_eigenthings/operators/ggn.py:60-62]()\n\n## 5. FisherOperator 与 EmpiricalFisherOperator\n\nFisher 信息矩阵是 GGN 的一个特例，在特定条件下（损失函数为负对数似然）两者数学上等价。项目提供两种 Fisher 算子实现。\n\n### 5.1 FisherOperator\n\n计算真实的 Fisher 信息矩阵，需要模型输出对应于正确的概率分布。对于语言模型，通常需要采样生成过程。\n\n### 5.2 EmpiricalFisherOperator\n\n计算经验 Fisher 信息矩阵，使用梯度的外积近似：\n\n$$\\hat{F} = \\frac{1}{N} \\sum_{i=1}^{N} \\nabla \\log p(y|x;\\theta) \\nabla \\log p(y|x;\\theta)^T$$\n\n## 6. 分布式支持：DDP 包装器\n\n对于使用 `torch.nn.parallel.DistributedDataParallel`（DDP）包装的模型，曲率算子需要额外处理参数同步和梯度聚合逻辑。\n\n### 6.1 同步机制\n\n```mermaid\ngraph TD\n subgraph \"单设备算子\"\n A[\"HessianOperator/GGNOperator\"]\n end\n \n subgraph \"DDP 包装层\"\n B[\"DDPWrappedCurvatureOperator\"]\n end\n \n subgraph \"分布式后端\"\n C[\"DistributedLinAlgBackend\"]\n end\n \n A --> B\n B --> C\n```\n\n`DDPWrappedCurvatureOperator` 负责：\n\n- 在每个 matvec 调用前同步模型参数（若使用分片参数）\n- 在梯度计算后聚合所有 rank 的梯度\n- 将梯度展平为与 `v` 相同形状的向量\n\n资料来源：[hessian_eigenthings/operators/distributed/ddp.py]()\n\n### 6.2 参数过滤与 DDP\n\n在使用 `param_filter` 进行参数子集选择时，DDP 包装器需要确保：\n\n1. 过滤后的参数在各 rank 间一致\n2. 梯度同步仅发生在选中的参数子集上\n\n## 7. 预置损失函数\n\n项目在 `hessian_eigenthings/loss_fns` 模块中提供了常用损失函数的 HVP 实现，可直接与 `GGNOperator` 配合使用。\n\n### 7.1 标准损失函数\n\n| 函数 | 说明 | 适用场景 |\n|------|------|----------|\n| `cross_entropy_loss_of_output()` | 交叉熵损失的 `loss_of_output_fn`，返回闭式 HVP | 分类模型 |\n| `make_loss_of_output_fn(criterion)` | 从任意损失函数创建适配器 | 自定义损失 |\n\n闭式 HVP 计算公式（以交叉熵为例）：\n\n对于形状为 `(N, C)` 的 logits，`H_loss @ u` 的第 $i$ 行计算为：\n\n$$(\\text{diag}(p_i) - p_i p_i^T) \\cdot u_i / N$$\n\n其中 $p_i = \\text{softmax}(\\text{logits}_i)$。\n\n资料来源：[hessian_eigenthings/loss_fns/standard.py:27-37]()\n\n### 7.2 HuggingFace 损失函数\n\n针对 HuggingFace Transformers 库的语言模型，提供了优化的融合 CE HVP 实现：\n\n| 后端 | 说明 | 性能特征 |\n|------|------|----------|\n| `auto` | 自动选择最快可用后端 | Triton > compile > eager |\n| `triton` | 手写 CUDA Triton 内核，零中间张量 | 约 3.4x 加速，2x 内存减少 |\n| `compile` | `torch.compile` 融合，CPU/CUDA/MPS 通用 | 约 2.6x 加速，2x 内存减少 |\n| `eager` | 朴素 PyTorch 实现 | 便于调试，V≥50k 时易 OOM |\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py:1-40]()\n\n融合内核的核心计算公式：\n\n```python\np = softmax(logits)\ndot = (p * u).sum(dim=-1, keepdim=True)\nout = (p * u - p * dot) * mask / n_valid\n```\n\n## 8. 参数过滤机制\n\n参数过滤允许用户仅对模型参数子集计算曲率矩阵，这对于分析特定层或模块的曲率特性非常有用。\n\n### 8.1 过滤函数类型\n\n```python\nParamFilter = Callable[[str, nn.Parameter], bool]\n```\n\n过滤函数接收参数名称和参数张量，返回布尔值表示是否纳入计算。\n\n### 8.2 使用示例\n\n```python\nfrom fnmatch import fnmatch\n\n# 匹配所有注意力层参数\nparam_filter = lambda name, _: fnmatch(name, \"transformer.h.*.attn.*\")\n\nop = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=loss_fn,\n param_filter=param_filter\n)\n```\n\n资料来源：[examples/huggingface_tiny_gpt2.py:42-46]()\n\n### 8.3 过滤后的参数重映射\n\n过滤后的算子 `size` 属性反映的是被选中参数的总数，`matvec` 接收和返回的向量形状均为 `(size,)`。算子内部维护参数名到参数张量的映射，确保向量索引与参数顺序正确对应。\n\n## 9. 线性代数后端\n\n`LinAlgBackend` 抽象了向量运算（点积、范数、归约等）的实现，支持不同硬件和分布式场景。\n\n### 9.1 后端类型\n\n| 后端 | 场景 |\n|------|------|\n| `SingleDeviceBackend` | 单设备 CPU/GPU 计算 |\n| `DistributedBackend` | 多设备/多节点分布式计算 |\n\n所有后端提供统一的向量运算接口，算子和算法代码通过后端进行所有线性代数操作。\n\n## 10. 使用流程总结\n\n```mermaid\ngraph LR\n A[\"定义模型
nn.Module\"] --> B[\"准备数据加载器
DataLoader\"]\n B --> C[\"选择/实现损失函数
LossFn / loss_of_output_fn\"]\n C --> D[\"创建曲率算子
HessianOperator / GGNOperator\"]\n D --> E[\"可选：参数过滤
param_filter\"]\n E --> F[\"调用算法
lanczos / trace / ... \"]\n F --> G[\"获取结果
特征值/特征向量/迹估计\"]\n```\n\n1. **模型准备**：创建待分析的 PyTorch 模型\n2. **数据准备**：准备与训练一致的数据加载器\n3. **损失函数**：选择合适的损失函数，对于 GGNOperator 需要提供 `loss_of_output_fn`\n4. **算子创建**：实例化曲率算子，可选配置参数过滤、计算方法等\n5. **算法调用**：使用 Lanczos 分解获取特征值/特征向量，或使用 Hutch++ 估计迹\n6. **结果解析**：分析返回的特征值分布、收敛性等信息\n\n## 11. 设计原则\n\n曲率算子系统的设计遵循以下核心原则：\n\n| 原则 | 说明 | 实现方式 |\n|------|------|----------|\n| **算子抽象** | 曲率矩阵计算与特征分解算法解耦 | 所有算子继承 `CurvatureOperator`，实现统一 `matvec` 接口 |\n| **内存效率** | 支持大规模模型的曲率分析 | 融合内核、流式计算、解析路径避免中间张量 |\n| **分布式友好** | 天然支持 DDP/FSDP/HSDP 等并行策略 | `finite_difference` 方法无二阶图；DDP 包装器处理梯度同步 |\n| **数值稳定性** | 提供多种精度/速度权衡选项 | autograd（精确）vs finite_difference；analytical vs autograd for GGN |\n\n---\n\n\n\n## 特征分解算法\n\n### 相关页面\n\n相关主题：[核心架构设计](#page-core-architecture), [曲率算子详解](#page-operators)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [hessian_eigenthings/algorithms/__init__.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/__init__.py)\n- [hessian_eigenthings/algorithms/lanczos.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/lanczos.py)\n- [hessian_eigenthings/algorithms/trace.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/trace.py)\n- [hessian_eigenthings/algorithms/spectral_density.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/spectral_density.py)\n- [hessian_eigenthings/algorithms/power_iteration.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/power_iteration.py)\n- [docs/concepts/top-k-eigenvalues.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/concepts/top-k-eigenvalues.md)\n- [docs/concepts/trace-estimation.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/concepts/trace-estimation.md)\n- [docs/concepts/spectral-density.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/concepts/spectral-density.md)\n- [docs/reference/algorithms.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/reference/algorithms.md)\n \n\n# 特征分解算法\n\n本页面详细介绍 `pytorch-hessian-eigenthings` 库中实现的特征分解算法。该库提供了一套完整的曲率矩阵特征分解工具，包括 Lanczos 算法、幂迭代法、迹估计和谱密度估计。\n\n## 算法概述\n\n特征分解算法在神经网络的 Hessian 分析中扮演核心角色。Hessian 矩阵的特征值和特征向量与神经网络的泛化特性密切相关，研究者假设\"平坦最小值\"具有更好的泛化能力。 资料来源：[README.md]()\n\n该库实现了多种迭代特征分解算法，均基于 `CurvatureOperator` 接口构建，与底层线性代数后端解耦。 资料来源：[CONTRIBUTING.md](CONTRIBUTING.md)\n\n## 核心算法架构\n\n```mermaid\ngraph TD\n subgraph \"特征分解算法模块\"\n A[Lanczos 算法] --> D[特征值/向量计算]\n B[幂迭代法] --> D\n C[迹估计] --> E[矩阵迹计算]\n F[谱密度估计] --> G[Stochastic Lanczos Quadrature]\n end\n \n subgraph \"底层接口\"\n D --> H[CurvatureOperator]\n E --> H\n G --> H\n H --> I[LinAlgBackend]\n end\n```\n\n## Lanczos 算法\n\nLanczos 算法是该库计算 top-k 特征值和特征向量的主要方法。它通过三对角化过程将大型稀疏特征问题转化为小型稠密特征问题。\n\n### 算法原理\n\nLanczos 算法是一种迭代方法，用于计算矩阵的极端特征值。对于 n×n 矩阵 A 和初始向量 v₀，算法生成三对角矩阵 T，其特征值逼近 A 的 Ritz 值。 资料来源：[hessian_eigenthings/algorithms/lanczos.py](hessian_eigenthings/algorithms/lanczos.py)\n\n### API 接口\n\n```python\ndef lanczos(\n operator: CurvatureOperator,\n k: int = 20,\n max_iter: int = 100,\n *,\n tol: float = 1e-8,\n which: Literal[\"LM\", \"LA\", \"SA\"] = \"LM\",\n seed: int | None = None,\n reorthogonalize: bool = False,\n backend: LinAlgBackend[torch.Tensor] | None = None,\n) -> LanczosResult\n```\n\n### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `operator` | CurvatureOperator | 必需 | 曲率算子，提供 matvec 操作 |\n| `k` | int | 20 | 要计算的特征值数量 |\n| `max_iter` | int | 100 | 最大迭代次数 |\n| `tol` | float | 1e-8 | 收敛阈值，基于残差范数 |\n| `which` | str | \"LM\" | 特征值选择策略 |\n| `seed` | int | None | 随机种子 |\n| `reorthogonalize` | bool | False | 是否使用重正交化 |\n\n### 特征值选择策略\n\n| 策略 | 含义 | 使用场景 |\n|------|------|----------|\n| `\"LM\"` | Largest Magnitude | 默认选项，查找最大模特征值 |\n| `\"LA\"` | Largest Algebraic | 查找最大代数特征值 |\n| `\"SA\"` | Smallest Algebraic | 查找最小代数特征值 |\n\n特征值排序逻辑：\n\n```python\nif which == \"LM\":\n order = torch.argsort(theta.abs(), descending=True)\nelif which == \"LA\":\n order = torch.argsort(theta, descending=True)\nelif which == \"SA\":\n order = torch.argsort(theta, descending=False)\n```\n\n资料来源：[hessian_eigenthings/algorithms/lanczos.py:47-57](hessian_eigenthings/algorithms/lanczos.py)\n\n### Ritz 向量计算优化\n\n该实现使用秩-1外积更新直接累积 Ritz 向量到最终 (k, n) 布局，避免了 (n, m) 基矩阵和瞬态 (n, k) → (k, n) 转置复制。在 LLM 规模下，两者合计峰值可达特征向量大小的 2 倍以上。 资料来源：[hessian_eigenthings/algorithms/lanczos.py:63-71](hessian_eigenthings/algorithms/lanczos.py)\n\n```python\n# 优化后的累积方式\nfor j, basis_vec in enumerate(td.basis):\n eigenvectors.addr_(s_sel[j], basis_vec)\n```\n\n### 收敛判定\n\n残差计算基于最后分量：\n\n```python\nlast_components = s[-1, sel]\nresiduals = last_components.abs() * td.last_beta\nconverged = residuals < tol * eigenvalues.abs().clamp(min=_EPS)\n```\n\n资料来源：[hessian_eigenthings/algorithms/lanczos.py:73-76](hessian_eigenthings/algorithms/lanczos.py)\n\n## 幂迭代法\n\n幂迭代法是计算矩阵主导特征值的经典方法，该库提供了带deflation的幂迭代和加速随机幂迭代两种变体。\n\n### 标准幂迭代\n\n标准幂迭代通过反复应用矩阵并归一化来收敛到最大特征值对应的特征向量。 资料来源：[docs/concepts/top-k-eigenvalues.md](docs/concepts/top-k-eigenvalues.md)\n\n### Deflated 幂迭代\n\nDeflated 幂迭代基于 [HessianFlow](https://github.com/amirgholami/HessianFlow) 实现，用于计算多个特征值。在找到第一个特征值后，通过投影去除其影响，可以继续计算次大特征值。 资料来源：[README.md](README.md)\n\n### 加速随机幂迭代\n\n加速随机幂迭代来自 C. De Sa 等人的工作，通过随机化技术加速收敛。该方法在保持统计效率的同时显著减少迭代次数。 资料来源：[README.md](README.md)\n\n## 迹估计\n\n迹估计用于计算矩阵的迹 `tr(A)`，无需完整矩阵分解。这对于大型 Hessian 矩阵尤其重要，因为完整分解在计算上不可行。\n\n### Hutchinson 估计器\n\nHutchinson 估计器使用随机向量样本：\n\n```\ntr(A) ≈ (1/m) Σ vᵢᵀ A vᵢ\n```\n\n其中 vᵢ 是从特定分布独立采样的随机向量。Rademacher 分布提供比 Gaussian 更低的方差。 资料来源：[hessian_eigenthings/algorithms/trace.py](hessian_eigenthings/algorithms/trace.py)\n\n### Hutch++ 估计器\n\nHutch++ 是 Hutchinson 估计器的改进版本，通过结构性随机化实现更快的收敛。 资料来源：[docs/concepts/trace-estimation.md](docs/concepts/trace-estimation.md)\n\n### API 接口\n\n```python\ndef trace(\n operator: CurvatureOperator,\n num_matvecs: int = 100,\n *,\n method: Literal[\"hutchinson\", \"hutch++\"] = \"hutchinson\",\n seed: int | None = None,\n distribution: Distribution = \"rademacher\",\n backend: LinAlgBackend[torch.Tensor] | None = None,\n) -> TraceResult\n```\n\n### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `operator` | CurvatureOperator | 必需 | 曲率算子 |\n| `num_matvecs` | int | 100 | 矩阵-向量积样本数量 |\n| `method` | str | \"hutchinson\" | 估计方法 |\n| `seed` | int | None | 随机种子 |\n| `distribution` | str | \"rademacher\" | 随机向量分布 |\n\n### 实现细节\n\n```python\ndef hutchinson(\n operator: CurvatureOperator,\n num_samples: int = 100,\n distribution: Distribution = \"rademacher\",\n seed: int | None = None,\n backend: LinAlgBackend[torch.Tensor] | None = None,\n) -> TraceResult:\n \"\"\"Hutchinson's estimator. Rademacher gives lower variance for trace.\"\"\"\n probe = torch.empty(operator.size, dtype=operator.dtype, device=operator.device)\n samples = torch.empty(num_samples, dtype=operator.dtype, device=operator.device)\n for i in range(num_samples):\n v = _draw(distribution, probe, gen, backend)\n av = operator.matvec(v)\n samples[i] = backend.dot(v, av)\n \n estimate = samples.mean().item()\n if num_samples > 1:\n stderr = (samples.std(unbiased=True) / (num_samples) ** 0.5).item()\n```\n\n资料来源：[hessian_eigenthings/algorithms/trace.py:54-74](hessian_eigenthings/algorithms/trace.py)\n\n## 谱密度估计\n\n谱密度（spectral density）描述了特征值在整个谱上的分布情况，使用 Stochastic Lanczos Quadrature (SLQ) 方法计算。\n\n### Stochastic Lanczos Quadrature\n\nSLQ 结合了 Lanczos 算法和蒙特卡洛积分，通过少量 Lanczos 迭代来估计谱密度函数。 资料来源：[docs/concepts/spectral-density.md](docs/concepts/spectral-density.md)\n\n### 核心思想\n\n对于对称矩阵 A，谱密度定义为：\n\n```\nρ(λ) = (1/n) Σ δ(λ - λᵢ)\n```\n\n其中 δ 是 Dirac delta 函数。SLQ 通过随机起始向量和 Lanczos 迭代来近似这一分布。\n\n### 应用场景\n\n| 场景 | 说明 |\n|------|------|\n| 特征值分布可视化 | 绘制谱密度曲线观察特征值聚集情况 |\n| 批量大小选择 | 根据谱的宽度判断最优批量大小 |\n| 收敛性分析 | 观察 Hessian 谱结构判断优化器收敛速度 |\n\n## 算法选择指南\n\n```mermaid\ngraph TD\n A[分析目标] --> B{需要什么结果?}\n B --> C[Top-k 特征值/向量]\n B --> D[矩阵迹]\n B --> E[谱密度分布]\n B --> F[仅主导特征值]\n \n C --> G[Lanczos 算法]\n D --> H{精度要求}\n H --> I[高精度]\n H --> J[一般精度]\n F --> K[幂迭代法]\n \n I --> L[Hutch++]\n J --> M[Hutchinson]\n E --> N[SLQ]\n \n G --> O[结果: 特征值 + 特征向量]\n L --> P[结果: 迹估计值 + 标准误差]\n M --> P\n K --> Q[结果: 主导特征值]\n N --> R[结果: 密度采样点]\n```\n\n### 选择建议\n\n| 目标 | 推荐算法 | 理由 |\n|------|----------|------|\n| 计算 top-k 特征对 | Lanczos | 数值稳定，效率高 |\n| 估计矩阵迹 | Hutch++ | 更快收敛，更少 matvec |\n| 谱密度可视化 | SLQ | 一次运行多点估计 |\n| 简单主导特征值 | 幂迭代 | 实现简单，内存低 |\n\n## 并行化与后端支持\n\n所有算法均通过 `LinAlgBackend` 接口支持不同的计算后端：\n\n| 后端 | 适用场景 |\n|------|----------|\n| SingleDeviceBackend | 单 GPU/CPU 计算 |\n| 分布式后端 | 多 GPU 分布式计算 |\n\n算法与后端完全解耦，可以无缝切换设备或分布式策略。 资料来源：[hessian_eigenthings/algorithms/__init__.py](hessian_eigenthings/algorithms/__init__.py)\n\n## 使用示例\n\n### Lanczos 计算 Top-3 特征值\n\n```python\nfrom hessian_eigenthings import HessianOperator, lanczos\n\n# 创建 Hessian 算子\nhessian_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=loss_fn,\n)\n\n# 计算 top-3 特征值和特征向量\nresult = lanczos(hessian_op, k=3, max_iter=20, tol=1e-3, seed=0)\n\nprint(\"Top-3 eigenvalues:\")\nfor i, val in enumerate(result.eigenvalues):\n print(f\" λ_{i+1} = {val.item():.4e}\")\n```\n\n### 迹估计\n\n```python\nfrom hessian_eigenthings import trace\n\ntrace_result = trace(\n hessian_op,\n num_matvecs=30,\n method=\"hutch++\",\n seed=0\n)\n\nprint(f\"Hutch++ trace estimate: {trace_result.estimate:.4e}\")\n```\n\n## 算法模块结构\n\n```\nhessian_eigenthings/algorithms/\n├── __init__.py # 公共 API 导出\n├── lanczos.py # Lanczos 特征分解\n├── trace.py # 迹估计 (Hutchinson/Hutch++)\n├── spectral_density.py # Stochastic Lanczos Quadrature\n└── power_iteration.py # 幂迭代法\n```\n\n资料来源：[docs/reference/algorithms.md](docs/reference/algorithms.md)\n\n## 性能考量\n\n| 算法 | 每次迭代复杂度 | 内存需求 | 收敛速度 |\n|------|----------------|----------|----------|\n| Lanczos | O(n²) per matvec | O(n·k) | 快（对极端特征值） |\n| 幂迭代 | O(n²) per matvec | O(n) | 慢（仅主导特征值） |\n| Hutchinson | O(n²) per matvec | O(n) | O(1/√m) |\n| Hutch++ | O(n²) per matvec | O(n) | 比 Hutchinson 快 |\n\n其中 n 是参数数量，k 是目标特征值数量，m 是随机样本数。\n\n---\n\n\n\n## 参数工具模块\n\n### 相关页面\n\n相关主题：[核心架构设计](#page-core-architecture), [曲率算子详解](#page-operators)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [hessian_eigenthings/param_utils.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/param_utils.py)\n- [docs/reference/param_utils.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/reference/param_utils.md)\n- [docs/how-to/per-layer-hessian.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/how-to/per-layer-hessian.md)\n \n\n# 参数工具模块\n\n参数工具模块（`param_utils`）是 `hessian-eigenthings` 库中用于参数选择、过滤和批量操作的实用工具集合。该模块提供了灵活的模式匹配机制，允许用户对 PyTorch 模型中的特定参数或参数组进行曲率分析，如 Hessian 矩阵的特征分解。\n\n## 模块概述\n\n在神经网络的曲率分析中，通常不需要对整个模型的所有参数进行计算。参数工具模块提供了基于名称模式的参数过滤功能，使得用户可以针对性地分析：\n\n- 模型中特定层的 Hessian 矩阵\n- 注意力机制的曲率特性\n- 全连接层或卷积层的参数\n- 任意自定义的参数子集\n\n资料来源：[hessian_eigenthings/param_utils.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/param_utils.py)\n\n## 核心功能\n\n### `match_names` 函数\n\n`match_names` 是该模块的核心函数，用于创建一个参数过滤器（`ParamFilter`），基于参数名称的模式匹配来选择特定参数。\n\n**函数签名：**\n\n```python\ndef match_names(*patterns: str) -> ParamFilter\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `patterns` | `str` | 逗号分隔的名称模式，支持通配符 `*` 匹配任意字符序列 |\n\n**返回值：**\n\n返回一个 `ParamFilter` 类型的函数，该函数接受模型参数名称列表，返回匹配模式的所有参数名称集合。\n\n资料来源：[hessian_eigenthings/param_utils.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/param_utils.py)\n\n### `ParamFilter` 类型\n\n`ParamFilter` 是模块中定义的核心类型别名：\n\n```python\nParamFilter = Callable[[list[str]], set[str]]\n```\n\n它表示一个函数，接收参数名称列表，返回匹配的参数名称集合。这种设计使得参数过滤逻辑与具体算子解耦，提高了模块的可复用性。\n\n资料来源：[docs/reference/param_utils.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/reference/param_utils.md)\n\n## 使用模式\n\n### 单层参数过滤\n\n选择模型中所有与 \"attention\" 相关的参数：\n\n```python\nfrom hessian_eigenthings import HessianOperator\nfrom hessian_eigenthings.param_utils import match_names\n\nattn_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=loss_fn,\n param_filter=match_names(\"*attn*\"),\n)\n```\n\n资料来源：[examples/transformer_lens_attention_only.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/examples/transformer_lens_attention_only.py)\n\n### 多层参数过滤\n\n使用多个模式匹配不同层级的参数：\n\n```python\nfrom hessian_eigenthings import HessianOperator\nfrom hessian_eigenthings.param_utils import match_names\n\n# 匹配 transformer.h.*.attn.* 模式的参数\nattn_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=loss_fn,\n param_filter=match_names(\"transformer.h.*.attn.*\"),\n)\n\n# 匹配 MLP 相关参数\nmlp_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=loss_fn,\n param_filter=match_names(\"blocks.*.mlp.*\"),\n)\n```\n\n资料来源：[examples/huggingface_tiny_gpt2.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/examples/huggingface_tiny_gpt2.py)\n\n### 与曲率算子集成\n\n参数过滤器与 `HessianOperator`、`GGNOperator` 等曲率算子无缝集成。当 `param_filter` 被指定时，算子仅对过滤后的参数子集进行操作：\n\n```python\nfrom hessian_eigenthings import HessianOperator, lanczos\nfrom hessian_eigenthings.param_utils import match_names\n\n# 创建仅包含注意力层参数的 Hessian 算子\nhessian_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=loss_fn,\n param_filter=match_names(\"*attention*\", \"*attn*\"),\n)\n\n# 计算该子集的 top-k 特征值\neigenvalues, eigenvectors = lanczos(hessian_op, k=5, max_iter=50)\n```\n\n资料来源：[docs/how-to/per-layer-hessian.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/how-to/per-layer-hessian.md)\n\n## 参数过滤流程\n\n以下流程图展示了参数过滤在曲率分析中的完整流程：\n\n```mermaid\ngraph TD\n A[PyTorch 模型] --> B[获取所有参数名称]\n B --> C[应用 param_filter]\n C --> D{匹配检查}\n D -->|匹配成功| E[包含在曲率计算中]\n D -->|匹配失败| F[排除在外]\n E --> G[创建 CurvatureOperator 子集]\n G --> H[执行 Lanczos 算法]\n H --> I[返回特征值/特征向量]\n F --> J[跳过该参数]\n```\n\n## 模式匹配语法\n\n| 模式示例 | 匹配内容 | 示例 |\n|----------|----------|------|\n| `*attn*` | 包含 \"attn\" 的任意参数名 | `blocks.0.attn.weight`, `model.attn_bias` |\n| `*.weight` | 以 \".weight\" 结尾的参数 | `layer1.weight`, `fc2.weight` |\n| `blocks.*.mlp.*` | blocks 下任意深度的 mlp 参数 | `blocks.0.mlp.linear1.weight` |\n| `*bias*` | 包含 \"bias\" 的参数 | `fc.bias`, `layer_norm.bias` |\n\n## 最佳实践\n\n### 1. 精确匹配优先\n\n为避免意外匹配无关参数，使用更精确的模式：\n\n```python\n# 较优：精确匹配 attention 层\nparam_filter=match_names(\"transformer.h.*.attn.*\")\n\n# 较粗：可能匹配到不相关的参数\nparam_filter=match_names(\"*attn*\")\n```\n\n### 2. 组合使用多个模式\n\n当需要选择多个非连续区域的参数时：\n\n```python\n# 同时选择 attention 和 embedding 层\nparam_filter=match_names(\"*attn*\", \"*embed*\", \"*embedding*\")\n```\n\n### 3. 验证过滤结果\n\n在实际计算前验证过滤是否正确：\n\n```python\nfrom hessian_eigenthings.param_utils import match_names\n\nparam_filter = match_names(\"blocks.*.attn.*\")\nall_params = list(model.named_parameters())\nmatched = param_filter([n for n, _ in all_params])\n\nprint(f\"匹配到的参数数量: {len(matched)}\")\nfor name in matched:\n print(f\" - {name}\")\n```\n\n资料来源：[docs/how-to/per-layer-hessian.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/how-to/per-layer-hessian.md)\n\n## API 参考\n\n### `hessian_eigenthings.param_utils`\n\n| 函数/类型 | 说明 |\n|-----------|------|\n| `match_names(*patterns: str) -> ParamFilter` | 创建基于模式的参数过滤器 |\n| `ParamFilter` | 类型别名，表示参数过滤函数类型 |\n\n### 导出列表\n\n模块默认导出：\n\n```python\nfrom hessian_eigenthings.param_utils import match_names, ParamFilter\n```\n\n资料来源：[docs/reference/param_utils.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/reference/param_utils.md)\n\n## 与其他模块的关系\n\n参数工具模块在整体架构中扮演基础工具角色，为曲率算子提供参数选择能力：\n\n```mermaid\ngraph LR\n A[param_utils] -->|提供 ParamFilter| B[HessianOperator]\n A -->|提供 ParamFilter| C[GGNOperator]\n A -->|提供 ParamFilter| D[EmpiricalFisher]\n B --> E[lanczos 算法]\n C --> E\n D --> E\n E --> F[特征值/特征向量结果]\n```\n\n这种设计确保了参数过滤逻辑的统一实现，避免了在各个算子中重复定义相同的过滤机制。\n\n---\n\n\n\n## 损失函数模块\n\n### 相关页面\n\n相关主题：[曲率算子详解](#page-operators)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [hessian_eigenthings/loss_fns/__init__.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/loss_fns/__init__.py)\n- [hessian_eigenthings/loss_fns/standard.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/loss_fns/standard.py)\n- [hessian_eigenthings/loss_fns/_fused_ce_hvp.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/loss_fns/_fused_ce_hvp.py)\n- [hessian_eigenthings/loss_fns/huggingface.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/loss_fns/huggingface.py)\n- [hessian_eigenthings/operators/ggn.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/ggn.py)\n \n\n# 损失函数模块\n\n## 概述\n\n损失函数模块（`hessian_eigenthings/loss_fns/`）是 pytorch-hessian-eigenthings 项目中连接用户模型输出与曲率算子（CurvatureOperator）的桥梁。该模块的核心职责是将各种损失函数的计算过程适配为统一的函数签名，使 HessianOperator 和 GGNOperator 能够正确计算损失相对于模型输出的 Hessian 向量积（HVP）。\n\n资料来源：[hessian_eigenthings/loss_fns/__init__.py]()\n\n```mermaid\ngraph TD\n subgraph 用户模型\n A[模型前向传播] --> B[logits 输出]\n end\n \n subgraph 损失函数模块\n C[forward_fn] --> D[loss_of_output_fn]\n B --> C\n B --> D\n end\n \n subgraph 曲率算子\n E[HessianOperator / GGNOperator]\n D --> E\n end\n \n E --> F[matvec 计算]\n F --> G[Hessian / GGN 向量积]\n```\n\n## 模块架构\n\n### 文件结构\n\n| 文件 | 用途 |\n|------|------|\n| `__init__.py` | 模块导出接口 |\n| `standard.py` | 标准分类/回归损失函数封装 |\n| `huggingface.py` | HuggingFace Transformers 模型专用损失封装 |\n| `_fused_ce_hvp.py` | 融合交叉熵 HVP 核心实现 |\n\n资料来源：[hessian_eigenthings/loss_fns/__init__.py](), [hessian_eigenthings/loss_fns/standard.py](), [hessian_eigenthings/loss_fns/huggingface.py]()\n\n### 核心函数签名\n\n损失函数模块定义了两类关键函数签名，供曲率算子调用：\n\n```python\n# 类型1: forward_fn - 模型前向传播函数\nForwardFn = Callable[[nn.Module, Any], torch.Tensor]\n\n# 类型2: loss_of_output_fn - 从模型输出计算损失的函数\nLossOfOutputFn = Callable[[torch.Tensor, Any], torch.Tensor]\n\n# 类型3: 可选的 HVP 函数 (用于 GGNOperator)\nHvpFn = Callable[[torch.Tensor, Any, torch.Tensor], torch.Tensor]\n```\n\n资料来源：[hessian_eigenthings/operators/ggn.py]()\n\n## 标准损失函数\n\n`standard.py` 模块提供了基于标准 PyTorch 损失函数的封装实现。\n\n资料来源：[hessian_eigenthings/loss_fns/standard.py]()\n\n### 分类损失\n\n对于多分类任务，模块实现了交叉熵损失的闭式 HVP 计算。对于 mean-reduced softmax + cross-entropy，损失函数为：\n\n```python\nH_row = (diag(p) - p p^T) / N\n```\n\n其中 `p = softmax(output)` 是模型输出的概率分布。\n\n```python\ndef _ce_hvp(\n output: torch.Tensor, \n batch: tuple[torch.Tensor, torch.Tensor], \n u: torch.Tensor\n) -> torch.Tensor:\n \"\"\"闭式 H @ u for mean-reduced softmax + cross-entropy.\"\"\"\n flat_output = output.reshape(-1, output.size(-1))\n flat_u = u.reshape(-1, u.size(-1))\n n = float(flat_output.size(0))\n p = torch.softmax(flat_output, dim=-1)\n dot = (p * flat_u).sum(dim=-1, keepdim=True)\n return ((p * flat_u - p * dot) / n).view_as(u)\n```\n\n资料来源：[hessian_eigenthings/loss_fns/standard.py:32-45]()\n\n### GGNOperator 兼容封装\n\n```python\ndef _make_loss_of_output_fn(\n criterion: Callable[[torch.Tensor, torch.Tensor], torch.Tensor]\n) -> Callable[[torch.Tensor, tuple[torch.Tensor, torch.Tensor]], torch.Tensor]:\n \"\"\"为 GGNOperator 从 (output, target) 损失构造 loss_of_output_fn.\"\"\"\n \n def _fn(output: torch.Tensor, batch: tuple[torch.Tensor, torch.Tensor]) -> torch.Tensor:\n _, y = batch\n return criterion(output, y)\n \n return _fn\n```\n\n资料来源：[hessian_eigenthings/loss_fns/standard.py:10-19]()\n\n## HuggingFace Transformers 损失函数\n\n`huggingface.py` 模块专为 HuggingFace Transformers 库设计的预训练模型提供损失函数封装。\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py]()\n\n### API 设计\n\nHuggingFace 模型在提供 `labels` 时会内部计算损失，返回包含 `.loss` 和 `.logits` 的 `ModelOutput`。模块将这些适配为算子期望的函数签名：\n\n```python\ndef hf_lm_loss(\n fused: FusedCEHvpBackend = \"auto\"\n) -> tuple[ForwardFn, LossOfOutputFn, HvpFn]:\n \"\"\"返回 HuggingFace LM 的 forward_fn, loss_of_output_fn 和 HVP 函数.\"\"\"\n```\n\n### Shifted Cross-Entropy 损失\n\n对于因果语言模型（Causal LM），输入 token 序列需要向右移动一位作为标签（shifted CE）：\n\n```python\ndef _hf_lm_shifted_ce(\n logits: torch.Tensor, \n batch: dict[str, Any]\n) -> torch.Tensor:\n \"\"\"Shifted cross-entropy loss for causal language models.\"\"\"\n labels = batch[\"labels\"]\n # logits: (B, T, V), labels: (B, T)\n logits = logits[:, :-1, :].contiguous()\n labels = labels[:, 1:].contiguous()\n return torch.nn.functional.cross_entropy(\n logits.view(-1, logits.size(-1)), \n labels.view(-1),\n ignore_index=-100\n )\n```\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py]()\n\n### 闭式 H_loss @ u\n\n对于 shifted CE loss，`H_loss` 在 `(B, T-1)` 上是块对角矩阵，每个块的形状为：\n\n```\nH_block = (diag(p_t) - p_t p_t^T) / n\n```\n\n其中 `p_t = softmax(shift_logits_t)`，`n` 是非忽略位置的数量。\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py]()\n\n## 融合 CE HVP 实现\n\n`_fused_ce_hvp.py` 提供了交叉熵 Hessian 向量积的高性能融合实现。\n\n资料来源：[hessian_eigenthings/loss_fns/_fused_ce_hvp.py]()\n\n### 计算公式\n\n融合实现计算：\n\n```\nout_flat = (p * u - p * ) * mask / n_valid\n```\n\n输出形状为 `(N, V)`，其中 `N` 是 batch 中的 token 数量，`V` 是词表大小。\n\n### 后端选项\n\n| 后端 | 描述 | 优势 |\n|------|------|------|\n| `\"auto\"` | 自动选择最快可用后端 | 智能适配 |\n| `\"eager\"` | 普通 PyTorch 实现 | 易调试、兼容性最好 |\n| `\"compile\"` | `torch.compile` 融合 | 约 2.6x 加速，2x 内存减少 |\n| `\"triton\"` | Triton CUDA kernel | 约 3.4x 加速，零中间内存 |\n\n资料来源：[hessian_eigenthings/loss_fns/_fused_ce_hvp.py](), [hessian_eigenthings/loss_fns/huggingface.py]()\n\n### 后端自动选择逻辑\n\n```python\ndef _resolve_backend(\n backend: FusedCEHvpBackend, \n logits: torch.Tensor | None = None\n) -> FusedCEHvpBackend:\n \"\"\"Resolve ``\"auto\"`` to the fastest available concrete backend.\"\"\"\n if backend != \"auto\":\n return backend\n \n # 优先级: triton (CUDA + Triton可用) → compile → eager\n if _triton_available and logits is not None and logits.is_cuda:\n return \"triton\"\n return \"compile\"\n```\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py]()\n\n### 参考实现\n\n```python\ndef _ce_hvp_reference(\n flat_logits: torch.Tensor,\n flat_u: torch.Tensor,\n valid: torch.Tensor,\n n: torch.Tensor,\n) -> torch.Tensor:\n \"\"\"Eager reference implementation.\"\"\"\n p = torch.softmax(flat_logits, dim=-1)\n dot = (p * flat_u).sum(dim=-1, keepdim=True)\n return (p * flat_u - p * dot) * valid.unsqueeze(-1) / n\n```\n\n资料来源：[hessian_eigenthings/loss_fns/_fused_ce_hvp.py]()\n\n## GGNOperator 中的损失函数集成\n\nGGNOperator 支持两种 matvec 实现路径，通过 `loss_hvp` 参数控制：\n\n资料来源：[hessian_eigenthings/operators/ggn.py]()\n\n### Analytical 路径（默认）\n\n```python\n# 有限差分 JVP + 解析 loss-Hessian-向量积\nloss_hvp = loss_of_output_fn.hvp # 必须存在\n```\n\n内存占用匹配一次正常训练步骤，适用于 LM 规模的使用场景。\n\n### Autograd 路径（备用）\n\n```python\n# torch.func.jvp + autograd 双重反向 + torch.func.vjp\n```\n\n数值精确、支持任意损失函数，但对大词表分类头内存消耗严重。\n\n## 使用示例\n\n### 标准分类任务\n\n```python\nfrom hessian_eigenthings.operators import HessianOperator\nfrom hessian_eigenthings.loss_fns.standard import cross_entropy_loss_of_output\n\nloss_fn = cross_entropy_loss_of_output()\n\nhessian_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=hf_lm_loss(),\n)\n```\n\n### HuggingFace 模型\n\n```python\nfrom hessian_eigenthings.loss_fns.huggingface import hf_lm_loss\n\nforward_fn, loss_of_output_fn, hvp_fn = hf_lm_loss(fused=\"auto\")\n```\n\n## 性能对比\n\n| 实现方式 | 内存峰值 (V=50304) | 速度 |\n|----------|-------------------|------|\n| eager | ~19.6 GB | 1x |\n| compile | ~3.3 GB | ~2.6x |\n| triton | 最小 | ~3.4x |\n\n资料来源：[scripts/bench_fused_ce_hvp.py]()\n\n## 扩展指南\n\n添加新的损失函数封装需要：\n\n1. 实现 `loss_of_output_fn(output, batch)` 接口\n2. 可选实现 `.hvp(output, batch, u)` 属性用于 GGNOperator\n3. 保持与 `CurvatureOperator` 的兼容性\n\n资料来源：[CONTRIBUTING.md]()\n\n---\n\n\n\n## HuggingFace 模型集成\n\n### 相关页面\n\n相关主题：[损失函数模块](#page-loss-functions)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [hessian_eigenthings/loss_fns/huggingface.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/loss_fns/huggingface.py)\n- [examples/huggingface_tiny_gpt2.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/examples/huggingface_tiny_gpt2.py)\n- [hessian_eigenthings/operators/ggn.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/ggn.py)\n- [hessian_eigenthings/loss_fns/_fused_ce_hvp.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/loss_fns/_fused_ce_hvp.py)\n- [hessian_eigenthings/algorithms/lanczos.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/lanczos.py)\n \n\n# HuggingFace 模型集成\n\n## 概述\n\nHuggingFace 模型集成是 `hessian-eigenthings` 库为 HuggingFace Transformer 模型提供的专用损失函数和优化计算路径。该模块位于 `hessian_eigenthings/loss_fns/huggingface.py`，专门针对因果语言模型（Causal Language Model）的交叉熵损失实现了闭合形式的 Hessian-向量乘积（Hessian-Vector Product, HVP）计算。\n\n主要功能包括：\n\n- **移位交叉熵损失**：适配因果语言建模任务的特殊损失计算\n- **闭合形式 HVP**：避免 autograd 双反向传播的内存开销\n- **多后端支持**：支持 Triton、torch.compile 和 eager 模式\n- **GGNOperator 集成**：与广义 Gauss-Newton 算子无缝配合\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py:1-100]()\n\n## 架构设计\n\n### 模块依赖关系\n\n```mermaid\ngraph TD\n subgraph \"用户代码\"\n A[\"用户模型
(如 GPT-2)\"]\n B[\"DataLoader\"]\n end\n \n subgraph \"huggingface.py\"\n C[\"huggingface_lm_loss()\"]\n D[\"_hf_lm_shifted_ce\"]\n E[\"_hf_lm_ce_hvp\"]\n end\n \n subgraph \"GGNOperator\"\n F[\"loss_of_output_fn\"]\n G[\"loss_hvp='analytical'\"]\n end\n \n subgraph \"后端实现\"\n H[\"Triton 内核\"]\n I[\"torch.compile\"]\n J[\"Eager PyTorch\"]\n end\n \n A --> C\n B --> C\n C --> D\n C --> E\n D --> F\n E --> G\n G --> H\n G --> I\n G --> J\n```\n\n### 闭合形式 Hessian 计算原理\n\n对于均规约的 softmax + 交叉熵损失，Hessian 在 `(B, T-1)` 上呈块对角结构。每个时间步 `t` 的块为：\n\n$$H_{loss}[t] = \\frac{1}{n}(\\text{diag}(p_t) - p_t p_t^T)$$\n\n其中：\n- $p_t = \\text{softmax}(\\text{shift\\_logits}_t)$ 是 softmax 概率分布\n- $n$ 是非忽略位置的计数\n\n这使得 Hessian-向量乘积可以闭合计算，无需构建完整的 Hessian 矩阵：\n\n$$H_{loss} \\cdot u = \\frac{p \\cdot u - p \\cdot \\langle p, u \\rangle}{n}$$\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py:28-40]()\n\n## 核心 API\n\n### `huggingface_lm_loss()`\n\n创建适用于 HuggingFace 因果语言模型的损失函数，包含闭合形式 HVP。\n\n```python\ndef huggingface_lm_loss(fused: str = \"auto\") -> _LossOfOutputWithHvp:\n```\n\n#### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `fused` | `str` | `\"auto\"` | CE HVP 核选择策略 |\n\n#### `fused` 选项\n\n| 值 | 说明 | 性能特性 |\n|----|------|----------|\n| `\"auto\"` | 自动选择（CUDA+Triton 可用时优先 Triton） | 最优性能 |\n| `\"eager\"` | 纯 PyTorch eager 模式 | 易调试，但 V≥50k 时易 OOM |\n| `\"compile\"` | `torch.compile` 融合 | CPU/CUDA/MPS 通用 |\n| `\"triton\"` | 手写 Triton CUDA 内核 | 峰值内存最小 |\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py:80-95]()\n\n### 返回值\n\n返回 `_LossOfOutputWithHvp` 对象，包含：\n\n- `__call__(logits, batch)` → `torch.Tensor`：损失标量\n- `.hvp(logits, batch, u)` → `torch.Tensor`：闭合形式 HVP\n\n## 计算后端\n\n### 后端选择流程\n\n```mermaid\ngraph TD\n A[\"fused='auto'\"] --> B{\"CUDA + Triton 可用?\"}\n B -->|是| C[\"使用 Triton 内核\"]\n B -->|否| D[\"使用 torch.compile\"]\n \n E[\"fused='eager'\"] --> F[\"纯 PyTorch Eager\"]\n G[\"fused='compile'\"] --> H[\"torch.compile 融合\"]\n I[\"fused='triton'\"] --> J{\"Triton/CUDA 可用?\"}\n J -->|否| K[\"回退到 compile\"]\n J -->|是| C\n```\n\n### 融合计算数学\n\n核心计算在 `(N, V)` 形状的张量上进行：\n\n```python\np = softmax(logits) # (N, V) 概率分布\ndot = (p * u).sum(dim=-1) # (N,) 点积\nhvp = (p * u - p * dot) * mask / n # (N, V) 结果\n```\n\n资料来源：[hessian_eigenthings/loss_fns/_fused_ce_hvp.py:1-50]()\n\n### 内存优化\n\n不同后端的内存占用对比（B=64, T=256, V=50304, fp32）：\n\n| 后端 | 内存估算 | (N,V) 张量数量 |\n|------|----------|----------------|\n| eager | ~19.6 GB | ~6 个中间张量 |\n| compile | ~3.3 GB | ~1 个（输出缓冲） |\n| triton | 最小 | 0 个中间张量 |\n\n资料来源：[scripts/bench_fused_ce_hvp.py:1-30]()\n\n## 与 GGNOperator 的集成\n\n### 工作流程\n\n```mermaid\ngraph LR\n A[\"模型 + DataLoader\"] --> B[\"GGNOperator\"]\n B --> C{\"loss_hvp 参数?\"}\n C -->|\"有 .hvp 方法\"| D[\"analytical 路径
有限差分 JVP + 解析 HVP\"]\n C -->|\"无 .hvp 方法\"| E[\"autograd 路径
torch.func.jvp + 双反向传播\"]\n \n D --> F[\"内存占用 = 单步训练\"]\n E --> G[\"内存随输出规模增长\"]\n```\n\n### analytical 路径优势\n\n当使用 `huggingface_lm_loss()` 返回的损失函数时：\n\n1. **有限差分 JVP**：单次前向通过计算雅可比向量乘积\n2. **解析 HVP**：使用闭合形式公式计算损失 Hessian-向量乘积\n3. **单次反向传播**：应用 $J^T$ 矩阵\n\n整体内存占用与单次训练步骤相当，适合 LLM 规模分析。\n\n资料来源：[hessian_eigenthings/operators/ggn.py:1-80]()\n\n## 使用示例\n\n### 完整分析流程\n\n```python\nimport torch\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\nfrom hessian_eigenthings.operators import HessianOperator, GGNOperator\nfrom hessian_eigenthings.loss_fns.huggingface import huggingface_lm_loss\nfrom hessian_eigenthings.algorithms import lanczos, trace\n\n# 1. 加载模型\nmodel = AutoModelForCausalLM.from_pretrained(\"openai-community/gpt2\")\ntokenizer = AutoTokenizer.from_pretrained(\"openai-community/gpt2\")\n\n# 2. 准备数据\ntexts = [\"the quick brown fox jumps over\"]\nencoded = tokenizer(texts, padding=True, return_tensors=\"pt\")\nencoded[\"labels\"] = encoded[\"input_ids\"].clone()\ndataloader = [dict(encoded)]\n\n# 3. 创建损失函数（带闭合形式 HVP）\nhf_loss = huggingface_lm_loss(fused=\"auto\")\n\n# 4. 创建 GGN 算子\nggn_op = GGNOperator(\n model=model,\n dataloader=dataloader,\n forward_fn=lambda m, b: m(**b).logits,\n loss_of_output_fn=hf_loss,\n)\n\n# 5. 计算 top-k 特征值\neig_result = lanczos(ggn_op, k=3, max_iter=20, tol=1e-3, seed=0)\nprint(f\"Top-3 特征值: {eig_result.eigenvalues}\")\n\n# 6. 估计迹\ntrace_result = trace(ggn_op, num_matvecs=30, method=\"hutch++\", seed=0)\nprint(f\"Hutch++ 迹估计: {trace_result.estimate}\")\n```\n\n资料来源：[examples/huggingface_tiny_gpt2.py:1-60]()\n\n### 注意力层子空间分析\n\n```python\nfrom hessian_eigenthings.operators import HessianOperator\n\n# 仅分析注意力参数\nattn_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=hf_loss,\n param_filter=lambda n, p: \"attn\" in n, # 参数过滤器\n)\n\neig_attn = lanczos(attn_op, k=3, max_iter=20, tol=1e-3, seed=0)\nprint(f\"注意力层 top-3 特征值: {eig_attn.eigenvalues}\")\n```\n\n## 参数过滤器\n\n参数过滤器用于限制 Hessian 分析的子空间：\n\n| 过滤器模式 | 说明 | 示例 |\n|-----------|------|------|\n| `lambda n, p: \"attn\" in n` | 按名称包含 | 提取注意力参数 |\n| `lambda n, p: \"mlp\" in n` | 按名称包含 | 提取 MLP 参数 |\n| `lambda n, p: p.numel() > 1000` | 按大小过滤 | 排除偏置和小型参数 |\n\n## 与 TransformerLens 的对比\n\n| 特性 | HuggingFace 集成 | TransformerLens 集成 |\n|------|------------------|---------------------|\n| 模型支持 | GPT-2, LLaMA 等主流模型 | HookedTransformer |\n| 损失函数 | 因果语言模型交叉熵 | 可自定义 |\n| 示例文件 | `huggingface_tiny_gpt2.py` | `transformer_lens_attention_only.py` |\n| API | `huggingface_lm_loss()` | `tlens_loss()` |\n\n资料来源：[examples/transformer_lens_attention_only.py:1-50]()\n\n## 常见问题与限制\n\n### 内存溢出 (OOM) 处理\n\n若在 LLM 上遇到 OOM：\n\n1. **使用 analytical 路径**：确保使用 `huggingface_lm_loss()` 而非通用损失\n2. **切换到 finite_difference**：对 HessianOperator 使用 `method=\"finite_difference\"`\n3. **减小批量大小**：减少 dataloader 中的样本数\n4. **使用 bf16**：对大模型使用 bfloat16 精度\n\n资料来源：[scripts/repro_ggn_oom.py:1-50]()\n\n### 数值精度\n\n- **autograd 路径**：数值精确（至浮点精度）\n- **finite_difference 路径**：存在 $O(\\varepsilon^2)$ 截断偏差\n- **analytical 路径**：闭合形式，数值精确\n\n## 扩展阅读\n\n- [自定义曲率算子](../how-to/custom-curvature-operators.md)\n- [Lanczos 算法详解](../concepts/lanczos-algorithm.md)\n- [迹估计方法](../concepts/trace-estimation.md)\n\n---\n\n\n\n## 分布式训练支持 (DDP)\n\n### 相关页面\n\n相关主题：[曲率算子详解](#page-operators), [HuggingFace 模型集成](#page-huggingface-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [hessian_eigenthings/operators/distributed/__init__.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/distributed/__init__.py)\n- [hessian_eigenthings/operators/distributed/ddp.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/distributed/ddp.py)\n- [hessian_eigenthings/operators/hessian.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/hessian.py)\n- [hessian_eigenthings/algorithms/lanczos.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/lanczos.py)\n- [hessian_eigenthings/algorithms/trace.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/trace.py)\n \n\n# 分布式训练支持 (DDP)\n\n## 概述\n\n`hessian-eigenthings` 库通过 `DDPHessianOperator` 提供对 PyTorch 分布式数据并行（DistributedDataParallel, DDP）训练的原生支持。这一功能允许用户在多 GPU 或多节点分布式训练环境下计算 Hessian 矩阵的特征值分解，而无需修改现有的 DDP 训练代码。\n\n在分布式训练场景中，Hessian 分析面临独特的挑战：由于模型参数分布在多个进程上，梯度计算和损失聚合需要在进程间同步。`DDPHessianOperator` 封装了这些复杂性，提供了与单机 `HessianOperator` 一致的接口，使得分布式 Hessian 分析可以像单机使用一样简单。\n\n## 模块结构\n\n分布式模块位于 `hessian_eigenthings/operators/distributed/` 目录下，通过统一的导出接口供外部使用：\n\n```python\nfrom hessian_eigenthings.operators.distributed import DDPHessianOperator\n```\n\n资料来源：[hessian_eigenthings/operators/distributed/__init__.py:1]()\n\n## DDPHessianOperator 核心设计\n\n### 类继承关系\n\n`DDPHessianOperator` 继承自 `CurvatureOperator` 基类，遵循库中统一的曲率算子架构。这使得它可以与现有的 Lanczos 算法、trace 估计等工具无缝配合工作。\n\n### 主要功能特性\n\n| 特性 | 说明 |\n|------|------|\n| 自动梯度同步 | 在 `no_grad` 上下文中执行模型前向传播，确保梯度计算的一致性 |\n| 进程间通信优化 | 复用 DDP 的梯度桶机制，减少额外通信开销 |\n| 参数过滤支持 | 可通过 `param_filter` 参数选择性地分析特定参数子集的 Hessian |\n| 与 DDP 兼容 | 直接接收包装后的 DDP 模型，无需特殊处理 |\n\n### 构造函数参数\n\n`DDPHessianOperator` 的初始化签名与 `HessianOperator` 保持高度一致，降低了用户的学习成本：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `model` | `nn.Module` | DDP 包装后的模型实例 |\n| `dataloader` | `Iterable[Any]` | 数据加载器，提供批次数数据 |\n| `loss_fn` | `LossFn` | 损失函数，签名 `loss_fn(model_output, target) -> scalar` |\n| `param_filter` | `ParamFilter \\| None` | 可选参数过滤器，用于选择分析的参数子集 |\n| `full_dataset` | `bool` | 是否使用完整数据集（默认 `True`） |\n| `num_batches` | `int \\| None` | 使用的批次数，优先于 `full_dataset` |\n| `method` | `HvpMethod` | HVP 计算方法：`\"autograd\"` 或 `\"finite_difference\"` |\n\n## 使用工作流\n\n### 基础使用模式\n\n```python\nimport torch\nimport torch.distributed as dist\nfrom torch.nn.parallel import DistributedDataParallel as DDP\nfrom hessian_eigenthings.operators.distributed import DDPHessianOperator\nfrom hessian_eigenthings.algorithms.lanczos import lanczos\n\n# 初始化分布式环境（本地示例）\ndist.init_process_group(backend=\"nccl\")\n\n# 创建和包装模型\nmodel = MyModel().cuda(rank)\nmodel = DDP(model, device_ids=[local_rank])\n\n# 准备数据\ndataloader = distributed_data_loader()\n\n# 创建分布式 Hessian 算子\nhessian_op = DDPHessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=my_loss_fn,\n)\n\n# 计算特征值分解\neigenvalues, eigenvectors = lanczos(hessian_op, k=10, max_iter=50)\n```\n\n### 与 Lanczos 算法集成\n\n`DDPHessianOperator` 可直接作为 `lanczos()` 函数的输入，用于计算分布式模型 Hessian 的 top-k 特征值和特征向量：\n\n```python\nfrom hessian_eigenthings.algorithms.lanczos import lanczos\n\nresult = lanczos(\n operator=hessian_op,\n k=5,\n max_iter=100,\n tol=1e-6,\n seed=42,\n backend=SingleDeviceBackend()\n)\n\nprint(f\"Top eigenvalues: {result.eigenvalues}\")\n```\n\n### 与 Trace 估计集成\n\n同样支持 `hutchinson()` 和 `hutch_plus_plus()` 方法进行 Hessian 迹估计：\n\n```python\nfrom hessian_eigenthings.algorithms.trace import hutch_plus_plus\n\ntrace_result = hutch_plus_plus(\n operator=hessian_op,\n num_matvecs=100,\n seed=0\n)\n\nprint(f\"Hessian trace estimate: {trace_result.estimate:.4e}\")\n```\n\n## 架构设计\n\n### 分布式 Hessian 计算流程\n\n```mermaid\ngraph TD\n A[初始化 DDP 模型] --> B[创建 DDPHessianOperator]\n B --> C[分布式数据加载]\n C --> D{每个 Rank 执行}\n D --> E[本地前向传播]\n E --> F[本地损失计算]\n F --> G[梯度同步 DDP]\n G --> H[本地 HVP 计算]\n H --> I[进程间结果聚合]\n I --> J[返回全局曲率信息]\n```\n\n### 与单机 HessianOperator 的差异\n\n| 方面 | HessianOperator | DDPHessianOperator |\n|------|-----------------|-------------------|\n| 模型输入 | 普通 `nn.Module` | DDP 包装后的模型 |\n| 梯度计算 | 单机梯度 | 聚合后的分布式梯度 |\n| 设备管理 | 单设备 | 多设备（每 Rank 一个） |\n| 通信开销 | 无 | DDP 梯度同步开销 |\n| 使用场景 | 单机实验 | 大规模分布式训练 |\n\n## 实现注意事项\n\n### 1. 分布式环境初始化\n\n使用 `DDPHessianOperator` 前必须确保分布式环境已正确初始化。库依赖 PyTorch 的 `torch.distributed` 模块进行进程间通信。\n\n### 2. 数据分发\n\n数据加载器应为分布式版本，确保每个 Rank 处理不同的数据分片。推荐使用 `DistributedSampler`：\n\n```python\nfrom torch.utils.data.distributed import DistributedSampler\n\nsampler = DistributedSampler(dataset, num_replicas=world_size, rank=rank)\ndataloader = DataLoader(dataset, sampler=sampler, batch_size=batch_size)\n```\n\n### 3. 同步点处理\n\n`DDPHessianOperator` 在计算过程中会自动处理必要的进程间同步，确保所有 Rank 在关键步骤上保持同步，避免不一致的梯度状态。\n\n## 性能考虑\n\n### 通信开销\n\n由于 Hessian 向量乘积计算需要梯度信息，`DDPHessianOperator` 会引入额外的梯度同步开销。优化建议：\n\n- 使用足够大的批量大小以分摊通信成本\n- 在需要分析的特定层使用参数过滤，减少计算范围\n- 考虑在训练间隙进行 Hessian 分析，而非实时计算\n\n### 内存效率\n\n分布式 Hessian 分析的内存需求随 Rank 数量增加而增加，因为每个进程需要保存本地激活和梯度副本。库通过 `no_grad` 上下文和适当的张量管理来优化内存使用。\n\n## 相关模块\n\n### CurvatureOperator 基类\n\n`DDPHessianOperator` 继承自 `CurvatureOperator`，这是库中所有曲率算子的抽象基类。它定义了统一的 `matvec()` 接口，所有算法（Lanczos、trace 估计等）都通过这一接口与算子交互。\n\n### 曲率算子家族\n\n| 算子 | 用途 |\n|------|------|\n| `HessianOperator` | 标准 Hessian 矩阵 |\n| `GGNOperator` | Generalized Gauss-Newton 近似 |\n| `DDPHessianOperator` | 分布式 DDP 环境下的 Hessian |\n| `KFACHessianOperator` | Kronecker-Factored Approximate Curvature |\n\n## 总结\n\n`DDPHessianOperator` 为 `hessian-eigenthings` 库提供了关键的分布式训练支持能力。通过继承统一的 `CurvatureOperator` 接口，它保持了与现有分析工具的兼容性，同时封装了 DDP 特有的分布式计算复杂性。这使得在大规模分布式训练环境中进行 Hessian 分析成为可能，为研究神经网络的收敛性、平坦性和泛化能力提供了有力工具。\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[项目简介](#page-project-intro)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [pyproject.toml](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/pyproject.toml)\n- [CONTRIBUTING.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/README.md)\n \n\n# 安装与配置\n\n## 概述\n\n`pytorch-hessian-eigenthings` 是一个用于计算 Hessian 矩阵特征分解的 PyTorch 库，支持 Lanczos 算法、随机幂迭代、Hutch++ trace 估计和随机 Lanczos quadrature 等高效算法。本节详细说明该库的安装方式、环境配置方法以及开发环境设置流程。\n\n## 系统要求\n\n### 依赖环境\n\n| 组件 | 要求 | 说明 |\n|------|------|------|\n| Python | ≥ 3.9 | 项目支持的最低 Python 版本 |\n| PyTorch | 兼容版本 | 核心依赖，提供自动微分和神经网络支持 |\n| uv | 最新版本 | 项目推荐的包管理工具 |\n\n资料来源：[CONTRIBUTING.md:1-5]()\n\n### 可选依赖\n\n| 额外功能 | 包名 | 用途 |\n|----------|------|------|\n| Transformers 支持 | `transformers` | 与 HuggingFace 模型集成 |\n| TransformerLens 支持 | `transformer-lens` | 分析 Transformer 架构 |\n| CurvLinOps 支持 | `curvlinops` | 外部对照库，用于测试验证 |\n| Triton | `triton` | CUDA 加速的 CE HVP 计算 |\n| mkdocs | - | 文档构建工具 |\n\n资料来源：[CONTRIBUTING.md:8]()\n\n## 安装方式\n\n### 方式一：从 PyPI 安装（稳定版）\n\n通过 pip 安装最新稳定版本：\n\n```bash\npip install hessian-eigenthings\n```\n\n> **注意**：当前版本为 v1.0.0a1（alpha 版本）。如需使用 0.x 版本的旧 API，请安装 `hessian-eigenthings==0.0.2`。\n\n资料来源：[README.md:16-18]()\n\n### 方式二：从源码安装（开发版）\n\n适合需要使用最新功能或进行二次开发的用户：\n\n```bash\ngit clone https://github.com/noahgolmant/pytorch-hessian-eigenthings\ncd pytorch-hessian-eigenthings\nuv sync --group dev --group docs --extra transformers --extra transformer-lens --extra curvlinops\n```\n\n#### 安装步骤详解\n\n```mermaid\ngraph TD\n A[克隆仓库] --> B[进入项目目录]\n B --> C[执行 uv sync]\n C --> D{检查额外依赖}\n D -->|需要 Transformers| E[安装 transformers 组]\n D -->|需要 TransformerLens| F[安装 transformer-lens 组]\n D -->|需要 CurvLinOps| G[安装 curvlinops 组]\n E --> H[环境就绪]\n F --> H\n G --> H\n```\n\n1. **克隆仓库**：使用 git 获取最新源码\n2. **进入目录**：切换到项目根目录\n3. **同步依赖**：uv 自动解析 `pyproject.toml` 并安装所有依赖\n\n资料来源：[CONTRIBUTING.md:1-9]()\n\n## 开发环境配置\n\n### 代码质量检查工具\n\n项目使用以下工具确保代码质量：\n\n| 工具 | 用途 | 命令 |\n|------|------|------|\n| ruff | 代码检查与格式化 | `uv run ruff check .` |\n| black | 代码格式化检查 | `uv run black --check .` |\n| mypy | 类型检查 | `uv run mypy` |\n| pytest | 单元测试 | `uv run pytest` |\n| mkdocs | 文档构建 | `uv run mkdocs build --strict` |\n\n### 提交前检查流程\n\n在提交 Pull Request 之前，必须运行以下检查确保代码符合项目规范：\n\n```mermaid\ngraph LR\n A[修改代码] --> B[运行 ruff check]\n B --> C[运行 black]\n C --> D[运行 mypy]\n D --> E[运行 pytest]\n E --> F[构建文档]\n F --> G{所有检查通过}\n G -->|是| H[提交 PR]\n G -->|否| I[修复问题]\n I --> B\n```\n\n具体执行命令：\n\n```bash\n# 代码风格检查\nuv run ruff check .\n\n# 代码格式化验证\nuv run black --check .\n\n# 类型检查\nuv run mypy\n\n# 运行测试套件\nuv run pytest\n\n# 构建文档\nuv run mkdocs build --strict\n```\n\n> **提示**：如果本地调试，lint 任务（ruff 和 black）的成本最低，建议优先运行这些检查。\n\n资料来源：[CONTRIBUTING.md:11-17]()\n\n## CUDA 加速配置（可选）\n\n### Triton 加速\n\n对于需要处理大规模语言模型的场景，建议安装 Triton 以获得更好的性能：\n\n```bash\npip install triton\n```\n\n启用后的性能提升：\n- **速度提升**：约 3.4 倍\n- **峰值内存减少**：约 50%\n\nTriton kernel 在 CUDA 环境下自动检测并使用，无需手动配置。\n\n### torch.compile 备选方案\n\n如果 Triton 不可用，库会自动回退到 `torch.compile` 模式：\n\n- **速度提升**：约 2.6 倍\n- **峰值内存减少**：约 50%\n\n支持 CPU/CUDA/MPS 平台。\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py:10-15]()\n\n## 验证安装\n\n安装完成后，可通过以下方式验证：\n\n```python\nimport torch\nfrom hessian_eigenthings import HessianOperator, lanczos\n\n# 创建简单模型\nmodel = torch.nn.Linear(10, 2)\n\n# 创建测试数据\nx = torch.randn(5, 10)\ny = torch.tensor([0, 1, 0, 1, 0])\n\n# 定义损失函数\nloss_fn = torch.nn.functional.cross_entropy\n\n# 创建 Hessian 算子\nhessian_op = HessianOperator(\n model=model,\n dataloader=[(x, y)],\n loss_fn=loss_fn\n)\n\n# 计算 top-3 特征值\neigenvals = lanczos(hessian_op, k=3, max_iter=20)\nprint(f\"Top eigenvalues: {eigenvals.eigenvalues}\")\n```\n\n如果输出正确的特征值，说明安装成功。\n\n## 常见问题\n\n### 问题一：uv 命令未找到\n\n**解决方案**：先安装 uv\n\n```bash\npip install uv\n```\n\n### 问题二：torch 版本不兼容\n\n**解决方案**：确保 PyTorch 版本 ≥ 1.12.0，建议使用最新稳定版：\n\n```bash\npip install --upgrade torch\n```\n\n### 问题三：CUDA 内存不足\n\n**解决方案**：\n1. 减小 batch size\n2. 使用 `method=\"finite_difference\"` 替代 `\"autograd\"`\n3. 考虑使用 GGNOperator 替代 HessianOperator\n\n资料来源：[hessian_eigenthings/operators/hessian.py:10-20]()\n\n## 快速开始清单\n\n| 步骤 | 任务 | 状态 |\n|------|------|------|\n| 1 | 安装 Python ≥ 3.9 | ☐ |\n| 2 | 安装 uv 包管理器 | ☐ |\n| 3 | 克隆或安装 hessian-eigenthings | ☐ |\n| 4 | （可选）安装额外依赖 | ☐ |\n| 5 | 验证安装（运行示例代码） | ☐ |\n| 6 | （开发者）配置 pre-commit 钩子 | ☐ |\n\n## 相关文档\n\n- [快速开始指南](./quickstart.md)\n- [Hessian 算子 API 参考](../api/operators/hessian.md)\n- [Lanczos 算法文档](../concepts/lanczos-algorithm.md)\n- [贡献指南](../community/contributing.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：noahgolmant/pytorch-hessian-eigenthings\n\n摘要：发现 15 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `pytorch-hessian-eigenthings` 与安装入口 `hessian-eigenthings` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`pip install hessian-eigenthings`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | repo=pytorch-hessian-eigenthings; install=hessian-eigenthings\n\n## 2. 安装坑 · 来源证据：Python Error: the following arguments are required: experimentname\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Python Error: the following arguments are required: experimentname\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_24f46464d79f4ae3830f046c077a2574 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/39 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：v1.0.0a2 — packaging fix\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.0a2 — packaging fix\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7540a696b30c46cdba07c12f33388567 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：v1.0.0a3 — fix lanczos OOM\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.0a3 — fix lanczos OOM\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e5e68e2f24e1436cb8f3c2f11cefe326 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：v1.0.0a4 — backend handles CPU-generator + CUDA-tensor combo\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.0a4 — backend handles CPU-generator + CUDA-tensor combo\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_914b7653aa8b4ef2844a2b4690fab2ad | https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：v1.0.0a5 — comprehensive LLM-scale memory fixes + regression tests\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.0a5 — comprehensive LLM-scale memory fixes + regression tests\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_509356ab9b68434992d7237219952ba6 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 配置坑 · 来源证据：RuntimeError: One of the differentiated Tensors appears to not have been used in the graph.\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：RuntimeError: One of the differentiated Tensors appears to not have been used in the graph.\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f79a3a34cbab435cb3730b7ae17cf492 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/30 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 配置坑 · 来源证据：ValueError: PENet on the Kitti benchmark suite\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：ValueError: PENet on the Kitti benchmark suite\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_850f8cf0010c4d269ab71d864610097a | https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/41 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | README/documentation is current enough for a first validation pass.\n\n## 10. 运行坑 · 来源证据：AttributeError: 'HVPOperator' object has no attribute 'zero_grad'\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：AttributeError: 'HVPOperator' object has no attribute 'zero_grad'\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b515f5c06a5744b19b667bcbc8123348 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/38 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | no_demo; severity=medium\n\n## 14. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | issue_or_pr_quality=unknown\n\n## 15. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | release_recency=unknown\n\n\n",
"markdown_key": "pytorch-hessian-eigenthings",
"pages": "draft",
"source_refs": [
{
"evidence_id": "hn_item:48132232",
"kind": "hn",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://news.ycombinator.com/item?id=48132232"
},
{
"evidence_id": "art_82176a1723a2491b89b1dc14bf5cdebd",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/noahgolmant/pytorch-hessian-eigenthings#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "pytorch-hessian-eigenthings 说明书",
"toc": [
"https://github.com/noahgolmant/pytorch-hessian-eigenthings 项目说明书",
"目录",
"项目简介",
"概述",
"核心定位",
"技术架构",
"核心算子",
"核心算法",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "eb04d493f7da48aa5fb19b58f057bb34ad57789a",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"uv.lock",
"docs/index.md",
"docs/how-to/distributed-ddp.md",
"docs/how-to/custom-curvature-operators.md",
"docs/how-to/analyze-a-huggingface-model.md",
"docs/how-to/per-layer-hessian.md",
"docs/how-to/analyze-with-transformer-lens.md",
"docs/how-to/custom-loss-functions.md",
"docs/reference/loss_fns.md",
"docs/reference/api.md",
"docs/reference/param_utils.md",
"docs/reference/operators.md",
"docs/reference/algorithms.md",
"docs/concepts/ggn-vs-fisher-vs-hessian.md",
"docs/concepts/fused-ce-hvp.md",
"docs/concepts/top-k-eigenvalues.md",
"docs/concepts/why-hvp-not-full-h.md",
"docs/concepts/trace-estimation.md",
"docs/concepts/numerical-stability.md",
"docs/concepts/what-is-the-hessian.md",
"docs/concepts/spectral-density.md",
"docs/getting-started/transformers-quickstart.md",
"docs/getting-started/quickstart.md",
"docs/getting-started/installation.md",
"examples/transformer_lens_attention_only.py",
"examples/README.md",
"examples/huggingface_tiny_gpt2.py",
"examples/supervised_mlp.py"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# pytorch-hessian-eigenthings - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 pytorch-hessian-eigenthings 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **想在安装前理解开源项目价值和边界的用户**：当前证据主要来自项目文档。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install hessian-eigenthings` 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0004` supported 0.86\n- `pip install \"hessian-eigenthings[transformers,transformer-lens]\"` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `git clone https://github.com/noahgolmant/pytorch-hessian-eigenthings` 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做角色匹配试用\n- **为什么**：这个项目更像角色库，核心风险是选错角色或把角色文案当执行能力；先用 Prompt Preview 试角色匹配，再决定是否沙盒导入。\n\n### 30 秒判断\n\n- **现在怎么做**：先做角色匹配试用\n- **最小安全下一步**：先用 Prompt Preview 试角色匹配；满意后再隔离导入\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：想在安装前理解开源项目价值和边界的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0004` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0006` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0007` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：88\n- 重要文件覆盖：40/88\n- 证据索引条目：42\n- 角色 / Skill 条目：26\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 pytorch-hessian-eigenthings 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 pytorch-hessian-eigenthings 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 pytorch-hessian-eigenthings 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 26 个角色 / Skill / 项目文档条目。\n\n- **pytorch-hessian-eigenthings**（project_doc）：! PyPI https://img.shields.io/pypi/v/hessian-eigenthings.svg https://pypi.org/project/hessian-eigenthings/ ! Documentation https://img.shields.io/badge/docs-noahgolmant.github.io-blue https://noahgolmant.github.io/pytorch-hessian-eigenthings/ ! CI https://github.com/noahgolmant/pytorch-hessian-eigenthings/actions/workflows/ci.yml/badge.svg https://github.com/noahgolmant/pytorch-hessian-eigenthings/actions/workflows/… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Examples**（project_doc）：Self-contained scripts demonstrating common usage patterns. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/README.md`\n- **Contributing**（project_doc）：Thanks for your interest in contributing. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **hessian-eigenthings**（project_doc）：Iterative eigendecomposition of curvature operators Hessian, GGN, empirical Fisher for arbitrary PyTorch models, including HuggingFace and TransformerLens transformers. Top eigenvalues via Lanczos or power iteration, trace via Hutch++, and the spectral density via Stochastic Lanczos Quadrature, all matrix-free. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/index.md`\n- **Fused CE Hessian-vector product**（project_doc）：When you analyze a HuggingFace causal LM with GGNOperator and hf lm loss of output , the library uses a fused kernel for the core cross-entropy Hessian-vector product CE HVP instead of relying on autograd to differentiate the loss twice. This page explains why, what the kernel does, and what trade-offs each backend has. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/concepts/fused-ce-hvp.md`\n- **GGN vs Fisher vs Hessian**（project_doc）：These three matrices are easy to conflate and often called \"the curvature\" interchangeably. They are not the same. Read this page before deciding which operator to instantiate; mistaking one for another is the most common pitfall in curvature analysis. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/concepts/ggn-vs-fisher-vs-hessian.md`\n- **Numerical stability**（project_doc）：A short guide to dtype choice, finite-difference $\\varepsilon$ tuning, and reorthogonalization defaults. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/concepts/numerical-stability.md`\n- **Spectral density**（project_doc）：The eigenvalue density or density of states of an $n \\times n$ symmetric operator $H$ is the probability density of its eigenvalues: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/concepts/spectral-density.md`\n- **Top-k eigenvalues**（project_doc）：The two algorithms in this library for computing the top $k$ eigenpairs of a symmetric operator: power iteration with deflation and Lanczos . They share the same EigenResult return type but differ in how they search the spectrum. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/concepts/top-k-eigenvalues.md`\n- **Trace estimation**（project_doc）：The trace of a matrix-free operator can't be read off directly — we don't have the diagonal. Stochastic estimators infer it from a small number of $Hv$ products. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/concepts/trace-estimation.md`\n- **What is the Hessian**（project_doc）：The Hessian of a scalar loss $L \\theta $ with respect to model parameters $\\theta \\in \\mathbb{R}^n$ is the matrix of second partial derivatives: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/concepts/what-is-the-hessian.md`\n- **Why HVP, not full $H$**（project_doc）：Forming the full Hessian costs $O n^2 $ memory. For a 7B-parameter model that's $\\sim$200 PB. Iterative algorithms power iteration, Lanczos, Hutchinson only ever need to apply $H$ to a vector, never to materialize it — so they cost $O n $ memory. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/concepts/why-hvp-not-full-h.md`\n- **Installation**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/getting-started/installation.md`\n- **Quickstart**（project_doc）：A complete top-k Hessian eigenvalue calculation on a small MLP, end to end. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/getting-started/quickstart.md`\n- **Transformers quickstart**（project_doc）：End-to-end on a HuggingFace causal LM. Requires the optional transformers extra. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/getting-started/transformers-quickstart.md`\n- **Analyze a HuggingFace model**（project_doc）：Compute the Hessian spectrum of any HuggingFace causal LM e.g. GPT-2, Llama, Qwen . Requires the optional transformers extra. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/how-to/analyze-a-huggingface-model.md`\n- **Analyze with TransformerLens**（project_doc）：Compute curvature on a TransformerLens https://github.com/TransformerLensOrg/TransformerLens HookedTransformer . Useful for mechanistic-interpretability work where you want to compute Hessian-related quantities while using TLens hooks. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/how-to/analyze-with-transformer-lens.md`\n- **Custom curvature operators**（project_doc）：The algorithms in this library Lanczos, power iteration, Hutchinson, Hutch++, SLQ operate on a CurvatureOperator interface. Subclass it to wire in any matrix-free symmetric operator. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/how-to/custom-curvature-operators.md`\n- **Custom loss functions**（project_doc）：Each operator takes a loss-function callable. The exact signature differs slightly by operator because GGN and empirical Fisher need to know more than just \"the loss\". 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/how-to/custom-loss-functions.md`\n- **Distributed DDP**（project_doc）：DDPHessianOperator averages the Hessian-vector product across torch.distributed ranks. Each rank receives its own shard of the dataset typical pattern: DistributedSampler ; the per-rank HVP is all-reduced before being returned. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/how-to/distributed-ddp.md`\n- **Per-layer Hessian**（project_doc）：Restrict the curvature operator to a subset of parameters using param filter . Operator size shrinks to match, and matvec only differentiates through the selected parameters. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/how-to/per-layer-hessian.md`\n- **Algorithms**（project_doc）：::: hessian eigenthings.algorithms.lanczos.lanczos 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reference/algorithms.md`\n- **API reference**（project_doc）：The library's public surface is re-exported from the top-level hessian eigenthings package, so from hessian eigenthings import HessianOperator, lanczos, ... works for everything below. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reference/api.md`\n- **Loss functions**（project_doc）：::: hessian eigenthings.loss fns.standard.supervised loss 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reference/loss_fns.md`\n- **Operators**（project_doc）：::: hessian eigenthings.operators.base.CurvatureOperator 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reference/operators.md`\n- **Parameter selection**（project_doc）：::: hessian eigenthings.param utils.select parameters 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reference/param_utils.md`\n\n## 证据索引\n\n- 共索引 42 条证据。\n\n- **pytorch-hessian-eigenthings**（documentation）：! PyPI https://img.shields.io/pypi/v/hessian-eigenthings.svg https://pypi.org/project/hessian-eigenthings/ ! Documentation https://img.shields.io/badge/docs-noahgolmant.github.io-blue https://noahgolmant.github.io/pytorch-hessian-eigenthings/ ! CI https://github.com/noahgolmant/pytorch-hessian-eigenthings/actions/workflows/ci.yml/badge.svg https://github.com/noahgolmant/pytorch-hessian-eigenthings/actions/workflows/ci.yml ! License https://img.shields.io/badge/license-MIT-green.svg LICENSE 证据：`README.md`\n- **Examples**（documentation）：Self-contained scripts demonstrating common usage patterns. 证据：`examples/README.md`\n- **Contributing**（documentation）：Thanks for your interest in contributing. 证据：`CONTRIBUTING.md`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **hessian-eigenthings**（documentation）：Iterative eigendecomposition of curvature operators Hessian, GGN, empirical Fisher for arbitrary PyTorch models, including HuggingFace and TransformerLens transformers. Top eigenvalues via Lanczos or power iteration, trace via Hutch++, and the spectral density via Stochastic Lanczos Quadrature, all matrix-free. 证据：`docs/index.md`\n- **Fused CE Hessian-vector product**（documentation）：When you analyze a HuggingFace causal LM with GGNOperator and hf lm loss of output , the library uses a fused kernel for the core cross-entropy Hessian-vector product CE HVP instead of relying on autograd to differentiate the loss twice. This page explains why, what the kernel does, and what trade-offs each backend has. 证据：`docs/concepts/fused-ce-hvp.md`\n- **GGN vs Fisher vs Hessian**（documentation）：These three matrices are easy to conflate and often called \"the curvature\" interchangeably. They are not the same. Read this page before deciding which operator to instantiate; mistaking one for another is the most common pitfall in curvature analysis. 证据：`docs/concepts/ggn-vs-fisher-vs-hessian.md`\n- **Numerical stability**（documentation）：A short guide to dtype choice, finite-difference $\\varepsilon$ tuning, and reorthogonalization defaults. 证据：`docs/concepts/numerical-stability.md`\n- **Spectral density**（documentation）：The eigenvalue density or density of states of an $n \\times n$ symmetric operator $H$ is the probability density of its eigenvalues: 证据：`docs/concepts/spectral-density.md`\n- **Top-k eigenvalues**（documentation）：The two algorithms in this library for computing the top $k$ eigenpairs of a symmetric operator: power iteration with deflation and Lanczos . They share the same EigenResult return type but differ in how they search the spectrum. 证据：`docs/concepts/top-k-eigenvalues.md`\n- **Trace estimation**（documentation）：The trace of a matrix-free operator can't be read off directly — we don't have the diagonal. Stochastic estimators infer it from a small number of $Hv$ products. 证据：`docs/concepts/trace-estimation.md`\n- **What is the Hessian**（documentation）：The Hessian of a scalar loss $L \\theta $ with respect to model parameters $\\theta \\in \\mathbb{R}^n$ is the matrix of second partial derivatives: 证据：`docs/concepts/what-is-the-hessian.md`\n- **Why HVP, not full $H$**（documentation）：Forming the full Hessian costs $O n^2 $ memory. For a 7B-parameter model that's $\\sim$200 PB. Iterative algorithms power iteration, Lanczos, Hutchinson only ever need to apply $H$ to a vector, never to materialize it — so they cost $O n $ memory. 证据：`docs/concepts/why-hvp-not-full-h.md`\n- **Installation**（documentation）：Installation Optional extras: To work on the library itself: 证据：`docs/getting-started/installation.md`\n- **Quickstart**（documentation）：A complete top-k Hessian eigenvalue calculation on a small MLP, end to end. 证据：`docs/getting-started/quickstart.md`\n- **Transformers quickstart**（documentation）：End-to-end on a HuggingFace causal LM. Requires the optional transformers extra. 证据：`docs/getting-started/transformers-quickstart.md`\n- **Analyze a HuggingFace model**（documentation）：Compute the Hessian spectrum of any HuggingFace causal LM e.g. GPT-2, Llama, Qwen . Requires the optional transformers extra. 证据：`docs/how-to/analyze-a-huggingface-model.md`\n- **Analyze with TransformerLens**（documentation）：Compute curvature on a TransformerLens https://github.com/TransformerLensOrg/TransformerLens HookedTransformer . Useful for mechanistic-interpretability work where you want to compute Hessian-related quantities while using TLens hooks. 证据：`docs/how-to/analyze-with-transformer-lens.md`\n- **Custom curvature operators**（documentation）：The algorithms in this library Lanczos, power iteration, Hutchinson, Hutch++, SLQ operate on a CurvatureOperator interface. Subclass it to wire in any matrix-free symmetric operator. 证据：`docs/how-to/custom-curvature-operators.md`\n- **Custom loss functions**（documentation）：Each operator takes a loss-function callable. The exact signature differs slightly by operator because GGN and empirical Fisher need to know more than just \"the loss\". 证据：`docs/how-to/custom-loss-functions.md`\n- **Distributed DDP**（documentation）：DDPHessianOperator averages the Hessian-vector product across torch.distributed ranks. Each rank receives its own shard of the dataset typical pattern: DistributedSampler ; the per-rank HVP is all-reduced before being returned. 证据：`docs/how-to/distributed-ddp.md`\n- **Per-layer Hessian**（documentation）：Restrict the curvature operator to a subset of parameters using param filter . Operator size shrinks to match, and matvec only differentiates through the selected parameters. 证据：`docs/how-to/per-layer-hessian.md`\n- **Algorithms**（documentation）：::: hessian eigenthings.algorithms.lanczos.lanczos 证据：`docs/reference/algorithms.md`\n- **API reference**（documentation）：The library's public surface is re-exported from the top-level hessian eigenthings package, so from hessian eigenthings import HessianOperator, lanczos, ... works for everything below. 证据：`docs/reference/api.md`\n- **Loss functions**（documentation）：::: hessian eigenthings.loss fns.standard.supervised loss 证据：`docs/reference/loss_fns.md`\n- **Operators**（documentation）：::: hessian eigenthings.operators.base.CurvatureOperator 证据：`docs/reference/operators.md`\n- **Parameter selection**（documentation）：::: hessian eigenthings.param utils.select parameters 证据：`docs/reference/param_utils.md`\n- **Settings**（structured_config）：{ \"hooks\": { \"PostToolUse\": { \"matcher\": \"Edit Write MultiEdit\", \"hooks\": { \"type\": \"command\", \"command\": \".claude/hooks/check-docs-affected.sh\" } } } } 证据：`.claude/settings.json`\n- **Byte-compiled / optimized / DLL files**（source_file）：Byte-compiled / optimized / DLL files pycache / .py cod $py.class 证据：`.gitignore`\n- **Eager attention: HF defaults to flash/SDPA which lacks a CPU**（source_file）：\"\"\"Top-k Hessian eigenvalues of a HuggingFace causal LM sshleifer/tiny-gpt2 . 证据：`examples/huggingface_tiny_gpt2.py`\n- **Supervised Mlp**（source_file）：\"\"\"Top-k eigenvalues, trace, and spectral density of a small MLP's Hessian. 证据：`examples/supervised_mlp.py`\n- **Transformer Lens Attention Only**（source_file）：\"\"\"Per-block Hessian analysis of a TransformerLens model: attention-only vs MLP-only. 证据：`examples/transformer_lens_attention_only.py`\n- **Init**（source_file）：\"\"\"Iterative eigendecomposition of curvature operators Hessian, GGN, Fisher for PyTorch models.\"\"\" 证据：`hessian_eigenthings/__init__.py`\n- **Batching**（source_file）：\"\"\"Dataloader iteration helpers and the microbatching safety guard. 证据：`hessian_eigenthings/batching.py`\n- **Param Utils**（source_file）：\"\"\"Parameter selection glob/regex and flat-vector ↔ per-param dict conversion.\"\"\" 证据：`hessian_eigenthings/param_utils.py`\n- **Mkdocs**（source_file）：site name: hessian-eigenthings site description: Iterative eigendecomposition of curvature operators for PyTorch models. site url: https://noahgolmant.github.io/pytorch-hessian-eigenthings/ repo url: https://github.com/noahgolmant/pytorch-hessian-eigenthings repo name: noahgolmant/pytorch-hessian-eigenthings edit uri: edit/master/docs/ 证据：`mkdocs.yml`\n- **ML conventions: N803/N806 uppercase vars like B, T, H, N , N812**（source_file）：build-system requires = \"hatchling\" build-backend = \"hatchling.build\" 证据：`pyproject.toml`\n- **Free between cells to keep peak-memory stats clean on CUDA.**（source_file）：\"\"\"Microbenchmark: eager vs fused CE HVP peak memory and wall time. 证据：`scripts/bench_fused_ce_hvp.py`\n- **!/usr/bin/env bash**（source_file）：!/usr/bin/env bash Spin up a single A100-80GB GCP VM, rsync the current branch, run the GPU-marked GGN matvec validation tests, capture results, teardown. Usage: ./scripts/gpu validate.sh Requires: gcloud configured, project set via PROJECT env var. 证据：`scripts/gpu_validate.sh`\n- **!/usr/bin/env bash**（source_file）：!/usr/bin/env bash Spin up an A100-80GB GCP VM, rsync the feat/fused-ce-hvp branch, run the fused CE HVP tests including the Triton path that skips without CUDA , run the microbenchmark for memory + wall-time numbers, capture results, teardown. 证据：`scripts/gpu_validate_fused.sh`\n- **---------------------------------------------------------------------------**（source_file）：\"\"\"Minimal CPU repro for the GGNOperator memory blowup. 证据：`scripts/repro_ggn_oom.py`\n- **Conftest**（source_file）：def pytest collection modifyitems config: pytest.Config, items: list pytest.Item - None: try: import curvlinops noqa: F401 except ImportError: skip = pytest.mark.skip reason=\"curvlinops not installed\" for item in items: if \"curvlinops\" in item.keywords: item.add marker skip 证据：`tests/conftest.py`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `examples/README.md`, `CONTRIBUTING.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `examples/README.md`, `CONTRIBUTING.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目简介**：importance `high`\n - source_paths: README.md, mkdocs.yml, pyproject.toml\n- **Hessian 矩阵基础概念**：importance `high`\n - source_paths: docs/concepts/what-is-the-hessian.md, docs/concepts/why-hvp-not-full-h.md\n- **核心架构设计**：importance `high`\n - source_paths: hessian_eigenthings/__init__.py, hessian_eigenthings/operators/base.py, hessian_eigenthings/batching.py, hessian_eigenthings/linalg/backend.py\n- **曲率算子详解**：importance `high`\n - source_paths: hessian_eigenthings/operators/__init__.py, hessian_eigenthings/operators/hessian.py, hessian_eigenthings/operators/ggn.py, hessian_eigenthings/operators/fisher.py, hessian_eigenthings/operators/distributed/ddp.py\n- **特征分解算法**：importance `high`\n - source_paths: hessian_eigenthings/algorithms/__init__.py, hessian_eigenthings/algorithms/lanczos.py, hessian_eigenthings/algorithms/trace.py, hessian_eigenthings/algorithms/spectral_density.py, hessian_eigenthings/algorithms/power_iteration.py\n- **参数工具模块**：importance `medium`\n - source_paths: hessian_eigenthings/param_utils.py, docs/reference/param_utils.md, docs/how-to/per-layer-hessian.md\n- **损失函数模块**：importance `medium`\n - source_paths: hessian_eigenthings/loss_fns/__init__.py, hessian_eigenthings/loss_fns/standard.py, hessian_eigenthings/loss_fns/_fused_ce_hvp.py, docs/reference/loss_fns.md, docs/concepts/fused-ce-hvp.md\n- **HuggingFace 模型集成**：importance `high`\n - source_paths: hessian_eigenthings/loss_fns/huggingface.py, examples/huggingface_tiny_gpt2.py, docs/how-to/analyze-a-huggingface-model.md, docs/getting-started/transformers-quickstart.md\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `eb04d493f7da48aa5fb19b58f057bb34ad57789a`\n- inspected_files: `pyproject.toml`, `README.md`, `uv.lock`, `docs/index.md`, `docs/how-to/distributed-ddp.md`, `docs/how-to/custom-curvature-operators.md`, `docs/how-to/analyze-a-huggingface-model.md`, `docs/how-to/per-layer-hessian.md`, `docs/how-to/analyze-with-transformer-lens.md`, `docs/how-to/custom-loss-functions.md`, `docs/reference/loss_fns.md`, `docs/reference/api.md`, `docs/reference/param_utils.md`, `docs/reference/operators.md`, `docs/reference/algorithms.md`, `docs/concepts/ggn-vs-fisher-vs-hessian.md`, `docs/concepts/fused-ce-hvp.md`, `docs/concepts/top-k-eigenvalues.md`, `docs/concepts/why-hvp-not-full-h.md`, `docs/concepts/trace-estimation.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 仓库名和安装名不一致\n\n- Trigger: 仓库名 `pytorch-hessian-eigenthings` 与安装入口 `hessian-eigenthings` 不完全一致。\n- Host AI rule: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Why it matters: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Evidence: identity.distribution | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | repo=pytorch-hessian-eigenthings; install=hessian-eigenthings\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Python Error: the following arguments are required: experimentname\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Python Error: the following arguments are required: experimentname\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_24f46464d79f4ae3830f046c077a2574 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/39 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：v1.0.0a2 — packaging fix\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.0a2 — packaging fix\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_7540a696b30c46cdba07c12f33388567 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a2 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：v1.0.0a3 — fix lanczos OOM\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.0a3 — fix lanczos OOM\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_e5e68e2f24e1436cb8f3c2f11cefe326 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a3 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：v1.0.0a4 — backend handles CPU-generator + CUDA-tensor combo\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.0a4 — backend handles CPU-generator + CUDA-tensor combo\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_914b7653aa8b4ef2844a2b4690fab2ad | https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a4 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：v1.0.0a5 — comprehensive LLM-scale memory fixes + regression tests\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.0a5 — comprehensive LLM-scale memory fixes + regression tests\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_509356ab9b68434992d7237219952ba6 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：RuntimeError: One of the differentiated Tensors appears to not have been used in the graph.\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：RuntimeError: One of the differentiated Tensors appears to not have been used in the graph.\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_f79a3a34cbab435cb3730b7ae17cf492 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/30 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：ValueError: PENet on the Kitti benchmark suite\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：ValueError: PENet on the Kitti benchmark suite\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_850f8cf0010c4d269ab71d864610097a | https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/41 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：AttributeError: 'HVPOperator' object has no attribute 'zero_grad'\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：AttributeError: 'HVPOperator' object has no attribute 'zero_grad'\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_b515f5c06a5744b19b667bcbc8123348 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/38 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：noahgolmant/pytorch-hessian-eigenthings\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 仓库名和安装名不一致（medium）：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 来源证据：Python Error: the following arguments are required: experimentname（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v1.0.0a2 — packaging fix（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v1.0.0a3 — fix lanczos OOM（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v1.0.0a4 — backend handles CPU-generator + CUDA-tensor combo（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/noahgolmant/pytorch-hessian-eigenthings 项目说明书\n\n生成时间：2026-05-16 15:01:33 UTC\n\n## 目录\n\n- [项目简介](#page-project-intro)\n- [Hessian 矩阵基础概念](#page-hessian-basics)\n- [核心架构设计](#page-core-architecture)\n- [曲率算子详解](#page-operators)\n- [特征分解算法](#page-algorithms)\n- [参数工具模块](#page-param-utils)\n- [损失函数模块](#page-loss-functions)\n- [HuggingFace 模型集成](#page-huggingface-integration)\n- [分布式训练支持 (DDP)](#page-distributed-ddp)\n- [安装与配置](#page-installation)\n\n\n\n## 项目简介\n\n### 相关页面\n\n相关主题：[Hessian 矩阵基础概念](#page-hessian-basics), [安装与配置](#page-installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/CONTRIBUTING.md)\n- [mkdocs.yml](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/mkdocs.yml)\n- [hessian_eigenthings/algorithms/lanczos.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/lanczos.py)\n- [hessian_eigenthings/operators/hessian.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/hessian.py)\n- [hessian_eigenthings/operators/ggn.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/ggn.py)\n- [hessian_eigenthings/algorithms/trace.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/trace.py)\n- [examples/huggingface_tiny_gpt2.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/examples/huggingface_tiny_gpt2.py)\n \n\n# 项目简介\n\n## 概述\n\npytorch-hessian-eigenthings 是一个专为 PyTorch 模型设计的**Hessian 特征分解高效计算库**。该项目由 UC Berkeley 的 RISELab 开发，旨在为大语言模型（LLM）和深度神经网络的曲率分析提供生产级工具。\n\n资料来源：[README.md:1]()\n\n## 核心定位\n\n该库的核心价值在于解决以下关键问题：\n\n- **Hessian 特征值计算**：在传统方法中，直接计算 Hessian 矩阵的特征分解需要 O(n²) 的存储和 O(n³) 的计算复杂度，对于拥有数十亿参数的现代深度学习模型而言完全不可行\n- **曲率算子抽象**：通过定义统一的 `CurvatureOperator` 接口，允许用户在不显式构造 Hessian 矩阵的情况下进行曲率分析\n- **多种曲率算子支持**：支持 Hessian、广义 Gauss-Newton（GGN）等多种曲率矩阵的特征分解和迹估计\n\n资料来源：[hessian_eigenthings/operators/hessian.py:1-20]()\n\n## 技术架构\n\n### 模块层次结构\n\n```\nhessian_eigenthings/\n├── algorithms/ # 特征分解和迹估计算法\n│ ├── lanczos.py # Lanczos 算法（特征值计算）\n│ └── trace.py # Hutchinson / Hutch++ 算法（迹估计）\n├── operators/ # 曲率算子实现\n│ ├── hessian.py # Hessian 算子\n│ └── ggn.py # 广义 Gauss-Newton 算子\n├── loss_fns/ # 损失函数模块\n│ ├── standard.py # 标准损失函数\n│ ├── huggingface.py # HuggingFace 模型支持\n│ └── _fused_ce_hvp.py # 融合的交叉熵 HVP\n└── backends/ # 线性代数后端\n```\n\n资料来源：[mkdocs.yml:1-20]()\n\n### 设计模式\n\n该项目采用**算子-算法分离**的设计模式：\n\n| 组件 | 职责 | 关键类/函数 |\n|------|------|-------------|\n| **CurvatureOperator** | 定义曲率矩阵接口，实现 matvec 操作 | `HessianOperator`, `GGNOperator` |\n| **LinAlgBackend** | 封装底层向量运算，确保数值稳定性 | `SingleDeviceBackend` |\n| **Algorithm** | 纯算法实现，仅依赖算子接口 | `lanczos()`, `hutchinson()`, `hutch_plus_plus()` |\n\n资料来源：[CONTRIBUTING.md:20-30]()\n\n### 工作流程图\n\n```mermaid\ngraph TD\n A[用户模型 + 数据] --> B[CurvatureOperator]\n B --> C[matvec 操作]\n C --> D{Lanczos 算法 / Hutch++ 算法}\n D --> E[特征值 & 特征向量]\n D --> F[矩阵迹估计]\n \n B --> G[HessianOperator]\n B --> H[GGNOperator]\n \n G --> I[autograd 双反向传播]\n G --> J[有限差分法]\n \n H --> K[分析路径]\n H --> L[autograd 路径]\n```\n\n## 核心算子\n\n### HessianOperator\n\n`HessianOperator` 是最基础的曲率算子，直接计算损失函数关于参数的 Hessian 矩阵与向量的乘积（Hessian-Vector Product, HVP）。\n\n**支持的 HVP 计算方法**：\n\n| 方法 | 描述 | 适用场景 |\n|------|------|----------|\n| `autograd` | 通过 `torch.autograd.grad` 实现精确双反向传播 | 参数规模 ≤ 7B 的单设备分析 |\n| `finite_difference` | 中心差分 `(∇L(θ+εv) − ∇L(θ−εv)) / 2ε` | FSDP/HSDP/TP 等分布式训练场景 |\n\n资料来源：[hessian_eigenthings/operators/hessian.py:10-30]()\n\n### GGNOperator\n\n广义 Gauss-Newton（GGN）算子是一种 **Hessian 的正向近似**，计算量更低且数值更稳定。\n\n**两种 matvec 实现路径**：\n\n| 路径 | 原理 | 内存开销 | 支持场景 |\n|------|------|----------|----------|\n| `analytical`（默认）| 有限差分 JVP + 分析损失 HVP + 单次反向传播 | 匹配单次训练步 | LLM 规模应用 |\n| `autograd` | `torch.func.jvp` + 自动双反向 + `torch.func.vjp` | 随输出规模增长 | 任意损失函数 |\n\n资料来源：[hessian_eigenthings/operators/ggn.py:40-60]()\n\n### 融合 CE HVP 优化\n\n针对大词表语言模型的交叉熵损失，库中实现了高度优化的 HVP 核：\n\n| 后端 | 特点 | 性能提升 |\n|------|------|----------|\n| `triton`（CUDA） | 零中间张量，仅输出缓冲区 | ~3.4x 加速，2x 内存降低 |\n| `torch.compile` | Inductor 核融合 | ~2.6x 加速，2x 内存降低 |\n| `eager` | 朴素 PyTorch 实现 | 基准参考 |\n\n资料来源：[hessian_eigenthings/loss_fns/_fused_ce_hvp.py:1-50]()\n\n## 核心算法\n\n### Lanczos 算法\n\nLanczos 算法是计算 **k 个极端特征值**的标准选方法，特别适合稀疏或结构化矩阵。通过 `lanczos_tridiagonal` 生成三对角矩阵，然后通过特征分解恢复目标特征值。\n\n**支持的特征值选择模式**：\n\n| 模式 | 含义 | 典型用途 |\n|------|------|----------|\n| `LM` | Largest Magnitude | 寻找最大曲率方向 |\n| `LA` | Largest Algebraic | 最大特征值 |\n| `SA` | Smallest Algebraic | 最小特征值（接近零区域） |\n\n资料来源：[hessian_eigenthings/algorithms/lanczos.py:20-40]()\n\n### 迹估计算法\n\nHutchinson 和 Hutch++ 算法通过随机投影估计矩阵迹，适用于计算 **Hessian 矩阵的谱范数/条件数**。\n\n```mermaid\ngraph LR\n A[随机向量 v] --> B[计算 Av]\n B --> C[v^T A v]\n C --> D{重复 m 次}\n D --> E[迹 ≈ (1/m) Σ v_i^T A v_i]\n```\n\n资料来源：[hessian_eigenthings/algorithms/trace.py:10-50]()\n\n## 使用示例\n\n### 基本用法（HuggingFace 模型）\n\n```python\nfrom hessian_eigenthings import HessianOperator, lanczos\nfrom hessian_eigenthings.loss_fns import hf_lm_loss\n\nfull_op = HessianOperator(model=model, dataloader=dataloader, loss_fn=hf_lm_loss())\neig_full = lanczos(full_op, k=3, max_iter=20, tol=1e-3, seed=0)\n```\n\n资料来源：[examples/huggingface_tiny_gpt2.py:40-50]()\n\n### 仅分析注意力层\n\n```python\nattn_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=hf_lm_loss(),\n param_filter=match_names(\"transformer.h.*.attn.*\"),\n)\neig_attn = lanczos(attn_op, k=3, max_iter=20, tol=1e-3, seed=0)\n```\n\n资料来源：[examples/huggingface_tiny_gpt2.py:55-65]()\n\n## 依赖与环境\n\n### 项目依赖\n\n| 依赖类型 | 核心依赖 | 可选依赖 |\n|----------|----------|----------|\n| 必须 | `torch`, `curvlinops` | `transformers`, `transformer-lens` |\n| 开发 | `pytest`, `ruff`, `black`, `mypy` | `triton` (CUDA) |\n\n资料来源：[CONTRIBUTING.md:8-15]()\n\n### 开发环境配置\n\n```bash\ngit clone https://github.com/noahgolmant/pytorch-hessian-eigenthings\ncd pytorch-hessian-eigenthings\nuv sync --group dev --group docs --extra transformers --extra transformer-lens --extra curvlinops\n```\n\n## 致谢与引用\n\n该项目由 Noah Golmant、Zhewei Yao、Amir Gholami、Michael Mahoney 和 Joseph Gonzalez 在 UC Berkeley 的 RISELab 开发完成。\n\n**去膨胀功率迭代**基于 [HessianFlow](https://github.com/amirgholami/HessianFlow)（Z. Yao et al., NeurIPS 2018）实现。**加速随机功率迭代**来自 C. De Sa et al. 的研究成果。\n\n引用格式：\n\n```bibtex\n@misc{hessian-eigenthings,\n author = {Noah Golmant and Zhewei Yao and Amir Gholami and Michael Mahoney and Joseph Gonzalez},\n title = {pytorch-hessian-eigenthings: efficient PyTorch Hessian eigendecomposition},\n month = oct,\n year = 2018,\n version = {1.0},\n url = {https://github.com/noahgolmant/pytorch-hessian-eigenthings}\n}\n```\n\n资料来源：[README.md:10-25]()\n\n## 质量保证\n\n项目在 CI 中运行以下检查确保代码质量：\n\n| 检查项 | 命令 | 说明 |\n|--------|------|------|\n| 代码格式 | `ruff check .` | Python linting |\n| 代码风格 | `black --check .` | PEP 8 格式化 |\n| 类型检查 | `mypy` | 静态类型验证 |\n| 单元测试 | `pytest` | 回归测试 |\n| 文档构建 | `mkdocs build --strict` | 文档验证 |\n\n资料来源：[CONTRIBUTING.md:15-25]()\n\n## 适用场景总结\n\n| 场景 | 推荐算子 | 推荐算法 |\n|------|----------|----------|\n| 小型模型特征分析 | `HessianOperator` | `lanczos()` |\n| LLM 曲率分析 | `GGNOperator` (analytical) | `lanczos()` |\n| 谱范数估计 | 任意算子 | `hutch_plus_plus()` |\n| 分布式训练环境 | `HessianOperator` (finite_difference) | `lanczos()` |\n| HuggingFace 模型 | `GGNOperator` + `hf_lm_loss()` | `lanczos()` + `trace()` |\n\n---\n\n\n\n## Hessian 矩阵基础概念\n\n### 相关页面\n\n相关主题：[项目简介](#page-project-intro), [曲率算子详解](#page-operators), [特征分解算法](#page-algorithms)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [hessian_eigenthings/operators/hessian.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/hessian.py)\n- [hessian_eigenthings/operators/ggn.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/ggn.py)\n- [hessian_eigenthings/algorithms/lanczos.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/lanczos.py)\n- [hessian_eigenthings/algorithms/trace.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/trace.py)\n- [hessian_eigenthings/loss_fns/huggingface.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/loss_fns/huggingface.py)\n- [hessian_eigenthings/loss_fns/_fused_ce_hvp.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/loss_fns/_fused_ce_hvp.py)\n- [README.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/README.md)\n \n\n# Hessian 矩阵基础概念\n\n## 概述\n\nHessian 矩阵（海森矩阵）是损失函数的二阶偏导数矩阵，定义为：\n\n$$H_{ij} = \\frac{\\partial^2 \\mathcal{L}}{\\partial \\theta_i \\partial \\theta_j}$$\n\n在深度学习中，Hessian 矩阵的**特征值和特征向量**与以下关键问题密切相关：\n\n- **泛化特性**：特征值分布可以揭示模型的收敛状态和泛化能力\n- **平坦最小值**：小特征值对应平坦方向，与良好泛化相关\n- **曲率信息**：帮助理解损失函数的局部几何结构\n\n资料来源：[README.md:1-20]()\n\n## Hessian 矩阵的核心性质\n\n### 正定与负定\n\n| 性质 | 条件 | 物理意义 |\n|------|------|----------|\n| 正定 (PSD) | 所有特征值 ≥ 0 | 局部最小值点 |\n| 负定 | 所有特征值 ≤ 0 | 局部最大值点 |\n| 不定 | 特征值有正有负 | 鞍点 |\n\n资料来源：[hessian_eigenthings/operators/ggn.py:1-30]()\n\n### Hessian 与广义高斯-牛顿 (GGN) 的关系\n\n对于机器学习中的损失函数，广义高斯-牛顿矩阵 G 是 Hessian 的良好近似：\n\n$$G = J^T H_{loss} J$$\n\n其中 $J$ 是模型输出的雅可比矩阵。GGN 矩阵具有以下特性：\n\n- **计算效率更高**：避免了 Hessian 的直接计算\n- **始终正定**：Hessian 的近似版本，可用于曲率分析\n- **Fisher 信息矩阵等价性**：对于交叉熵损失 + softmax，GGN 等于 Fisher 信息矩阵\n\n资料来源：[hessian_eigenthings/operators/ggn.py:1-35]()\n\n## 为什么使用 HVP 而非完整 Hessian\n\n### 计算复杂度对比\n\n| 方法 | 空间复杂度 | 时间复杂度 | 适用场景 |\n|------|------------|------------|----------|\n| 完整 Hessian | O(n²) | O(n²) | 小模型 (< 1M 参数) |\n| Hessian 向量积 (HVP) | O(n) | O(k×n) | 大规模模型 |\n\n其中 n 是参数数量，k 是向量积调用次数。\n\n资料来源：[CONTRIBUTING.md:1-30]()\n\n### 两种 HVP 计算方法\n\n```python\nclass HessianOperator:\n \"\"\"支持两种 HVP 计算方法\"\"\"\n \n def __init__(self, ..., method: HvpMethod = \"autograd\"):\n```\n\n| 方法 | 描述 | 精度 | 内存占用 | 适用场景 |\n|------|------|------|----------|----------|\n| `autograd` | 通过 `torch.autograd.grad` 的精确双重反向传播 | 数值精确（舍入精度） | 较高 | 单设备分析至 ~7B 参数 |\n| `finite_difference` | 中心差分 `(∇L(θ+εv) − ∇L(θ−εv)) / 2ε` | O(ε²) 截断误差 | 低 | FSDP/HSDP/TP 分布式训练 |\n\n资料来源：[hessian_eigenthings/operators/hessian.py:1-40]()\n\n## 架构设计\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n A[用户代码] --> B[CurvatureOperator 基类]\n B --> C[HessianOperator]\n B --> D[GGNOperator]\n B --> E[EmpiricalFisherOperator]\n \n F[LinAlgBackend] --> C\n F --> D\n F --> E\n \n G[Lanczos 算法] --> H[特征值分解]\n G --> I[Ritz 向量]\n \n J[Trace 估计] --> K[Hutchinson]\n J --> L[Hutch++]\n \n C --> G\n D --> G\n E --> G\n```\n\n资料来源：[CONTRIBUTING.md:1-25]()\n\n### 算子-算法分离设计\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ 算法层 │\n│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │\n│ │ Lanczos │ │ Trace 估计 │ │ 谱密度估计 │ │\n│ └──────┬──────┘ └──────┬──────┘ └────────┬────────┘ │\n└─────────┼────────────────┼──────────────────┼──────────┘\n │ │ │\n ▼ ▼ ▼\n┌─────────────────────────────────────────────────────────┐\n│ CurvatureOperator │\n│ (抽象基类 - 所有曲率算子的接口) │\n└─────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ 后端层 │\n│ ┌─────────────────────────────────────────────────────┐│\n│ │ LinAlgBackend ││\n│ │ (统一的向量运算接口) ││\n│ └─────────────────────────────────────────────────────┘│\n└─────────────────────────────────────────────────────────┘\n```\n\n资料来源：[hessian_eigenthings/algorithms/lanczos.py:1-30]()\n\n## Hessian 特征值分解的计算流程\n\n```mermaid\ngraph LR\n A[初始化向量 v₀] --> B[Lanczos 迭代]\n B --> C{收敛判断}\n C -->|未收敛| D[正交化 v]\n D --> B\n C -->|收敛| E[构建三对角矩阵 T]\n E --> F[特征值分解: T = QΛQᵀ]\n F --> G[Ritz 值 ≈ 真实特征值]\n G --> H[Ritz 向量 = VQ]\n```\n\n资料来源：[hessian_eigenthings/algorithms/lanczos.py:1-60]()\n\n## 交叉熵损失 HVP 的融合实现\n\n### 数学推导\n\n对于 softmax 输出的交叉熵损失，Hessian 向量积具有闭式解：\n\n$$H_{loss} @ u = \\left( p \\cdot u - p \\cdot \\langle p, u \\rangle \\right) \\cdot \\frac{mask}{n_{valid}}$$\n\n其中 $p = softmax(logits)$ 是预测概率分布。\n\n资料来源：[hessian_eigenthings/loss_fns/_fused_ce_hvp.py:1-35]()\n\n### 融合策略对比\n\n| 实现方式 | 中间张量数量 | 内存占用 (N=16384, V=50304, fp32) | 加速比 |\n|----------|--------------|-----------------------------------|--------|\n| Eager | ~6 个 (N,V) 张量 | ~19.6 GB | 1x |\n| torch.compile | ~1 个 (N,V) 张量 | ~3.3 GB | ~2.6x |\n| Triton | 0 个中间张量 | ~1.6 GB | ~3.4x |\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py:1-50]()\n\n## 主要 API 接口\n\n### HessianOperator\n\n```python\nclass HessianOperator:\n def __init__(\n self,\n model: nn.Module,\n dataloader: Iterable[Any],\n loss_fn: LossFn,\n *,\n param_filter: ParamFilter | None = None,\n full_dataset: bool = True,\n num_batches: int | None = None,\n method: HvpMethod = \"autograd\",\n fd_eps: float | None = None,\n backend: LinAlgBackend[torch.Tensor] | None = None,\n ) -> None:\n```\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `model` | nn.Module | 必需 | PyTorch 模型 |\n| `dataloader` | Iterable | 必需 | 数据加载器 |\n| `loss_fn` | LossFn | 必需 | 损失函数 |\n| `param_filter` | ParamFilter | None | 参数过滤函数 |\n| `method` | HvpMethod | \"autograd\" | HVP 计算方法 |\n| `full_dataset` | bool | True | 是否使用完整数据集 |\n\n资料来源：[hessian_eigenthings/operators/hessian.py:1-35]()\n\n### GGNOperator\n\n```python\nclass GGNOperator:\n def __init__(\n self,\n model: nn.Module,\n dataloader: Iterable[Any],\n forward_fn: ForwardFn,\n loss_of_output_fn: LossOfOutputFn,\n *,\n loss_hvp: GgnHvpMethod = \"analytical\",\n ):\n```\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `loss_hvp` | GgnHvpMethod | \"analytical\" | GGN HVP 计算方法 |\n\n资料来源：[hessian_eigenthings/operators/ggn.py:1-45]()\n\n## 特征值选择模式\n\nLanczos 算法支持多种特征值选择策略：\n\n| 模式 | 含义 | 用途 |\n|------|------|------|\n| `\"LM\"` | Largest Magnitude | 寻找最大特征值（最尖锐方向） |\n| `\"LA\"` | Largest Algebraic | 寻找最大代数特征值 |\n| `\"SA\"` | Smallest Algebraic | 寻找最小特征值（最平坦方向） |\n\n```python\neig_result = lanczos(operator, k=10, which=\"LM\", max_iter=100)\n```\n\n资料来源：[hessian_eigenthings/algorithms/lanczos.py:1-70]()\n\n## Trace 估计方法\n\n### Hutchinson 方法\n\n通过蒙特卡洛采样估计矩阵的迹：\n\n$$\\text{tr}(A) \\approx \\frac{1}{m} \\sum_{i=1}^{m} v_i^T A v_i$$\n\n其中 $v_i$ 是随机向量（Rademacher 或 Gaussian 分布）。\n\n资料来源：[hessian_eigenthings/algorithms/trace.py:1-40]()\n\n### Hutch++ 方法\n\n改进的采样策略，提供更低的方差估计：\n\n$$\\text{tr}(A) = \\mathbb{E}[v^T A v] - \\mathbb{E}[g^T A g] + \\mathbb{E}[w^T A w]$$\n\n其中 $g$ 和 $w$ 是特殊的偏向采样向量。\n\n| 方法 | 采样数量 | 方差 | 适用场景 |\n|------|----------|------|----------|\n| Hutchinson | O(m) | 较高 | 快速估计 |\n| Hutch++ | O(2m) | 较低 | 精确估计 |\n\n## 使用示例\n\n### 基本特征值计算\n\n```python\nfrom hessian_eigenthings import HessianOperator, lanczos\n\n# 定义模型和数据\nmodel = MyModel()\ndataloader = DataLoader(dataset, batch_size=32)\n\n# 创建 Hessian 算子\nhessian_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=loss_fn,\n)\n\n# 计算 top-k 特征值\neig_result = lanczos(hessian_op, k=10, max_iter=100, seed=42)\n\nprint(f\"Top eigenvalues: {eig_result.eigenvalues}\")\n```\n\n### 注意力机制子空间分析\n\n```python\n# 只计算注意力参数的 Hessian\nattn_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=loss_fn,\n param_filter=match_names(\"blocks.*.attn.*\"),\n)\n\neig_attn = lanczos(attn_op, k=3, max_iter=20)\n```\n\n资料来源：[examples/transformer_lens_attention_only.py:1-45]()\n\n## 与其他工具的集成\n\n| 外部库 | 集成方式 | 用途 |\n|--------|----------|------|\n| FSDP/HSDP | `method=\"finite_difference\"` | 分布式训练中的 Hessian 分析 |\n| DeepSpeed | 通过参数过滤 | 特定参数组的曲率分析 |\n| Transformer-Lens | 自定义 dataloader | Attention-only 分析 |\n| HuggingFace Transformers | `hf_lm_loss()` | 语言模型 Hessian |\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py:1-60]()\n\n## 扩展阅读\n\n- **概念页面**：算法原理、适用场景\n- **操作指南**：具体用户工作流程\n- **参考页面**：自动生成的 API 文档\n\n资料来源：[CONTRIBUTING.md:1-35]()\n\n---\n\n\n\n## 核心架构设计\n\n### 相关页面\n\n相关主题：[曲率算子详解](#page-operators), [特征分解算法](#page-algorithms), [参数工具模块](#page-param-utils)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [hessian_eigenthings/__init__.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/__init__.py)\n- [hessian_eigenthings/operators/base.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/base.py)\n- [hessian_eigenthings/operators/hessian.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/hessian.py)\n- [hessian_eigenthings/operators/ggn.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/ggn.py)\n- [hessian_eigenthings/algorithms/lanczos.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/lanczos.py)\n- [hessian_eigenthings/algorithms/trace.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/trace.py)\n- [hessian_eigenthings/linalg/backend.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/linalg/backend.py)\n- [hessian_eigenthings/batching.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/batching.py)\n \n\n# 核心架构设计\n\n## 概述\n\n`pytorch-hessian-eigenthings` 是一个用于计算 PyTorch 模型 Hessian 矩阵特征分解的高效可扩展库。该项目的核心架构遵循**算子-算法分离**设计模式，通过抽象的曲率算子（Curvature Operator）接口连接不同的曲率矩阵实现与特征分解算法。\n\n架构的核心设计理念：\n\n- **模块化**：曲率矩阵（Hessian、GGN、Fisher）通过统一接口暴露\n- **可扩展性**：新增曲率矩阵只需实现 `CurvatureOperator` 基类\n- **算法无关性**：特征分解算法（Lanczos、Hutchinson、Hutch++）可作用于任意曲率算子\n- **硬件适配**：通过 `LinAlgBackend` 抽象支持多设备（CPU/GPU/MPS）\n\n资料来源：[CONTRIBUTING.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/CONTRIBUTING.md)\n\n## 架构总览\n\n### 系统组件图\n\n```mermaid\ngraph TB\n subgraph \"用户层\"\n U[用户代码]\n end\n \n subgraph \"算法层\"\n LZ[Lanczos 算法]\n HC[Hutchinson 算法]\n HP[Hutch++ 算法]\n SLQ[Stochastic Lanczos Quadrature]\n end\n \n subgraph \"算子层\"\n HO[HessianOperator]\n GGN[GGNOperator]\n EF[EmpiricalFisherOperator]\n end\n \n subgraph \"后端层\"\n BE[LinAlgBackend]\n SD[SingleDeviceBackend]\n MD[MultiDeviceBackend]\n end\n \n U --> LZ\n U --> HC\n U --> HP\n U --> SLQ\n \n LZ --> HO\n HC --> HO\n HP --> HO\n SLQ --> HO\n \n LZ --> GGN\n LZ --> EF\n \n HO --> BE\n GGN --> BE\n EF --> BE\n \n BE --> SD\n BE --> MD\n```\n\n### 核心接口契约\n\n| 组件 | 职责 | 关键方法 |\n|------|------|----------|\n| `CurvatureOperator` | 定义曲率矩阵算子接口 | `matvec(v)` |\n| `LinAlgBackend` | 封装向量运算 | `dot()`, `norm()`, `axpy()` |\n| 算法函数 | 执行特征分解 | `lanczos()`, `hutchinson()`, `hutch_plus_plus()` |\n\n资料来源：[hessian_eigenthings/operators/base.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/base.py)\n\n## CurvatureOperator 基类\n\n### 抽象接口定义\n\n`CurvatureOperator` 是整个库的核心抽象，所有曲率矩阵（Hessian、广义 Gauss-Newton、Fisher 等）都必须继承此类并实现 `matvec(v)` 方法。\n\n```python\nclass CurvatureOperator(ABC):\n @property\n @abstractmethod\n def dtype(self) -> torch.dtype: ...\n \n @property\n @abstractmethod\n def device(self) -> torch.device: ...\n \n @property\n @abstractmethod\n def size(self) -> int: ...\n \n @abstractmethod\n def matvec(self, v: torch.Tensor) -> torch.Tensor: ...\n```\n\n核心方法说明：\n\n| 方法 | 输入 | 输出 | 说明 |\n|------|------|------|------|\n| `matvec(v)` | 维度为 `size` 的向量 | 维度为 `size` 的向量 | 计算曲率矩阵与向量的乘积（矩阵-向量乘积） |\n| `dtype` | - | `torch.dtype` | 算子的数据类型 |\n| `device` | - | `torch.device` | 算子所在设备 |\n| `size` | - | `int` | 参数空间的维度（即模型参数总数） |\n\n### 向量展开与重塑机制\n\n算子内部维护参数列表及其形状信息，用于在扁平向量与原始参数结构之间转换：\n\n```python\nclass CurvatureOperator:\n def _unflatten(self, v: torch.Tensor) -> dict[str, torch.Tensor]:\n offset = 0\n out = {}\n for n, p, sz in zip(self._param_names, self._param_list, self._sizes, strict=True):\n out[n] = v[offset : offset + sz].reshape_as(p)\n offset += sz\n return out\n```\n\n此机制确保算法层始终操作扁平的 1-D 向量，而算子层负责与模型的原始参数结构交互。\n\n资料来源：[hessian_eigenthings/operators/base.py:1-100](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/base.py)\n\n## LinAlgBackend 线性代数后端\n\n### 后端抽象层\n\n`LinAlgBackend` 是一个泛型抽象类，封装了所有向量运算操作。这种设计使得：\n\n1. 单设备场景使用标准 PyTorch 操作\n2. 多设备/分布式场景可注入自定义实现\n3. 测试时可注入模拟后端进行单元测试\n\n```python\nclass LinAlgBackend(ABC, Generic[V]):\n @abstractmethod\n def dot(self, a: V, b: V) -> torch.Tensor: ...\n \n @abstractmethod\n def norm(self, a: V) -> torch.Tensor: ...\n \n @abstractmethod\n def axpy(self, a: torch.Tensor, x: V, y: V) -> V: ...\n \n @abstractmethod\n def zero(self, shape: int) -> V: ...\n```\n\n### 单设备后端实现\n\n`SingleDeviceBackend` 是默认后端实现，直接委托给 PyTorch 张量操作：\n\n| 方法 | 实现 | 说明 |\n|------|------|------|\n| `dot(a, b)` | `torch.dot(a.flatten(), b.flatten())` | 向量点积 |\n| `norm(a)` | `torch.linalg.vector_norm(a)` | L2 范数 |\n| `axpy(a, x, y)` | `a * x + y` | 标量-向量乘加 |\n| `zero(shape)` | `torch.zeros(shape, ...) ` | 创建零向量 |\n\n资料来源：[hessian_eigenthings/linalg/backend.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/linalg/backend.py)\n\n## HessianOperator 实现\n\n### 架构设计\n\n`HessianOperator` 是 Hessian 矩阵的算子实现，支持两种 HVP（Hamiltonian-Vector Product）计算方法：\n\n```mermaid\ngraph LR\n A[输入向量 v] --> B{method 参数}\n B -->|\"autograd\"| C[双反向传播]\n B -->|\"finite_difference\"| D[有限差分]\n \n C --> E[create_graph=True]\n C --> F[梯度 → 二阶导]\n E --> G[H_loss · v]\n \n D --> H[L θ+εv]\n D --> I[L θ-εv]\n H --> J[(∇L₊ - ∇L₋) / 2ε]\n I --> J\n J --> G\n```\n\n### 两种方法的对比\n\n| 特性 | `autograd` | `finite_difference` |\n|------|------------|---------------------|\n| 数值精度 | 精确（浮点舍入内） | O(ε²) 截断误差 |\n| 内存占用 | 较大（需构建反向图） | 较小（仅两次前反向） |\n| FSDP/HSDP/TP 兼容性 | 需特殊处理 | 原生支持 |\n| 适用场景 | 7B 参数以下单机分析 | 大规模分布式训练 |\n\n资料来源：[hessian_eigenthings/operators/hessian.py:1-80](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/hessian.py)\n\n## GGNOperator 实现\n\n### Generalized Gauss-Newton 近似\n\nGGN（广义 Gauss-Newton）矩阵是 Hessian 的正向定矩阵近似，其定义为：\n\n```\nG = J^T · H_loss · J\n```\n\n其中 `J` 是损失函数相对于模型输出的雅可比矩阵，`H_loss` 是损失函数的 Hessian。\n\n### 双路径 HVP 计算\n\nGGNOperator 支持两种 HVP 计算路径：\n\n```python\nif loss_hvp == \"analytical\":\n # 分析路径：有限差分 JVP + 解析 H_loss HVP + 单次反向\n # 内存占用匹配一次正常训练步\nelse:\n # autograd 路径：torch.func.jvp + 双反向 + vjp\n # 数值精确但内存随输出维度扩展\n```\n\n| 路径 | `loss_hvp` 参数 | 内存特性 | 精度 |\n|------|----------------|----------|------|\n| 分析路径 | `\"analytical\"` | 与训练步相同 | 有限差分精度 |\n| 自动微分路径 | `\"autograd\"` | O(vocab_size) | 精确 |\n\n资料来源：[hessian_eigenthings/operators/ggn.py:1-60](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/ggn.py)\n\n## 批处理机制\n\n### Microbatch 支持\n\n对于大数据集场景，算子支持将数据分成多个 microbatch 分别计算后聚合：\n\n```python\nclass HessianOperator:\n def __init__(\n self,\n model: nn.Module,\n dataloader: Iterable[Any],\n loss_fn: LossFn,\n *,\n microbatch_size: int | None = None,\n num_batches: int | None = None,\n ): ...\n```\n\n批处理流程：\n\n```mermaid\ngraph TD\n A[完整数据集] --> B{microbatch_size?}\n B -->|是| C[分割为 N 个 microbatch]\n B -->|否| D[使用完整 dataloader]\n \n C --> E[对每个 microbatch 计算 HVP]\n D --> F[计算 HVP]\n \n E --> G[加权求和]\n F --> G\n```\n\n### 参数过滤\n\n通过 `param_filter` 函数可以选择性地只对模型的部分参数构造算子：\n\n```python\n# 示例：只对注意力层参数构造 Hessian\nattn_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=loss_fn,\n param_filter=match_names(\"transformer.h.*.attn.*\"),\n)\n```\n\n资料来源：[hessian_eigenthings/batching.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/batching.py)\n\n## Lanczos 算法实现\n\n### 算法核心流程\n\nLanczos 算法是计算 Hessian 特征分解的核心算法，该实现具有以下特性：\n\n```mermaid\ngraph LR\n A[初始向量 v₀] --> B[Lanczos 迭代]\n B --> C[生成三对角矩阵 T]\n C --> D[特征分解 T]\n D --> E[Ritz 值 = 特征值近似]\n D --> F[Ritz 向量 = 特征向量近似]\n```\n\n### 特征向量累积优化\n\n代码使用 rank-1 外积更新直接累积 Ritz 向量，避免了临时的大矩阵分配：\n\n```python\n# 直接累积到最终 (k, n) 布局，避免 (n, m) 基底矩阵和转置拷贝\neigenvectors = torch.zeros(sel.shape[0], n, dtype=operator.dtype, device=operator.device)\nfor j, basis_vec in enumerate(td.basis):\n eigenvectors.addr_(s_sel[j], basis_vec)\n```\n\n### 关键参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `k` | int | - | 返回的特征值数量 |\n| `max_iter` | int | - | 最大迭代次数 |\n| `tol` | float | 1e-5 | 收敛阈值 |\n| `which` | str | \"LM\" | 选择策略（LM/LA/SA） |\n| `seed` | int | None | 随机种子 |\n\n`which` 参数说明：\n- `\"LM\"`: Largest Magnitude（绝对值最大）\n- `\"LA\"`: Largest Algebraic（代数最大）\n- `\"SA\"`: Smallest Algebraic（代数最小）\n\n资料来源：[hessian_eigenthings/algorithms/lanczos.py:1-80](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/lanczos.py)\n\n## 追踪估计算法\n\n### Hutchinson 估计器\n\nHutchinson 方法通过随机采样估计矩阵迹：\n\n```\ntr(A) ≈ (1/m) Σ vᵢᵀ A vᵢ\n```\n\n其中 `vᵢ` 是 Rademacher 或 Gaussian 分布的随机向量。\n\n### Hutch++ 改进算法\n\nHutch++ 通过更智能的采样策略降低方差：\n\n| 算法 | 采样数量 | 方差特性 | 适用场景 |\n|------|----------|----------|----------|\n| Hutchinson | m | O(1/√m) | 通用 |\n| Hutch++ | ⌈3m/2⌉ | O(1/m) | 高精度需求 |\n\n资料来源：[hessian_eigenthings/algorithms/trace.py:1-60](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/trace.py)\n\n## 完整调用流程\n\n### 端到端工作流\n\n```mermaid\nsequenceDiagram\n participant User as 用户代码\n participant Op as CurvatureOperator\n participant Algo as 算法函数\n participant Backend as LinAlgBackend\n \n User->>Op: 创建算子实例\n Op->>Backend: 注册后端\n User->>Algo: 调用 lanczos/trac e\n Algo->>Op: 调用 matvec(v)\n Op->>Backend: 执行向量运算\n Backend-->>Op: 返回结果\n Op-->>Algo: 返回 HVP\n Algo-->>User: 返回特征值/向量\n```\n\n### 典型使用示例\n\n```python\n# 1. 创建 Hessian 算子\nhessian_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=loss_fn,\n)\n\n# 2. 调用 Lanczos 算法\nresult = lanczos(hessian_op, k=10, max_iter=50)\n\n# 3. 获取特征值和特征向量\neigenvalues = result.eigenvalues\neigenvectors = result.eigenvectors\n```\n\n资料来源：[examples/huggingface_tiny_gpt2.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/examples/huggingface_tiny_gpt2.py)\n\n## 扩展机制\n\n### 新增曲率算子\n\n要添加新的曲率矩阵（如 Fisher 信息矩阵），只需继承 `CurvatureOperator` 并实现 `matvec` 方法：\n\n```python\nclass MyCurvatureOperator(CurvatureOperator):\n def __init__(self, model, dataloader, ...):\n super().__init__()\n # 初始化参数列表等\n \n @property\n def dtype(self) -> torch.dtype:\n return self._param_list[0].dtype\n \n def matvec(self, v: torch.Tensor) -> torch.Tensor:\n # 实现矩阵-向量乘积\n return ...\n```\n\n### 新增算法\n\n算法通过 `CurvatureOperator` 接口与所有算子兼容，无需修改：\n\n```python\ndef my_algorithm(operator: CurvatureOperator, **kwargs) -> MyResult:\n # operator.matvec(v) 可用于任意曲率算子\n ...\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/CONTRIBUTING.md)\n\n## 总结\n\n`pytorch-hessian-eigenthings` 的核心架构以**算子-算法分离**为核心设计原则，通过抽象的 `CurvatureOperator` 接口连接曲率矩阵实现与特征分解算法。这种设计使得：\n\n1. **代码复用**：不同算法可作用于同一算子\n2. **易于扩展**：新增曲率矩阵或算法无需修改现有代码\n3. **硬件适配**：通过后端抽象支持多设备场景\n4. **内存优化**：不同实现路径（autograd vs analytical）可权衡精度与内存\n\n整个库的架构简洁而高效，核心文件仅包含算子基类、算法实现和后端抽象三个主要层次，配合专门的损失函数模块完成特定任务的优化。\n\n---\n\n\n\n## 曲率算子详解\n\n### 相关页面\n\n相关主题：[核心架构设计](#page-core-architecture), [特征分解算法](#page-algorithms), [分布式训练支持 (DDP)](#page-distributed-ddp)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [hessian_eigenthings/operators/__init__.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/__init__.py)\n- [hessian_eigenthings/operators/hessian.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/hessian.py)\n- [hessian_eigenthings/operators/ggn.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/ggn.py)\n- [hessian_eigenthings/operators/fisher.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/fisher.py)\n- [hessian_eigenthings/operators/distributed/ddp.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/distributed/ddp.py)\n- [docs/reference/operators.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/reference/operators.md)\n \n\n# 曲率算子详解\n\n曲率算子（Curvature Operator）是 pytorch-hessian-eigenthings 项目的核心抽象，封装了对任意 PyTorch 模型进行曲率矩阵（如 Hessian、广义 Gauss-Newton 矩阵、Fisher 信息矩阵）矩阵-向量乘积（matvec）的计算逻辑。通过将曲率矩阵的操作抽象为统一的算子接口，该项目得以支持多种高效的算法（如 Lanczos、随机幂迭代、Hutchinson/Hutch++ 迹估计），而无需关心底层曲率矩阵的具体实现细节。\n\n## 1. 架构概述\n\n曲率算子系统采用**算子模式**（Operator Pattern）设计，所有曲率算子均继承自 `CurvatureOperator` 基类，暴露统一的 `matvec(v)` 接口。算法模块仅依赖此接口，从而实现曲率矩阵计算与特征值分解、迹估计等操作的解耦。\n\n```mermaid\ngraph TD\n subgraph \"用户层\"\n A[\"HessianOperator\"] --> B[\"GGNOperator\"]\n A --> C[\"FisherOperator\"]\n C --> D[\"EmpiricalFisherOperator\"]\n end\n \n subgraph \"抽象基类\"\n E[\"CurvatureOperator
size: int
dtype: dtype
device: device
matvec(v) → Av\"]\n end\n \n subgraph \"算法层\"\n F[\"lanczos()\"]\n G[\"power_iteration()\"]\n H[\"trace()\"]\n I[\"spectral_density()\"]\n end\n \n subgraph \"后端层\"\n J[\"LinAlgBackend
SingleDeviceBackend
DistributedBackend\"]\n end\n \n A --> E\n B --> E\n C --> E\n D --> E\n E --> J\n F --> E\n G --> E\n H --> E\n I --> E\n```\n\n## 2. 基类设计：CurvatureOperator\n\n`CurvatureOperator` 是所有曲率算子的抽象基类，定义了算子的通用接口和属性。\n\n### 2.1 核心属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `size` | `int` | 模型中被纳入计算的参数总数 |\n| `dtype` | `torch.dtype` | 算子的数据类型 |\n| `device` | `torch.device` | 算子所在的设备 |\n\n### 2.2 核心方法\n\n```python\nclass CurvatureOperator(ABC):\n @abstractmethod\n def matvec(self, v: torch.Tensor) -> torch.Tensor:\n \"\"\"计算曲率矩阵与向量 v 的乘积 Av，返回形状与 v 相同\"\"\"\n ...\n```\n\n`matvec` 方法接收一个展平后的参数向量 `v`（形状为 `(size,)`），返回曲率矩阵与 `v` 的乘积结果。该方法内部处理参数重排、梯度计算、重塑等逻辑，对外保持一致的接口。\n\n资料来源：[hessian_eigenthings/operators/__init__.py]()\n\n## 3. HessianOperator\n\n`HessianOperator` 用于计算损失函数关于模型参数的 Hessian 矩阵与向量的乘积。\n\n### 3.1 数学背景\n\nHessian 矩阵定义为损失函数对参数的二阶导数矩阵：\n\n$$H = \\nabla_\\theta^2 \\mathcal{L}(\\theta)$$\n\n对于神经网络，直接构建完整的 Hessian 矩阵成本高昂（参数可达数十亿），因此 `HessianOperator` 仅实现矩阵-向量乘积 `Hv`，支持后续的特征值分解等分析操作。\n\n### 3.2 初始化参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `model` | `nn.Module` | 必选 | 待分析的 PyTorch 模型 |\n| `dataloader` | `Iterable[Any]` | 必选 | 数据加载器，用于迭代数据批次 |\n| `loss_fn` | `LossFn` | 必选 | 损失函数，签名 `Callable[[Tensor, Any], Tensor]` |\n| `param_filter` | `ParamFilter \\| None` | `None` | 参数过滤器，仅对匹配参数计算曲率 |\n| `full_dataset` | `bool` | `True` | 是否对整个数据集求平均 |\n| `num_batches` | `int \\| None` | `None` | 使用的批次数，`None` 表示全部 |\n| `microbatch_size` | `int \\| None` | `None` | 微批次大小 |\n| `microbatch_unsafe` | `bool` | `False` | 是否跳过微批次安全检查 |\n| `method` | `HvpMethod` | `\"autograd\"` | HVP 计算方法 |\n| `fd_eps` | `float \\| None` | `None` | 有限差分方法的步长 |\n| `backend` | `LinAlgBackend \\| None` | `None` | 线性代数后端 |\n\n资料来源：[hessian_eigenthings/operators/hessian.py:19-43]()\n\n### 3.3 HVP 计算方法\n\n`HessianOperator` 支持两种 Hessian 向量积（HVP）的计算方式：\n\n#### 3.3.1 autograd 方法（默认）\n\n通过 `torch.autograd.grad` 进行精确的双反向传播计算：\n\n```python\n# 伪代码实现\ngrad_params = grad(loss, params, create_graph=True)\nhvp = grad(grad_params, params, grad_outputs=v)\n```\n\n该方法数值精确，适合单设备分析场景，参数规模上限约为 70 亿。资料来源：[hessian_eigenthings/operators/hessian.py:20-23]()\n\n#### 3.3.2 finite_difference 方法\n\n采用中心差分公式近似 HVP：\n\n$$\\text{Hv} \\approx \\frac{\\nabla\\mathcal{L}(\\theta + \\epsilon v) - \\nabla\\mathcal{L}(\\theta - \\epsilon v)}{2\\epsilon}$$\n\n该方法每个 HVP 需要两次正常的前向和反向传播，**不涉及任何二阶反向传播图**，天然支持 FSDP/HSDP/张量并行等分布式训练框架。代价是存在 $O(\\epsilon^2)$ 的截断误差。资料来源：[hessian_eigenthings/operators/hessian.py:23-25]()\n\n## 4. GGNOperator（广义 Gauss-Newton 矩阵）\n\n`GGNOperator` 计算广义 Gauss-Newton（GGN）矩阵与向量的乘积。GGN 是 Hessian 的 PSD（半正定）近似，常用于大规模神经网络的曲率分析。\n\n### 4.1 数学背景\n\nGGN 矩阵定义为：\n\n$$G = J^T H_{loss} J$$\n\n其中 $J$ 是模型输出对参数的雅可比矩阵，$H_{loss}$ 是损失函数对模型输出的 Hessian。由于 $H_{loss}$ 被替换为近似 PSD 矩阵，$G$ 必然是 PSD 矩阵。\n\n对于交叉熵损失 + Softmax 分类，GGN 矩阵恰好等于 Fisher 信息矩阵。资料来源：[hessian_eigenthings/operators/ggn.py:45-50]()\n\n### 4.2 两函数 API 设计\n\n`GGNOperator` 采用解耦的双函数接口：\n\n| 函数 | 签名 | 说明 |\n|------|------|------|\n| `forward_fn` | `Callable[..., Tensor]` | 返回模型输出 |\n| `loss_of_output_fn` | `Callable[[Tensor, Any], Tensor]` | 将模型输出和批次转换为标量损失 |\n\n这种设计使得 `GGNOperator` 可以独立计算 $Jv$（雅可比-向量积）、$H_{loss} \\cdot (Jv)$ 和 $J^T \\cdot (H_{loss} \\cdot Jv)$，而不依赖于损失函数的内部实现细节。资料来源：[hessian_eigenthings/operators/ggn.py:52-54]()\n\n### 4.3 matvec 实现方式\n\n| 方式 | 默认 | 说明 |\n|------|------|------|\n| `analytical` | ✅ | 有限差分 JVP + 解析 loss-Hessian-向量积 + 一次正常反向传播应用 $J^T$。内存占用与单次训练步相当，是 LLM 规模使用的首选方案 |\n| `autograd` | - | `torch.func.jvp` + 自动微分双反向传播 + `torch.func.vjp` 路径。数值精确但内存随输出规模快速膨胀，适用于没有解析 `.hvp` 的损失函数 |\n\n资料来源：[hessian_eigenthings/operators/ggn.py:56-66]()\n\n### 4.4 内部结构\n\n```mermaid\ngraph LR\n A[\"参数字典
{name: Tensor}\"] --> B[\"模型前向
forward_fn\"]\n B --> C[\"模型输出
Tensor\"]\n C --> D[\"损失计算
loss_of_output_fn\"]\n D --> E[\"标量损失
loss\"]\n \n F[\"向量 v
(参数空间)\"] --> G[\"JVP
Jv\"]\n G --> H[\"H_loss @ Jv
解析或 autograd\"]\n H --> I[\"VJP
J^T @ (H_loss @ Jv)\"]\n I --> J[\"结果
Av = Gv\"]\n```\n\nGGN matvec 的完整流程包括：\n\n1. 从参数字典中提取参数值和梯度\n2. 计算雅可比-向量积 $u = Jv$\n3. 计算损失 Hessian 对 $u$ 的作用 $w = H_{loss} \\cdot u$\n4. 通过反向传播计算 $J^T \\cdot w$ 资料来源：[hessian_eigenthings/operators/ggn.py:60-62]()\n\n## 5. FisherOperator 与 EmpiricalFisherOperator\n\nFisher 信息矩阵是 GGN 的一个特例，在特定条件下（损失函数为负对数似然）两者数学上等价。项目提供两种 Fisher 算子实现。\n\n### 5.1 FisherOperator\n\n计算真实的 Fisher 信息矩阵，需要模型输出对应于正确的概率分布。对于语言模型，通常需要采样生成过程。\n\n### 5.2 EmpiricalFisherOperator\n\n计算经验 Fisher 信息矩阵，使用梯度的外积近似：\n\n$$\\hat{F} = \\frac{1}{N} \\sum_{i=1}^{N} \\nabla \\log p(y|x;\\theta) \\nabla \\log p(y|x;\\theta)^T$$\n\n## 6. 分布式支持：DDP 包装器\n\n对于使用 `torch.nn.parallel.DistributedDataParallel`（DDP）包装的模型，曲率算子需要额外处理参数同步和梯度聚合逻辑。\n\n### 6.1 同步机制\n\n```mermaid\ngraph TD\n subgraph \"单设备算子\"\n A[\"HessianOperator/GGNOperator\"]\n end\n \n subgraph \"DDP 包装层\"\n B[\"DDPWrappedCurvatureOperator\"]\n end\n \n subgraph \"分布式后端\"\n C[\"DistributedLinAlgBackend\"]\n end\n \n A --> B\n B --> C\n```\n\n`DDPWrappedCurvatureOperator` 负责：\n\n- 在每个 matvec 调用前同步模型参数（若使用分片参数）\n- 在梯度计算后聚合所有 rank 的梯度\n- 将梯度展平为与 `v` 相同形状的向量\n\n资料来源：[hessian_eigenthings/operators/distributed/ddp.py]()\n\n### 6.2 参数过滤与 DDP\n\n在使用 `param_filter` 进行参数子集选择时，DDP 包装器需要确保：\n\n1. 过滤后的参数在各 rank 间一致\n2. 梯度同步仅发生在选中的参数子集上\n\n## 7. 预置损失函数\n\n项目在 `hessian_eigenthings/loss_fns` 模块中提供了常用损失函数的 HVP 实现，可直接与 `GGNOperator` 配合使用。\n\n### 7.1 标准损失函数\n\n| 函数 | 说明 | 适用场景 |\n|------|------|----------|\n| `cross_entropy_loss_of_output()` | 交叉熵损失的 `loss_of_output_fn`，返回闭式 HVP | 分类模型 |\n| `make_loss_of_output_fn(criterion)` | 从任意损失函数创建适配器 | 自定义损失 |\n\n闭式 HVP 计算公式（以交叉熵为例）：\n\n对于形状为 `(N, C)` 的 logits，`H_loss @ u` 的第 $i$ 行计算为：\n\n$$(\\text{diag}(p_i) - p_i p_i^T) \\cdot u_i / N$$\n\n其中 $p_i = \\text{softmax}(\\text{logits}_i)$。\n\n资料来源：[hessian_eigenthings/loss_fns/standard.py:27-37]()\n\n### 7.2 HuggingFace 损失函数\n\n针对 HuggingFace Transformers 库的语言模型，提供了优化的融合 CE HVP 实现：\n\n| 后端 | 说明 | 性能特征 |\n|------|------|----------|\n| `auto` | 自动选择最快可用后端 | Triton > compile > eager |\n| `triton` | 手写 CUDA Triton 内核，零中间张量 | 约 3.4x 加速，2x 内存减少 |\n| `compile` | `torch.compile` 融合，CPU/CUDA/MPS 通用 | 约 2.6x 加速，2x 内存减少 |\n| `eager` | 朴素 PyTorch 实现 | 便于调试，V≥50k 时易 OOM |\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py:1-40]()\n\n融合内核的核心计算公式：\n\n```python\np = softmax(logits)\ndot = (p * u).sum(dim=-1, keepdim=True)\nout = (p * u - p * dot) * mask / n_valid\n```\n\n## 8. 参数过滤机制\n\n参数过滤允许用户仅对模型参数子集计算曲率矩阵，这对于分析特定层或模块的曲率特性非常有用。\n\n### 8.1 过滤函数类型\n\n```python\nParamFilter = Callable[[str, nn.Parameter], bool]\n```\n\n过滤函数接收参数名称和参数张量，返回布尔值表示是否纳入计算。\n\n### 8.2 使用示例\n\n```python\nfrom fnmatch import fnmatch\n\n# 匹配所有注意力层参数\nparam_filter = lambda name, _: fnmatch(name, \"transformer.h.*.attn.*\")\n\nop = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=loss_fn,\n param_filter=param_filter\n)\n```\n\n资料来源：[examples/huggingface_tiny_gpt2.py:42-46]()\n\n### 8.3 过滤后的参数重映射\n\n过滤后的算子 `size` 属性反映的是被选中参数的总数，`matvec` 接收和返回的向量形状均为 `(size,)`。算子内部维护参数名到参数张量的映射，确保向量索引与参数顺序正确对应。\n\n## 9. 线性代数后端\n\n`LinAlgBackend` 抽象了向量运算（点积、范数、归约等）的实现，支持不同硬件和分布式场景。\n\n### 9.1 后端类型\n\n| 后端 | 场景 |\n|------|------|\n| `SingleDeviceBackend` | 单设备 CPU/GPU 计算 |\n| `DistributedBackend` | 多设备/多节点分布式计算 |\n\n所有后端提供统一的向量运算接口，算子和算法代码通过后端进行所有线性代数操作。\n\n## 10. 使用流程总结\n\n```mermaid\ngraph LR\n A[\"定义模型
nn.Module\"] --> B[\"准备数据加载器
DataLoader\"]\n B --> C[\"选择/实现损失函数
LossFn / loss_of_output_fn\"]\n C --> D[\"创建曲率算子
HessianOperator / GGNOperator\"]\n D --> E[\"可选：参数过滤
param_filter\"]\n E --> F[\"调用算法
lanczos / trace / ... \"]\n F --> G[\"获取结果
特征值/特征向量/迹估计\"]\n```\n\n1. **模型准备**：创建待分析的 PyTorch 模型\n2. **数据准备**：准备与训练一致的数据加载器\n3. **损失函数**：选择合适的损失函数，对于 GGNOperator 需要提供 `loss_of_output_fn`\n4. **算子创建**：实例化曲率算子，可选配置参数过滤、计算方法等\n5. **算法调用**：使用 Lanczos 分解获取特征值/特征向量，或使用 Hutch++ 估计迹\n6. **结果解析**：分析返回的特征值分布、收敛性等信息\n\n## 11. 设计原则\n\n曲率算子系统的设计遵循以下核心原则：\n\n| 原则 | 说明 | 实现方式 |\n|------|------|----------|\n| **算子抽象** | 曲率矩阵计算与特征分解算法解耦 | 所有算子继承 `CurvatureOperator`，实现统一 `matvec` 接口 |\n| **内存效率** | 支持大规模模型的曲率分析 | 融合内核、流式计算、解析路径避免中间张量 |\n| **分布式友好** | 天然支持 DDP/FSDP/HSDP 等并行策略 | `finite_difference` 方法无二阶图；DDP 包装器处理梯度同步 |\n| **数值稳定性** | 提供多种精度/速度权衡选项 | autograd（精确）vs finite_difference；analytical vs autograd for GGN |\n\n---\n\n\n\n## 特征分解算法\n\n### 相关页面\n\n相关主题：[核心架构设计](#page-core-architecture), [曲率算子详解](#page-operators)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [hessian_eigenthings/algorithms/__init__.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/__init__.py)\n- [hessian_eigenthings/algorithms/lanczos.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/lanczos.py)\n- [hessian_eigenthings/algorithms/trace.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/trace.py)\n- [hessian_eigenthings/algorithms/spectral_density.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/spectral_density.py)\n- [hessian_eigenthings/algorithms/power_iteration.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/power_iteration.py)\n- [docs/concepts/top-k-eigenvalues.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/concepts/top-k-eigenvalues.md)\n- [docs/concepts/trace-estimation.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/concepts/trace-estimation.md)\n- [docs/concepts/spectral-density.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/concepts/spectral-density.md)\n- [docs/reference/algorithms.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/reference/algorithms.md)\n \n\n# 特征分解算法\n\n本页面详细介绍 `pytorch-hessian-eigenthings` 库中实现的特征分解算法。该库提供了一套完整的曲率矩阵特征分解工具，包括 Lanczos 算法、幂迭代法、迹估计和谱密度估计。\n\n## 算法概述\n\n特征分解算法在神经网络的 Hessian 分析中扮演核心角色。Hessian 矩阵的特征值和特征向量与神经网络的泛化特性密切相关，研究者假设\"平坦最小值\"具有更好的泛化能力。 资料来源：[README.md]()\n\n该库实现了多种迭代特征分解算法，均基于 `CurvatureOperator` 接口构建，与底层线性代数后端解耦。 资料来源：[CONTRIBUTING.md](CONTRIBUTING.md)\n\n## 核心算法架构\n\n```mermaid\ngraph TD\n subgraph \"特征分解算法模块\"\n A[Lanczos 算法] --> D[特征值/向量计算]\n B[幂迭代法] --> D\n C[迹估计] --> E[矩阵迹计算]\n F[谱密度估计] --> G[Stochastic Lanczos Quadrature]\n end\n \n subgraph \"底层接口\"\n D --> H[CurvatureOperator]\n E --> H\n G --> H\n H --> I[LinAlgBackend]\n end\n```\n\n## Lanczos 算法\n\nLanczos 算法是该库计算 top-k 特征值和特征向量的主要方法。它通过三对角化过程将大型稀疏特征问题转化为小型稠密特征问题。\n\n### 算法原理\n\nLanczos 算法是一种迭代方法，用于计算矩阵的极端特征值。对于 n×n 矩阵 A 和初始向量 v₀，算法生成三对角矩阵 T，其特征值逼近 A 的 Ritz 值。 资料来源：[hessian_eigenthings/algorithms/lanczos.py](hessian_eigenthings/algorithms/lanczos.py)\n\n### API 接口\n\n```python\ndef lanczos(\n operator: CurvatureOperator,\n k: int = 20,\n max_iter: int = 100,\n *,\n tol: float = 1e-8,\n which: Literal[\"LM\", \"LA\", \"SA\"] = \"LM\",\n seed: int | None = None,\n reorthogonalize: bool = False,\n backend: LinAlgBackend[torch.Tensor] | None = None,\n) -> LanczosResult\n```\n\n### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `operator` | CurvatureOperator | 必需 | 曲率算子，提供 matvec 操作 |\n| `k` | int | 20 | 要计算的特征值数量 |\n| `max_iter` | int | 100 | 最大迭代次数 |\n| `tol` | float | 1e-8 | 收敛阈值，基于残差范数 |\n| `which` | str | \"LM\" | 特征值选择策略 |\n| `seed` | int | None | 随机种子 |\n| `reorthogonalize` | bool | False | 是否使用重正交化 |\n\n### 特征值选择策略\n\n| 策略 | 含义 | 使用场景 |\n|------|------|----------|\n| `\"LM\"` | Largest Magnitude | 默认选项，查找最大模特征值 |\n| `\"LA\"` | Largest Algebraic | 查找最大代数特征值 |\n| `\"SA\"` | Smallest Algebraic | 查找最小代数特征值 |\n\n特征值排序逻辑：\n\n```python\nif which == \"LM\":\n order = torch.argsort(theta.abs(), descending=True)\nelif which == \"LA\":\n order = torch.argsort(theta, descending=True)\nelif which == \"SA\":\n order = torch.argsort(theta, descending=False)\n```\n\n资料来源：[hessian_eigenthings/algorithms/lanczos.py:47-57](hessian_eigenthings/algorithms/lanczos.py)\n\n### Ritz 向量计算优化\n\n该实现使用秩-1外积更新直接累积 Ritz 向量到最终 (k, n) 布局，避免了 (n, m) 基矩阵和瞬态 (n, k) → (k, n) 转置复制。在 LLM 规模下，两者合计峰值可达特征向量大小的 2 倍以上。 资料来源：[hessian_eigenthings/algorithms/lanczos.py:63-71](hessian_eigenthings/algorithms/lanczos.py)\n\n```python\n# 优化后的累积方式\nfor j, basis_vec in enumerate(td.basis):\n eigenvectors.addr_(s_sel[j], basis_vec)\n```\n\n### 收敛判定\n\n残差计算基于最后分量：\n\n```python\nlast_components = s[-1, sel]\nresiduals = last_components.abs() * td.last_beta\nconverged = residuals < tol * eigenvalues.abs().clamp(min=_EPS)\n```\n\n资料来源：[hessian_eigenthings/algorithms/lanczos.py:73-76](hessian_eigenthings/algorithms/lanczos.py)\n\n## 幂迭代法\n\n幂迭代法是计算矩阵主导特征值的经典方法，该库提供了带deflation的幂迭代和加速随机幂迭代两种变体。\n\n### 标准幂迭代\n\n标准幂迭代通过反复应用矩阵并归一化来收敛到最大特征值对应的特征向量。 资料来源：[docs/concepts/top-k-eigenvalues.md](docs/concepts/top-k-eigenvalues.md)\n\n### Deflated 幂迭代\n\nDeflated 幂迭代基于 [HessianFlow](https://github.com/amirgholami/HessianFlow) 实现，用于计算多个特征值。在找到第一个特征值后，通过投影去除其影响，可以继续计算次大特征值。 资料来源：[README.md](README.md)\n\n### 加速随机幂迭代\n\n加速随机幂迭代来自 C. De Sa 等人的工作，通过随机化技术加速收敛。该方法在保持统计效率的同时显著减少迭代次数。 资料来源：[README.md](README.md)\n\n## 迹估计\n\n迹估计用于计算矩阵的迹 `tr(A)`，无需完整矩阵分解。这对于大型 Hessian 矩阵尤其重要，因为完整分解在计算上不可行。\n\n### Hutchinson 估计器\n\nHutchinson 估计器使用随机向量样本：\n\n```\ntr(A) ≈ (1/m) Σ vᵢᵀ A vᵢ\n```\n\n其中 vᵢ 是从特定分布独立采样的随机向量。Rademacher 分布提供比 Gaussian 更低的方差。 资料来源：[hessian_eigenthings/algorithms/trace.py](hessian_eigenthings/algorithms/trace.py)\n\n### Hutch++ 估计器\n\nHutch++ 是 Hutchinson 估计器的改进版本，通过结构性随机化实现更快的收敛。 资料来源：[docs/concepts/trace-estimation.md](docs/concepts/trace-estimation.md)\n\n### API 接口\n\n```python\ndef trace(\n operator: CurvatureOperator,\n num_matvecs: int = 100,\n *,\n method: Literal[\"hutchinson\", \"hutch++\"] = \"hutchinson\",\n seed: int | None = None,\n distribution: Distribution = \"rademacher\",\n backend: LinAlgBackend[torch.Tensor] | None = None,\n) -> TraceResult\n```\n\n### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `operator` | CurvatureOperator | 必需 | 曲率算子 |\n| `num_matvecs` | int | 100 | 矩阵-向量积样本数量 |\n| `method` | str | \"hutchinson\" | 估计方法 |\n| `seed` | int | None | 随机种子 |\n| `distribution` | str | \"rademacher\" | 随机向量分布 |\n\n### 实现细节\n\n```python\ndef hutchinson(\n operator: CurvatureOperator,\n num_samples: int = 100,\n distribution: Distribution = \"rademacher\",\n seed: int | None = None,\n backend: LinAlgBackend[torch.Tensor] | None = None,\n) -> TraceResult:\n \"\"\"Hutchinson's estimator. Rademacher gives lower variance for trace.\"\"\"\n probe = torch.empty(operator.size, dtype=operator.dtype, device=operator.device)\n samples = torch.empty(num_samples, dtype=operator.dtype, device=operator.device)\n for i in range(num_samples):\n v = _draw(distribution, probe, gen, backend)\n av = operator.matvec(v)\n samples[i] = backend.dot(v, av)\n \n estimate = samples.mean().item()\n if num_samples > 1:\n stderr = (samples.std(unbiased=True) / (num_samples) ** 0.5).item()\n```\n\n资料来源：[hessian_eigenthings/algorithms/trace.py:54-74](hessian_eigenthings/algorithms/trace.py)\n\n## 谱密度估计\n\n谱密度（spectral density）描述了特征值在整个谱上的分布情况，使用 Stochastic Lanczos Quadrature (SLQ) 方法计算。\n\n### Stochastic Lanczos Quadrature\n\nSLQ 结合了 Lanczos 算法和蒙特卡洛积分，通过少量 Lanczos 迭代来估计谱密度函数。 资料来源：[docs/concepts/spectral-density.md](docs/concepts/spectral-density.md)\n\n### 核心思想\n\n对于对称矩阵 A，谱密度定义为：\n\n```\nρ(λ) = (1/n) Σ δ(λ - λᵢ)\n```\n\n其中 δ 是 Dirac delta 函数。SLQ 通过随机起始向量和 Lanczos 迭代来近似这一分布。\n\n### 应用场景\n\n| 场景 | 说明 |\n|------|------|\n| 特征值分布可视化 | 绘制谱密度曲线观察特征值聚集情况 |\n| 批量大小选择 | 根据谱的宽度判断最优批量大小 |\n| 收敛性分析 | 观察 Hessian 谱结构判断优化器收敛速度 |\n\n## 算法选择指南\n\n```mermaid\ngraph TD\n A[分析目标] --> B{需要什么结果?}\n B --> C[Top-k 特征值/向量]\n B --> D[矩阵迹]\n B --> E[谱密度分布]\n B --> F[仅主导特征值]\n \n C --> G[Lanczos 算法]\n D --> H{精度要求}\n H --> I[高精度]\n H --> J[一般精度]\n F --> K[幂迭代法]\n \n I --> L[Hutch++]\n J --> M[Hutchinson]\n E --> N[SLQ]\n \n G --> O[结果: 特征值 + 特征向量]\n L --> P[结果: 迹估计值 + 标准误差]\n M --> P\n K --> Q[结果: 主导特征值]\n N --> R[结果: 密度采样点]\n```\n\n### 选择建议\n\n| 目标 | 推荐算法 | 理由 |\n|------|----------|------|\n| 计算 top-k 特征对 | Lanczos | 数值稳定，效率高 |\n| 估计矩阵迹 | Hutch++ | 更快收敛，更少 matvec |\n| 谱密度可视化 | SLQ | 一次运行多点估计 |\n| 简单主导特征值 | 幂迭代 | 实现简单，内存低 |\n\n## 并行化与后端支持\n\n所有算法均通过 `LinAlgBackend` 接口支持不同的计算后端：\n\n| 后端 | 适用场景 |\n|------|----------|\n| SingleDeviceBackend | 单 GPU/CPU 计算 |\n| 分布式后端 | 多 GPU 分布式计算 |\n\n算法与后端完全解耦，可以无缝切换设备或分布式策略。 资料来源：[hessian_eigenthings/algorithms/__init__.py](hessian_eigenthings/algorithms/__init__.py)\n\n## 使用示例\n\n### Lanczos 计算 Top-3 特征值\n\n```python\nfrom hessian_eigenthings import HessianOperator, lanczos\n\n# 创建 Hessian 算子\nhessian_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=loss_fn,\n)\n\n# 计算 top-3 特征值和特征向量\nresult = lanczos(hessian_op, k=3, max_iter=20, tol=1e-3, seed=0)\n\nprint(\"Top-3 eigenvalues:\")\nfor i, val in enumerate(result.eigenvalues):\n print(f\" λ_{i+1} = {val.item():.4e}\")\n```\n\n### 迹估计\n\n```python\nfrom hessian_eigenthings import trace\n\ntrace_result = trace(\n hessian_op,\n num_matvecs=30,\n method=\"hutch++\",\n seed=0\n)\n\nprint(f\"Hutch++ trace estimate: {trace_result.estimate:.4e}\")\n```\n\n## 算法模块结构\n\n```\nhessian_eigenthings/algorithms/\n├── __init__.py # 公共 API 导出\n├── lanczos.py # Lanczos 特征分解\n├── trace.py # 迹估计 (Hutchinson/Hutch++)\n├── spectral_density.py # Stochastic Lanczos Quadrature\n└── power_iteration.py # 幂迭代法\n```\n\n资料来源：[docs/reference/algorithms.md](docs/reference/algorithms.md)\n\n## 性能考量\n\n| 算法 | 每次迭代复杂度 | 内存需求 | 收敛速度 |\n|------|----------------|----------|----------|\n| Lanczos | O(n²) per matvec | O(n·k) | 快（对极端特征值） |\n| 幂迭代 | O(n²) per matvec | O(n) | 慢（仅主导特征值） |\n| Hutchinson | O(n²) per matvec | O(n) | O(1/√m) |\n| Hutch++ | O(n²) per matvec | O(n) | 比 Hutchinson 快 |\n\n其中 n 是参数数量，k 是目标特征值数量，m 是随机样本数。\n\n---\n\n\n\n## 参数工具模块\n\n### 相关页面\n\n相关主题：[核心架构设计](#page-core-architecture), [曲率算子详解](#page-operators)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [hessian_eigenthings/param_utils.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/param_utils.py)\n- [docs/reference/param_utils.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/reference/param_utils.md)\n- [docs/how-to/per-layer-hessian.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/how-to/per-layer-hessian.md)\n \n\n# 参数工具模块\n\n参数工具模块（`param_utils`）是 `hessian-eigenthings` 库中用于参数选择、过滤和批量操作的实用工具集合。该模块提供了灵活的模式匹配机制，允许用户对 PyTorch 模型中的特定参数或参数组进行曲率分析，如 Hessian 矩阵的特征分解。\n\n## 模块概述\n\n在神经网络的曲率分析中，通常不需要对整个模型的所有参数进行计算。参数工具模块提供了基于名称模式的参数过滤功能，使得用户可以针对性地分析：\n\n- 模型中特定层的 Hessian 矩阵\n- 注意力机制的曲率特性\n- 全连接层或卷积层的参数\n- 任意自定义的参数子集\n\n资料来源：[hessian_eigenthings/param_utils.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/param_utils.py)\n\n## 核心功能\n\n### `match_names` 函数\n\n`match_names` 是该模块的核心函数，用于创建一个参数过滤器（`ParamFilter`），基于参数名称的模式匹配来选择特定参数。\n\n**函数签名：**\n\n```python\ndef match_names(*patterns: str) -> ParamFilter\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `patterns` | `str` | 逗号分隔的名称模式，支持通配符 `*` 匹配任意字符序列 |\n\n**返回值：**\n\n返回一个 `ParamFilter` 类型的函数，该函数接受模型参数名称列表，返回匹配模式的所有参数名称集合。\n\n资料来源：[hessian_eigenthings/param_utils.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/param_utils.py)\n\n### `ParamFilter` 类型\n\n`ParamFilter` 是模块中定义的核心类型别名：\n\n```python\nParamFilter = Callable[[list[str]], set[str]]\n```\n\n它表示一个函数，接收参数名称列表，返回匹配的参数名称集合。这种设计使得参数过滤逻辑与具体算子解耦，提高了模块的可复用性。\n\n资料来源：[docs/reference/param_utils.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/reference/param_utils.md)\n\n## 使用模式\n\n### 单层参数过滤\n\n选择模型中所有与 \"attention\" 相关的参数：\n\n```python\nfrom hessian_eigenthings import HessianOperator\nfrom hessian_eigenthings.param_utils import match_names\n\nattn_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=loss_fn,\n param_filter=match_names(\"*attn*\"),\n)\n```\n\n资料来源：[examples/transformer_lens_attention_only.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/examples/transformer_lens_attention_only.py)\n\n### 多层参数过滤\n\n使用多个模式匹配不同层级的参数：\n\n```python\nfrom hessian_eigenthings import HessianOperator\nfrom hessian_eigenthings.param_utils import match_names\n\n# 匹配 transformer.h.*.attn.* 模式的参数\nattn_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=loss_fn,\n param_filter=match_names(\"transformer.h.*.attn.*\"),\n)\n\n# 匹配 MLP 相关参数\nmlp_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=loss_fn,\n param_filter=match_names(\"blocks.*.mlp.*\"),\n)\n```\n\n资料来源：[examples/huggingface_tiny_gpt2.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/examples/huggingface_tiny_gpt2.py)\n\n### 与曲率算子集成\n\n参数过滤器与 `HessianOperator`、`GGNOperator` 等曲率算子无缝集成。当 `param_filter` 被指定时，算子仅对过滤后的参数子集进行操作：\n\n```python\nfrom hessian_eigenthings import HessianOperator, lanczos\nfrom hessian_eigenthings.param_utils import match_names\n\n# 创建仅包含注意力层参数的 Hessian 算子\nhessian_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=loss_fn,\n param_filter=match_names(\"*attention*\", \"*attn*\"),\n)\n\n# 计算该子集的 top-k 特征值\neigenvalues, eigenvectors = lanczos(hessian_op, k=5, max_iter=50)\n```\n\n资料来源：[docs/how-to/per-layer-hessian.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/how-to/per-layer-hessian.md)\n\n## 参数过滤流程\n\n以下流程图展示了参数过滤在曲率分析中的完整流程：\n\n```mermaid\ngraph TD\n A[PyTorch 模型] --> B[获取所有参数名称]\n B --> C[应用 param_filter]\n C --> D{匹配检查}\n D -->|匹配成功| E[包含在曲率计算中]\n D -->|匹配失败| F[排除在外]\n E --> G[创建 CurvatureOperator 子集]\n G --> H[执行 Lanczos 算法]\n H --> I[返回特征值/特征向量]\n F --> J[跳过该参数]\n```\n\n## 模式匹配语法\n\n| 模式示例 | 匹配内容 | 示例 |\n|----------|----------|------|\n| `*attn*` | 包含 \"attn\" 的任意参数名 | `blocks.0.attn.weight`, `model.attn_bias` |\n| `*.weight` | 以 \".weight\" 结尾的参数 | `layer1.weight`, `fc2.weight` |\n| `blocks.*.mlp.*` | blocks 下任意深度的 mlp 参数 | `blocks.0.mlp.linear1.weight` |\n| `*bias*` | 包含 \"bias\" 的参数 | `fc.bias`, `layer_norm.bias` |\n\n## 最佳实践\n\n### 1. 精确匹配优先\n\n为避免意外匹配无关参数，使用更精确的模式：\n\n```python\n# 较优：精确匹配 attention 层\nparam_filter=match_names(\"transformer.h.*.attn.*\")\n\n# 较粗：可能匹配到不相关的参数\nparam_filter=match_names(\"*attn*\")\n```\n\n### 2. 组合使用多个模式\n\n当需要选择多个非连续区域的参数时：\n\n```python\n# 同时选择 attention 和 embedding 层\nparam_filter=match_names(\"*attn*\", \"*embed*\", \"*embedding*\")\n```\n\n### 3. 验证过滤结果\n\n在实际计算前验证过滤是否正确：\n\n```python\nfrom hessian_eigenthings.param_utils import match_names\n\nparam_filter = match_names(\"blocks.*.attn.*\")\nall_params = list(model.named_parameters())\nmatched = param_filter([n for n, _ in all_params])\n\nprint(f\"匹配到的参数数量: {len(matched)}\")\nfor name in matched:\n print(f\" - {name}\")\n```\n\n资料来源：[docs/how-to/per-layer-hessian.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/how-to/per-layer-hessian.md)\n\n## API 参考\n\n### `hessian_eigenthings.param_utils`\n\n| 函数/类型 | 说明 |\n|-----------|------|\n| `match_names(*patterns: str) -> ParamFilter` | 创建基于模式的参数过滤器 |\n| `ParamFilter` | 类型别名，表示参数过滤函数类型 |\n\n### 导出列表\n\n模块默认导出：\n\n```python\nfrom hessian_eigenthings.param_utils import match_names, ParamFilter\n```\n\n资料来源：[docs/reference/param_utils.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/docs/reference/param_utils.md)\n\n## 与其他模块的关系\n\n参数工具模块在整体架构中扮演基础工具角色，为曲率算子提供参数选择能力：\n\n```mermaid\ngraph LR\n A[param_utils] -->|提供 ParamFilter| B[HessianOperator]\n A -->|提供 ParamFilter| C[GGNOperator]\n A -->|提供 ParamFilter| D[EmpiricalFisher]\n B --> E[lanczos 算法]\n C --> E\n D --> E\n E --> F[特征值/特征向量结果]\n```\n\n这种设计确保了参数过滤逻辑的统一实现，避免了在各个算子中重复定义相同的过滤机制。\n\n---\n\n\n\n## 损失函数模块\n\n### 相关页面\n\n相关主题：[曲率算子详解](#page-operators)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [hessian_eigenthings/loss_fns/__init__.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/loss_fns/__init__.py)\n- [hessian_eigenthings/loss_fns/standard.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/loss_fns/standard.py)\n- [hessian_eigenthings/loss_fns/_fused_ce_hvp.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/loss_fns/_fused_ce_hvp.py)\n- [hessian_eigenthings/loss_fns/huggingface.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/loss_fns/huggingface.py)\n- [hessian_eigenthings/operators/ggn.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/ggn.py)\n \n\n# 损失函数模块\n\n## 概述\n\n损失函数模块（`hessian_eigenthings/loss_fns/`）是 pytorch-hessian-eigenthings 项目中连接用户模型输出与曲率算子（CurvatureOperator）的桥梁。该模块的核心职责是将各种损失函数的计算过程适配为统一的函数签名，使 HessianOperator 和 GGNOperator 能够正确计算损失相对于模型输出的 Hessian 向量积（HVP）。\n\n资料来源：[hessian_eigenthings/loss_fns/__init__.py]()\n\n```mermaid\ngraph TD\n subgraph 用户模型\n A[模型前向传播] --> B[logits 输出]\n end\n \n subgraph 损失函数模块\n C[forward_fn] --> D[loss_of_output_fn]\n B --> C\n B --> D\n end\n \n subgraph 曲率算子\n E[HessianOperator / GGNOperator]\n D --> E\n end\n \n E --> F[matvec 计算]\n F --> G[Hessian / GGN 向量积]\n```\n\n## 模块架构\n\n### 文件结构\n\n| 文件 | 用途 |\n|------|------|\n| `__init__.py` | 模块导出接口 |\n| `standard.py` | 标准分类/回归损失函数封装 |\n| `huggingface.py` | HuggingFace Transformers 模型专用损失封装 |\n| `_fused_ce_hvp.py` | 融合交叉熵 HVP 核心实现 |\n\n资料来源：[hessian_eigenthings/loss_fns/__init__.py](), [hessian_eigenthings/loss_fns/standard.py](), [hessian_eigenthings/loss_fns/huggingface.py]()\n\n### 核心函数签名\n\n损失函数模块定义了两类关键函数签名，供曲率算子调用：\n\n```python\n# 类型1: forward_fn - 模型前向传播函数\nForwardFn = Callable[[nn.Module, Any], torch.Tensor]\n\n# 类型2: loss_of_output_fn - 从模型输出计算损失的函数\nLossOfOutputFn = Callable[[torch.Tensor, Any], torch.Tensor]\n\n# 类型3: 可选的 HVP 函数 (用于 GGNOperator)\nHvpFn = Callable[[torch.Tensor, Any, torch.Tensor], torch.Tensor]\n```\n\n资料来源：[hessian_eigenthings/operators/ggn.py]()\n\n## 标准损失函数\n\n`standard.py` 模块提供了基于标准 PyTorch 损失函数的封装实现。\n\n资料来源：[hessian_eigenthings/loss_fns/standard.py]()\n\n### 分类损失\n\n对于多分类任务，模块实现了交叉熵损失的闭式 HVP 计算。对于 mean-reduced softmax + cross-entropy，损失函数为：\n\n```python\nH_row = (diag(p) - p p^T) / N\n```\n\n其中 `p = softmax(output)` 是模型输出的概率分布。\n\n```python\ndef _ce_hvp(\n output: torch.Tensor, \n batch: tuple[torch.Tensor, torch.Tensor], \n u: torch.Tensor\n) -> torch.Tensor:\n \"\"\"闭式 H @ u for mean-reduced softmax + cross-entropy.\"\"\"\n flat_output = output.reshape(-1, output.size(-1))\n flat_u = u.reshape(-1, u.size(-1))\n n = float(flat_output.size(0))\n p = torch.softmax(flat_output, dim=-1)\n dot = (p * flat_u).sum(dim=-1, keepdim=True)\n return ((p * flat_u - p * dot) / n).view_as(u)\n```\n\n资料来源：[hessian_eigenthings/loss_fns/standard.py:32-45]()\n\n### GGNOperator 兼容封装\n\n```python\ndef _make_loss_of_output_fn(\n criterion: Callable[[torch.Tensor, torch.Tensor], torch.Tensor]\n) -> Callable[[torch.Tensor, tuple[torch.Tensor, torch.Tensor]], torch.Tensor]:\n \"\"\"为 GGNOperator 从 (output, target) 损失构造 loss_of_output_fn.\"\"\"\n \n def _fn(output: torch.Tensor, batch: tuple[torch.Tensor, torch.Tensor]) -> torch.Tensor:\n _, y = batch\n return criterion(output, y)\n \n return _fn\n```\n\n资料来源：[hessian_eigenthings/loss_fns/standard.py:10-19]()\n\n## HuggingFace Transformers 损失函数\n\n`huggingface.py` 模块专为 HuggingFace Transformers 库设计的预训练模型提供损失函数封装。\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py]()\n\n### API 设计\n\nHuggingFace 模型在提供 `labels` 时会内部计算损失，返回包含 `.loss` 和 `.logits` 的 `ModelOutput`。模块将这些适配为算子期望的函数签名：\n\n```python\ndef hf_lm_loss(\n fused: FusedCEHvpBackend = \"auto\"\n) -> tuple[ForwardFn, LossOfOutputFn, HvpFn]:\n \"\"\"返回 HuggingFace LM 的 forward_fn, loss_of_output_fn 和 HVP 函数.\"\"\"\n```\n\n### Shifted Cross-Entropy 损失\n\n对于因果语言模型（Causal LM），输入 token 序列需要向右移动一位作为标签（shifted CE）：\n\n```python\ndef _hf_lm_shifted_ce(\n logits: torch.Tensor, \n batch: dict[str, Any]\n) -> torch.Tensor:\n \"\"\"Shifted cross-entropy loss for causal language models.\"\"\"\n labels = batch[\"labels\"]\n # logits: (B, T, V), labels: (B, T)\n logits = logits[:, :-1, :].contiguous()\n labels = labels[:, 1:].contiguous()\n return torch.nn.functional.cross_entropy(\n logits.view(-1, logits.size(-1)), \n labels.view(-1),\n ignore_index=-100\n )\n```\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py]()\n\n### 闭式 H_loss @ u\n\n对于 shifted CE loss，`H_loss` 在 `(B, T-1)` 上是块对角矩阵，每个块的形状为：\n\n```\nH_block = (diag(p_t) - p_t p_t^T) / n\n```\n\n其中 `p_t = softmax(shift_logits_t)`，`n` 是非忽略位置的数量。\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py]()\n\n## 融合 CE HVP 实现\n\n`_fused_ce_hvp.py` 提供了交叉熵 Hessian 向量积的高性能融合实现。\n\n资料来源：[hessian_eigenthings/loss_fns/_fused_ce_hvp.py]()\n\n### 计算公式\n\n融合实现计算：\n\n```\nout_flat = (p * u - p * ) * mask / n_valid\n```\n\n输出形状为 `(N, V)`，其中 `N` 是 batch 中的 token 数量，`V` 是词表大小。\n\n### 后端选项\n\n| 后端 | 描述 | 优势 |\n|------|------|------|\n| `\"auto\"` | 自动选择最快可用后端 | 智能适配 |\n| `\"eager\"` | 普通 PyTorch 实现 | 易调试、兼容性最好 |\n| `\"compile\"` | `torch.compile` 融合 | 约 2.6x 加速，2x 内存减少 |\n| `\"triton\"` | Triton CUDA kernel | 约 3.4x 加速，零中间内存 |\n\n资料来源：[hessian_eigenthings/loss_fns/_fused_ce_hvp.py](), [hessian_eigenthings/loss_fns/huggingface.py]()\n\n### 后端自动选择逻辑\n\n```python\ndef _resolve_backend(\n backend: FusedCEHvpBackend, \n logits: torch.Tensor | None = None\n) -> FusedCEHvpBackend:\n \"\"\"Resolve ``\"auto\"`` to the fastest available concrete backend.\"\"\"\n if backend != \"auto\":\n return backend\n \n # 优先级: triton (CUDA + Triton可用) → compile → eager\n if _triton_available and logits is not None and logits.is_cuda:\n return \"triton\"\n return \"compile\"\n```\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py]()\n\n### 参考实现\n\n```python\ndef _ce_hvp_reference(\n flat_logits: torch.Tensor,\n flat_u: torch.Tensor,\n valid: torch.Tensor,\n n: torch.Tensor,\n) -> torch.Tensor:\n \"\"\"Eager reference implementation.\"\"\"\n p = torch.softmax(flat_logits, dim=-1)\n dot = (p * flat_u).sum(dim=-1, keepdim=True)\n return (p * flat_u - p * dot) * valid.unsqueeze(-1) / n\n```\n\n资料来源：[hessian_eigenthings/loss_fns/_fused_ce_hvp.py]()\n\n## GGNOperator 中的损失函数集成\n\nGGNOperator 支持两种 matvec 实现路径，通过 `loss_hvp` 参数控制：\n\n资料来源：[hessian_eigenthings/operators/ggn.py]()\n\n### Analytical 路径（默认）\n\n```python\n# 有限差分 JVP + 解析 loss-Hessian-向量积\nloss_hvp = loss_of_output_fn.hvp # 必须存在\n```\n\n内存占用匹配一次正常训练步骤，适用于 LM 规模的使用场景。\n\n### Autograd 路径（备用）\n\n```python\n# torch.func.jvp + autograd 双重反向 + torch.func.vjp\n```\n\n数值精确、支持任意损失函数，但对大词表分类头内存消耗严重。\n\n## 使用示例\n\n### 标准分类任务\n\n```python\nfrom hessian_eigenthings.operators import HessianOperator\nfrom hessian_eigenthings.loss_fns.standard import cross_entropy_loss_of_output\n\nloss_fn = cross_entropy_loss_of_output()\n\nhessian_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=hf_lm_loss(),\n)\n```\n\n### HuggingFace 模型\n\n```python\nfrom hessian_eigenthings.loss_fns.huggingface import hf_lm_loss\n\nforward_fn, loss_of_output_fn, hvp_fn = hf_lm_loss(fused=\"auto\")\n```\n\n## 性能对比\n\n| 实现方式 | 内存峰值 (V=50304) | 速度 |\n|----------|-------------------|------|\n| eager | ~19.6 GB | 1x |\n| compile | ~3.3 GB | ~2.6x |\n| triton | 最小 | ~3.4x |\n\n资料来源：[scripts/bench_fused_ce_hvp.py]()\n\n## 扩展指南\n\n添加新的损失函数封装需要：\n\n1. 实现 `loss_of_output_fn(output, batch)` 接口\n2. 可选实现 `.hvp(output, batch, u)` 属性用于 GGNOperator\n3. 保持与 `CurvatureOperator` 的兼容性\n\n资料来源：[CONTRIBUTING.md]()\n\n---\n\n\n\n## HuggingFace 模型集成\n\n### 相关页面\n\n相关主题：[损失函数模块](#page-loss-functions)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [hessian_eigenthings/loss_fns/huggingface.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/loss_fns/huggingface.py)\n- [examples/huggingface_tiny_gpt2.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/examples/huggingface_tiny_gpt2.py)\n- [hessian_eigenthings/operators/ggn.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/ggn.py)\n- [hessian_eigenthings/loss_fns/_fused_ce_hvp.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/loss_fns/_fused_ce_hvp.py)\n- [hessian_eigenthings/algorithms/lanczos.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/lanczos.py)\n \n\n# HuggingFace 模型集成\n\n## 概述\n\nHuggingFace 模型集成是 `hessian-eigenthings` 库为 HuggingFace Transformer 模型提供的专用损失函数和优化计算路径。该模块位于 `hessian_eigenthings/loss_fns/huggingface.py`，专门针对因果语言模型（Causal Language Model）的交叉熵损失实现了闭合形式的 Hessian-向量乘积（Hessian-Vector Product, HVP）计算。\n\n主要功能包括：\n\n- **移位交叉熵损失**：适配因果语言建模任务的特殊损失计算\n- **闭合形式 HVP**：避免 autograd 双反向传播的内存开销\n- **多后端支持**：支持 Triton、torch.compile 和 eager 模式\n- **GGNOperator 集成**：与广义 Gauss-Newton 算子无缝配合\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py:1-100]()\n\n## 架构设计\n\n### 模块依赖关系\n\n```mermaid\ngraph TD\n subgraph \"用户代码\"\n A[\"用户模型
(如 GPT-2)\"]\n B[\"DataLoader\"]\n end\n \n subgraph \"huggingface.py\"\n C[\"huggingface_lm_loss()\"]\n D[\"_hf_lm_shifted_ce\"]\n E[\"_hf_lm_ce_hvp\"]\n end\n \n subgraph \"GGNOperator\"\n F[\"loss_of_output_fn\"]\n G[\"loss_hvp='analytical'\"]\n end\n \n subgraph \"后端实现\"\n H[\"Triton 内核\"]\n I[\"torch.compile\"]\n J[\"Eager PyTorch\"]\n end\n \n A --> C\n B --> C\n C --> D\n C --> E\n D --> F\n E --> G\n G --> H\n G --> I\n G --> J\n```\n\n### 闭合形式 Hessian 计算原理\n\n对于均规约的 softmax + 交叉熵损失，Hessian 在 `(B, T-1)` 上呈块对角结构。每个时间步 `t` 的块为：\n\n$$H_{loss}[t] = \\frac{1}{n}(\\text{diag}(p_t) - p_t p_t^T)$$\n\n其中：\n- $p_t = \\text{softmax}(\\text{shift\\_logits}_t)$ 是 softmax 概率分布\n- $n$ 是非忽略位置的计数\n\n这使得 Hessian-向量乘积可以闭合计算，无需构建完整的 Hessian 矩阵：\n\n$$H_{loss} \\cdot u = \\frac{p \\cdot u - p \\cdot \\langle p, u \\rangle}{n}$$\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py:28-40]()\n\n## 核心 API\n\n### `huggingface_lm_loss()`\n\n创建适用于 HuggingFace 因果语言模型的损失函数，包含闭合形式 HVP。\n\n```python\ndef huggingface_lm_loss(fused: str = \"auto\") -> _LossOfOutputWithHvp:\n```\n\n#### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `fused` | `str` | `\"auto\"` | CE HVP 核选择策略 |\n\n#### `fused` 选项\n\n| 值 | 说明 | 性能特性 |\n|----|------|----------|\n| `\"auto\"` | 自动选择（CUDA+Triton 可用时优先 Triton） | 最优性能 |\n| `\"eager\"` | 纯 PyTorch eager 模式 | 易调试，但 V≥50k 时易 OOM |\n| `\"compile\"` | `torch.compile` 融合 | CPU/CUDA/MPS 通用 |\n| `\"triton\"` | 手写 Triton CUDA 内核 | 峰值内存最小 |\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py:80-95]()\n\n### 返回值\n\n返回 `_LossOfOutputWithHvp` 对象，包含：\n\n- `__call__(logits, batch)` → `torch.Tensor`：损失标量\n- `.hvp(logits, batch, u)` → `torch.Tensor`：闭合形式 HVP\n\n## 计算后端\n\n### 后端选择流程\n\n```mermaid\ngraph TD\n A[\"fused='auto'\"] --> B{\"CUDA + Triton 可用?\"}\n B -->|是| C[\"使用 Triton 内核\"]\n B -->|否| D[\"使用 torch.compile\"]\n \n E[\"fused='eager'\"] --> F[\"纯 PyTorch Eager\"]\n G[\"fused='compile'\"] --> H[\"torch.compile 融合\"]\n I[\"fused='triton'\"] --> J{\"Triton/CUDA 可用?\"}\n J -->|否| K[\"回退到 compile\"]\n J -->|是| C\n```\n\n### 融合计算数学\n\n核心计算在 `(N, V)` 形状的张量上进行：\n\n```python\np = softmax(logits) # (N, V) 概率分布\ndot = (p * u).sum(dim=-1) # (N,) 点积\nhvp = (p * u - p * dot) * mask / n # (N, V) 结果\n```\n\n资料来源：[hessian_eigenthings/loss_fns/_fused_ce_hvp.py:1-50]()\n\n### 内存优化\n\n不同后端的内存占用对比（B=64, T=256, V=50304, fp32）：\n\n| 后端 | 内存估算 | (N,V) 张量数量 |\n|------|----------|----------------|\n| eager | ~19.6 GB | ~6 个中间张量 |\n| compile | ~3.3 GB | ~1 个（输出缓冲） |\n| triton | 最小 | 0 个中间张量 |\n\n资料来源：[scripts/bench_fused_ce_hvp.py:1-30]()\n\n## 与 GGNOperator 的集成\n\n### 工作流程\n\n```mermaid\ngraph LR\n A[\"模型 + DataLoader\"] --> B[\"GGNOperator\"]\n B --> C{\"loss_hvp 参数?\"}\n C -->|\"有 .hvp 方法\"| D[\"analytical 路径
有限差分 JVP + 解析 HVP\"]\n C -->|\"无 .hvp 方法\"| E[\"autograd 路径
torch.func.jvp + 双反向传播\"]\n \n D --> F[\"内存占用 = 单步训练\"]\n E --> G[\"内存随输出规模增长\"]\n```\n\n### analytical 路径优势\n\n当使用 `huggingface_lm_loss()` 返回的损失函数时：\n\n1. **有限差分 JVP**：单次前向通过计算雅可比向量乘积\n2. **解析 HVP**：使用闭合形式公式计算损失 Hessian-向量乘积\n3. **单次反向传播**：应用 $J^T$ 矩阵\n\n整体内存占用与单次训练步骤相当，适合 LLM 规模分析。\n\n资料来源：[hessian_eigenthings/operators/ggn.py:1-80]()\n\n## 使用示例\n\n### 完整分析流程\n\n```python\nimport torch\nfrom transformers import AutoTokenizer, AutoModelForCausalLM\nfrom hessian_eigenthings.operators import HessianOperator, GGNOperator\nfrom hessian_eigenthings.loss_fns.huggingface import huggingface_lm_loss\nfrom hessian_eigenthings.algorithms import lanczos, trace\n\n# 1. 加载模型\nmodel = AutoModelForCausalLM.from_pretrained(\"openai-community/gpt2\")\ntokenizer = AutoTokenizer.from_pretrained(\"openai-community/gpt2\")\n\n# 2. 准备数据\ntexts = [\"the quick brown fox jumps over\"]\nencoded = tokenizer(texts, padding=True, return_tensors=\"pt\")\nencoded[\"labels\"] = encoded[\"input_ids\"].clone()\ndataloader = [dict(encoded)]\n\n# 3. 创建损失函数（带闭合形式 HVP）\nhf_loss = huggingface_lm_loss(fused=\"auto\")\n\n# 4. 创建 GGN 算子\nggn_op = GGNOperator(\n model=model,\n dataloader=dataloader,\n forward_fn=lambda m, b: m(**b).logits,\n loss_of_output_fn=hf_loss,\n)\n\n# 5. 计算 top-k 特征值\neig_result = lanczos(ggn_op, k=3, max_iter=20, tol=1e-3, seed=0)\nprint(f\"Top-3 特征值: {eig_result.eigenvalues}\")\n\n# 6. 估计迹\ntrace_result = trace(ggn_op, num_matvecs=30, method=\"hutch++\", seed=0)\nprint(f\"Hutch++ 迹估计: {trace_result.estimate}\")\n```\n\n资料来源：[examples/huggingface_tiny_gpt2.py:1-60]()\n\n### 注意力层子空间分析\n\n```python\nfrom hessian_eigenthings.operators import HessianOperator\n\n# 仅分析注意力参数\nattn_op = HessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=hf_loss,\n param_filter=lambda n, p: \"attn\" in n, # 参数过滤器\n)\n\neig_attn = lanczos(attn_op, k=3, max_iter=20, tol=1e-3, seed=0)\nprint(f\"注意力层 top-3 特征值: {eig_attn.eigenvalues}\")\n```\n\n## 参数过滤器\n\n参数过滤器用于限制 Hessian 分析的子空间：\n\n| 过滤器模式 | 说明 | 示例 |\n|-----------|------|------|\n| `lambda n, p: \"attn\" in n` | 按名称包含 | 提取注意力参数 |\n| `lambda n, p: \"mlp\" in n` | 按名称包含 | 提取 MLP 参数 |\n| `lambda n, p: p.numel() > 1000` | 按大小过滤 | 排除偏置和小型参数 |\n\n## 与 TransformerLens 的对比\n\n| 特性 | HuggingFace 集成 | TransformerLens 集成 |\n|------|------------------|---------------------|\n| 模型支持 | GPT-2, LLaMA 等主流模型 | HookedTransformer |\n| 损失函数 | 因果语言模型交叉熵 | 可自定义 |\n| 示例文件 | `huggingface_tiny_gpt2.py` | `transformer_lens_attention_only.py` |\n| API | `huggingface_lm_loss()` | `tlens_loss()` |\n\n资料来源：[examples/transformer_lens_attention_only.py:1-50]()\n\n## 常见问题与限制\n\n### 内存溢出 (OOM) 处理\n\n若在 LLM 上遇到 OOM：\n\n1. **使用 analytical 路径**：确保使用 `huggingface_lm_loss()` 而非通用损失\n2. **切换到 finite_difference**：对 HessianOperator 使用 `method=\"finite_difference\"`\n3. **减小批量大小**：减少 dataloader 中的样本数\n4. **使用 bf16**：对大模型使用 bfloat16 精度\n\n资料来源：[scripts/repro_ggn_oom.py:1-50]()\n\n### 数值精度\n\n- **autograd 路径**：数值精确（至浮点精度）\n- **finite_difference 路径**：存在 $O(\\varepsilon^2)$ 截断偏差\n- **analytical 路径**：闭合形式，数值精确\n\n## 扩展阅读\n\n- [自定义曲率算子](../how-to/custom-curvature-operators.md)\n- [Lanczos 算法详解](../concepts/lanczos-algorithm.md)\n- [迹估计方法](../concepts/trace-estimation.md)\n\n---\n\n\n\n## 分布式训练支持 (DDP)\n\n### 相关页面\n\n相关主题：[曲率算子详解](#page-operators), [HuggingFace 模型集成](#page-huggingface-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [hessian_eigenthings/operators/distributed/__init__.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/distributed/__init__.py)\n- [hessian_eigenthings/operators/distributed/ddp.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/distributed/ddp.py)\n- [hessian_eigenthings/operators/hessian.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/operators/hessian.py)\n- [hessian_eigenthings/algorithms/lanczos.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/lanczos.py)\n- [hessian_eigenthings/algorithms/trace.py](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/hessian_eigenthings/algorithms/trace.py)\n \n\n# 分布式训练支持 (DDP)\n\n## 概述\n\n`hessian-eigenthings` 库通过 `DDPHessianOperator` 提供对 PyTorch 分布式数据并行（DistributedDataParallel, DDP）训练的原生支持。这一功能允许用户在多 GPU 或多节点分布式训练环境下计算 Hessian 矩阵的特征值分解，而无需修改现有的 DDP 训练代码。\n\n在分布式训练场景中，Hessian 分析面临独特的挑战：由于模型参数分布在多个进程上，梯度计算和损失聚合需要在进程间同步。`DDPHessianOperator` 封装了这些复杂性，提供了与单机 `HessianOperator` 一致的接口，使得分布式 Hessian 分析可以像单机使用一样简单。\n\n## 模块结构\n\n分布式模块位于 `hessian_eigenthings/operators/distributed/` 目录下，通过统一的导出接口供外部使用：\n\n```python\nfrom hessian_eigenthings.operators.distributed import DDPHessianOperator\n```\n\n资料来源：[hessian_eigenthings/operators/distributed/__init__.py:1]()\n\n## DDPHessianOperator 核心设计\n\n### 类继承关系\n\n`DDPHessianOperator` 继承自 `CurvatureOperator` 基类，遵循库中统一的曲率算子架构。这使得它可以与现有的 Lanczos 算法、trace 估计等工具无缝配合工作。\n\n### 主要功能特性\n\n| 特性 | 说明 |\n|------|------|\n| 自动梯度同步 | 在 `no_grad` 上下文中执行模型前向传播，确保梯度计算的一致性 |\n| 进程间通信优化 | 复用 DDP 的梯度桶机制，减少额外通信开销 |\n| 参数过滤支持 | 可通过 `param_filter` 参数选择性地分析特定参数子集的 Hessian |\n| 与 DDP 兼容 | 直接接收包装后的 DDP 模型，无需特殊处理 |\n\n### 构造函数参数\n\n`DDPHessianOperator` 的初始化签名与 `HessianOperator` 保持高度一致，降低了用户的学习成本：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `model` | `nn.Module` | DDP 包装后的模型实例 |\n| `dataloader` | `Iterable[Any]` | 数据加载器，提供批次数数据 |\n| `loss_fn` | `LossFn` | 损失函数，签名 `loss_fn(model_output, target) -> scalar` |\n| `param_filter` | `ParamFilter \\| None` | 可选参数过滤器，用于选择分析的参数子集 |\n| `full_dataset` | `bool` | 是否使用完整数据集（默认 `True`） |\n| `num_batches` | `int \\| None` | 使用的批次数，优先于 `full_dataset` |\n| `method` | `HvpMethod` | HVP 计算方法：`\"autograd\"` 或 `\"finite_difference\"` |\n\n## 使用工作流\n\n### 基础使用模式\n\n```python\nimport torch\nimport torch.distributed as dist\nfrom torch.nn.parallel import DistributedDataParallel as DDP\nfrom hessian_eigenthings.operators.distributed import DDPHessianOperator\nfrom hessian_eigenthings.algorithms.lanczos import lanczos\n\n# 初始化分布式环境（本地示例）\ndist.init_process_group(backend=\"nccl\")\n\n# 创建和包装模型\nmodel = MyModel().cuda(rank)\nmodel = DDP(model, device_ids=[local_rank])\n\n# 准备数据\ndataloader = distributed_data_loader()\n\n# 创建分布式 Hessian 算子\nhessian_op = DDPHessianOperator(\n model=model,\n dataloader=dataloader,\n loss_fn=my_loss_fn,\n)\n\n# 计算特征值分解\neigenvalues, eigenvectors = lanczos(hessian_op, k=10, max_iter=50)\n```\n\n### 与 Lanczos 算法集成\n\n`DDPHessianOperator` 可直接作为 `lanczos()` 函数的输入，用于计算分布式模型 Hessian 的 top-k 特征值和特征向量：\n\n```python\nfrom hessian_eigenthings.algorithms.lanczos import lanczos\n\nresult = lanczos(\n operator=hessian_op,\n k=5,\n max_iter=100,\n tol=1e-6,\n seed=42,\n backend=SingleDeviceBackend()\n)\n\nprint(f\"Top eigenvalues: {result.eigenvalues}\")\n```\n\n### 与 Trace 估计集成\n\n同样支持 `hutchinson()` 和 `hutch_plus_plus()` 方法进行 Hessian 迹估计：\n\n```python\nfrom hessian_eigenthings.algorithms.trace import hutch_plus_plus\n\ntrace_result = hutch_plus_plus(\n operator=hessian_op,\n num_matvecs=100,\n seed=0\n)\n\nprint(f\"Hessian trace estimate: {trace_result.estimate:.4e}\")\n```\n\n## 架构设计\n\n### 分布式 Hessian 计算流程\n\n```mermaid\ngraph TD\n A[初始化 DDP 模型] --> B[创建 DDPHessianOperator]\n B --> C[分布式数据加载]\n C --> D{每个 Rank 执行}\n D --> E[本地前向传播]\n E --> F[本地损失计算]\n F --> G[梯度同步 DDP]\n G --> H[本地 HVP 计算]\n H --> I[进程间结果聚合]\n I --> J[返回全局曲率信息]\n```\n\n### 与单机 HessianOperator 的差异\n\n| 方面 | HessianOperator | DDPHessianOperator |\n|------|-----------------|-------------------|\n| 模型输入 | 普通 `nn.Module` | DDP 包装后的模型 |\n| 梯度计算 | 单机梯度 | 聚合后的分布式梯度 |\n| 设备管理 | 单设备 | 多设备（每 Rank 一个） |\n| 通信开销 | 无 | DDP 梯度同步开销 |\n| 使用场景 | 单机实验 | 大规模分布式训练 |\n\n## 实现注意事项\n\n### 1. 分布式环境初始化\n\n使用 `DDPHessianOperator` 前必须确保分布式环境已正确初始化。库依赖 PyTorch 的 `torch.distributed` 模块进行进程间通信。\n\n### 2. 数据分发\n\n数据加载器应为分布式版本，确保每个 Rank 处理不同的数据分片。推荐使用 `DistributedSampler`：\n\n```python\nfrom torch.utils.data.distributed import DistributedSampler\n\nsampler = DistributedSampler(dataset, num_replicas=world_size, rank=rank)\ndataloader = DataLoader(dataset, sampler=sampler, batch_size=batch_size)\n```\n\n### 3. 同步点处理\n\n`DDPHessianOperator` 在计算过程中会自动处理必要的进程间同步，确保所有 Rank 在关键步骤上保持同步，避免不一致的梯度状态。\n\n## 性能考虑\n\n### 通信开销\n\n由于 Hessian 向量乘积计算需要梯度信息，`DDPHessianOperator` 会引入额外的梯度同步开销。优化建议：\n\n- 使用足够大的批量大小以分摊通信成本\n- 在需要分析的特定层使用参数过滤，减少计算范围\n- 考虑在训练间隙进行 Hessian 分析，而非实时计算\n\n### 内存效率\n\n分布式 Hessian 分析的内存需求随 Rank 数量增加而增加，因为每个进程需要保存本地激活和梯度副本。库通过 `no_grad` 上下文和适当的张量管理来优化内存使用。\n\n## 相关模块\n\n### CurvatureOperator 基类\n\n`DDPHessianOperator` 继承自 `CurvatureOperator`，这是库中所有曲率算子的抽象基类。它定义了统一的 `matvec()` 接口，所有算法（Lanczos、trace 估计等）都通过这一接口与算子交互。\n\n### 曲率算子家族\n\n| 算子 | 用途 |\n|------|------|\n| `HessianOperator` | 标准 Hessian 矩阵 |\n| `GGNOperator` | Generalized Gauss-Newton 近似 |\n| `DDPHessianOperator` | 分布式 DDP 环境下的 Hessian |\n| `KFACHessianOperator` | Kronecker-Factored Approximate Curvature |\n\n## 总结\n\n`DDPHessianOperator` 为 `hessian-eigenthings` 库提供了关键的分布式训练支持能力。通过继承统一的 `CurvatureOperator` 接口，它保持了与现有分析工具的兼容性，同时封装了 DDP 特有的分布式计算复杂性。这使得在大规模分布式训练环境中进行 Hessian 分析成为可能，为研究神经网络的收敛性、平坦性和泛化能力提供了有力工具。\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[项目简介](#page-project-intro)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [pyproject.toml](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/pyproject.toml)\n- [CONTRIBUTING.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/noahgolmant/pytorch-hessian-eigenthings/blob/main/README.md)\n \n\n# 安装与配置\n\n## 概述\n\n`pytorch-hessian-eigenthings` 是一个用于计算 Hessian 矩阵特征分解的 PyTorch 库，支持 Lanczos 算法、随机幂迭代、Hutch++ trace 估计和随机 Lanczos quadrature 等高效算法。本节详细说明该库的安装方式、环境配置方法以及开发环境设置流程。\n\n## 系统要求\n\n### 依赖环境\n\n| 组件 | 要求 | 说明 |\n|------|------|------|\n| Python | ≥ 3.9 | 项目支持的最低 Python 版本 |\n| PyTorch | 兼容版本 | 核心依赖，提供自动微分和神经网络支持 |\n| uv | 最新版本 | 项目推荐的包管理工具 |\n\n资料来源：[CONTRIBUTING.md:1-5]()\n\n### 可选依赖\n\n| 额外功能 | 包名 | 用途 |\n|----------|------|------|\n| Transformers 支持 | `transformers` | 与 HuggingFace 模型集成 |\n| TransformerLens 支持 | `transformer-lens` | 分析 Transformer 架构 |\n| CurvLinOps 支持 | `curvlinops` | 外部对照库，用于测试验证 |\n| Triton | `triton` | CUDA 加速的 CE HVP 计算 |\n| mkdocs | - | 文档构建工具 |\n\n资料来源：[CONTRIBUTING.md:8]()\n\n## 安装方式\n\n### 方式一：从 PyPI 安装（稳定版）\n\n通过 pip 安装最新稳定版本：\n\n```bash\npip install hessian-eigenthings\n```\n\n> **注意**：当前版本为 v1.0.0a1（alpha 版本）。如需使用 0.x 版本的旧 API，请安装 `hessian-eigenthings==0.0.2`。\n\n资料来源：[README.md:16-18]()\n\n### 方式二：从源码安装（开发版）\n\n适合需要使用最新功能或进行二次开发的用户：\n\n```bash\ngit clone https://github.com/noahgolmant/pytorch-hessian-eigenthings\ncd pytorch-hessian-eigenthings\nuv sync --group dev --group docs --extra transformers --extra transformer-lens --extra curvlinops\n```\n\n#### 安装步骤详解\n\n```mermaid\ngraph TD\n A[克隆仓库] --> B[进入项目目录]\n B --> C[执行 uv sync]\n C --> D{检查额外依赖}\n D -->|需要 Transformers| E[安装 transformers 组]\n D -->|需要 TransformerLens| F[安装 transformer-lens 组]\n D -->|需要 CurvLinOps| G[安装 curvlinops 组]\n E --> H[环境就绪]\n F --> H\n G --> H\n```\n\n1. **克隆仓库**：使用 git 获取最新源码\n2. **进入目录**：切换到项目根目录\n3. **同步依赖**：uv 自动解析 `pyproject.toml` 并安装所有依赖\n\n资料来源：[CONTRIBUTING.md:1-9]()\n\n## 开发环境配置\n\n### 代码质量检查工具\n\n项目使用以下工具确保代码质量：\n\n| 工具 | 用途 | 命令 |\n|------|------|------|\n| ruff | 代码检查与格式化 | `uv run ruff check .` |\n| black | 代码格式化检查 | `uv run black --check .` |\n| mypy | 类型检查 | `uv run mypy` |\n| pytest | 单元测试 | `uv run pytest` |\n| mkdocs | 文档构建 | `uv run mkdocs build --strict` |\n\n### 提交前检查流程\n\n在提交 Pull Request 之前，必须运行以下检查确保代码符合项目规范：\n\n```mermaid\ngraph LR\n A[修改代码] --> B[运行 ruff check]\n B --> C[运行 black]\n C --> D[运行 mypy]\n D --> E[运行 pytest]\n E --> F[构建文档]\n F --> G{所有检查通过}\n G -->|是| H[提交 PR]\n G -->|否| I[修复问题]\n I --> B\n```\n\n具体执行命令：\n\n```bash\n# 代码风格检查\nuv run ruff check .\n\n# 代码格式化验证\nuv run black --check .\n\n# 类型检查\nuv run mypy\n\n# 运行测试套件\nuv run pytest\n\n# 构建文档\nuv run mkdocs build --strict\n```\n\n> **提示**：如果本地调试，lint 任务（ruff 和 black）的成本最低，建议优先运行这些检查。\n\n资料来源：[CONTRIBUTING.md:11-17]()\n\n## CUDA 加速配置（可选）\n\n### Triton 加速\n\n对于需要处理大规模语言模型的场景，建议安装 Triton 以获得更好的性能：\n\n```bash\npip install triton\n```\n\n启用后的性能提升：\n- **速度提升**：约 3.4 倍\n- **峰值内存减少**：约 50%\n\nTriton kernel 在 CUDA 环境下自动检测并使用，无需手动配置。\n\n### torch.compile 备选方案\n\n如果 Triton 不可用，库会自动回退到 `torch.compile` 模式：\n\n- **速度提升**：约 2.6 倍\n- **峰值内存减少**：约 50%\n\n支持 CPU/CUDA/MPS 平台。\n\n资料来源：[hessian_eigenthings/loss_fns/huggingface.py:10-15]()\n\n## 验证安装\n\n安装完成后，可通过以下方式验证：\n\n```python\nimport torch\nfrom hessian_eigenthings import HessianOperator, lanczos\n\n# 创建简单模型\nmodel = torch.nn.Linear(10, 2)\n\n# 创建测试数据\nx = torch.randn(5, 10)\ny = torch.tensor([0, 1, 0, 1, 0])\n\n# 定义损失函数\nloss_fn = torch.nn.functional.cross_entropy\n\n# 创建 Hessian 算子\nhessian_op = HessianOperator(\n model=model,\n dataloader=[(x, y)],\n loss_fn=loss_fn\n)\n\n# 计算 top-3 特征值\neigenvals = lanczos(hessian_op, k=3, max_iter=20)\nprint(f\"Top eigenvalues: {eigenvals.eigenvalues}\")\n```\n\n如果输出正确的特征值，说明安装成功。\n\n## 常见问题\n\n### 问题一：uv 命令未找到\n\n**解决方案**：先安装 uv\n\n```bash\npip install uv\n```\n\n### 问题二：torch 版本不兼容\n\n**解决方案**：确保 PyTorch 版本 ≥ 1.12.0，建议使用最新稳定版：\n\n```bash\npip install --upgrade torch\n```\n\n### 问题三：CUDA 内存不足\n\n**解决方案**：\n1. 减小 batch size\n2. 使用 `method=\"finite_difference\"` 替代 `\"autograd\"`\n3. 考虑使用 GGNOperator 替代 HessianOperator\n\n资料来源：[hessian_eigenthings/operators/hessian.py:10-20]()\n\n## 快速开始清单\n\n| 步骤 | 任务 | 状态 |\n|------|------|------|\n| 1 | 安装 Python ≥ 3.9 | ☐ |\n| 2 | 安装 uv 包管理器 | ☐ |\n| 3 | 克隆或安装 hessian-eigenthings | ☐ |\n| 4 | （可选）安装额外依赖 | ☐ |\n| 5 | 验证安装（运行示例代码） | ☐ |\n| 6 | （开发者）配置 pre-commit 钩子 | ☐ |\n\n## 相关文档\n\n- [快速开始指南](./quickstart.md)\n- [Hessian 算子 API 参考](../api/operators/hessian.md)\n- [Lanczos 算法文档](../concepts/lanczos-algorithm.md)\n- [贡献指南](../community/contributing.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：noahgolmant/pytorch-hessian-eigenthings\n\n摘要：发现 15 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `pytorch-hessian-eigenthings` 与安装入口 `hessian-eigenthings` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`pip install hessian-eigenthings`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | repo=pytorch-hessian-eigenthings; install=hessian-eigenthings\n\n## 2. 安装坑 · 来源证据：Python Error: the following arguments are required: experimentname\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Python Error: the following arguments are required: experimentname\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_24f46464d79f4ae3830f046c077a2574 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/39 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：v1.0.0a2 — packaging fix\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.0a2 — packaging fix\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7540a696b30c46cdba07c12f33388567 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：v1.0.0a3 — fix lanczos OOM\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.0a3 — fix lanczos OOM\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e5e68e2f24e1436cb8f3c2f11cefe326 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：v1.0.0a4 — backend handles CPU-generator + CUDA-tensor combo\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.0a4 — backend handles CPU-generator + CUDA-tensor combo\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_914b7653aa8b4ef2844a2b4690fab2ad | https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：v1.0.0a5 — comprehensive LLM-scale memory fixes + regression tests\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.0a5 — comprehensive LLM-scale memory fixes + regression tests\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_509356ab9b68434992d7237219952ba6 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 配置坑 · 来源证据：RuntimeError: One of the differentiated Tensors appears to not have been used in the graph.\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：RuntimeError: One of the differentiated Tensors appears to not have been used in the graph.\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f79a3a34cbab435cb3730b7ae17cf492 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/30 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 配置坑 · 来源证据：ValueError: PENet on the Kitti benchmark suite\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：ValueError: PENet on the Kitti benchmark suite\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_850f8cf0010c4d269ab71d864610097a | https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/41 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | README/documentation is current enough for a first validation pass.\n\n## 10. 运行坑 · 来源证据：AttributeError: 'HVPOperator' object has no attribute 'zero_grad'\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：AttributeError: 'HVPOperator' object has no attribute 'zero_grad'\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b515f5c06a5744b19b667bcbc8123348 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/38 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | no_demo; severity=medium\n\n## 14. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | issue_or_pr_quality=unknown\n\n## 15. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：noahgolmant/pytorch-hessian-eigenthings\n\n摘要：发现 15 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `pytorch-hessian-eigenthings` 与安装入口 `hessian-eigenthings` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`pip install hessian-eigenthings`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | repo=pytorch-hessian-eigenthings; install=hessian-eigenthings\n\n## 2. 安装坑 · 来源证据：Python Error: the following arguments are required: experimentname\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Python Error: the following arguments are required: experimentname\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_24f46464d79f4ae3830f046c077a2574 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/39 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：v1.0.0a2 — packaging fix\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.0a2 — packaging fix\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7540a696b30c46cdba07c12f33388567 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：v1.0.0a3 — fix lanczos OOM\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.0a3 — fix lanczos OOM\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e5e68e2f24e1436cb8f3c2f11cefe326 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：v1.0.0a4 — backend handles CPU-generator + CUDA-tensor combo\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.0a4 — backend handles CPU-generator + CUDA-tensor combo\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_914b7653aa8b4ef2844a2b4690fab2ad | https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：v1.0.0a5 — comprehensive LLM-scale memory fixes + regression tests\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.0a5 — comprehensive LLM-scale memory fixes + regression tests\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_509356ab9b68434992d7237219952ba6 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/releases/tag/v1.0.0a5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 配置坑 · 来源证据：RuntimeError: One of the differentiated Tensors appears to not have been used in the graph.\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：RuntimeError: One of the differentiated Tensors appears to not have been used in the graph.\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f79a3a34cbab435cb3730b7ae17cf492 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/30 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 配置坑 · 来源证据：ValueError: PENet on the Kitti benchmark suite\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：ValueError: PENet on the Kitti benchmark suite\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_850f8cf0010c4d269ab71d864610097a | https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/41 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | README/documentation is current enough for a first validation pass.\n\n## 10. 运行坑 · 来源证据：AttributeError: 'HVPOperator' object has no attribute 'zero_grad'\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：AttributeError: 'HVPOperator' object has no attribute 'zero_grad'\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b515f5c06a5744b19b667bcbc8123348 | https://github.com/noahgolmant/pytorch-hessian-eigenthings/issues/38 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | no_demo; severity=medium\n\n## 14. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | issue_or_pr_quality=unknown\n\n## 15. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | hn_item:48132232 | https://news.ycombinator.com/item?id=48132232 | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# pytorch-hessian-eigenthings - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 pytorch-hessian-eigenthings 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: pytorch-hessian-eigenthings 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-project-intro：项目简介。围绕“项目简介”模拟一次用户任务，不展示安装或运行结果。\n2. page-hessian-basics：Hessian 矩阵基础概念。围绕“Hessian 矩阵基础概念”模拟一次用户任务，不展示安装或运行结果。\n3. page-core-architecture：核心架构设计。围绕“核心架构设计”模拟一次用户任务，不展示安装或运行结果。\n4. page-operators：曲率算子详解。围绕“曲率算子详解”模拟一次用户任务，不展示安装或运行结果。\n5. page-algorithms：特征分解算法。围绕“特征分解算法”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-project-intro\n输入：用户提供的“项目简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-hessian-basics\n输入：用户提供的“Hessian 矩阵基础概念”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-core-architecture\n输入：用户提供的“核心架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-operators\n输入：用户提供的“曲率算子详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-algorithms\n输入：用户提供的“特征分解算法”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-project-intro：Step 1 必须围绕“项目简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-hessian-basics：Step 2 必须围绕“Hessian 矩阵基础概念”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-core-architecture：Step 3 必须围绕“核心架构设计”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-operators：Step 4 必须围绕“曲率算子详解”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-algorithms：Step 5 必须围绕“特征分解算法”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://news.ycombinator.com/item?id=48132232\n- https://github.com/noahgolmant/pytorch-hessian-eigenthings#readme\n- README.md\n- mkdocs.yml\n- pyproject.toml\n- docs/concepts/what-is-the-hessian.md\n- docs/concepts/why-hvp-not-full-h.md\n- hessian_eigenthings/__init__.py\n- hessian_eigenthings/operators/base.py\n- hessian_eigenthings/batching.py\n- hessian_eigenthings/linalg/backend.py\n- hessian_eigenthings/operators/__init__.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 pytorch-hessian-eigenthings 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：noahgolmant/pytorch-hessian-eigenthings\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install hessian-eigenthings\n```\n\n来源：https://github.com/noahgolmant/pytorch-hessian-eigenthings#readme\n\n## 来源\n\n- hn: https://news.ycombinator.com/item?id=48132232\n- docs: https://github.com/noahgolmant/pytorch-hessian-eigenthings#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_8a294b814b3b4037a843c14c510c47df"
}