入門指南

安裝

我們推薦的 Python 環境取決於您的平台：

步驟 1：Python 環境（Windows x86-64, macOS, Linux）

我們建議使用 Miniconda 來管理您的 Python 版本與環境。請在您的機器上安裝 miniconda。

Windows：安裝完成後，從開始選單中啟動 Anaconda Prompt。

macOS/Linux：安裝完成後，啟動一個新的 shell 視窗程序。

為 Qualcomm® AI Hub Workbench 建立環境：

conda create python=3.10 -n qai_hub
conda activate qai_hub

步驟 1：Python 環境（Windows on ARM）

Miniconda 並未原生支援 Windows on ARM（例如：Snapdragon X Elite）。我們建議直接從 Python download page 下載 Windows ARM64 版本的 Python。在此情況下，需使用 Python 3.11 或更高版本。

設定 Qualcomm® AI Hub 的環境：

python -m venv qai_hub
.\qai_hub\Scripts\activate

警告

如果在任何步驟中出現 SSL: CERTIFICATE_VERIFY_FAILED 或 self-signed certificate 錯誤，您可能安裝了 SSL 攔截與流量檢查工具。請向您的 IT 部門索取一組內部信任的 PEM 格式憑證（通常為 .pem 或 .``.crt`` 檔案）。接著，您需要在建立環境之前，使用該憑證來設定 Python 的 pip 以及 Python 的 Requests 函式庫：

• Miniconda: conda config --set ssl_verify <path to certificate>

• 直接使用 Python：將環境變數 REQUESTS_CA_BUNDLE 設定為憑證路徑。

步驟 2：安裝 Python 客戶端

pip3 install qai-hub

步驟 3：登錄

前往 Qualcomm® AI Hub Workbench，並使用您的 Qualcomm ID 登入，以檢視您建立的工作相關資訊。

登錄後，導航到 Account -> Settings -> API Token。這應該會提供一個 API Token，您可以用來配置您的客戶端。

步驟 4，選項 A（推薦）：設定持久性 API Token

在您的工作站上設定客戶端，並將 API Token 永久保存。您只需要執行一次。這是使用 Qualcomm® AI Hub Workbench 的建議方式。

請在終端機中執行以下指令：

qai-hub configure --api_token INSERT_API_TOKEN

您可以透過取得可用裝置的清單來確認 API token 是否正確安裝。請在 Python 終端機中輸入以下內容：

import qai_hub as hub
client = hub.Client()
client.get_devices()

如果您選擇此方式，就不需要執行下方的選項 B。

步驟 4，選項 B（適用於短暫環境）：設定 Session API Token

在臨時性客戶環境（例如 Amazon SageMaker）中，因為無法將 API Token 永久儲存在磁碟上，您需要在每次使用時重新設定 AI Hub Workbench 客戶端。

在匯入 Qualcomm® AI Hub Workbench 客戶端後，請提供您的 API Token。例如：

import qai_hub as hub
client_config = hub.ClientConfig(api_token="INSERT_API_TOKEN")
client = hub.Client(client_config)

您可以透過取得可用裝置的清單來確認 API token 是否正常運作。請在初始化用戶端後，將以下程式碼加入您的 Python 腳本中：

client.get_devices()

使用此 token 設定方式初始化 session 時，您每次都必須提供 API token。

您現在已完成在 Qualcomm® AI Hub Workbench 上提交工作的設定。如果遇到任何問題，請 聯絡我們。歡迎嘗試以下範例，在您選擇的裝置上執行分析工作。

快速示例 (PyTorch)

一旦您完成設定 Qualcomm® AI Hub Workbench 環境，下一步就是提交一個 profiling 工作。首先，安裝此範例所需的相依套件：

pip3 install "qai-hub[torch]"

警告

如果任何代碼因 API 身份驗證錯誤而失敗，則表示您沒有安裝有效的 API Token。請參閱 安裝 了解如何設置。

提交對您選擇的設備類型上的 MobileNet v2 網絡的分析。您可以使用上面列表中的任何設備來指定不同於以下選項的設備。

移動設備

import numpy as np
import requests
import torch
from PIL import Image
from torchvision.models import mobilenet_v2

import qai_hub as hub

client = hub.Client()

# Using pre-trained MobileNet
torch_model = mobilenet_v2(pretrained=True)
torch_model.eval()

# Step 1: Trace model
input_shape = (1, 3, 224, 224)
example_input = torch.rand(input_shape)
traced_torch_model = torch.jit.trace(torch_model, example_input)

# Step 2: Compile model
compile_job = client.submit_compile_job(
    model=traced_torch_model,
    device=hub.Device("Samsung Galaxy S24 (Family)"),
    input_specs=dict(image=input_shape),
    options="--target_runtime tflite",
)
assert isinstance(compile_job, hub.CompileJob)

# Step 3: Profile on cloud-hosted device
target_model = compile_job.get_target_model()
assert isinstance(target_model, hub.Model)
profile_job = client.submit_profile_job(
    model=target_model,
    device=hub.Device("Samsung Galaxy S24 (Family)"),
)
assert isinstance(profile_job, hub.ProfileJob)


# Step 4: Run inference on cloud-hosted device
sample_image_url = (
    "https://qaihub-public-assets.s3.us-west-2.amazonaws.com/apidoc/input_image1.jpg"
)
response = requests.get(sample_image_url, stream=True)
response.raw.decode_content = True
image = Image.open(response.raw).resize((224, 224))
input_array = np.expand_dims(
    np.transpose(np.array(image, dtype=np.float32) / 255.0, (2, 0, 1)), axis=0
)

# Run inference using the on-device model on the input image
inference_job = client.submit_inference_job(
    model=target_model,
    device=hub.Device("Samsung Galaxy S24 (Family)"),
    inputs=dict(image=[input_array]),
)
assert isinstance(inference_job, hub.InferenceJob)

on_device_output = inference_job.download_output_data()
assert isinstance(on_device_output, dict)

# Step 5: Post-processing the on-device output
output_name = list(on_device_output.keys())[0]
out = on_device_output[output_name][0]
on_device_probabilities = np.exp(out) / np.sum(np.exp(out), axis=1)

# Read the class labels for imagenet
sample_classes = "https://qaihub-public-assets.s3.us-west-2.amazonaws.com/apidoc/imagenet_classes.txt"
response = requests.get(sample_classes, stream=True)
response.raw.decode_content = True
categories = [str(s.strip()) for s in response.raw]

# Print top five predictions for the on-device model
print("Top-5 On-Device predictions:")
top5_classes = np.argsort(on_device_probabilities[0], axis=0)[-5:]
for c in reversed(top5_classes):
    print(f"{c} {categories[c]:20s} {on_device_probabilities[0][c]:>6.1%}")

# Step 6: Download model
target_model = compile_job.get_target_model()
assert isinstance(target_model, hub.Model)
target_model.download("mobilenet_v2.tflite")

IOT

import numpy as np
import requests
import torch
from PIL import Image
from torchvision.models import mobilenet_v2

import qai_hub as hub

client = hub.Client()

# Using pre-trained MobileNet
torch_model = mobilenet_v2(pretrained=True)
torch_model.eval()

# Step 1: Trace model
input_shape = (1, 3, 224, 224)
example_input = torch.rand(input_shape)
traced_torch_model = torch.jit.trace(torch_model, example_input)

# Step 2: Compile model
compile_job = client.submit_compile_job(
    model=traced_torch_model,
    device=hub.Device("RB3 Gen 2 (Proxy)"),
    input_specs=dict(image=input_shape),
    options="--target_runtime tflite",
)
assert isinstance(compile_job, hub.CompileJob)


# Step 3: Profile on cloud-hosted device
target_model = compile_job.get_target_model()
assert isinstance(target_model, hub.Model)
profile_job = client.submit_profile_job(
    model=target_model,
    device=hub.Device("RB3 Gen 2 (Proxy)"),
)
assert isinstance(profile_job, hub.ProfileJob)


# Step 4: Run inference on cloud-hosted device
sample_image_url = (
    "https://qaihub-public-assets.s3.us-west-2.amazonaws.com/apidoc/input_image1.jpg"
)
response = requests.get(sample_image_url, stream=True)
response.raw.decode_content = True
image = Image.open(response.raw).resize((224, 224))
input_array = np.expand_dims(
    np.transpose(np.array(image, dtype=np.float32) / 255.0, (2, 0, 1)), axis=0
)

# Run inference using the on-device model on the input image
inference_job = client.submit_inference_job(
    model=target_model,
    device=hub.Device("RB3 Gen 2 (Proxy)"),
    inputs=dict(image=[input_array]),
)
assert isinstance(inference_job, hub.InferenceJob)

on_device_output = inference_job.download_output_data()
assert isinstance(on_device_output, dict)

# Step 5: Post-processing the on-device output
output_name = list(on_device_output.keys())[0]
out = on_device_output[output_name][0]
on_device_probabilities = np.exp(out) / np.sum(np.exp(out), axis=1)

# Read the class labels for imagenet
sample_classes = "https://qaihub-public-assets.s3.us-west-2.amazonaws.com/apidoc/imagenet_classes.txt"
response = requests.get(sample_classes, stream=True)
response.raw.decode_content = True
categories = [str(s.strip()) for s in response.raw]

# Print top five predictions for the on-device model
print("Top-5 On-Device predictions:")
top5_classes = np.argsort(on_device_probabilities[0], axis=0)[-5:]
for c in reversed(top5_classes):
    print(f"{c} {categories[c]:20s} {on_device_probabilities[0][c]:>6.1%}")

# Step 6: Download model
target_model = compile_job.get_target_model()
assert isinstance(target_model, hub.Model)
target_model.download("mobilenet_v2.tflite")

計算設備

import numpy as np
import requests
import torch
from PIL import Image
from torchvision.models import mobilenet_v2

import qai_hub as hub

client = hub.Client()

# Using pre-trained MobileNet
torch_model = mobilenet_v2(pretrained=True)
torch_model.eval()

# Step 1: Trace model
input_shape = (1, 3, 224, 224)
example_input = torch.rand(input_shape)
traced_torch_model = torch.jit.trace(torch_model, example_input)

# Step 2: Compile model
compile_job = client.submit_compile_job(
    model=traced_torch_model,
    device=hub.Device("Snapdragon X Elite CRD"),
    input_specs=dict(image=input_shape),
    options="--target_runtime onnx",
)
assert isinstance(compile_job, hub.CompileJob)

# Step 3: Profile on cloud-hosted device
target_model = compile_job.get_target_model()
assert isinstance(target_model, hub.Model)
profile_job = client.submit_profile_job(
    model=target_model,
    device=hub.Device("Snapdragon X Elite CRD"),
)
assert isinstance(profile_job, hub.ProfileJob)


# Step 4: Run inference on cloud-hosted device
sample_image_url = (
    "https://qaihub-public-assets.s3.us-west-2.amazonaws.com/apidoc/input_image1.jpg"
)
response = requests.get(sample_image_url, stream=True)
response.raw.decode_content = True
image = Image.open(response.raw).resize((224, 224))
input_array = np.expand_dims(
    np.transpose(np.array(image, dtype=np.float32) / 255.0, (2, 0, 1)), axis=0
)

# Run inference using the on-device model on the input image
inference_job = client.submit_inference_job(
    model=target_model,
    device=hub.Device("Snapdragon X Elite CRD"),
    inputs=dict(image=[input_array]),
)
assert isinstance(inference_job, hub.InferenceJob)

on_device_output = inference_job.download_output_data()
assert isinstance(on_device_output, dict)

# Step 5: Post-processing the on-device output
output_name = list(on_device_output.keys())[0]
out = on_device_output[output_name][0]
on_device_probabilities = np.exp(out) / np.sum(np.exp(out), axis=1)

# Read the class labels for imagenet
sample_classes = "https://qaihub-public-assets.s3.us-west-2.amazonaws.com/apidoc/imagenet_classes.txt"
response = requests.get(sample_classes, stream=True)
response.raw.decode_content = True
categories = [str(s.strip()) for s in response.raw]

# Print top five predictions for the on-device model
print("Top-5 On-Device predictions:")
top5_classes = np.argsort(on_device_probabilities[0], axis=0)[-5:]
for c in reversed(top5_classes):
    print(f"{c} {categories[c]:20s} {on_device_probabilities[0][c]:>6.1%}")

# Step 6: Download model
target_model = compile_job.get_target_model()
assert isinstance(target_model, hub.Model)
target_model.download("mobilenet_v2.onnx")

汽車設備

import numpy as np
import requests
import torch
from PIL import Image
from torchvision.models import mobilenet_v2

import qai_hub as hub

client = hub.Client()

# Using pre-trained MobileNet
torch_model = mobilenet_v2(pretrained=True)
torch_model.eval()

# Step 1: Trace model
input_shape = (1, 3, 224, 224)
example_input = torch.rand(input_shape)
traced_torch_model = torch.jit.trace(torch_model, example_input)

# Step 2: Compile model
compile_job = client.submit_compile_job(
    model=traced_torch_model,
    device=hub.Device("SA8650 (Proxy)"),
    input_specs=dict(image=input_shape),
    options="--target_runtime qnn_dlc",
)
assert isinstance(compile_job, hub.CompileJob)

# Step 3: Profile on cloud-hosted device
target_model = compile_job.get_target_model()
assert isinstance(target_model, hub.Model)
profile_job = client.submit_profile_job(
    model=target_model,
    device=hub.Device("SA8650 (Proxy)"),
)
assert isinstance(profile_job, hub.ProfileJob)

# Step 4: Run inference on cloud-hosted device
sample_image_url = (
    "https://qaihub-public-assets.s3.us-west-2.amazonaws.com/apidoc/input_image1.jpg"
)
response = requests.get(sample_image_url, stream=True)
response.raw.decode_content = True
image = Image.open(response.raw).resize((224, 224))
input_array = np.expand_dims(
    np.transpose(np.array(image, dtype=np.float32) / 255.0, (2, 0, 1)), axis=0
)

# Run inference using the on-device model on the input image
inference_job = client.submit_inference_job(
    model=target_model,
    device=hub.Device("SA8650 (Proxy)"),
    inputs=dict(image=[input_array]),
)
assert isinstance(inference_job, hub.InferenceJob)

on_device_output = inference_job.download_output_data()
assert isinstance(on_device_output, dict)

# Step 5: Post-processing the on-device output
output_name = list(on_device_output.keys())[0]
out = on_device_output[output_name][0]
on_device_probabilities = np.exp(out) / np.sum(np.exp(out), axis=1)

# Read the class labels for imagenet
sample_classes = "https://qaihub-public-assets.s3.us-west-2.amazonaws.com/apidoc/imagenet_classes.txt"
response = requests.get(sample_classes, stream=True)
response.raw.decode_content = True
categories = [str(s.strip()) for s in response.raw]

# Print top five predictions for the on-device model
print("Top-5 On-Device predictions:")
top5_classes = np.argsort(on_device_probabilities[0], axis=0)[-5:]
for c in reversed(top5_classes):
    print(f"{c} {categories[c]:20s} {on_device_probabilities[0][c]:>6.1%}")

# Step 6: Download model
target_model = compile_job.get_target_model()
assert isinstance(target_model, hub.Model)
target_model.download("mobilenet_v2.so")

這將提交一個編譯作業，然後提交一個分析文件作業，印出兩個作業的 URL。最後，代碼在一些示例數據上執行推理作業。在 /jobs/ 查看您所有的作業。

您可以透過程式查詢作業的狀態：

status = profile_job.get_status()
print(status)

您可以使用以下代碼訪問作業結果。主要有三個部分

• 分析文件: JSON 格式的分析文件結果。

• 目標模型: 已優化的模型，準備部署。

• 結果: 包含作業所有工件（包括日誌）的文件夾。

請注意，這些是同步API ，調用後會等待作業完成：

• 下載分析結果（JSON 格式，同步呼叫）

profile = profile_job.download_profile()
print(profile)

• 下載最佳化模型（同步呼叫）

compile_job.model.download("model_filename")

• 將結果下載至目前目錄（同步呼叫）

profile_job.download_results(".")

欲了解更多信息，請繼續參閱 分析模型 或參考 API documentation。