QAI AppBuilder 的 GenieWebUI 及 GenieAPIService 是助力用户在 Windows on Snapdragon 等平台高效部署本地AI 应用的工具套件。GenieWebUI 是WebUI应用，需先配置好模型（如Qwen2 7B SSD、IBM-Granite-v3.1-8B-Instruct 等），放入指定模型目录后，通过运行对应批处理文件启动，支持文生图、文档处理、多语言交互等功能，可灵活切换适配模型。而GenieAPIService 则提供一些OpenAI API兼容接口，启动对应脚本后，可以本地通过客户端代码调用，或借助第三方应用（如 LangFlow）来进行调用，只需修改 API 端点即可无缝对接本地 NPU 上的大语言模型，支持 C++ 和 Python。QAI AppBuilder 预置部分模型配置，通过自动环境设置脚本简化配置流程，让用户无需复杂操作即可利用本地算力运行大模型，实现从模型部署到应用交互的全流程支持。
前置条件
- 高通 Windows on Snapdragon
操作方法及 步骤：
一、 WebUI 的使用与模型配置
- 配置基础环境
对于快速配置基础环境，我们有完整的批处理文件提供使用，详细的使用说明和方法请参阅：launcher/README.md
为了尝试WebUI+MODEL的使用，我们可以先运行1.Install_QAI_AppBuilder.bat来快速配置好基础环境，下面是运行成功后的目录结构：
准备模型
下载模型到本地，或准备好自己需要使用的模型，里面通常会包含bin、tokenizer.json以及其他json文件。其中bin和tokenizer.json文件是模型本身自带的且无需改动。而config文件也是模型自带的，但需要我们去配置和修改才可以使用。
在上面步骤已经配置的基础环境的ai-engine-direct-helper的仓库中，切换到ai-engine-direct-helper\samples\genie\python\models下。如果所准备的模型在models目录下存在，那么可以直接将这些文件移动到对应的模型目录下；若不存在，则需要我们在models下为模型新建一个目录，并将这些文件移动到该目录下：
这里演示准备的模型是Qwen2.5-3B-Instruct，因此在models下创建了模型目录Qwen2.5-3B用来存放模型文件。
1 、 bin 文件的路径修改
如下图所示，有一些模型的bin文件没有放在根目录下，而是整体存放于子目录下面，并且也没有config.json的文件在模型目录中：
那么就需要我们先将模型的bin文件移动到模型根目录下面
2 、找到和 修改 config 配置信息
由于模型的不同，目录下可能会有很多文件，而config文件通常包含dialog、sampler、tokenizer、engine、model等字段，我们可以打开文件内容进行确认。如果没有找到确定的config文件，可以参阅llm_on_genie/configs找到对应模型的config文件。将config文件更名为config.json。修改config的内容，主要修改config中的路径配置信息：
将tokenizer.path和model.binary.ctx-bins部分的路径修改成
"path" : "genie\\python\\models\\<your_model_dir>\\tokenizer.json"
"ctx-bins" : [
"genie\\python\\models\\<your_model_dir>\\weight_sharing_model_1_of_3.serialized.bin",
"genie\\python\\models\\<your_model_dir>\\weight_sharing_model_2_of_3.serialized.bin",
"genie\\python\\models\\<your_model_dir>\\weight_sharing_model_3_of_3.serialized.bin"
]
将engine.extensions部分的路径修改成
"extensions" : "genie\\python\\config\\htp_backend_ext_config.json"
说明：
WebUI启动后的工作路径统一为ai-engine-direct-helper\samples，因此，修改的路径信息均为其路径的相对路径。
tokenizer.path和model.binary.ctx-bins部分的路径分别指向的是模型的tokenizer.json文件和bin文件，<your_model_dir>部分需要替换为你在models下具体的模型目录名称。还是以演示的Qwen2.5-3B-Instruct为例，就需要替换为所创建的Qwen2.5-3B。
engine.extensions部分的路径所指向的是htp_backend_ext_config.json文件，我们将使用统一的genie\\python\\config\\htp_backend_ext_config.json即可。
3 、添加 prompt 文件
Prompt文件是模型断句及上下文关系的关键，是必须配置的文件。而模型具体使用的标签及模板可以参阅prompt-formats
1 ） 在旧的GenieAPIService版本中，模型仅支持prompt.conf文件。
以Qwen2.5-3B-Instruct为例，我们可以找到Qwen模型使用的标签组合 ，那么可以组合成如下prompt文件内容：
prompt_tags_1: <|im_start|>system\nYou are a helpful AI Assistant<|im_end|><|im_start|>user\n
prompt_tags_2: <|im_end|>\n<|im_start|>assistant\n
说明 ：
将文档中"What is France's capital?"部分的内容替换成"user"，意味着模型可以根据用户的提问进行回答问题；
prompt_tags_1对应"You are a helpful AI Assistant"所在的sample prompt信息行，表示提示助手用户输入的开始，并给模型设定默认的角色； prompt_tags_2对应"assistant"所在的sample prompt信息行，表示提示助手回复的开始。
其他特殊的参照文档部分遵循以角色和标签进行分割尝试即可。
可以根据上述模板同样为其他模型在模型根目录创建prompt.conf文件。
2 ） 在新的GenieAPIService版本中(v2.0.0开始，预计将在9月份发布)，模型仅支持prompt.json文件，需要在模型根目录创建prompt.json文件，其他文件不变。prompt.json 文件定义了模型在接收用户请求时，如何组织系统提示、用户输入、模型回复等信息的输入格式模板。以下是qwen模型的prompt.json文件的格式模板：
{
"prompt_system": "<|im_start|>system\n string <|im_end|>\n",
"prompt_user": "<|im_start|>user\n string <|im_end|>\n",
"prompt_assistant": "<|im_start|>assistant\n string <|im_end|>\n",
"prompt_tool": "<|im_start|>tool\n string <|im_end|>\n",
"prompt_start": "<|im_start|>assistant\n"
}
字段说明：
prompt_system: 系统角色提示的格式模板,string 会被替换为实际的系统提示；
prompt_user: 用户输入的格式模板,string 会被替换为用户的实际问题；
prompt_assistant: 模型回复的格式模板,string 会被替换为模型已生成的历史回复；
prompt_tool: 工具/函数调用返回内容的格式模板,string 为工具返回结果的占位符；
prompt_start: 生成起始标记，表示"轮到模型回复了",末尾不包含结束标记，模型将从此处开始生成文本。
为其他模型配置 prompt.json：
参考项目中的 prompt-formats 文档,查找对应模型的起始和结束标记,通用结构为： <起始标记> 角色名\n 内容占位符（string） <结束标记>\n，角色名有system、user、assistant、tool，进而配置prompt_ system、 prompt_user、 prompt_assistant、 prompt_tool、 prompt_start。 prompt_start表示模型应开始生成回复，通常等于 prompt_assistant 的前半部分（不含 string 和结束标记），注意：有些模型（如 Llama）不需要额外起始标记，可留空或根据 tokenizer 设置特殊 token。
4 、 已准备好的模型及文件目录预览
旧版本GenieAPIService所需的目录结构
新版本GenieAPIService所需的目录结构
运行 GenieWebUI
1 、启动 WebUI
在Launcher目录下运行WebUI启动脚本3.Start_WebUI.bat,在弹出的终端窗口中键入数字"2"并"回车"，等待运行一段时间后自动会弹出WebUI的窗口界面：
2 、选择模型
在页面models中找到自己配置的模型并选中，在右边的Q&A对话框中输入问题并发送即可等待助手回复的信息：
3 、注意事项
若models中没有找到自己配置的模型名称，请确认模型是否配置在ai-engine-direct-helper\samples\genie\python\models目录下且模型目录名称是否正确，若没有问题，则需要检查之前的所有步骤是否都已正确配置。
二、 GenieServe 工具的使用与配置
准备默认模型
在前面的步骤里，已经运行了1.Install_QAI_AppBuilder.bat来配置了基础环境。这里我们需要运行2.Install_LLM_Models.bat脚本，将默认的IBM模型配置在models中，这样可以保证自己没有准备模型的时候，GenieService仍可正确运行。如果已经按照上文配置好自己的模型，可以跳过这一步。
1 、 使用C++程序启动
- 启动 Genie Service
1）运行Start_GenieAPIService.bat一共有两种方式：
双击.bat脚本或在终端脚本目录中不带参数直接执行运行脚本的命令，这种情况下，脚本会使用默认IBM-Granite-v3.1-8B模型来启动Genie API Service：
2）打开终端，进入脚本所在目录，使用"脚本+模型名称"的方式启动Genie Service。这里演示的是Qwen2.5-3B，输入以下命令：
.\4.Start_GenieAPIService.bat "Qwen2.5-3B"
成功启动Genie Service后，切记不要关闭窗口，保持Service一直处于开启状态。
2 、 使用python程序启动
对于已经配置好第一步基础环境的设备，使用python启动service需要以下几个步骤。
打开终端，进入 launcher/env目录，运行pixi shell进入python虚拟环境：
cd <your workdir>launcher/env
pixi shell
然后进入 ai-engine-direct-helper\samples\下，执行启动命令：
python genie\python\GenieAPIService.py
成功启动Genie Service后，同样不要关闭窗口，保持Service一直处于开启状态。
GenieAPIClient 测试
1 、 C++ 方式
启动Genie Service后，可以使用Client工具实现测试
打开一个新的终端窗口，进入工作目录的ai-engine-direct-helper\samples\下，使用命令运行Client：
GenieAPIService\GenieAPIClient.exe --model "Qwen2.5-3B" --prompt "How to fish?" --stream
2 、 Python 方式
打开终端，进入 launcher/env目录，运行pixi shell进入python虚拟环境，然后进入 ai-engine-direct-helper\samples\下，执行以下命令：
python genie\python\GenieAPIClient.py --model "Qwen2.5-3B" --prompt "How to fish?" --stream
