Phi-3-mini-128k-instruct实战：使用Qt开发跨平台AI桌面应用

Phi-3-mini-128k-instruct实战：使用Qt开发跨平台AI桌面应用

最近在捣鼓一些本地AI应用，发现很多开发者朋友对如何把大模型塞进自己的桌面程序里很感兴趣。特别是用C++和Qt的，总觉得这块门槛有点高。其实没那么复杂，我今天就用微软开源的Phi-3-mini-128k-instruct模型，带大家走一遍完整的流程。

Phi-3-mini是个轻量级但能力不错的模型，128k的上下文也够应付很多场景了。咱们的目标很明确：不用管复杂的模型推理框架，直接通过HTTP调用本地的模型服务，用Qt快速搭一个带界面的聊天工具出来。最后还能打包成独立应用，在Windows、Linux或者macOS上都能直接运行。

如果你会一点C++和Qt基础，跟着做下来，一两个小时就能看到效果。整个过程就像给现有的模型服务套个壳，重点是Qt这边怎么去调用和展示。

1. 先让模型服务跑起来

在写Qt代码之前，咱们得先有个能对话的模型服务。这里假设你已经按照Phi-3-mini的官方说明，用类似Ollama、LM Studio或者vLLM这样的工具把模型部署好了。我以Ollama为例，因为它比较简单。

打开你的终端，输入下面这条命令拉取并运行模型：

ollama run phi3:mini-128k-instruct

第一次运行会下载模型，需要点时间。跑起来之后，你应该能看到终端提示模型已经加载成功，并进入一个交互式对话界面。先别急着在这里聊天，咱们需要的是它的API服务。

Ollama默认会在http://localhost:11434提供一个HTTP API。为了验证服务是否正常，我们可以用curl快速测试一下：

curl http://localhost:11434/api/generate -d '{ "model": "phi3:mini-128k-instruct", "prompt": "你好，请介绍一下你自己。", "stream": false }'

如果返回了一段包含模型回复的JSON数据，比如{"response": "你好！我是Phi-3-mini..."}，那就说明一切就绪，模型服务在本地11434端口上等着被调用呢。

这一步的关键是确保这个服务进程一直开着，我们的Qt程序才能找到它。你可以把它放在后台运行，或者单独开一个终端窗口挂着。

2. 搭建Qt项目的基本框架

接下来，打开你的Qt Creator，我们来创建一个新项目。选择Qt Widgets Application，给项目起个名字，比如Phi3DesktopAssistant。在选择组件的页面，记得勾选上Network模块，这个待会儿用来发HTTP请求，必不可少。

项目创建好后，你会看到主窗口类（通常是MainWindow）的文件。我们先来设计一个最简单的界面。打开mainwindow.ui文件，从左侧的部件盒子里拖拽以下控件到窗体上：

1. 一个QTextEdit：放在上面，作为我们输入问题（Prompt）的区域。可以把它的placeholderText属性设为“在这里输入你的问题...”。
2. 一个QPushButton：放在输入框右边或下面，文本改成“发送”或者“提问”。点击它就会触发请求。
3. 另一个QTextEdit：放在界面下方，用来显示模型的回复。把它的readOnly属性勾选上，因为这只是用来展示结果的。
4. 一个QLabel：可以放在最下面，用来显示一些状态信息，比如“正在思考...”或“就绪”。

排布差不多后，记得用布局管理器（比如垂直布局Vertical Layout）把控件组织一下，这样窗口缩放时界面不会乱。一个简单的设计草图是这样的：上面是输入框和按钮，中间是回复展示区，最下面是状态栏。

界面设计好之后，我们需要为“发送”按钮添加点击事件的响应。在Qt Creator里，右键点击按钮，选择“转到槽...”，然后选中clicked()信号。这会在mainwindow.cpp里自动生成一个槽函数，比如on_pushButton_clicked()。我们主要的逻辑就会写在这里。

3. 编写核心的网络请求逻辑

模型服务和界面都有了，现在要把它们连起来。核心就是用Qt的网络模块，向http://localhost:11434/api/generate发送一个POST请求，并把输入框的文本传过去。

首先，在mainwindow.h文件里，包含必要的头文件，并声明网络管理器和一些必要的槽函数：

#include <QMainWindow> #include <QNetworkAccessManager> #include <QNetworkReply> namespace Ui { class MainWindow; } class MainWindow : public QMainWindow { Q_OBJECT public: explicit MainWindow(QWidget *parent = nullptr); ~MainWindow(); private slots: void on_pushButton_clicked(); // 发送按钮的槽函数 void onReplyFinished(QNetworkReply *reply); // 网络请求完成的槽函数 private: Ui::MainWindow *ui; QNetworkAccessManager *networkManager; // 网络访问管理器 };

接着，在mainwindow.cpp的构造函数里，初始化networkManager：

#include "mainwindow.h" #include "ui_mainwindow.h" #include <QJsonDocument> #include <QJsonObject> #include <QJsonArray> #include <QNetworkRequest> #include <QMessageBox> MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent), ui(new Ui::MainWindow), networkManager(new QNetworkAccessManager(this)) { ui->setupUi(this); // 连接网络请求完成信号到我们的槽函数 connect(networkManager, &QNetworkAccessManager::finished, this, &MainWindow::onReplyFinished); } MainWindow::~MainWindow() { delete ui; }

现在，实现发送按钮的槽函数on_pushButton_clicked()：

void MainWindow::on_pushButton_clicked() { QString prompt = ui->inputTextEdit->toPlainText().trimmed(); if (prompt.isEmpty()) { QMessageBox::information(this, "提示", "请输入问题内容。"); return; } // 更新UI状态，提示用户正在处理 ui->statusLabel->setText("正在思考..."); ui->pushButton->setEnabled(false); // 禁用按钮，防止重复发送 // 构造请求的JSON数据 QJsonObject json; json["model"] = "phi3:mini-128k-instruct"; json["prompt"] = prompt; json["stream"] = false; // 我们使用非流式响应，一次性获取全部内容 QJsonDocument doc(json); QByteArray data = doc.toJson(); // 设置网络请求 QNetworkRequest request(QUrl("http://localhost:11434/api/generate")); request.setHeader(QNetworkRequest::ContentTypeHeader, "application/json"); // 发起POST请求 networkManager->post(request, data); }

最后，实现处理响应的槽函数onReplyFinished：

void MainWindow::onReplyFinished(QNetworkReply *reply) { // 无论成功失败，先恢复按钮状态 ui->pushButton->setEnabled(true); if (reply->error() == QNetworkReply::NoError) { // 读取返回的JSON数据 QByteArray responseData = reply->readAll(); QJsonDocument jsonResponse = QJsonDocument::fromJson(responseData); QJsonObject jsonObject = jsonResponse.object(); if (jsonObject.contains("response")) { QString modelResponse = jsonObject["response"].toString(); ui->responseTextEdit->setPlainText(modelResponse); ui->statusLabel->setText("就绪"); } else { ui->responseTextEdit->setPlainText("错误：未在返回数据中找到'response'字段。\n" + responseData); ui->statusLabel->setText("响应解析错误"); } } else { // 处理网络错误 ui->responseTextEdit->setPlainText("请求失败：\n" + reply->errorString()); ui->statusLabel->setText("请求失败"); // 可以更详细地检查是否是模型服务未启动 if (reply->error() == QNetworkReply::ConnectionRefusedError) { ui->responseTextEdit->append("\n\n提示：请确保Ollama服务正在运行（localhost:11434）。"); } } reply->deleteLater(); // 重要：释放reply对象 }

到这里，核心功能就完成了。编译并运行你的程序，在输入框里敲点问题，点击发送，应该就能在下面的框里看到Phi-3模型的回复了。

4. 打磨一下用户体验

基础功能跑通后，我们可以加点小功能让它更好用。

添加一个清空按钮：在UI上再放一个按钮，文本叫“清空”。给它创建槽函数，里面写两行代码：ui->inputTextEdit->clear();和ui->responseTextEdit->clear();。这样就能快速开始新一轮对话。

让回复显示更舒服：可以设置responseTextEdit的字体，比如用个等宽字体Courier New，这样看代码或格式化的内容会更整齐。在构造函数里加一句：ui->responseTextEdit->setFont(QFont("Courier New", 10));。

处理长文本的滚动：当回复很长时，自动滚动到底部能看到最新内容。在onReplyFinished函数里，设置完文本后加一句：ui->responseTextEdit->ensureCursorVisible();。

保存对话记录：这是个很有用的进阶功能。可以添加一个“保存”按钮，点击后将当前问答保存到文件。简单实现的话，可以用QFileDialog让用户选个保存位置，然后把inputTextEdit和responseTextEdit的内容写到文本文件里。

做这些优化的时候，不用追求一步到位，先让主要功能稳定，再一点点往上加。每加一个小功能，都编译运行测试一下，确保没引入新的问题。

5. 打包成独立的可执行文件

开发完了，我们肯定不想每次都开着Qt Creator来运行。Qt提供了工具，可以把程序打包成能在其他电脑上独立运行的软件包。

第一步：以Release模式编译。在Qt Creator左下角，将构建套件从Debug切换到Release，然后点击构建。这会在你的项目构建目录（比如build-Phi3DesktopAssistant-Release）里生成一个优化过的、不带调试信息的可执行文件（.exe或.out）。

第二步：找到依赖的DLL（Windows）。光有.exe文件还不行，它需要一堆Qt的动态链接库。最简单的方法是使用Qt自带的命令行工具windeployqt（Windows）或macdeployqt（macOS）。打开Qt 5.15.2 (MinGW 8.1.0 64-bit)这样的终端，切换到你的Release版.exe文件所在的目录，然后运行：

windeployqt --release Phi3DesktopAssistant.exe

这个命令会自动扫描你的exe文件需要哪些Qt模块的DLL，并把它们都复制到当前文件夹。对于Linux，情况稍微复杂，通常需要将程序打包成AppImage、Snap或者直接提供编译好的二进制文件加安装脚本。

第三步：整理和测试。windeployqt会拉进来很多文件。你可以新建一个文件夹，比如叫Phi3Assistant_Release，把.exe文件和它生成的所有.dll、.qm等文件都放进去。然后，在另外一台没有安装Qt开发环境的电脑上，或者至少在一个全新的目录下，双击这个.exe文件，看看能不能正常运行。如果能成功启动并调用本地的模型服务，那打包就基本成功了。

关于模型服务的提醒：我们打包的只是Qt客户端程序。Phi-3模型服务（Ollama）需要用户在自己的电脑上单独安装和运行。你可以在程序里加个更明显的提示，或者在README文件里写清楚这一点。

6. 实际用起来的感受和延伸想法

把这个小工具跑起来之后，我感觉最大的好处就是“方便”。不用开浏览器，不用记API地址，一个独立的桌面窗口，随用随开。对于经常需要和本地模型交互的场景，比如写代码时查个语法、快速翻译一段文字、或者整理一些想法，还是挺顺手的。

当然，现在这个版本还很简单。如果你有兴趣继续深化，有几个方向可以考虑：

一个是界面美化，Qt的样式表（QSS）功能很强大，可以轻松做出现代化的界面。另一个是功能增强，比如支持多轮对话历史（需要程序里维护一个上下文列表发给模型）、支持不同的模型参数（如temperature、max_tokens）、或者把对话记录做成带时间戳的日志。

还有一个更实用的点，就是错误处理和稳定性。比如网络中断后自动重试、模型服务未启动时给出更明确的引导提示、或者支持用户自定义模型服务的IP和端口。这些都能让这个小工具从“玩具”变得更像“产品”。

总的来说，用Qt来集成这类HTTP API的AI服务，思路很直接，就是“发请求-等回复-展示”。它把复杂的模型推理留给了专业的后端工具，我们只需要专注于做一个好用、好看的客户端。这种分工让开发桌面AI应用的门槛降低了不少，特别适合想要快速验证想法或者打造个人效率工具的开发者。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。