Coverage for  / home / jenkins / .local / lib / python3.10 / site-packages / hyper_parallel / components / functional / kimi_delta_attention_fla_adapter.py: 42%

98 statements  

« prev     ^ index     » next       coverage.py v7.13.1, created at 2026-11-19 05:29 +0800

1# Copyright 2026 Huawei Technologies Co., Ltd 

2# 

3# Licensed under the Apache License, Version 2.0 (the "License"); 

4# you may not use this file except in compliance with the License. 

5# You may obtain a copy of the License at 

6# 

7# http://www.apache.org/licenses/LICENSE-2.0 

8# 

9# Unless required by applicable law or agreed to in writing, software 

10# distributed under the License is distributed on an "AS IS" BASIS, 

11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 

12# See the License for the specific language governing permissions and 

13# limitations under the License. 

14# ============================================================================ 

15"""Lazy adapter for the external FLA Triton-Ascend KDA backend.""" 

16from __future__ import annotations 

17 

18 

19__all__ = [ 

20 "FLAKDAStagedOps", 

21 "get_fla_kda_staged_ops", 

22 "is_fla_triton_kda_available", 

23 "run_fla_chunk_kda", 

24] 

25 

26import importlib 

27import importlib.util 

28import re 

29from dataclasses import dataclass 

30from functools import lru_cache 

31from typing import Any, Callable, Optional 

32 

33import torch 

34 

35 

36_MIN_FLA_VERSION = (0, 6, 0) 

37 

38 

39@dataclass(frozen=True) 

40class FLAKDAStagedOps: 

41 """FLA operators required around Hyper's affine state summary.""" 

42 

43 l2norm_fwd: Callable[..., Any] 

44 l2norm_bwd: Callable[..., Any] 

45 fused_beta_sigmoid: Callable[..., Any] 

46 fused_beta_sigmoid_bwd: Callable[..., Any] 

47 kda_gate_chunk_cumsum: Callable[..., Any] 

48 kda_gate_bwd: Callable[..., Any] 

49 chunk_kda_fwd_intra: Callable[..., Any] 

50 recompute_w_u_fwd: Callable[..., Any] 

51 chunk_gated_delta_rule_fwd_h: Callable[..., Any] 

52 chunk_gla_fwd_o_gk: Callable[..., Any] 

53 chunk_kda_bwd_dav: Callable[..., Any] 

54 chunk_gated_delta_rule_bwd_dhu: Callable[..., Any] 

55 chunk_kda_bwd_wy_dqkg_fused: Callable[..., Any] 

56 chunk_kda_bwd_intra: Callable[..., Any] 

57 chunk_local_cumsum: Callable[..., Any] 

58 

59 

60@dataclass(frozen=True) 

61class _FLAKDARuntime: 

62 """Resolved external FLA runtime and its required KDA entry points.""" 

63 

64 version: str 

65 chunk_kda: Callable[..., Any] 

66 staged: FLAKDAStagedOps 

67 

68 

69def _get_attribute(module_name: str, attribute: str) -> Any: 

70 """Import one required FLA symbol with a useful compatibility error.""" 

71 try: 

72 module = importlib.import_module(module_name) 

73 except ModuleNotFoundError as exc: 

74 missing_name = getattr(exc, "name", None) 

75 is_fla_module = ( 

76 missing_name is not None and str(missing_name).startswith("fla.") 

77 ) 

78 if missing_name == module_name or is_fla_module: 

79 raise RuntimeError( 

80 "The installed FLA package is incompatible with Hyper KDA: " 

81 f"missing module {module_name}." 

82 ) from exc 

83 raise RuntimeError( 

84 f"FLA module {module_name} could not load runtime dependency " 

85 f"{missing_name!r}." 

86 ) from exc 

87 except ImportError as exc: 

88 raise RuntimeError( 

89 f"FLA module {module_name} failed to import; inspect the chained " 

90 "exception for the incompatible runtime library." 

91 ) from exc 

92 try: 

93 return getattr(module, attribute) 

94 except AttributeError as exc: 

95 raise RuntimeError( 

96 "The installed FLA package is incompatible with Hyper KDA: " 

97 f"missing {module_name}.{attribute}. Install an FLA revision with " 

98 "the Triton-Ascend KDA backend." 

99 ) from exc 

100 

101 

102def _parse_version(version: str) -> tuple[int, int, int]: 

103 """Parse the numeric prefix of an FLA semantic version.""" 

104 match = re.match(r"^(\d+)\.(\d+)\.(\d+)", version) 

105 if match is None: 

106 raise RuntimeError(f"Unable to parse the installed FLA version {version!r}.") 

107 return tuple(int(part) for part in match.groups()) 

108 

109 

110def _require_triton_ascend() -> None: 

111 """Require the external FLA runtime to have a Triton Ascend backend.""" 

112 try: 

113 importlib.import_module("triton") 

114 ascend_backend = importlib.util.find_spec("triton.backends.ascend") 

115 except (ImportError, ModuleNotFoundError) as exc: 

116 raise RuntimeError( 

117 "KDA backend='triton' requires Triton-Ascend in the runtime environment." 

118 ) from exc 

119 if ascend_backend is None: 

120 raise RuntimeError( 

121 "KDA backend='triton' found Triton, but its Ascend backend is missing." 

122 ) 

123 

124 

125def _require_npu_backends() -> None: 

126 """Verify that FLA registered every backend used by the staged P2P path.""" 

127 backend_specs = ( 

128 ( 

129 "fla.ops.kda.backends.triton_ascend", 

130 "TritonAscendKDABackend", 

131 ), 

132 ( 

133 "fla.ops.common.backends.triton_ascend", 

134 "TritonAscendCommonBackend", 

135 ), 

136 ( 

137 "fla.ops.gla.backends.triton_ascend", 

138 "TritonAscendGLABackend", 

139 ), 

140 ) 

141 for module_name, class_name in backend_specs: 

142 backend = _get_attribute(module_name, class_name) 

143 if not backend.is_available(): 

144 raise RuntimeError( 

145 "KDA backend='triton' requires FLA's Triton-Ascend backend " 

146 f"{class_name}, but it is unavailable in this process." 

147 ) 

148 

149 

150@lru_cache(maxsize=1) 

151def _require_fla_kda_runtime() -> _FLAKDARuntime: 

152 """Resolve and validate the optional external FLA dependency once.""" 

153 try: 

154 fla = importlib.import_module("fla") 

155 except ModuleNotFoundError as exc: 

156 missing_name = getattr(exc, "name", None) 

157 if missing_name != "fla": 

158 raise RuntimeError( 

159 "The external FLA package is present but cannot load runtime " 

160 f"dependency {missing_name!r}." 

161 ) from exc 

162 raise RuntimeError( 

163 "KDA backend='triton' requires the optional flash-linear-attention " 

164 "package with its Triton-Ascend KDA backend." 

165 ) from exc 

166 except ImportError as exc: 

167 raise RuntimeError( 

168 "The external FLA package is present but failed to import; inspect " 

169 "the chained exception for the incompatible runtime library." 

170 ) from exc 

171 

172 version = getattr(fla, "__version__", None) 

173 if not isinstance(version, str): 

174 raise RuntimeError("The installed FLA package does not expose __version__.") 

175 if _parse_version(version) < _MIN_FLA_VERSION: 

176 minimum = ".".join(str(part) for part in _MIN_FLA_VERSION) 

177 raise RuntimeError( 

178 f"KDA backend='triton' requires FLA >= {minimum}, got {version}." 

179 ) 

180 

181 _require_triton_ascend() 

182 _require_npu_backends() 

183 staged = FLAKDAStagedOps( 

184 l2norm_fwd=_get_attribute("fla.modules.l2norm", "l2norm_fwd"), 

185 l2norm_bwd=_get_attribute("fla.modules.l2norm", "l2norm_bwd"), 

186 fused_beta_sigmoid=_get_attribute( 

187 "fla.ops.common.gate", "fused_beta_sigmoid" 

188 ), 

189 fused_beta_sigmoid_bwd=_get_attribute( 

190 "fla.ops.common.gate", "fused_beta_sigmoid_bwd" 

191 ), 

192 kda_gate_chunk_cumsum=_get_attribute( 

193 "fla.ops.kda.gate", "kda_gate_chunk_cumsum" 

194 ), 

195 kda_gate_bwd=_get_attribute("fla.ops.kda.gate", "kda_gate_bwd"), 

196 chunk_kda_fwd_intra=_get_attribute( 

197 "fla.ops.kda.chunk_intra", "chunk_kda_fwd_intra" 

198 ), 

199 recompute_w_u_fwd=_get_attribute( 

200 "fla.ops.kda.wy_fast", "recompute_w_u_fwd" 

201 ), 

202 chunk_gated_delta_rule_fwd_h=_get_attribute( 

203 "fla.ops.common.chunk_delta_h", "chunk_gated_delta_rule_fwd_h" 

204 ), 

205 chunk_gla_fwd_o_gk=_get_attribute( 

206 "fla.ops.gla.chunk", "chunk_gla_fwd_o_gk" 

207 ), 

208 chunk_kda_bwd_dav=_get_attribute( 

209 "fla.ops.kda.chunk_bwd", "chunk_kda_bwd_dAv" 

210 ), 

211 chunk_gated_delta_rule_bwd_dhu=_get_attribute( 

212 "fla.ops.common.chunk_delta_h", "chunk_gated_delta_rule_bwd_dhu" 

213 ), 

214 chunk_kda_bwd_wy_dqkg_fused=_get_attribute( 

215 "fla.ops.kda.chunk_bwd", "chunk_kda_bwd_wy_dqkg_fused" 

216 ), 

217 chunk_kda_bwd_intra=_get_attribute( 

218 "fla.ops.kda.chunk_intra", "chunk_kda_bwd_intra" 

219 ), 

220 chunk_local_cumsum=_get_attribute( 

221 "fla.ops.utils.cumsum", "chunk_local_cumsum" 

222 ), 

223 ) 

224 return _FLAKDARuntime( 

225 version=version, 

226 chunk_kda=_get_attribute("fla.ops.kda", "chunk_kda"), 

227 staged=staged, 

228 ) 

229 

230 

231def is_fla_triton_kda_available() -> bool: 

232 """Return whether the optional external FLA KDA backend is usable.""" 

233 try: 

234 _require_fla_kda_runtime() 

235 except RuntimeError: 

236 return False 

237 return True 

238 

239 

240def get_fla_kda_staged_ops() -> FLAKDAStagedOps: 

241 """Return FLA staged operators for Hyper's state-P2P autograd function.""" 

242 return _require_fla_kda_runtime().staged 

243 

244 

245def run_fla_chunk_kda( 

246 query: torch.Tensor, 

247 key: torch.Tensor, 

248 value: torch.Tensor, 

249 gate: torch.Tensor, 

250 beta: torch.Tensor, 

251 *, 

252 a_log: torch.Tensor, 

253 dt_bias: torch.Tensor, 

254 scale: Optional[float] = None, 

255 initial_state: Optional[torch.Tensor] = None, 

256 output_final_state: bool = False, 

257 lower_bound: float = -5.0, 

258 chunk_size: int = 64, 

259 safe_gate: bool = True, 

260 cu_seqlens: Optional[torch.Tensor] = None, 

261) -> tuple[torch.Tensor, Optional[torch.Tensor]]: 

262 """Run FLA's public KDA API with the validated Kimi K3 fused contract.""" 

263 runtime = _require_fla_kda_runtime() 

264 return runtime.chunk_kda( 

265 q=query, 

266 k=key, 

267 v=value, 

268 g=gate, 

269 beta=beta, 

270 A_log=a_log, 

271 dt_bias=dt_bias, 

272 scale=scale, 

273 initial_state=initial_state, 

274 output_final_state=output_final_state, 

275 use_qk_l2norm_in_kernel=True, 

276 use_gate_in_kernel=True, 

277 use_beta_sigmoid_in_kernel=True, 

278 safe_gate=safe_gate, 

279 lower_bound=lower_bound, 

280 chunk_size=chunk_size, 

281 cu_seqlens=cu_seqlens, 

282 )