Skip to content

Sharing Models on Hugging Face

After training a surrogate model with ORCA, you can publish it to Hugging Face so that COBRA — or anyone else — can discover and use it directly. Sharing models reduces redundant EM simulations across the community.

Requirements

  • A Hugging Face account
  • The huggingface_hub Python package: pip install huggingface_hub

File structure

Each model repository must contain exactly two files, named exactly like the repository (COBRA looks for <repository name>.onnx, so your-username/tf_octa_c_ports holds tf_octa_c_ports.onnx):

File Description
<repository name>.onnx The exported ONNX surrogate model produced by OnnxExporter
<repository name>.py The Python geometry class (subclass of BaseGeometry) used to generate and train the model

The geometry class file is required so that COBRA can reconstruct the parameter space, call back into the geometry for EM verification, and correctly pre-process inference inputs.

Step-by-step upload

  1. Create a new model repository at https://huggingface.co/new. Set visibility to Public and note the repository ID (e.g. your-username/tf_octa_c_ports, named like the model files). Click on "Create model".

  2. Create a Model Card (essentially just a structured README) for your repository. Click on "Add Model Card". From there, add the tag orca-rfic to make it discoverable by COBRA and other users looking for ORCA models. The model card should then include this section:

    ---
    tags:
    - orca-rfic
    
  3. Upload the files using the huggingface_hub library:

    from huggingface_hub import HfApi
    
    api = HfApi()
    repo_id = "your-username/tf_octa_c_ports"  # replace with your repo
    
    api.upload_file(path_or_fileobj="tf_octa_c_ports.onnx", path_in_repo="tf_octa_c_ports.onnx", repo_id=repo_id)
    api.upload_file(path_or_fileobj="tf_octa_c_ports.py",   path_in_repo="tf_octa_c_ports.py",   repo_id=repo_id)
    

    Or via the Hugging Face web interface: go to your repository → Files → Add file → Upload files.

  4. Verify the repository contains both <repository name>.onnx and <repository name>.py and is tagged orca-rfic.

Using a shared model in COBRA

Once uploaded, COBRA can query all public orca-rfic models or load a specific one directly by its Hugging Face repository ID. Refer to the COBRA documentation for details on how to point COBRA at a Hugging Face model repository.