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.