第一部分：基础环境安装

在开始之前，请确保您的系统中已安装以下核心软件。如果您已经安装，可以跳至第二部分。

1.1 安装 Python 3.12

目的： 本项目依赖 Python 3.12 版本。QAI AppBuilder 的预编译包 (.whl) 也是针对此版本构建的。

1. 下载安装程序：访问 Python 官方网站下载 3.12.8 版本的 Windows 安装程序：Python for Windows。

2. 执行安装：

• 运行下载的 .exe 文件。

• 关键步骤： 在安装界面的第一页，务必勾选 “Add Python 3.12 to PATH” 选项。

• 然后点击 “Install Now” 并按照默认设置完成安装。

1.2 安装 Git

目的： Git 是用于从 GitHub 克隆（下载）项目源代码的版本控制工具。

1. 下载安装程序：访问 Git 官网下载页面：Git for Windows。

2. 执行安装：运行下载的 .exe 文件，在安装过程中使用默认选项（一路点击 “Next”）即可。

第二部分：项目设置与依赖安装

环境准备就绪后，我们将开始创建项目环境、下载代码并安装所有必需的库。

2.1 创建并激活 Python 虚拟环境

目的： 使用虚拟环境可以为本项目创建一个独立、隔离的 Python 环境，避免与系统中其他项目产生依赖冲突。

1. 打开 Windows 终端：使用快捷键 Windows + X，选择 “终端 (管理员)”。

2. 创建并激活虚拟环境：

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

   注意: 后续所有命令都应在这个已激活的虚拟环境中执行。如果关闭了终端，下次需要重新进入此目录并执行激活命令。

2.2 安装 QAI AppBuilder

1. 下载 QAI AppBuilder 包：

• 访问项目的 GitHub Releases 页面：AI Engine Direct Helper Releases。

• 在页面中找到与您系统和 Python 版本匹配的 .whl 文件。例如 qai_appbuilder-2.34.0-cp312-cp312-win_amd64.whl。

• 将下载的 .whl 文件放置到您方便访问的目录。

2. 安装 .whl 文件：

   # 确保路径正确pip install .\qai_appbuilder-2.34.0-cp312-cp312-win_amd64.whl

2.3 安装核心 Python 依赖项

目的： 为项目安装所有必需的第三方库，如 Web 框架、AI 模型库等。

在已激活虚拟环境的终端中，运行以下命令一次性安装所有依赖。

pip install uvicorn py3-wget pydantic_settings fastapi langchain langchain_core langchain_community sse_starlette ^
pypdf python-pptx docx2txt openai requests wget tqdm importlib-metadata qai-hub qai_hub_models huggingface_hub ^
Pillow numpy opencv-python torch torchvision torchaudio transformers diffusers basicsr ultralytics==8.0.193 gradio==5.30.0

第三部分：项目代码部署与运行

3.1 下载 QAI AppBuilder 示例代码

1. 克隆代码仓库：在您的工作目录中，运行以下命令克隆包含所有示例代码的主仓库。--recursive 参数至关重要，它会一并下载项目依赖的子模块。

   git clone https://github.com/quic/ai-engine-direct-helper.git --recursive

2. （可选）更新代码：如果您之前已经克隆过此仓库，可以进入项目目录并运行以下命令来更新到最新版本：

   cd ai-engine-direct-helper
   git pull --recurse-submodules

3.2 运行项目初始化脚本

目的： 此脚本会进一步配置环境。

cd ai-engine-direct-helper\samples
python python\setup.py

3.3 放置 Qwen 模型文件

目的： 将预先准备好的 Qwen 模型文件放置到项目指定的目录中。

1. 下载并准备模型文件：下载模型 Qwen2.5-3B-Instruct-qptq_250714.zip，并解压得到 Qwen2.5-3B-Instruct-qptq_250714 文件夹。

2. 放置模型文件夹：将解压后的文件夹复制或移动到以下目标路径： ai-engine-direct-helper\samples\genie\python\models\。如果提示已存在，请选择“替换目标中的文件”。

3. 放置配置文件：从附件下载 config.json 和 prompt.conf，并放入刚刚放置的 Qwen2.5-3B-Instruct-qptq_250714 文件夹内。

3.4 启动 Genie WebUI

所有准备工作就绪，现在可以启动聊天机器人 Web 界面了。

1. 运行启动脚本：确保您当前的终端路径位于 ai-engine-direct-helper\samples 目录下，然后执行：

   python webui\GenieWebUI.py

2. 访问 Web 界面：

   

   等待模型加载成功后，即可开始对话。

   

• 启动成功后，终端会显示类似 Running on local URL: http://127.0.0.1:8976 的信息。

• 在您的浏览器中打开该 URL。

• 在 Web 界面中，选择加载 Qwen2.5-3B-Instruct-qptq_250714 模型。