kvcache-fa-precision-debug

Diagnose precision issues from KVCache writes and Flash Attention fusion operators.

Updated Apr 11, 2026
One-click install
npx skills add https://github.com/tuliang1024/cann-recipes-infer --skill kvcache-fa-precision-debug
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: kvcache-fa-precision-debug
Source: https://github.com/tuliang1024/cann-recipes-infer/tree/main/.agent/skills/kvcache-fa-precision-debug
Command: npx skills add https://github.com/tuliang1024/cann-recipes-infer --skill kvcache-fa-precision-debug

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

KVCache 与 FA 精度调试技能。诊断 KVCache 写入和 Flash Attention 融合算子引入的精度问题,提供系统化的排查流程和常见问题修复方案。触发场景包括:KVCache/FA 替换后精度验证未通过、模型输出与基线存在显著偏差、Prefill 和 Decode 精度表现不一致、出现 NaN/Inf、量化模式下精度放大等。

Core Features & Use Cases

  • 系统化排查流程:按症状分类、快速诊断、分模块定位、精细对比
  • 模块级定位:Prefill/Decode、KVCache 写入、FA 计算与后处理的分层排查
  • 产出调试报告:问题概要、根因分析、修复措施、修复验证、遗留风险

Quick Start

在目标模型上运行 KVCache-FA 精度诊断工作流,以复现并修复精度差异。

Frequently Asked Questions about kvcache-fa-precision-debug

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug Flash Attention precision issues after replacing KVCache in model inference?

Debug Flash Attention precision issues by systematically comparing baseline and optimized outputs, isolating Prefill and Decode misalignment, and validating FA invocation parameters like atten_mask and actual_seq_lengths to locate root causes.

Why does my model output NaN or Inf values after integrating Flash Attention operators?

NaN or Inf values during inference often stem from KVCache writes or FA fusion operator discrepancies; diagnose by checking block_table configurations, kv_len, and sparse_mode settings against baseline tensor comparisons.

How do I fix Prefill and Decode precision inconsistencies in KVCache implementations?

Fix Prefill and Decode precision inconsistencies by performing module-level isolation to compare FA computations and post-processing steps, ensuring actual_seq_lengths and kv_len parameters align across both inference phases.

Can I diagnose KVCache precision problems in multi-device inference setups?

Yes, KVCache precision debugging supports both single-device and multi-device setups, validating atten_mask, block_table, and actual_seq_lengths across distributed configurations to resolve discrepancies between baseline and optimized outputs.

What causes exaggerated precision changes under quantization with Flash Attention fusion?

Exaggerated precision changes under quantization typically arise from FA fusion operator mismatches; diagnose by validating FA invocation parameters and comparing quantized tensor outputs against baseline to isolate the affected modules.

What parameters should I validate when Flash Attention precision verification fails?

Validate FA invocation parameters including atten_mask, sparse_mode, actual_seq_lengths, kv_len, and block_table, then compare optimized outputs against baseline tensors to systematically isolate the precision failure root cause.