Skip to content

Latest commit

 

History

History
96 lines (62 loc) · 8.06 KB

README.md

File metadata and controls

96 lines (62 loc) · 8.06 KB

NumericBridge logo

NumericBridge

License: MIT CI status Project homepage: NumericBridge community GitHub stars

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 is a community for investigating numerical precision across inference and training stacks, including RL. Start by querying the live community case library for records that match your setup, then deploy the workload locally to reproduce and diagnose precision differences. Verify the fix by rerunning the original workload and submit the verified result to the community for review.

Framework overview

NumericBridge workflow: target setup, numerical comparison, issue diagnosis, repair and optimization, regression testing, deliverables, and community knowledge retrieval

The Ascend 910C / Qwen3.8-27B / verl configuration in the figure is an example. See Typical cases for measured results and verified coverage.

Search the community case library by hardware, model and framework version to retrieve known issues, candidate fixes and prior measurements. In your own environment, compare the affected outputs, gradients or weight updates before and after the change. Include the configuration, patch and measured coverage in the community submission so the next team can reproduce the result.

Getting started

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-skills

Look 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 1

Run 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.py

For 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.

Workflow and skills

The workflow directs the agent to Framework Adapt for native setup, Precision Compare for numerical comparisons, and Precision Repair when the evidence warrants diagnosis or repair. Each skill uses the confirmed request and available evidence.

Choose the guide for the quantity you want to compare. The inference guide covers token distributions on a shared history. The SFT guide covers gradients and optimizer updates. The RL guide covers action scores and losses on fixed trajectories. Inference · SFT · RL

Typical cases

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

Evaluation and repair history

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.

Contributing

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 validate

Trusted by Industry and Research

Sun Yat-sen University, CUHK-Shenzhen, Shenzhen Loop Area Institute, China Merchants Lion Rock AI Lab and AutoKernel

Sun Yat-sen University · The Chinese University of Hong Kong, Shenzhen · Shenzhen Loop Area Institute · China Merchants Lion Rock AI Lab · AutoKernel