Add comprehensive knowledge base documentation across multiple domains

2026-02-12 14:36:37 +08:00
parent f754f6f383
commit 0fdd35bd78
8 changed files with 336 additions and 0 deletions
@@ -0,0 +1,33 @@
+# OPENGAIT RUNTIME KNOWLEDGE BASE
+
+## OVERVIEW
+`opengait/` is the runtime package: distributed launch entry, model lifecycle orchestration, data/evaluation integration.
+
+## STRUCTURE
+```text
+opengait/
+├── main.py         # DDP entrypoint + config load + model dispatch
+├── modeling/       # BaseModel + model/backbone/loss registries
+├── data/           # dataset parser + sampler/collate/transform
+├── evaluation/     # benchmark-specific evaluation functions
+└── utils/          # config merge, DDP passthrough, logging helpers
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| Start train/test flow | `main.py` | parses `--cfgs`/`--phase`, initializes DDP |
+| Resolve model name from YAML | `modeling/models/__init__.py` | class auto-registration via iter_modules |
+| Build full train loop | `modeling/base_model.py` | loaders, optimizer/scheduler, ckpt, inference |
+| Merge config with defaults | `utils/common.py::config_loader` | overlays onto `configs/default.yaml` |
+| Shared logging | `utils/msg_manager.py` | global message manager |
+
+## CONVENTIONS
+- Imports are package-relative-at-runtime (`from modeling...`, `from data...`, `from utils...`) because `opengait/main.py` is launched as script target.
+- Runtime is DDP-first; non-DDP assumptions are usually invalid.
+- Losses and models are configured by names, not direct imports in `main.py`.
+
+## ANTI-PATTERNS
+- Don’t bypass `config_loader`; default config merge is expected by all modules.
+- Don’t instantiate models outside registry path (`modeling/models`), or YAML `model_cfg.model` lookup breaks.
+- Don’t bypass `get_ddp_module`; attribute passthrough wrapper is used for downstream method access.