介绍

这些示例可帮助开发人员使用 QAI AppBuilder + Python Gradio 扩展在 Windows 上的 Snapdragon （WoS） 平台上构建 WebUI AI 应用程序

为 WebUI 应用程序设置环境：

您还可以从 QAI AppBuilder Launcher 运行批处理文件以自动设置环境

1. 第 1 步：安装基本依赖项

请参阅有关如何设置 x64 版本 Python 环境的：QAI AppBuilder快速上手（2）：环境设置（Python x64）

2. 第 2 步：为 WebUI 安装基本的 Python 依赖项
   在 Windows 终端中运行以下命令：

pip install gradio qai_hub_models huggingface_hub Pillow numpy opencv-python torch torchvision torchaudio transformers diffusers

3. 步骤 3：切换到 samples 目录：
   在 Windows 终端中运行以下命令：

cd ai-engine-direct-helper\samples

4. 第 4 步：运行 WebUI 应用程序：

• 运行下表中的命令以启动 WebUI 应用程序
• 您还可以通过双击相应的批处理文件来启动它们：start_ImageRepairApp.bat、start_StableDiffusionApp.bat 和 start_GeneWebUI.bat

4. WebUI 应用程序列表：

应用程序	命令
图像修复应用程序	python webui\ImageRepairApp.py
StableDiffusionApp*	python webui\StableDiffusionApp.py
精灵 WebUI **	python webui\GenieWebUI.py

• StableDiffusionApp 仅支持英文提示

在运行“GenieWebUI.py”之前，请参下文设置LLM

1. 第 1 步：安装依赖项
   请参阅有关如何设置 x64 版本 Python 环境的
2. 步骤 2：为服务安装基本的 Python 依赖项
   在 Windows 终端中运行以下命令：

pip install uvicorn pydantic_settings fastapi langchain langchain_core langchain_community sse_starlette pypdf python-pptx docx2txt openai json-repair

第 3 步：下载模型和分词器文件
下载文件，并将其保存到以下路径。

ai-engine-direct-helper\samples\genie\python\models\<model name>

• 下载模型时选择“Snapdragon® X Elite”作为 WoS 平台的设备。
• 您需要从模型包中解压缩“weight_sharing_model_N_of_N.serialized.bin”文件并将它们复制到以下路径。下载相应的“tokenizer.json”文件并将其复制到以下目录路径。
• 请注意不要混淆不同型号的“tokenizer.json”文件。确保将 IBM Granite 模型对应的 ‘tokenizer.json’ 文件放在 “samples\genie\python\models\IBM-Granite-v3.1-8B” 目录下，将 Phi 3.5 模型对应的 ‘tokenizer.json’ 文件放在 “samples\genie\python\models\Phi-3.5-mini” 目录下。

如果要修改模型文件所在目录的相对路径，需要修改模型对应目录下的“config.json”文件，以确保能够正确找到配置文件中设置的“tokenizer.json”、“htp_backend_ext_config.json”和模型文件。

ai-engine-direct-helper\samples\genie\python\models\<model name>\config.json

您还可以使用自己的 LLM Genie 模型（如果有）。有关详细步骤，请参阅设置自定义模型部件。

4. 第 4 步：切换到 samples 目录
   在 Windows 终端中运行以下命令：

cd ai-engine-direct-helper\samples

5. 步骤 5：运行服务
   运行以下命令启动 Genie API 服务（服务运行时不要关闭此终端窗口）

python genie\python\GenieAPIService.py --modelname "IBM-Granite-v3.1-8B" --loadmodel --profile

该服务打印以下日志，表明 GenieAPIService 启动成功。

INFO:     loading model <<< IBM-Granite-v3.1-8B >>>
[INFO]  "Using create From Binary"
[INFO]  "Allocated total size = 353404160 across 10 buffers"
INFO:     model <<< IBM-Granite-v3.1-8B >>> is ready!
INFO:     model init time: 4.71 (s)
INFO:     Started service process [7608]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8910 (Press CTRL+C to quit)

更多参数：

–all-text：输出所有文本，包括工具调用文本。默认禁用。
–enable-thinking：启用思维模式。默认禁用。
*.建议在使用工具调用功能时禁用思考模式。
.您可以参考有关如何使用工具调用的 GenieAPIClientTools.py。

python genie\python\GenieAPIService.py --modelname "Qwen3.0-8B-v31" --loadmodel --profile --all-text --enable-thinking

6. 第 6 步：现在您可以访问 API 服务

此 API 的默认 IP 地址为：“localhost：8910”，您可以在客户端应用程序中访问此 IP 地址。您可以在新的终端窗口中运行以下 Python。

以下命令从文本提示符生成文本：

python genie\python\GenieAPIClient.py --prompt "How to fish?" --stream

以下命令从文本提示符生成图像：

python genie\python\GenieAPIClientImage.py --prompt "spectacular view of northern lights from Alaska"

• 运行客户端时，可以从服务终端窗口查看处理客户端请求的当前状态。
• 首次运行图像生成请求时，服务可能需要从 AI-Hub 下载 Stable Diffusion 模型，并且需要很长时间。

样品清单：

样本	描述
GenieAPIClient.py	调用 GenieAPIService 生成文本的客户端示例代码
GenieAPIClientTools.py	用于对 GenieAPIService 进行工具调用的客户端示例代码
GenieAPIClientImage.py *	调用 GenieAPIService 生成图像的客户端示例代码
GenieSample.py	使用 GenieContext 在本地进程中加载和运行 LLM 模型

仅 Python 版本的 GenieAPIService 支持图像生成。

• 当您运行“GenieAPIService.py”时，分词器文件将自动下载
• 对于“Phi-3.5-Mini-Instruct”模型，要在输出中查看适当的空格，如果手动下载，请删除“tokenizer.json”文件中的第 192-197 行（剥离规则）。请记住删除第 191 行上多余的逗号。（如果您通过“GenieAPIService.py”下载，Python 脚本将自动修改“tokenizer.json”文件
• 以下是对“Phi-3.5-Mini-Instruct”模型的“tokenizer.json”文件的正确更改：

-      },
-      {
-        "type": "Strip",
-        "content": " ",
-        "start": 1,
-        "stop": 0
-      }
+      }

在运行 ‘GenieAPIService.py’ 之前，请参阅设置 Stable Diffusion v2.1 模型 （我们的 Python 版本 ‘GenieAPIService.py’ 支持生成图像，这取决于 Stable Diffusion v2.1 示例代码。

设置自定义模型：

您可以在路径“ai-engine-direct-helper\samples\genie\python\models”中为自己的模型创建一个子目录，并为您的模型自定义“config.json”和“prompt.conf”文件。这两个文件都应存储在与模型文件相同的目录中。然后使用您创建的新目录作为模型名称，该名称可以在客户端应用程序中使用。

1. config.json ：模型配置文件。它包括模型的关键参数。您可以从这里获取 Llama 2 和 3、Phi 3.5、Qwen 2 等流行模型的几个模板配置文件：

https://github.com/quic/ai-hub-apps/tree/main/tutorials/llm_on_genie/configs/genie

您需要确保配置文件中的以下参数指向正确的文件路径。

• 分词器：模型“tokenizer.json”文件的路径。
• extensions：Genie 扩展配置文件的路径。你可以从路径找到它：

'ai-engine-direct-helper\samples\genie\python\config\htp_backend_ext_config.json'

• ctx-bins：模型上下文 bin 文件（ctx-bins）的路径。通常一个模型有 3~5 个上下文 bin 文件
• forecast-prefix-name：存储 SSD 型号’kv-cache.primary.qnn-htp’文件的目录路径。只有 SSD 型号需要此参数
• 其他参数：根据您的模型设置其他参数

2. prompt.conf ：模型提示格式配置文件。该文件中有两行，分别用于设置 prompt_tags_1 和 prompt_tags_2 参数。完整的提示由以下内容组成：
   提示 = prompt_tags_1 + < 个用户问题 > + prompt_tags_2

以 QWen 2 模型为例，完整的提示示例如下：

<|im_start|>system\nYou are a helpful assistant.<|im_end|>\n<|im_start|>user\nHow to fish?<|im_end|>\n<|im_start|>assistant\n

在这个例子中，用户的问题是“如何钓鱼？因此，我们将问题前的内容提取为 prompt_tags_1 的内容，提取问题后的内容作为 prompt_tags_2 的内容。我们将 ‘promtp.conf’ 的内容设置如下：

prompt_tags_1: <|im_start|>system\nYou are a helpful assistant.<|im_end|>\n<|im_start|>user\n


prompt_tags_2: <|im_end|>\n<|im_start|>assistant\n