{"id":4994,"library":"onnxconverter-common","title":"ONNX Converter and Optimization Tools","description":"The `onnxconverter-common` package provides common functions and utilities for use in converters from various AI frameworks to ONNX. It also enables different converters to work together, such as converting a scikit-learn pipeline embedding an XGBoost model. It is actively maintained by Microsoft with frequent releases, often tied to ONNX and ONNX Runtime updates, focusing on compatibility and optimization.","status":"active","version":"1.16.0","language":"en","source_language":"en","source_url":"https://github.com/microsoft/onnxconverter-common","tags":["ONNX","model conversion","optimization","float16","mixed precision","machine learning","deep learning"],"install":[{"cmd":"pip install onnxconverter-common","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core numerical operations dependency for ONNX model manipulation.","package":"numpy","optional":false},{"reason":"Used for version comparisons and managing package metadata.","package":"packaging","optional":false},{"reason":"Required for working with ONNX graph structures and model definitions.","package":"onnx","optional":false},{"reason":"Core dependency for ONNX model serialization and deserialization. Specific versions can be critical.","package":"protobuf","optional":false},{"reason":"Commonly used for inference and validation of ONNX models, especially after conversion or optimization. Its import is delayed to avoid mandatory dependency.","package":"onnxruntime","optional":true}],"imports":[{"note":"This is the primary function for converting an ONNX model to float16 precision.","symbol":"convert_float_to_float16","correct":"from onnxconverter_common import float16\nmodel_fp16 = float16.convert_float_to_float16(model)"},{"note":"Provides common ONNX operator utilities for graph manipulation.","symbol":"onnx_ops","correct":"from onnxconverter_common import onnx_ops"}],"quickstart":{"code":"import onnx\nfrom onnxconverter_common import float16\nimport os\n\n# Create a dummy ONNX model for demonstration\n# In a real scenario, you would load your model: model = onnx.load(\"path/to/model.onnx\")\n\n# Example: A simple Add operation\nnodes = [onnx.helper.make_node(\"Add\", [\"input1\", \"input2\"], [\"output\"]) ]\ngraph = onnx.helper.make_graph(\n    nodes,\n    \"simple-graph\",\n    [\n        onnx.helper.make_tensor_value_info(\"input1\", onnx.TensorProto.FLOAT, [None, 2]),\n        onnx.helper.make_tensor_value_info(\"input2\", onnx.TensorProto.FLOAT, [None, 2]),\n    ],\n    [\n        onnx.helper.make_tensor_value_info(\"output\", onnx.TensorProto.FLOAT, [None, 2]),\n    ],\n)\nmodel_fp32 = onnx.helper.make_model(graph, producer_name=\"onnx-example\")\n\n# Convert the model to float16\nmodel_fp16 = float16.convert_float_to_float16(model_fp32)\n\n# Save the converted model\noutput_path = \"dummy_model_fp16.onnx\"\nonnx.save(model_fp16, output_path)\nprint(f\"FP32 model converted to FP16 and saved to {output_path}\")\n\n# Clean up the dummy file\nos.remove(output_path)","lang":"python","description":"This quickstart demonstrates how to use `onnxconverter-common` to convert an ONNX model from float32 to float16 precision. This is a common optimization to reduce model size and potentially improve inference performance on compatible hardware. It creates a dummy ONNX model, converts it, and saves the result."},"warnings":[{"fix":"Always install `onnxconverter-common` alongside compatible `onnx` and `onnxruntime` versions. Refer to the project's GitHub releases and ONNX Runtime compatibility matrix. Upgrade `onnxconverter-common` to the latest version to ensure compatibility with recent ONNX releases.","message":"Breaking changes in ONNX or ONNX Runtime can cause compatibility issues. Specifically, `v1.16.0` fixed an `onnx.mapping` reference for `onnx 1.19`, indicating tight coupling and potential breakage with unaligned ONNX versions.","severity":"breaking","affected_versions":"<1.16.0 with ONNX >=1.19"},{"fix":"Carefully manage `protobuf` versions in your environment. If encountering conflicts, try pinning `protobuf` to a version compatible with both `onnxconverter-common` and other major dependencies (e.g., `tensorflow`, `onnx`). Virtual environments are highly recommended.","message":"Specific `protobuf` versions have been critical dependencies, leading to conflicts. `v1.14.0` explicitly required `protobuf==3.20.2` due to security concerns, which often clashed with other libraries (e.g., TensorFlow) requiring different `protobuf` versions. While recent versions might be more flexible, `protobuf` version clashes remain a common footgun in the ONNX ecosystem.","severity":"gotcha","affected_versions":"All versions, especially around 1.14.0"},{"fix":"When converting to FP16, always validate the converted model's accuracy and functionality. Utilize `convert_float_to_float16` arguments like `op_block_list`, `node_block_list`, and `keep_io_types` to fine-tune the conversion. Monitor for warning messages during conversion and check relevant GitHub issues for known limitations.","message":"Float16 (FP16) conversion can be complex and may introduce accuracy issues or runtime errors. Common problems include `SubGraph` bugs, incorrect operator ordering, `Cast` node issues, and failures with specific ops (e.g., `RandomUniformLike`, `Resize`). The tool might also log warnings about FP32 truncation.","severity":"gotcha","affected_versions":"All versions performing FP16 conversion"},{"fix":"For models over 2GB, consider splitting the model, using external data storage for large tensors in ONNX, or exploring specific `onnxruntime` nightly builds or older `onnxruntime`/`onnxconverter-common` combinations that might have workarounds. The `auto_mixed_precision_model_path` function might help with large models.","message":"Models exceeding 2GB can hit Protobuf deserialization limits, leading to `ValueError: Message onnx.ModelProto exceeds maximum protobuf size of 2GB`. This is a limitation of the Protobuf format, not `onnxconverter-common` directly, but affects its usage with large models.","severity":"gotcha","affected_versions":"All versions, when dealing with very large ONNX models."}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}