A framework and collaborative community for cross-stack precision alignment in inference, training, and reinforcement learning
English · 简体中文
Overview · Getting started · Typical cases · Results and repair history
NumericBridge helps compare, diagnose and repair numerical differences across inference, training and RL stacks. Confirm the setup, look up community cases, then run the checks in your environment. Verify fixes on the original workload and share results with the community if you choose.
The Ascend 910C / Qwen3.8-27B / verl configuration in the figure is an example. See Typical cases for measured results and verified coverage.
Clone the repository and export the skills to a fresh directory. Point your agent client at the exported skills, or use its skills directory as the output path. Precision Compare includes the shared tools and an offline snapshot of the community case library. Installation and updates
git clone https://github.com/satsuki2486441738/NumericBridge.git
cd NumericBridge
python -B -m scripts install --output ../numericbridge-skillsLook up a case. From the repository root, fetch the current community index and return one record for PEFT. Substitute the library used by your workload.
python -B -m tools.community_search \
--index https://freedomintelligence.github.io/NumericBridge/data/search-index.json \
--library peft --limit 1Run a first comparison. With PyTorch and NumPy installed, run this CPU example from the repository root. It uses the same classifier, weights and batch for two backward passes, one in FP32 and one in BF16. The output gives the gradient differences and the path to both captures and report.json.
python skills/precision-compare/examples/compare_gradients.pyFor your workload, start with the NumericBridge Skill. Give the agent your hardware, model, framework and task, along with any run commands or captures you have.
The workflow loads only the method it needs: Framework Adapt for native setup, Precision Compare for measurement, and Precision Repair for supported-path failures or numerical findings that warrant diagnosis. Each stage reuses the confirmed request and evidence.
Task recipes: Inference · SFT · RL.
| Workload | What the measurements showed | Evidence |
|---|---|---|
| Qwen3.5-9B-Base · LoRA | On the first training step, cosine similarity across GPU and NPU was about 0.9976 for gradients and 0.9775 for stored weight updates. | Training measurements |
| Qwen3.8-Flash-Next · inference | With automatic placement on GPU and TP8 on NPU, the top token matched in 254 of 264 sampled full-forward rows and 2 of 32 later fixed-history rows. The runs included 32K inputs. Native NPU vLLM and SGLang failed during initialization, before scoring. | Inference report |
| DeepSeek-V4.1-Flash-1017 · GPU/NPU comparison | The original comparison paired 191 of 275 tensor observations and all 3,168 target scores. A later, separately adapted configuration paired 275 of 275 observations. | Original comparison · Follow-up report |
| PEFT 0.17.1 · LoRA adapter merging | SVD combination applied the adapter scale twice. After backporting the upstream fix, all 24 small CPU workloads passed, including forward, input-gradient and checkpoint checks. | Repair record · Patch |
The three model comparisons report measurements for the configurations tested. Numerical acceptance thresholds were unspecified. Browse all reports
Use the community case library to select your model, hardware and framework version. Open a matching case to see the observed difference, candidate fixes and the workload used to verify each tested fix.
- History archive — look up earlier evaluations and repairs by configuration.
- Results and evidence — find the figures, measured values and source records behind a report.
Share a comparison or repair through the community submission MCP. Include the model and library revisions, run configuration, observed difference and evidence. For a fix, include before-and-after results on the original workload. Community maintainers review submissions, publish records and coordinate any upstream PRs. Community record guide · Publication guidelines
Before submitting, run the repository and record checks from the repository root. Developer guide
python -m pip install -r requirements-dev.txt
python -B -m scripts validate
python -B -m community.records validateSun Yat-sen University · The Chinese University of Hong Kong, Shenzhen · Shenzhen Loop Area Institute · China Merchants Lion Rock AI Lab · AutoKernel
