Coverage for  / home / jenkins / .local / lib / python3.10 / site-packages / hyper_parallel / codegen / model_build_overlay.py: 98%

145 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"""Codegen-owned model observation layered over the native AutoModel API.""" 

16 

17from collections.abc import Sequence 

18from contextlib import contextmanager 

19from dataclasses import dataclass 

20import inspect 

21import random 

22from typing import Any, Iterator, Optional 

23 

24import torch 

25 

26from hyper_parallel.codegen.manager import ensure_codegen_artifact_from_snapshot 

27from hyper_parallel.codegen.session import CodegenBuildSession 

28from hyper_parallel.core.dtensor.init_weights import init_empty_weights 

29from hyper_parallel.distributed._builder.applier import ( 

30 _get_active_mesh, 

31 _preflight_compute_injection, 

32) 

33from hyper_parallel.models._transformers import auto_model, model_builder 

34from hyper_parallel.models import module_build, replacement as replacement_api 

35 

36 

37def _prepare_model_source_compat(adapter: Any) -> None: 

38 """Run an optional model-owned compatibility hook before construction.""" 

39 loader = getattr(adapter, "codegen", None) if adapter is not None else None 

40 provider = loader() if loader is not None else None 

41 prepare = getattr(provider, "prepare_model_import", None) 

42 if prepare is not None: 

43 prepare() 

44 

45 

46@dataclass 

47class CodegenModelBuildResult: 

48 """Result populated by one scoped offline model observation.""" 

49 

50 artifact_layout: Optional[Any] = None 

51 snapshot: Optional[Any] = None 

52 

53 

54@contextmanager 

55def _codegen_model_init_context() -> Iterator[None]: 

56 """Build codegen's observation model with parameters and buffers on meta.""" 

57 with init_empty_weights(include_buffers=True), auto_model._model_init_context( # pylint: disable=protected-access 

58 True 

59 ): 

60 yield 

61 

62 

63def _record_source( 

64 session: CodegenBuildSession, 

65 model: Any, 

66 hf_config: Any, 

67 pretrained_model_name_or_path: Any, 

68 is_hf_model: bool, 

69) -> None: 

70 """Record deterministic source identity from the constructed meta model.""" 

71 model_type = type(model) 

72 source_path = inspect.getsourcefile(model_type) 

73 architectures = list(getattr(hf_config, "architectures", None) or ()) 

74 architecture = architectures[0] if architectures else model_type.__name__ 

75 session.record_source({ 

76 "model_type": getattr(hf_config, "model_type", None), 

77 "architecture": architecture, 

78 "architectures": architectures, 

79 "model_class": f"{model_type.__module__}:{model_type.__qualname__}", 

80 "module_name": model_type.__module__, 

81 "file_path": source_path, 

82 "pretrained_model_name_or_path": ( 

83 None if pretrained_model_name_or_path is None else str(pretrained_model_name_or_path) 

84 ), 

85 "is_hf_model": bool(is_hf_model), 

86 }) 

87 

88 

89def _observe_replacements( 

90 model: Any, 

91 distributed_setup: Any, 

92 low_precision_config: Any, 

93 load_base_model: bool, 

94 session: CodegenBuildSession, 

95) -> Any: 

96 """Apply native replacement declarations while recording their result.""" 

97 specs = list(getattr(distributed_setup, "module_replacements", None) or ()) 

98 original_compile = module_build.compile_module_replacements 

99 

100 def _observe_compile(*args: Any, **kwargs: Any) -> Any: 

101 plan = original_compile(*args, **kwargs) 

102 specs[:] = plan.specs 

103 return plan 

104 

105 module_build.compile_module_replacements = _observe_compile 

106 try: 

107 with _observe_replacement_installations(specs) as applications: 

108 model, _ = model_builder._maybe_apply_module_replacements( # pylint: disable=protected-access 

109 model, distributed_setup, low_precision_config, load_base_model, 

110 ) 

111 except replacement_api.ModuleReplacementMatchError as exc: 

112 session.record_replacements( 

113 declarations=replacement_api.describe_replacement_declarations(specs), 

114 applications=(), unmatched=exc.unmatched, 

115 ) 

116 raise 

117 finally: 

118 module_build.compile_module_replacements = original_compile 

119 session.record_replacements( 

120 declarations=replacement_api.describe_replacement_declarations(specs), 

121 applications=applications, unmatched=(), 

122 ) 

123 return model 

124 

125 

126@contextmanager 

127def _observe_replacement_installations(specs: Sequence[Any]) -> Iterator[list[dict[str, Any]]]: 

128 """Record metadata only after the shared installer commits a prepared candidate.""" 

129 applications: list[dict[str, Any]] = [] 

130 spec_indexes = {id(spec): index for index, spec in enumerate(specs)} 

131 pending = {} 

132 original_prepare = replacement_api._prepare_replacement_target # pylint: disable=protected-access 

133 original_install = replacement_api._install_module_candidates # pylint: disable=protected-access 

134 

135 def _observe_prepare(target: Any, *args: Any, **kwargs: Any) -> Any: 

136 candidate, transforms = original_prepare(target, *args, **kwargs) 

137 if id(target.spec) not in spec_indexes: 

138 spec_indexes.update({id(spec): index for index, spec in enumerate(specs)}) 

139 index = spec_indexes.setdefault(id(target.spec), len(spec_indexes)) 

140 pending[(target.module_fqns, id(candidate))] = { 

141 "rule_id": replacement_api._replacement_rule_id(target.spec, index), # pylint: disable=protected-access 

142 "module_fqns": list(target.module_fqns), 

143 "primary_fqn": target.module_fqns[0], 

144 "source_type": replacement_api._symbol_path(type(target.source)), 

145 "replacement_type": replacement_api._symbol_path(type(candidate)), 

146 "weight_transforms": [replacement_api._symbol_path(type(transform)) for transform in transforms], 

147 } 

148 return candidate, transforms 

149 

150 def _observe_install(root: Any, candidates: Any) -> Any: 

151 candidates = tuple(candidates) 

152 result = original_install(root, candidates) 

153 for fqns, _, candidate in candidates: 

154 record = pending.pop((fqns, id(candidate)), None) 

155 if record is not None: 

156 applications.append(record) 

157 return result 

158 

159 replacement_api._prepare_replacement_target = _observe_prepare # pylint: disable=protected-access 

160 replacement_api._install_module_candidates = _observe_install # pylint: disable=protected-access 

161 try: 

162 yield applications 

163 finally: 

164 replacement_api._prepare_replacement_target = original_prepare # pylint: disable=protected-access 

165 replacement_api._install_module_candidates = original_install # pylint: disable=protected-access 

166 

167 

168def _observe_plan( 

169 model: Any, 

170 mesh: Any, 

171 sharding_planner: Any, 

172 is_hf_model: bool, 

173 session: CodegenBuildSession, 

174) -> None: 

175 """Derive a native plan without applying distributed runtime operations.""" 

176 model_sharding_requested = ( 

177 mesh is not None 

178 and any(size > 1 for size in (mesh.tp_size, mesh.cp_size, mesh.ep_size)) 

179 ) 

180 if sharding_planner is None: 

181 session.mark_not_required("planner_unavailable") 

182 return 

183 if mesh is None: 

184 session.mark_not_required("mesh_unavailable") 

185 return 

186 if mesh.device_mesh is None: 

187 session.mark_not_required("device_mesh_unavailable") 

188 return 

189 if (is_hf_model and not model_sharding_requested 

190 and not model_builder._has_module_owned_layouts(model)): # pylint: disable=protected-access 

191 if session.has_replacement_applications: 

192 session.observe_plan(None, None, mesh) 

193 else: 

194 session.mark_not_required("pure_data_parallel") 

195 return 

196 plan = sharding_planner.plan( 

197 model, 

198 mesh.device_mesh, 

199 tp_size=mesh.tp_size, 

200 cp_size=mesh.cp_size, 

201 ep_size=mesh.ep_size, 

202 sequence_parallel=mesh.sequence_parallel, 

203 loss_parallel=mesh.loss_parallel, 

204 ) 

205 active_mesh = _get_active_mesh(mesh.device_mesh, plan.mesh_dim_names) 

206 _preflight_compute_injection(plan, active_mesh, model=model) 

207 session.observe_plan(plan, model, mesh) 

208 

209 

210def _publish_session( 

211 session: CodegenBuildSession, 

212 artifact_dir: Optional[str], 

213 result: CodegenModelBuildResult, 

214) -> Any: 

215 """Publish an offline snapshot while preserving host RNG state.""" 

216 cpu_rng_state = torch.get_rng_state() 

217 python_rng_state = random.getstate() 

218 

219 def _publish(snapshot: Any) -> None: 

220 """Publish one snapshot and restore RNG state afterward.""" 

221 try: 

222 result.artifact_layout = ensure_codegen_artifact_from_snapshot(snapshot, artifact_dir) 

223 finally: 

224 torch.set_rng_state(cpu_rng_state) 

225 random.setstate(python_rng_state) 

226 

227 return session.finish(_publish) 

228 

229 

230def _codegen_build_model(session: CodegenBuildSession, artifact_dir: Optional[str], result: CodegenModelBuildResult): 

231 """Create the classmethod used only while the CLI constructs a meta model.""" 

232 def _build_model( 

233 cls, 

234 pretrained_model_name_or_path, 

235 *model_args, 

236 is_hf_model, 

237 hf_config, 

238 mesh, 

239 sharding_planner, 

240 fsdp2_manager, 

241 peft_config, 

242 torch_dtype, 

243 attn_implementation, 

244 validate_placement, 

245 load_base_model, 

246 distributed_setup=None, 

247 qat_config=None, 

248 fp8_config=None, 

249 compile_config=None, 

250 freeze_config=None, 

251 activation_checkpoint=None, 

252 activation_checkpoint_selection=None, 

253 swap_inputs=False, 

254 allow_cache_entry_mutation=False, 

255 activation_swap="none", 

256 model_init_dtype=None, 

257 **kwargs, 

258 ) -> Any: 

259 """Construct and observe a meta model without runtime infrastructure.""" 

260 del ( 

261 fsdp2_manager, 

262 validate_placement, 

263 compile_config, 

264 activation_checkpoint, 

265 activation_checkpoint_selection, 

266 swap_inputs, 

267 allow_cache_entry_mutation, 

268 activation_swap, 

269 ) 

270 factory, context = auto_model._resolve_module_construction( # pylint: disable=protected-access 

271 kwargs, hf_config, distributed_setup, model_init_dtype or torch_dtype, 

272 ) 

273 init_kwargs = auto_model._model_init_kwargs( # pylint: disable=protected-access 

274 dict(kwargs), 

275 load_base_model=False, 

276 ) 

277 if "trust_remote_code" in kwargs: 

278 init_kwargs["trust_remote_code"] = kwargs["trust_remote_code"] 

279 _prepare_model_source_compat(context["model_spec"]) 

280 with _codegen_model_init_context(): 

281 if factory is not None: 

282 if model_args: 

283 raise ValueError("model_factory uses config and context, not additional positional model arguments") 

284 model = auto_model.construct_family_model(factory, hf_config, context=context) 

285 else: 

286 _, model = auto_model._init_model( # pylint: disable=protected-access 

287 cls, None, hf_config, attn_implementation, torch_dtype, is_hf_model, 

288 *model_args, **init_kwargs, 

289 ) 

290 auto_model.attach_build_context(model, context) 

291 _record_source( 

292 session, 

293 model, 

294 hf_config, 

295 pretrained_model_name_or_path, 

296 is_hf_model, 

297 ) 

298 model_builder._apply_pre_sharding_features( # pylint: disable=protected-access 

299 peft_config, 

300 qat_config, 

301 fp8_config, 

302 ) 

303 model = _observe_replacements( 

304 model, 

305 distributed_setup, 

306 getattr(distributed_setup, "low_precision_config", None), 

307 load_base_model, 

308 session, 

309 ) 

310 if freeze_config is not None: 

311 model_builder._apply_parameter_freezing( # pylint: disable=protected-access 

312 model, 

313 freeze_config, 

314 ) 

315 model_builder._apply_model_method_replacements( # pylint: disable=protected-access 

316 model, distributed_setup, getattr(distributed_setup, "low_precision_config", None), 

317 ) 

318 _observe_plan(model, mesh, sharding_planner, is_hf_model, session) 

319 snapshot = _publish_session(session, artifact_dir, result) 

320 result.snapshot = snapshot 

321 model._hp_codegen_snapshot = snapshot # pylint: disable=protected-access 

322 model.train() 

323 return model 

324 

325 return _build_model 

326 

327 

328@contextmanager 

329def use_codegen_model_build_overlay( 

330 session: CodegenBuildSession, 

331 artifact_dir: Optional[str] = None, 

332) -> Iterator[CodegenModelBuildResult]: 

333 """Temporarily replace AutoModel's final build step for offline codegen.""" 

334 model_class = auto_model._BaseHyperAutoModelClass # pylint: disable=protected-access 

335 original = model_class.__dict__["_build_model"] 

336 result = CodegenModelBuildResult() 

337 model_class._build_model = classmethod( # pylint: disable=protected-access 

338 _codegen_build_model(session, artifact_dir, result) 

339 ) 

340 try: 

341 yield result 

342 finally: 

343 model_class._build_model = original # pylint: disable=protected-access 

344 

345 

346__all__ = ["CodegenModelBuildResult", "use_codegen_model_build_overlay"]