How google/ml-compiler-opt works
Project type and purpose
• MLGO is an open-source Python framework for training machine-learning-driven compiler optimizations (in LLVM). It provides CLI scripts, libraries, and distributed/local trainers (Policy Gradient today, ES planned) to replace hard-coded inlining and register-allocation heuristics with learned models.
High-level architecture overview
At its core, MLGO is a pipeline with these major phases:
a. Configuration & orchestration (CLI entrypoints + gin config system)
b. Data generation & collection (feature extraction from LLVM IR corpora, traces)
c. Training loop (RL trainer or ES trainer, local or distributed)
d. Model serialization (TensorFlow SavedModel)
e. Benchmarking & evaluation (scripts to measure performance against LLVM baselines)
f. Integration & deployment (buildbot scripts, LLVM CMake flags to load models)
Main components & how they interact
• CLI Entrypoints (train_locally.py, train_bc.py, inlining_runner.py, regalloc_runner.py)
– Invoke pipeline based on gin configs.
– Pass control to the orchestration layer.
• Orchestration Layer (compiler_opt.rl.compilation_runner and equivalent ES trainer)
– Reads gin configs, spawns data collectors and workers.
– For distributed mode: interacts with ppo_reverb_server, ppo_collect, ppo_train, ppo_eval.
– For local mode: uses LocalDataCollector and local WorkerManager.
• Data Collection & Environment
– compiler_opt.rl.data_collector / local_data_collector: compile code with LLVM “development-mode,” extract IR features, traces.
– compiler_opt.es.blackbox_evaluator / inlining_worker / regalloc_trace_worker for ES pipelines.
• Policy & Learner
– RL: constant_value_network, policy_saver, ppo_*.py (distributed)
– ES: blackbox_learner, blackbox_evaluators
– Both rely on TensorFlow and gin-configurable networks.
• Storage & Serialization
– Models serialized as TensorFlow SavedModel (saved_model.pb + variables/).
– Pipelines write checkpoints & logs.
• Benchmarking & Reporting
– compiler_opt.benchmark: list_gtests, gtest_executable_utils, benchmark_report_converter.
– Produce performance regressions or wins vs. LLVM defaults.
• Buildbot & Deployment
– buildbot scripts to compile LLVM, point -DLLVM_INLINER_MODEL_PATH to “download” or local model.
– check-license, CI workflows, Dockerfile for reproducible environments.
Architectural patterns & principles
• Separation of concerns: CLI/orchestrator vs. data collection vs. training vs. evaluation
• Modular design: “compiler_opt” Python package divided into subpackages (rl, es, benchmark, tools, distributed)
• Pluggable configuration: gin-config files in each subpackage to swap agents/algorithms without code changes
• Support for horizontal scaling: distributed learners & collectors coordinate via Reverb (actor-learner pattern)
Final recommendations
• External dependencies (TensorFlow, LLVM, Docker, GitHub releases) at the periphery