I'm onboarding NanoDet as an external recipe for Qualcomm's qai-hub-models (the official flow publishes to my own Hugging Face namespace and gets aggregated on the catalog page). The model code was never the problem. Every single wall I hit was Python packaging. Four of them, in order:
Wall 1: the upstream wheel is missing its own subpackages
Upstream NanoDet's model/ and data/ directories have no __init__.py. Its setup.py uses find_packages(), so those directories simply don't make it into the wheel. pip install succeeds; the first import dies with ModuleNotFoundError.
The near-miss: my first self-check compared against the source tree, where everything exists, and almost recorded a false pass. Validate the installed artifact, never the source tree. pip show -f and a clean-venv import are the check; the repo checkout is not.
Dead end: bridging with pkgutil.extend_path
I tried to bridge the recipe folder and the upstream package with a namespace-style extend_path trick. It can't work here: the recipe folder and the upstream package shadow each other by name, and there is no extendable target on sys.path. Measured, understood, abandoned.
The supported route: external_repos
The framework has an official mechanism for exactly this: the recipe's manifest declares the upstream repo and a pinned commit. On first import the framework clones it, adds the missing __init__.py files itself, and rewrites the clone's absolute imports to fully-qualified paths. After switching to it: tests 4/4.
Wall 2: the official template's undeclared dependencies
In a clean pip install qai-hub-models environment, validation died at step one. The Yolo template hard-imports podm, ultralytics, and shapely; none are declared by the base package. Extra trap: the metrics library's distribution name is object-detection-metrics — PyPI's podm package is an unrelated project, and installing it just moves the error. (Also pin setuptools: ≥82 removed pkg_resources, which breaks pytorch-lightning-era dependencies.) Filed upstream as qualcomm/ai-hub-models#363. After installing the three, the same recipe validates 28 passed / 0 failed / 0 warnings.
The takeaway
Onboarding a model to someone else's catalog is a packaging audit wearing an ML costume. The checks that mattered: install into a clean venv, import from the wheel, run the official validator against the installed artifact. The model itself — the part I expected to fight — never objected once.
Top comments (0)