#PyTorch Model Quantization FAQ

#Training Environment

#Why can't a Docker container use Nvidia resources?

Possible cause: The GPU Docker environment is not configured correctly.

What to check first: Check the GPU Docker section in Environment Deployment.

Recommendation: Confirm that the Docker startup method, GPU device mapping, and driver environment all meet the documented requirements.

#QAT Quantized Training

#If Calibration accuracy is poor, does it mean QAT accuracy will probably also be low?

Possible causes:

• For the same model, Calibration accuracy and QAT accuracy are usually positively correlated.

• Different models have different sensitivity to quantization error, so there is no single metric that can be used as a universal judgment standard.

What to check first:

• Check whether the Calibration accuracy is already clearly below expectation.

• Further check whether the model contains quantization-unfriendly structures, such as high-risk operators, shared modules, or large differences across multiple input distributions.

• If QAT has already started, also check the accuracy of the quantized model instead of looking only at the QAT model.

• If you still need to narrow down the issue, continue with Calibration, Build Floating-point Model, and Deployment Consistency Analysis.

Recommendation: If Calibration accuracy is already clearly low, it is better to return to the Calibration stage first instead of expecting QAT to fully fix the problem.

#How good should Calibration be before starting QAT?

Possible causes:

• Adjusting calibration parameters alone usually brings only limited improvement.

• Whether to stay in the Calibration stage should be judged together with the current accuracy and the result of a small-scale QAT trial run.

What to check first:

• Check the gap between Calibration accuracy and the target accuracy.

• If needed, run a small-scale QAT experiment and observe both the QAT model and the quantized model.

Recommendation:

1. If Calibration accuracy is already very close to the target, continuing to tune calibration parameters is usually still worthwhile.

2. If QAT accuracy is higher than Calibration accuracy but still clearly below the target, it is recommended to stay in the Calibration stage and continue troubleshooting quantization-unfriendly issues.

3. If QAT accuracy is lower than Calibration accuracy, it is recommended to check the QAT pipeline and training strategy first instead of continuing training blindly.

#Should the behavior during QAT training be basically consistent with float training?

Possible causes:

• In general, the overall trends of loss and accuracy should remain basically consistent with float training.

• If the difference is large, the issue usually lies in the QAT pipeline, training state control, or quantization configuration.

What to check first:

• Check whether the loss curve differs too much from the final stage of float training.

• Further check whether the state switching of train() / eval() and set_fake_quantize() is correct.

• Also confirm whether the initialization parameters from the Calibration stage were loaded correctly, and whether the model was modified again after prepare.

Recommendation: If the observed behavior is clearly inconsistent with float training, check the QAT pipeline itself first instead of immediately adjusting a large number of training hyperparameters.

#If quantized model accuracy is abnormal, which related topics should be checked first?

Possible cause: When the accuracy of the QAT model or HBIR model does not meet expectations, the issue often involves one or more parts of the quantization configuration, training strategy, or training-to-deployment consistency.

What to check first:

• If the issue appears as accuracy drop, more bad cases, or an unclear problem scope, start with PyTorch Model Accuracy Tuning Tool.

• If further quantization tuning is needed, continue with Accuracy Tuning Guide.

• If the problem mainly appears after export, convert, compile, or board-side validation, continue with Deployment Consistency Analysis.

Recommendation: First determine whether the issue occurs in training, export, or deployment, and then move to the corresponding topic for further troubleshooting.

#What should be done if the initial QAT loss is very large, or if NAN / INF appears during training?

Possible causes:

• The input data itself contains NAN.

• The floating-point model has not converged.

• Calibration initialization was not performed correctly.

• The learning rate is too large, the training strategy is not suitable, or the fake quant / observer states are configured incorrectly.

What to check first:

• Check whether the input data contains NAN or INF.

• Further check whether the floating-point model has already converged.

• Further check whether Calibration was enabled and whether the Calibration model parameters were loaded correctly.

• Also check model_check_result.txt and qconfig_dtypes.pt.py to confirm that there are no obvious abnormalities in the graph structure or dtype configuration.

• If necessary, then check the training strategy, such as the learning rate, optimizer, and gradient clipping.

Recommendation:

1. First confirm that the input data does not contain abnormal values.

2. First confirm that the floating-point model has converged, otherwise even small quantization errors may be amplified into obvious instability.

3. Complete Calibration first so that the model starts from a more stable set of initial coefficients.

4. If the learning rate is too large, lower it first, and add gradient clipping if necessary.

5. If float training uses strategies such as OneCycle that strongly affect the learning rate, QAT is usually easier to verify first with a more stable SGD strategy.

#What should be done if QAT accuracy does not improve, or is even worse than Calibration?

Possible causes:

• The training strategy is not appropriate.

• The BN handling strategy does not match the current float training setup.

• The scale update strategy is not appropriate.

• The quantized model accuracy is also dropping at the same time.

What to check first:

• Check the accuracies of both the QAT model and the quantized model together instead of observing only the QAT model.

• Further check whether the BN strategy matches the current float training method.

• Further check whether the quantization parameters should stay fixed or continue updating.

• If the issue becomes more obvious after export, continue with Deployment Consistency Analysis.

Recommendation:

• If QAT accuracy is lower than Calibration accuracy, start by checking the training strategy, BN handling, and scale update method.

• If the quantized model accuracy is also dropping, the issue is usually not only a training-side symptom, and it is likely to affect the later deployment result.

#What should be done if accuracy drops after enabling multi-machine training?

Possible cause: After multi-machine training is enabled, the total batch size increases significantly, but hyperparameters such as the learning rate are not adjusted accordingly.

What to check first:

• Check whether the total batch size has changed significantly.

• Further check whether LR, weight decay, and other hyperparameters still use the single-machine configuration.

Recommendation: After enabling multi-machine training, adjust LR and related hyperparameters accordingly instead of reusing the original configuration directly.

#Does Qconfig require user intervention?

Possible cause: Qconfig directly defines how activations and weights are quantized. If its role is not clearly understood, later troubleshooting often loses a reliable basis.

What to check first:

• Confirm whether the current qconfig templates, quantization algorithms, and final dtype settings match the model and platform requirements.

• If you need more detail on configuration methods, refer to Build QConfig.

Recommendation: At minimum, make sure the quantization method for activations and weights, as well as the main template configuration in use, are clear. Current supported quantization algorithms include FakeQuantize, LSQ, and PACT.

#How can ONNX models be exported for different stages?

First confirm whether the object to export is qat_model or quantized_model. After that, you can export the ONNX models for the QAT model and quantized model as follows:

from horizon_plugin_pytorch.utils import onnx_helper as horizon_onnx_helper

# [Optional] Export float, qat net to ONNX
# --------------------------------------------------------------------
logging.info("Export qat model to ONNX...")
data = torch.rand((1, 3, 228, 228), device=device)
horizon_onnx_helper.export_to_onnx(qat_net, data, "resnet_qat.onnx")

# [Optional] Export quantized_model to ONNX
# --------------------------------------------------------------------
horizon_onnx_helper.export_quantized_onnx(
    quantized_model, data, "resnet_quantized.onnx"
)

#What should be done if int16 / fp16 settings do not take effect as expected?

Possible causes:

• module_name is configured incorrectly.

• The configuration is overridden by a later template.

• Operator fallback occurs, so the final dtype does not match the expectation.

What to check first:

• Check whether module_name is correct. This field supports only string values and does not support index-based configuration.

• Further check model_check_result.txt, qconfig_dtypes.pt.py, and qconfig_changelogs.txt to confirm whether the final operator dtype matches expectations.

• If the platform strategy is still unclear, continue with Build QConfig.

Recommendation:

• First confirm that the configuration is applied to the correct module.

• If int16 / fp16 has been configured but the final result still does not take effect, check the template override order and fallback logs first instead of looking only at the configuration code itself.

#How can you confirm whether a specific layer has high-precision output enabled?

Possible cause: The model output node is not configured correctly as high-precision output.

What to check first: Print the corresponding layer in qat_model and check whether that layer contains (activation_post_process): FakeQuantize.

For example, an int32 high-precision conv is printed as follows:

(1): ConvModule2d(
  (0): Conv2d(
    64, 3, kernel_size=(3, 3), stride=(1, 1), padding=(1, 1)
    (weight_fake_quant): FakeQuantize(
      fake_quant_enabled=tensor([1], dtype=torch.uint8), observer_enabled=tensor([1], dtype=torch.uint8),
      quant_min=-128, quant_max=127, dtype=qint8, qscheme=torch.per_channel_symmetric, ch_axis=0,
      scale=tensor([1., 1., 1.]), zero_point=tensor([0, 0, 0])
      (activation_post_process): MovingAveragePerChannelMinMaxObserver(min_val=tensor([]), max_val=tensor([]))
    )
  )
)

An int8 low-precision conv is printed as follows:

(0): ConvModule2d(
  (0): ConvReLU2d(
    64, 64, kernel_size=(3, 3), stride=(1, 1), padding=(1, 1)
    (weight_fake_quant): FakeQuantize(
      fake_quant_enabled=tensor([1], dtype=torch.uint8), observer_enabled=tensor([1], dtype=torch.uint8),
      quant_min=-128, quant_max=127, dtype=qint8, qscheme=torch.per_channel_symmetric, ch_axis=0,
      scale=tensor([1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1.,
                    1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1.,
                    1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1.,
                    1., 1., 1., 1., 1., 1., 1., 1., 1., 1.]),
      zero_point=tensor([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
                         0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
                         0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0])
      (activation_post_process): MovingAveragePerChannelMinMaxObserver(min_val=tensor([]), max_val=tensor([]))
    )
    (activation_post_process): FakeQuantize(
      fake_quant_enabled=tensor([1], dtype=torch.uint8), observer_enabled=tensor([1], dtype=torch.uint8),
      quant_min=-128, quant_max=127, dtype=qint8, qscheme=torch.per_tensor_symmetric, ch_axis=-1,
      scale=tensor([1.]), zero_point=tensor([0])
      (activation_post_process): MovingAverageMinMaxObserver(min_val=tensor([]), max_val=tensor([]))
    )
  )
)

Recommendation:

• If activation_post_process: FakeQuantize is not present, the layer usually has high-precision output.

• If the layer is expected to be high precision but still appears as low precision, check the qconfig setting and output template configuration first.

• If the configuration looks correct but the final dtype still does not match expectations, continue checking qconfig_dtypes.pt.py and qconfig_changelogs.txt.

#What should be done if QAT and quantized model accuracy are inconsistent?

Possible causes:

• The QAT stage cannot fully simulate the pure fixed-point computation logic in HBIR.

• Additional error is introduced during export, convert, or lookup-table fixed-point conversion.

What to check first:

• Verify the quantized HBIR model accuracy first instead of looking only at the QAT torch module.

• If accuracy drops after export, use pre_export first to determine whether the issue is caused by lookup-table fixed-point conversion.

• Further check Deployment Consistency Analysis and per-layer comparison results from quantization tuning tools, such as compare_per_layer_out.txt.

Recommendation:

• After QAT, validate the quantized model accuracy at least once.

• If QAT accuracy is normal but quantized accuracy is abnormal, treat it first as an export consistency issue instead of continuing training blindly.

#If accuracy drops on the board, which parts should be checked first?

Possible causes:

• There is a consistency issue between quantized.bc and hbm.

• Extra error is introduced by preprocessing, input domain differences, color space conversion, or the deployment pipeline.

What to check first:

• Confirm first whether the accuracy of quantized.bc is normal.

• If quantized.bc is normal but the result drops on hbm or on the board, continue with Deployment Consistency Analysis.

• Also check whether the input data format is consistent with the training stage, for example whether it changed from RGB to centered YUV444 / nv12.

• If the issue looks more deployment-related, continue checking whether preprocessing, postprocessing, inserted nodes, and board-side input and output adaptation are consistent.

Recommendation: Do not immediately attribute on-board accuracy drop to QAT training itself. First determine whether the issue occurs in QAT, export, convert, compile, or board-side input preparation.

#Why are the weight parameters not updated in QAT training after loading Calibration?

Possible causes:

• prepare is called after the optimizer is defined.

• fake_quant_enabled or observe_enabled is not in the correct state.

• The module training state is incorrect.

What to check first:

• Check whether prepare is called before the optimizer is defined.

• Further check whether fake_quant_enabled and observe_enabled are both 1.

• Further check whether the module training variable is True.

Recommendation:

• First confirm that the QAT model structure and the optimizer are bound to the same model after prepare, and then continue checking the training state switching.

• If the issue still cannot be located, return to Prepare to confirm whether model replacement and training state handling are as expected.

#Can auxiliary branches insert fake quantization nodes?

Possible cause: The auxiliary branch is not used for deployment, but it is still included in global QAT training.

What to check first:

• Confirm whether the branch really belongs to the path that will be deployed on the board.

• Further check whether the data distribution of that branch differs significantly from other branches in the main path.

Recommendation:

• In general, fake quantization nodes should be inserted only in the part of the model that will actually be deployed on the board.

• Auxiliary branches usually make training harder. If their data distribution also differs significantly from other branches, they further increase the risk to accuracy, so removing them is usually recommended.

#How can the Horizon gridsample operator be rewritten with the public torch implementation?

Possible cause: The gridsample operator in horizon_plugin_pytorch uses a different grid definition from the public torch implementation.

What to check first:

• Confirm whether the current grid input uses int16 absolute coordinates.

• If you plan to switch to torch.nn.functional.grid_sample, also confirm whether coordinate normalization has already been applied.

Recommendation: In horizon_plugin_pytorch, the gridsample operator uses int16 absolute coordinates as the grid input, while the public torch implementation uses float32 normalized coordinates in the range [-1, 1]. After importing the operator from torch.nn.functional.grid_sample, the coordinates can be normalized as follows.

def norm_grid(x, grid):
  n = grid.size(0)
  h = grid.size(1)
  w = grid.size(2)

  base_coord_y = (
      torch.arange(h, dtype=grid.dtype, device=grid.device)
      .unsqueeze(-1)
      .unsqueeze(0)
      .expand(n, h, w)
  )

  base_coord_x = (
      torch.arange(w, dtype=grid.dtype, device=grid.device)
      .unsqueeze(0)
      .unsqueeze(0)
      .expand(n, h, w)
  )

  absolute_grid_x = grid[:, :, :, 0] + base_coord_x
  absolute_grid_y = grid[:, :, :, 1] + base_coord_y
  norm_grid_x = absolute_grid_x * 2 / (x.size(3) - 1) - 1
  norm_grid_y = absolute_grid_y * 2 / (x.size(2) - 1) - 1
  norm_grid = torch.stack((norm_grid_x, norm_grid_y), dim=-1)

  return norm_grid

#Setting Errors

#What should be done if the model output node is not set to high-precision output and the quantization accuracy is lower than expected?

Possible cause: The model output node is still executed with the default low-precision configuration, so the result does not meet expectations.

What to check first: Check the qconfig setting for the output node and whether template optimization for high-precision output is enabled.

The following is an incorrect example.

Assume the model is defined as follows:

class ToyNet(nn.Module):
    def __init__(self):
        self.conv0 = nn.Conv2d(4,4,3,3)
        self.relu0 = nn.ReLU()
        self.classifier = nn.Conv2d(4,4,3,3)

    def forward(self, x):
        out = self.conv0(x)
        out = self.relu(out)
        out = self.classifier(out)
        return out

# Incorrect qconfig setting example:

float_model = ToyNet()
# Set the whole network to int8 quantization
float_model.qconfig = default_qat_8bit_fake_quant_qconfig
qat_model = prepare(float_model, example_input)

Recommendation: If you want the model output node to remain high precision, you can configure it through QconfigSetter and template optimization, for example:

qat_model = horizon.quantization.prepare(
    float_model,
    example_input,
    qconfig_setter=QconfigSetter(
        get_qconfig(),
        templates=[
            ModuleNameTemplate({"": qint8}),
            ConvDtypeTemplate(),
        ],
        enable_optimize=True,
    ),
)

#Why are some modules assigned a non-None qconfig even though they should not be quantized?

Possible cause: Modules such as preprocessing, postprocessing, or loss functions that do not belong to the quantized path are assigned qconfig by mistake.

What to check first: Check whether these modules really belong to the deployment path.

Recommendation: Assign qconfig only to modules that actually need quantization.

#What issues can be caused by an incorrect march setting?

Possible cause: The march setting does not match the actual deployment processor.

What to check first: Check the BPU architecture corresponding to the target platform.

Recommendation: Select the correct march according to the target processor. For example, J6 requires Nash.

horizon.march.set_march("nash-e")

#Method Errors

#Why can using RGB or other non-centered YUV444 formats as model input lead to inconsistent deployment accuracy?

Possible cause: The training input format is inconsistent with the input format supported by Horizon hardware.

What to check first: Check whether the training input format is consistent with the deployment-side format.

Recommendation: It is recommended to use centered YUV444 directly as the network input from the beginning of model training.

#Why can monitoring only the qat model fail to reveal deployment-side accuracy issues in time?

Possible cause: The QAT stage cannot fully simulate the pure fixed-point computation logic in HBIR, so looking only at qat model results may hide deployment-side error introduced later.

What to check first:

• Add accuracy validation results for the quantized model or quantized HBIR model.

• If the results are inconsistent, return to Deployment Consistency Analysis for further troubleshooting.

Recommendation: During QAT training, keep observing validation results in the quantized direction instead of using only the qat model as the basis for evaluation and monitoring.

quantized_hbir_model = hbdk4.compiler.convert(qat_hbir_model)
acc = evaluate(quantized_hbir_model, eval_data_loader)

#Operator Errors

#Why does calling the same FloatFunctional() member multiple times cause problems?

Possible cause: When the same FloatFunctional instance is called multiple times, it shares the same set of quantization parameters, which can easily introduce additional error.

What to check first: Check whether the forward path calls the same member defined through FloatFunctional() multiple times.

The incorrect example is as follows:

class ToyNet(nn.Module):
    def __init__(self):
        self.add = FloatFunctional()

    def forward(self, x, y, z)
        out = self.add.add(x, y)
        return self.add.add(out, z)

Recommendation: It is generally not recommended to call the same FloatFunctional() variable multiple times in forward. It is better to split it into multiple independent members.

class ToyNet(nn.Module):
    def __init__(self):
        self.add0 = FloatFunctional()
        self.add1 = FloatFunctional()

    def forward(self, x, y, z)
        out = self.add0.add(x, y)
        return self.add1.add(out, z)

#Why can a Quantized model fail inference or show abnormal deployment accuracy if some operators did not go through Calibration or QAT?

Possible cause: Some operators in the fixed-point stage depend on real quantization parameters obtained during Calibration or QAT. If the earlier quantization process is missing, correct inference behavior and stable accuracy may not be guaranteed.

What to check first:

• Confirm whether newly added operators participated in quantization during Calibration or QAT.

• If the operator is added in postprocessing or in a deployment-stage path, also confirm whether it belongs to a type that is allowed to be added directly.

Recommendation: The Quantized stage does not mean that no operators can be added directly. Some operators, such as color space conversion, can be handled according to the documentation. However, not all operators are suitable for direct insertion. Operators such as cat usually require real quantization parameters collected during Calibration or QAT. If similar operators need to be added to the network, evaluate first whether their quantization path is complete.

#Model Errors

#Can overfitting in the floating-point model affect QAT?

Possible cause: If the floating-point model is already overfitted, even small perturbations in the input may cause large output changes, and quantization error is then more easily amplified.

Common ways to judge model overfitting:

What to check first:

• Check whether the output changes significantly after a small change is applied to the input.

• Further check whether model parameter values are too large.

• Further check whether model activations are too large.

Recommendation: Solve the overfitting problem in the floating-point model first before continuing with QAT.

#Model Export

#Why can export cause accuracy loss?

Possible cause: During the QAT stage, lookup-table operations are still floating-point operators wrapped by fake quantization, and they are converted into real lookup-table fixed-point implementations only after export.

What to check first:

• Use pre_export first to verify whether the accuracy loss is caused by lookup-table fixed-point conversion.

• Then continue with Deployment Consistency Analysis to distinguish whether the issue occurs in export, convert, or compile.

The following code can be used to verify whether lookup-table operators are causing the accuracy loss:

# Only lookup-table operators are converted to fixed point, while the rest remains qat torch.
from horizon_plugin_pytorch.quantization.hbdk4 import pre_export
qat_export_pt = pre_export(qat_model)

# The inference result after lookup-table fixed-point conversion can be used to verify whether accuracy or visualization is degraded at this stage.
qat_lut_ret = self.qat_model(self.example_input)

Recommendation: If accuracy drops after export, first determine whether the problem appears before and after export, or later in convert / compile, and then choose the next troubleshooting direction accordingly.

#If export code and training code are inconsistent, how can code intrusion be minimized?

Possible cause: The model contains training logic, validation logic, and deployment logic at the same time, which causes the forward path to differ across stages.

What to check first:

• Check whether the model contains only deployment logic.

• If not, then check whether forward already distinguishes the path through the training variable or a deployment flag.

If the model contains only deployment logic, there is no inconsistency between export code and training code. Otherwise, the following approach can be used:

# Control the path through the module training variable and a custom deployment flag.
def forward(self, x):
    if self.training
        ...
    elif self.deploy:
        ...
    else:
        ...

# Defining separate forward methods is not recommended. All of them need to be adapted, and it is less maintainable.
def train_forward(self, x):
    ...

def val_forward(self, x):
    ...

def deploy_forward(self, x):
    ...

Recommendation: In general, it is better to control the forward path through the module training variable and a custom deployment flag instead of splitting the model into multiple independent forward methods.