shreyajn commited on
Commit
ea0ff4d
1 Parent(s): d697338

Upload README.md with huggingface_hub

Browse files
Files changed (1) hide show
  1. README.md +224 -0
README.md ADDED
@@ -0,0 +1,224 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ datasets:
3
+ - cityscapes
4
+ library_name: pytorch
5
+ license: bsd-3-clause
6
+ pipeline_tag: image-segmentation
7
+ tags:
8
+ - android
9
+
10
+ ---
11
+
12
+ ![](https://qaihub-public-assets.s3.us-west-2.amazonaws.com/qai-hub-models/models/ffnet_54s/web-assets/banner.png)
13
+
14
+ # FFNet-54S: Optimized for Mobile Deployment
15
+ ## Semantic segmentation for automotive street scenes
16
+
17
+ FFNet-54S is a "fuss-free network" that segments street scene images with per-pixel classes like road, sidewalk, and pedestrian. Trained on the Cityscapes dataset.
18
+
19
+ This model is an implementation of FFNet-54S found [here](https://github.com/Qualcomm-AI-research/FFNet).
20
+ This repository provides scripts to run FFNet-54S on Qualcomm® devices.
21
+ More details on model performance across various devices, can be found
22
+ [here](https://aihub.qualcomm.com/models/ffnet_54s).
23
+
24
+
25
+ ### Model Details
26
+
27
+ - **Model Type:** Semantic segmentation
28
+ - **Model Stats:**
29
+ - Model checkpoint: ffnet54S_dBBB_cityscapes_state_dict_quarts
30
+ - Input resolution: 2048x1024
31
+ - Number of parameters: 18.0M
32
+ - Model size: 68.8 MB
33
+
34
+
35
+ | Device | Chipset | Target Runtime | Inference Time (ms) | Peak Memory Range (MB) | Precision | Primary Compute Unit | Target Model
36
+ | ---|---|---|---|---|---|---|---|
37
+ | Samsung Galaxy S23 Ultra (Android 13) | Snapdragon® 8 Gen 2 | TFLite | 25.261 ms | 2 - 5 MB | FP16 | NPU | [FFNet-54S.tflite](https://huggingface.co/qualcomm/FFNet-54S/blob/main/FFNet-54S.tflite)
38
+ | Samsung Galaxy S23 Ultra (Android 13) | Snapdragon® 8 Gen 2 | QNN Model Library | 20.585 ms | 24 - 39 MB | FP16 | NPU | [FFNet-54S.so](https://huggingface.co/qualcomm/FFNet-54S/blob/main/FFNet-54S.so)
39
+
40
+
41
+ ## Installation
42
+
43
+ This model can be installed as a Python package via pip.
44
+
45
+ ```bash
46
+ pip install "qai-hub-models[ffnet_54s]"
47
+ ```
48
+
49
+
50
+
51
+ ## Configure Qualcomm® AI Hub to run this model on a cloud-hosted device
52
+
53
+ Sign-in to [Qualcomm® AI Hub](https://app.aihub.qualcomm.com/) with your
54
+ Qualcomm® ID. Once signed in navigate to `Account -> Settings -> API Token`.
55
+
56
+ With this API token, you can configure your client to run models on the cloud
57
+ hosted devices.
58
+ ```bash
59
+ qai-hub configure --api_token API_TOKEN
60
+ ```
61
+ Navigate to [docs](https://app.aihub.qualcomm.com/docs/) for more information.
62
+
63
+
64
+
65
+ ## Demo off target
66
+
67
+ The package contains a simple end-to-end demo that downloads pre-trained
68
+ weights and runs this model on a sample input.
69
+
70
+ ```bash
71
+ python -m qai_hub_models.models.ffnet_54s.demo
72
+ ```
73
+
74
+ The above demo runs a reference implementation of pre-processing, model
75
+ inference, and post processing.
76
+
77
+ **NOTE**: If you want running in a Jupyter Notebook or Google Colab like
78
+ environment, please add the following to your cell (instead of the above).
79
+ ```
80
+ %run -m qai_hub_models.models.ffnet_54s.demo
81
+ ```
82
+
83
+
84
+ ### Run model on a cloud-hosted device
85
+
86
+ In addition to the demo, you can also run the model on a cloud-hosted Qualcomm®
87
+ device. This script does the following:
88
+ * Performance check on-device on a cloud-hosted device
89
+ * Downloads compiled assets that can be deployed on-device for Android.
90
+ * Accuracy check between PyTorch and on-device outputs.
91
+
92
+ ```bash
93
+ python -m qai_hub_models.models.ffnet_54s.export
94
+ ```
95
+
96
+ ```
97
+ Profile Job summary of FFNet-54S
98
+ --------------------------------------------------
99
+ Device: Samsung Galaxy S23 Ultra (13)
100
+ Estimated Inference Time: 25.26 ms
101
+ Estimated Peak Memory Range: 2.43-4.68 MB
102
+ Compute Units: NPU (113) | Total (113)
103
+
104
+ Profile Job summary of FFNet-54S
105
+ --------------------------------------------------
106
+ Device: Samsung Galaxy S23 Ultra (13)
107
+ Estimated Inference Time: 20.59 ms
108
+ Estimated Peak Memory Range: 24.04-39.17 MB
109
+ Compute Units: NPU (176) | Total (176)
110
+
111
+
112
+ ```
113
+ ## How does this work?
114
+
115
+ This [export script](https://github.com/quic/ai-hub-models/blob/main/qai_hub_models/models/FFNet-54S/export.py)
116
+ leverages [Qualcomm® AI Hub](https://aihub.qualcomm.com/) to optimize, validate, and deploy this model
117
+ on-device. Lets go through each step below in detail:
118
+
119
+ Step 1: **Compile model for on-device deployment**
120
+
121
+ To compile a PyTorch model for on-device deployment, we first trace the model
122
+ in memory using the `jit.trace` and then call the `submit_compile_job` API.
123
+
124
+ ```python
125
+ import torch
126
+
127
+ import qai_hub as hub
128
+ from qai_hub_models.models.ffnet_54s import Model
129
+
130
+ # Load the model
131
+ torch_model = Model.from_pretrained()
132
+ torch_model.eval()
133
+
134
+ # Device
135
+ device = hub.Device("Samsung Galaxy S23")
136
+
137
+ # Trace model
138
+ input_shape = torch_model.get_input_spec()
139
+ sample_inputs = torch_model.sample_inputs()
140
+
141
+ pt_model = torch.jit.trace(torch_model, [torch.tensor(data[0]) for _, data in sample_inputs.items()])
142
+
143
+ # Compile model on a specific device
144
+ compile_job = hub.submit_compile_job(
145
+ model=pt_model,
146
+ device=device,
147
+ input_specs=torch_model.get_input_spec(),
148
+ )
149
+
150
+ # Get target model to run on-device
151
+ target_model = compile_job.get_target_model()
152
+
153
+ ```
154
+
155
+
156
+ Step 2: **Performance profiling on cloud-hosted device**
157
+
158
+ After compiling models from step 1. Models can be profiled model on-device using the
159
+ `target_model`. Note that this scripts runs the model on a device automatically
160
+ provisioned in the cloud. Once the job is submitted, you can navigate to a
161
+ provided job URL to view a variety of on-device performance metrics.
162
+ ```python
163
+ profile_job = hub.submit_profile_job(
164
+ model=target_model,
165
+ device=device,
166
+ )
167
+
168
+ ```
169
+
170
+ Step 3: **Verify on-device accuracy**
171
+
172
+ To verify the accuracy of the model on-device, you can run on-device inference
173
+ on sample input data on the same cloud hosted device.
174
+ ```python
175
+ input_data = torch_model.sample_inputs()
176
+ inference_job = hub.submit_inference_job(
177
+ model=target_model,
178
+ device=device,
179
+ inputs=input_data,
180
+ )
181
+
182
+ on_device_output = inference_job.download_output_data()
183
+
184
+ ```
185
+ With the output of the model, you can compute like PSNR, relative errors or
186
+ spot check the output with expected output.
187
+
188
+ **Note**: This on-device profiling and inference requires access to Qualcomm®
189
+ AI Hub. [Sign up for early access](https://aihub.qualcomm.com/sign-up).
190
+
191
+
192
+
193
+ ## Deploying compiled model to Android
194
+
195
+
196
+ The models can be deployed using multiple runtimes:
197
+ - TensorFlow Lite (`.tflite` export): [This
198
+ tutorial](https://www.tensorflow.org/lite/android/quickstart) provides a
199
+ guide to deploy the .tflite model in an Android application.
200
+
201
+
202
+ - QNN (`.so` export ): This [sample
203
+ app](https://docs.qualcomm.com/bundle/publicresource/topics/80-63442-50/sample_app.html)
204
+ provides instructions on how to use the `.so` shared library in an Android application.
205
+
206
+
207
+ ## View on Qualcomm® AI Hub
208
+ Get more details on FFNet-54S's performance across various devices [here](https://aihub.qualcomm.com/models/ffnet_54s).
209
+ Explore all available models on [Qualcomm® AI Hub](https://aihub.qualcomm.com/)
210
+
211
+ ## License
212
+ - The license for the original implementation of FFNet-54S can be found
213
+ [here](https://github.com/Qualcomm-AI-research/FFNet/blob/master/LICENSE).
214
+ - The license for the compiled assets for on-device deployment can be found [here](https://qaihub-public-assets.s3.us-west-2.amazonaws.com/qai-hub-models/Qualcomm+AI+Hub+Proprietary+License.pdf).
215
+
216
+ ## References
217
+ * [Simple and Efficient Architectures for Semantic Segmentation](https://arxiv.org/abs/2206.08236)
218
+ * [Source Model Implementation](https://github.com/Qualcomm-AI-research/FFNet)
219
+
220
+ ## Community
221
+ * Join [our AI Hub Slack community](https://join.slack.com/t/qualcomm-ai-hub/shared_invite/zt-2dgf95loi-CXHTDRR1rvPgQWPO~ZZZJg) to collaborate, post questions and learn more about on-device AI.
222
+ * For questions or feedback please [reach out to us](mailto:ai-hub-support@qti.qualcomm.com).
223
+
224
+