Skip to main content

AdapterBridge

LoRA Checkpoint & Config Compatibility Engine for Enterprise Inference Runtimes

CI Workflow PyPI version License: Apache 2.0 Python Version Docker Image

AdapterBridge is an open-source pre-flight compatibility, validation, and remediation engine that eliminates runtime deployment failures when moving fine-tuned Low-Rank Adaptation (LoRA/QLoRA) checkpoints into production inference runtimes (vLLM, SGLang, Ollama, TensorRT-LLM).


Executive Summary & Case Study

1. Problem Statement

Post-training frameworks (Unsloth, Axolotl, LLaMA-Factory, Hugging Face PEFT) make fine-tuning open-weight foundation models (Llama 3.x, Qwen 2.5, Mistral, DeepSeek) accessible. However, exported checkpoint directories are frequently incompatible with production serving runtimes without manual intervention.

Incompatibilities are typically discovered only after a deployment has already consumed compute resources:

Failure Mode Root Cause Downstream Impact
Missing Config Files Training exports include adapter_model.safetensors + adapter_config.json only, omitting config.json or tokenizer bundles. Serving engine process crashes at startup before accepting requests.
"Silent Dropping" Trap Runtime kernels discard embed_tokens and lm_head adapters while applying projection deltas. Model loads without errors but fine-tuned behavior is silently stripped.
Upstream Engine Churn Hardcoded layer mapping rules break when vLLM or SGLang releases minor updates. Validation rules lag upstream engine releases.
MoE 2D vs. 3D Stacked Keys Conflicting 2D per-expert weight matrices vs 3D fused expert tensors (is_3d_lora_weight: true). Tensor dimension mismatches during expert routing.
State-Dict Key Drift Inconsistent framework prefixes (base_model.model.model.layers.0... vs. model.layers.0...). Weight loading fails or silently drops layers.
Malformed Chat Templates Custom Jinja2 chat templates with syntax errors, double-BOS tokens (<s><s>), or delimiter leakage (`< im_end

High-Performance Architectural Enhancements

┌────────────────────────────────────────────────────────────────────────┐
│             ADVANCED ADAPTERBRIDGE RE-ENGINEERED PIPELINE              │
└──────────────────────────────────┬─────────────────────────────────────┘
                                   │
      ┌────────────────────────────┼────────────────────────────┐
      ▼                            ▼                            ▼
┌──────────────┐             ┌──────────────┐             ┌──────────────┐
│  Lightweight │             │ Dynamic Spec │             │ Logit Canary │
│ Engine Core  │             │ Cloud Sync   │             │ Verification │
│ (Zero Torch, │             │ (Auto-fetch  │             │ (Micro CPU   │
│  Pure Rust/  │             │  latest vLLM │             │  activation  │
│  Safetensors)│             │  rule-sets)  │             │  assertion)  │
└──────────────┘             └──────────────┘             └──────────────┘
  1. Zero-Torch Architecture (Ultra-Lightweight Core):

    • Core CLI, linting, header parsing, auto-fixing, and chat-template validation execute in pure Python using memory-mapped safetensors and jinja2 (< 15MB base installation).
    • Eliminates PyTorch/CUDA installation friction in CI/CD pipelines.
  2. Dynamic Target Profiles via Remote Schema Sync:

    • Decouples target engine rules from Python package releases.
    • Run adapterbridge check --target vllm@0.6.4 to fetch or cache dynamic rule specifications.
    • Use adapterbridge sync to refresh local rule specifications.
  3. Logit Canary & Activation Probing (Zero-GPU Activation Check):

    • CPU micro-activation pass computing $\Delta \mathbf{h} = (\alpha / r) \mathbf{B}\mathbf{A}\mathbf{x}$ on memory-mapped safetensors.
    • Asserts $\lVert\Delta \mathbf{h}\rVert_2 > \epsilon$ and flags silent module dropping (embed_tokens, lm_head).
  4. MoE 2D vs. 3D Stacked Weight Inspector:

    • Analyzes Mixture-of-Experts (MoE) tensor layouts (DeepSeek-V3, Mixtral, Qwen-2.5-MoE).
    • Validates 2D per-expert weight matrices (experts.0.gate_proj) against 3D fused expert tensors (experts.gate_up_proj.weight).
  5. Direct Chat-Completion Round-Trip Tester:

    • Renders OpenAI-compatible payload messages ({"messages": [...]}) through Jinja templates.
    • Asserts against delimiter leakage (<|im_end|>, [INST]), double-BOS token injection (<s><s>), and system instruction truncation.

System Architecture

+-------------------------------------------------------------+
|                Presentation & Ingestion Layer               |
|   CLI (Typer + Rich)   |  Python SDK  |  CI/CD Gatekeepers  |
+-------------------------------+-----------------------------+
                                |
                                v
+-------------------------------------------------------------+
|                     AdapterBridge Core Engine               |
|  +---------------+ +---------------+ +-------------------+  |
|  | Dynamic Schema| | Zero-GPU      | | Logit Canary      |  |
|  | Sync Manager  | | Safetensors   | | Activation      |  |
|  | (vllm@0.6.4)  | | Header Engine | | Probe (||Δh||)  |  |
|  +---------------+ +---------------+ +-------------------+  |
|  +---------------+ +---------------+ +-------------------+  |
|  | MoE 2D/3D     | | Chat Template | | Live Cluster      |  |
|  | Stacked       | | Round-Trip    | | Endpoint        |  |
|  | Inspector     | | Verifier      | | Doctor          |  |
|  +---------------+ +---------------+ +-------------------+  |
+-------------------------------+-----------------------------+
                                |
                                v
+-------------------------------------------------------------+
|                  Target Engine Specifications               |
|   vLLM  |  SGLang  |  Ollama  |  TensorRT-LLM  | (Pluggable)|
+-------------------------------------------------------------+

Core Commands & Capabilities

                  +------------------+
                  | Input Checkpoint |
                  +--------+---------+
                           |
     +---------------------+---------------------+---------------------+
     |                     |                     |                     |
     v                     v                     v                     v
+---------+           +---------+           +----------+          +----------+
|  CHECK  |           |   FIX   |           |  DOCTOR  |          |   SYNC   |
+---------+           +---------+           +----------+          +----------+
Static Linter       One-Command           Live Endpoint         Dynamic Remote
& Canary Probe      Auto-Remapper         Health Doctor         Schema Refresh

1. adapterbridge check

Static schema inspection, versioned target rules (vllm@0.6.4), zero-GPU canary activation probing (--canary), and chat template round-trip testing (--chat-test).

2. adapterbridge fix

One-command automated normalizer and metadata synthesizer. Resolves base model lineage from Hugging Face Hub, fixes unsupported target modules, normalizes state-dict prefixes, and injects architecture-matched chat templates.

3. adapterbridge doctor

Operational health checker querying live, active inference endpoints (/v1/models, /v1/chat/completions) to verify that the cluster is actively serving adapter weights rather than silently falling back to the base model.

4. adapterbridge sync

Synchronizes remote target engine rule specifications into local schema cache.


Installation

Standard Ultra-Lightweight Core Installation (< 15MB)

pip install adapterbridge

Installation with PyTorch Meta-Tensor Dry-Run Support

pip install adapterbridge[verify]

Development Installation

git clone https://github.com/adapterbridge/adapterbridge.git
cd AdapterBridge
pip install -e .[dev,verify]

Usage Examples

Scenario 1: CLI Inspection and One-Command Fix

# 1. Run compatibility check with canary probing and chat testing
adapterbridge check --path ./my-lora-adapter --target vllm@0.6.4 --canary --chat-test

# 2. Execute automated fix
adapterbridge fix --src ./my-lora-adapter --dst ./my-lora-vllm --target vllm

# 3. Synchronize dynamic remote schemas
adapterbridge sync

# 4. Probe live running inference cluster endpoint
adapterbridge doctor --endpoint http://vllm-service:8000/v1 --adapter-id sql-lora-v1

Scenario 2: GitHub Actions CI/CD Gatekeeper

Add .github/workflows/adapterbridge-validate.yml:

name: Validate Adapter Deployment

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  adapterbridge-preflight:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate Adapter Checkpoints
        uses: adapterbridge/action-validate@v1
        with:
          checkpoint-path: ./checkpoints/latest
          target-engine: vllm@0.6.4
          fail-on-warning: false

Scenario 3: Kubernetes Pre-Flight Init-Container

Run as an init-container in Kubernetes pods to validate or auto-repair mounted adapter volumes before serving servers launch:

initContainers:
  - name: adapterbridge-preflight
    image: ghcr.io/adapterbridge/adapterbridge-k8s:latest
    env:
      - name: ADAPTER_PATH
        value: "/mnt/adapters/latest"
      - name: TARGET_ENGINE
        value: "vllm@0.6.4"
      - name: AUTO_FIX
        value: "true"
    volumeMounts:
      - name: adapter-volume
        mountPath: /mnt/adapters

Scenario 4: Training Framework Integration (Unsloth / Axolotl)

from adapterbridge.integrations.unsloth import verify_unsloth_export

# Post-export hook in Unsloth fine-tuning pipeline
verify_unsloth_export("outputs/lora_model", target_engine="vllm@0.6.4", raise_on_error=True)

Python SDK Reference

from adapterbridge import AdapterInspector, TargetEngine

# Initialize inspector with versioned target engine
inspector = AdapterInspector(
    checkpoint_path="./checkpoints/my-adapter",
    target_engine="vllm@0.6.4",
)

# Run Diagnostics
report = inspector.run_diagnostics()

# Run Canary Activation Probe
canary_res = inspector.run_canary_probe()
print(f"Canary probe passed: {canary_res.passed}, delta norm: {canary_res.activation_delta_norm}")

# Run Chat Template Round-Trip Test
chat_res = inspector.run_chat_test()
print(f"Chat roundtrip status: {chat_res.success}")

# Auto-repair checkpoint
if not report.is_compatible:
    plan = inspector.auto_repair(
        destination_path="./checkpoints/my-adapter-repaired",
        fallback_base_model="meta-llama/Llama-3.1-8B-Instruct",
    )

Target Engine Specification Matrix

Feature / Requirement vLLM (vllm) SGLang (sglang) Ollama (ollama) TensorRT-LLM (tensorrt)
config.json Required (model_type, hidden_size) Required Converted into Modelfile Required
adapter_config.json Standard PEFT schema Standard PEFT schema Converted to GGUF adapter Mapped to TRT LoRA layers
Unsupported Target Modules embed_tokens, lm_head embed_tokens None None
MoE Weight Format Fused 3D stacked weights (is_3d_lora_weight: true) Fused 3D stacked weights 2D per-expert matrices Fused 3D stacked weights
Chat Template Jinja2 (tokenizer_config.json) Jinja2 (Radix format) Ollama TEMPLATE string Formatted prompt template
Dynamic Schema Sync Enabled (vllm@0.6.4) Enabled (sglang@0.2.0) Enabled Enabled

License

AdapterBridge is released under the Apache 2.0 License.

Metadata

Release files for adapterbridge 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for adapterbridge 0.2.0
File Size Uploaded Provenance Actions
adapterbridge-0.2.0.tar.gz 38.0 kB Without provenance Details for adapterbridge-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for adapterbridge 0.2.0
File Interpreter ABI Platform Actions
adapterbridge-0.2.0-py3-none-any.whl Python 3 none any Details for adapterbridge-0.2.0-py3-none-any.whl

Total release size: 82.8 kB

Release files / adapterbridge-0.2.0.tar.gz

Download URL adapterbridge-0.2.0.tar.gz
Size 38.0 kB
Tags Source
SHA-256 checksum
How to use checksums
f99563264659a71311826c464d688a034ea998d066b8d71d7e7c10afbf83d461
BLAKE2b-256 checksum
How to use checksums
264a16969843e9428e06e22344af1ae0da94d554c45b35cb2e7aaa8f0b46194f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.13

Release files / adapterbridge-0.2.0-py3-none-any.whl

Download URL adapterbridge-0.2.0-py3-none-any.whl
Size 44.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d7fa458eba7f551e4ec79c2c29aa32bc1d7cb3243b762cfb8c1333fc1b38f2a7
BLAKE2b-256 checksum
How to use checksums
28c8c1a6e5f72298fe63b592a6c408f9a67d7013a9cdef29a5a3d0afc1ee78ed
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.13

Security for adapterbridge 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page