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
« 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."""
17from collections.abc import Sequence
18from contextlib import contextmanager
19from dataclasses import dataclass
20import inspect
21import random
22from typing import Any, Iterator, Optional
24import torch
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
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()
46@dataclass
47class CodegenModelBuildResult:
48 """Result populated by one scoped offline model observation."""
50 artifact_layout: Optional[Any] = None
51 snapshot: Optional[Any] = None
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
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 })
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
100 def _observe_compile(*args: Any, **kwargs: Any) -> Any:
101 plan = original_compile(*args, **kwargs)
102 specs[:] = plan.specs
103 return plan
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
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
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
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
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
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)
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()
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)
227 return session.finish(_publish)
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
325 return _build_model
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
346__all__ = ["CodegenModelBuildResult", "use_codegen_model_build_overlay"]