{ "cells": [ { "attachments": {}, "cell_type": "markdown", "id": "df002fab-0e64-4c14-8bfa-30f1aa29a9ff", "metadata": { "tags": [] }, "source": [ "# Using the Edge Impulse Python SDK with Hugging Face\n", "\n", "" ] }, { "attachments": {}, "cell_type": "markdown", "id": "0932ea79-3cbd-4b2f-91ee-632338c5e19b", "metadata": {}, "source": [ "\n", " \n", " \n", " \n", " \n", "
\n", " View on edgeimpulse.com\n", " \n", " Run in Colab\n", " \n", " View source on GitHub\n", " \n", " Download notebook\n", "
" ] }, { "attachments": {}, "cell_type": "markdown", "id": "7583a486-afd6-42d8-934b-fdb33a6f3362", "metadata": { "tags": [] }, "source": [ "🤗 [Hugging Face](https://huggingface.co/) offers a suite of tools that assist with various AI applications. Most notably, they provide a [hub](https://huggingface.co/models) for people to share their pre-trained models. In this tutorial, we will demonstrate how to download a simple [ResNet](https://en.wikipedia.org/wiki/Residual_neural_network) model from the Hugging Face hub, profile it, and convert it to a C++ library for use in your edge application. This particular model was trained to identify species of bean plants using the [bean dataset](https://www.tensorflow.org/datasets/catalog/beans).\n", "\n", "To learn more about using the Python SDK, please see: [Edge Impulse Python SDK Overview](https://docs.edgeimpulse.com/docs/edge-impulse-python-sdk/overview)" ] }, { "cell_type": "code", "execution_count": null, "id": "e0de311a-de4c-4fe1-8dd9-e7b2206217d0", "metadata": {}, "outputs": [], "source": [ "# If you have not done so already, install the following dependencies\n", "!python -m pip install huggingface_hub edgeimpulse" ] }, { "cell_type": "code", "execution_count": null, "id": "2f85b7c9-e76b-459e-ac37-4b348cbb5906", "metadata": { "tags": [] }, "outputs": [], "source": [ "import json\n", "from huggingface_hub import hf_hub_download\n", "import edgeimpulse as ei" ] }, { "attachments": {}, "cell_type": "markdown", "id": "8aef50a1-0a2d-4743-bfc3-de0a9755a87b", "metadata": { "tags": [] }, "source": [ "You will need to obtain an API key from an Edge Impulse project. Log into [edgeimpulse.com](https://edgeimpulse.com/) and create a new project. Open the project, navigate to **Dashboard** and click on the **Keys** tab to view your API keys. Double-click on the API key to highlight it, right-click, and select **Copy**.\n", "\n", "![Copy API key from Edge Impulse project](https://raw.githubusercontent.com/edgeimpulse/notebooks/main/.assets/images/python-sdk-copy-ei-api-key.png)\n", "\n", "Note that you do not actually need to use the project in the Edge Impulse Studio. We just need the API Key.\n", "\n", "Paste that API key string in the `ei.API_KEY` value in the following cell:" ] }, { "cell_type": "code", "execution_count": null, "id": "3429e02d-5188-4215-97c7-5a50b854b06b", "metadata": { "tags": [] }, "outputs": [], "source": [ "# Edge Impulse Settings\n", "ei.API_KEY = \"ei_dae2...\"\n", "target_device = 'cortex-m4f-80mhz'\n", "deploy_filename = \"my_model_cpp.zip\"" ] }, { "attachments": {}, "cell_type": "markdown", "id": "0e1ea5ad-a7fd-4db0-9a38-235d9e324a9f", "metadata": { "tags": [] }, "source": [ "To download a model from the Hugging Face hub, we need to first find a model. Head to [huggingface.co/models](https://huggingface.co/models). On the left side, click **Image Classification** to filter under the *Tasks* tab and under the *Libraries* tab, filter by **ONNX** (as the Edge Impulse Python SDK easily accepts ONNX models). You should see the *resnet-tiny-beans* model trained by user *fxmarty*.\n", "\n", "![Filter models on Hugging Face](https://raw.githubusercontent.com/edgeimpulse/notebooks/main/.assets/images/python-sdk-hugging-face-filter-models.png)\n", "\n", "Click on the *resnet-tiny-beans* entry (or follow [this link](https://huggingface.co/fxmarty/resnet-tiny-beans)) to read about the model and view the files. If you click on the Files* tab, you can see all of the files available in this particular model.\n", "\n", "![View files in Hugging Face model](https://raw.githubusercontent.com/edgeimpulse/notebooks/main/.assets/images/python-sdk-hugging-face-resnet-tiny-beans-files.png)\n", "\n", "Set the name of the repo (username/repo-name) and the file we want to download." ] }, { "cell_type": "code", "execution_count": null, "id": "37f7f296-802e-4943-9837-5b22f4a03e31", "metadata": { "tags": [] }, "outputs": [], "source": [ "# Define file location for our model\n", "repo_name = \"fxmarty/resnet-tiny-beans\"\n", "download_dir = \"./\"\n", "model_filename = \"model.onnx\"\n", "\n", "# Download pre-trained model\n", "hf_hub_download(repo_id=repo_name,\n", " filename=model_filename,\n", " local_dir=download_dir)" ] }, { "attachments": {}, "cell_type": "markdown", "id": "4e04b239-80c6-43e0-87e0-e3a41b8457db", "metadata": { "tags": [] }, "source": [ "## Profile your model\n", "\n", "To start, we need to list the possible target devices we can use for profiling. We need to pick from this list." ] }, { "cell_type": "code", "execution_count": null, "id": "9d87ebdd-a7b1-424f-9af4-49faf765dd79", "metadata": { "tags": [] }, "outputs": [], "source": [ "# List the available profile target devices\n", "ei.model.list_profile_devices()" ] }, { "attachments": {}, "cell_type": "markdown", "id": "ad2db795-4f7d-48e2-bf47-60b146c1bfb2", "metadata": {}, "source": [ "You should see a list printed such as:\n", "\n", "```\n", "['alif-he',\n", " 'alif-hp',\n", " 'arduino-nano-33-ble',\n", " 'arduino-nicla-vision',\n", " 'portenta-h7',\n", " 'brainchip-akd1000',\n", " 'cortex-m4f-80mhz',\n", " 'cortex-m7-216mhz',\n", " ...\n", " 'ti-tda4vm']\n", "```\n", "\n", "A common option is the `cortex-m4f-80mhz`, as this is a relatively low-power microcontroller family. From there, we can use the Edge Impulse Python SDK to generate a profile for your model to ensure it fits on your target hardware and meets your timing requirements." ] }, { "cell_type": "code", "execution_count": null, "id": "e59440ee-1077-4d51-8cfb-8fe213543045", "metadata": { "tags": [] }, "outputs": [], "source": [ "# Estimate the RAM, ROM, and inference time for our model on the target hardware family\n", "try:\n", " profile = ei.model.profile(model=model_filename,\n", " device='cortex-m4f-80mhz')\n", " print(profile.summary())\n", "except Exception as e:\n", " print(f\"Could not profile: {e}\")" ] }, { "attachments": {}, "cell_type": "markdown", "id": "29e4bc88-032a-4d8a-8b3a-4cbf2ec5d778", "metadata": { "tags": [] }, "source": [ "## Deploy your model\n", "\n", "Once you are happy with the performance of the model, you can deploy it to a number of possible hardware targets. To see the available hardware targets, run the following:" ] }, { "cell_type": "code", "execution_count": null, "id": "a9cdd719-e888-40a0-abd0-ab3d487cc43e", "metadata": {}, "outputs": [], "source": [ "# List the available profile target devices\n", "ei.model.list_deployment_targets()" ] }, { "attachments": {}, "cell_type": "markdown", "id": "5eae6c58-c293-43f1-8efc-a76db9b597e2", "metadata": {}, "source": [ "You should see a list printed such as:\n", "\n", "```\n", "['zip',\n", " 'arduino',\n", " 'tinkergen',\n", " 'cubemx',\n", " 'wasm',\n", " ...\n", " 'runner-linux-aarch64-tda4vm']\n", "```\n", "\n", "The most generic target is to download a .zip file containing a C++ library containing the inference runtime and your trained model, so we choose `'zip'` from the above list. We also need to tell Edge Impulse how we are planning to use the model. In this case, we want to perform classification, so we set the output type to Classification.\n", "\n", "Note that instead of writing the raw bytes to a file, you can also specify an `output_directory` argument in the `.deploy()` function. Your deployment file(s) will be downloaded to that directory." ] }, { "cell_type": "code", "execution_count": null, "id": "f45a3c73-fbc2-477a-9f8d-04c3e10b1863", "metadata": { "tags": [] }, "outputs": [], "source": [ "# Create C++ library with trained model\n", "deploy_bytes = None\n", "try:\n", " deploy_bytes = ei.model.deploy(model=model_filename,\n", " model_output_type=ei.model.output_type.Classification(),\n", " deploy_target='zip')\n", "except Exception as e:\n", " print(f\"Could not deploy: {e}\")\n", " \n", "# Write the downloaded raw bytes to a file\n", "if deploy_bytes:\n", " with open(deploy_filename, 'wb') as f:\n", " f.write(deploy_bytes)" ] }, { "attachments": {}, "cell_type": "markdown", "id": "eddfdb39-215c-4f09-88d6-3e9c75ef3603", "metadata": { "tags": [] }, "source": [ "Your model C++ library should be downloaded as the file *my_model_cpp.zip* in the same directory as this notebook. You are now ready to use your C++ model in your embedded and edge device application! To use the C++ model for local inference, see our documentation [here](https://docs.edgeimpulse.com/docs/deployment/running-your-impulse-locally)." ] } ], "metadata": { "kernelspec": { "display_name": "edgeimpulse-EyjE3PPw-py3.10", "language": "python", "name": "edgeimpulse-eyje3ppw-py3.10" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.10.4" } }, "nbformat": 4, "nbformat_minor": 5 }