{"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":"python","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":[{"wrong":"from onnxconverter_common import float16","symbol":"convert_float_to_float16","correct":"from onnxconverter_common import float16"}],"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,"search_vec":"'activ':48 'ai':22 'also':27 'common':9,12 'compat':65 'convers':70 'convert':2,19,30,36 'deep':77 'differ':29 'embed':42 'enabl':28 'float16':72 'focus':63 'framework':23 'frequent':53 'function':13 'learn':40,76,78 'machin':75 'maintain':49 'microsoft':51 'mix':73 'model':45,69 'often':55 'onnx':1,25,58,60,68 'onnxconvert':8 'onnxconverter-common':7 'optim':4,67,71 'packag':10 'pipelin':41 'precis':74 'provid':11 'releas':54 'runtim':61 'scikit':39 'scikit-learn':38 'tie':56 'togeth':33 'tool':5 'updat':62 'use':17 'util':15 'various':21 'work':32 'xgboost':44","created_at":"2026-04-12T16:49:31.866174+00:00","updated_at":"2026-04-16T17:32:38.151372+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.16.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/microsoft/onnxconverter-common","docs":null,"changelog":null,"pypi":"https://pypi.org/project/onnxconverter-common/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","serialization","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-07-03","last_verified":"2026-08-30","next_check":"2026-08-02","install_tag":null}}