qt-llm：为 Qt/C++ 桌面应用打造的 LLM 集成基础库

qt-llm 是一个面向 Qt/C++ 应用的 LLM 集成基础库，提供从简单模型调用到复杂 Agent 工作流的完整能力栈，支持多种 Provider 和本地 llama.cpp 托管。

在 AI 应用快速普及的今天，将大语言模型能力集成到桌面软件已成为许多开发者的刚需。然而，直接对接 OpenAI、Ollama、vLLM 等不同服务需要处理大量协议细节，而本地部署 llama.cpp 又涉及复杂的运行时管理。qt-llm 正是为解决这一痛点而生——它提供了一个轻量级的 Qt/C++ 基础层，让开发者能够专注于业务逻辑，而非底层 LLM 集成细节。

项目的核心定位非常清晰：作为可嵌入的 Qt 工程，为外部 Qt 应用提供稳定的 C++ 接口，屏蔽各类 LLM 服务的实现差异。无论是简单的单轮对话，还是复杂的多会话聊天、工具调用、MCP 服务集成，qt-llm 都提供了相应的抽象层级供开发者选择。

qt-llm 的架构采用分层设计，从简单到复杂提供了多个使用层级：

RuntimeFacade 是最简单的入口，面向普通 Host App 提供单轮调用接口。开发者只需配置 provider 名称、模型 ID 和系统提示词，即可发送请求并获取响应。这种设计让基础功能的使用门槛降到最低。

QtLLMClient 位于更底层，提供请求执行、流式 Token 接收、Provider Payload 处理和取消请求等高级控制能力。适合需要对请求生命周期进行精细控制的场景。

ConversationClient 支持多会话管理，内置历史记录、用户 Profile、会话快照和持久化能力。这是构建聊天类应用的首选层级。

ToolEnabledChatEntry 则面向 Agent 场景，提供工具定义、选择、执行和协议适配能力，同时支持 MCP Server 的注册、同步和调用。

此外，项目还包含 ToolsInside 模块用于运行观测（trace、事件、span、artifact 记录），以及 ToolStudio 用于工具目录管理和工作区元数据管理。

qt-llm 内置了对多种 LLM Provider 的支持：OpenAI、OpenAI-compatible、Ollama、vLLM 和 llama.cpp。其中对 llama.cpp 的支持尤为完善——项目可以自动托管 llama-server，无需开发者手动管理启动参数。

本地运行时的查找逻辑设计得相当实用：首先查找当前程序目录下的 llama-cpp-runtime，然后依次检查 ZNZ_HOME、ZNZ_BLACKBOARD、YIDA_HOME、YIDA_BLACKBOARD、IETA_HOME、IETA_BLACKBOARD 等环境变量指向的目录，最后在 Linux 系统的 /home/ieta/LLMs/llama-cpp-runtime 或 /home/IETA/LLMs/llama-cpp-runtime，以及 Windows 所有磁盘根目录下的 LLMs/llama-cpp-runtime 中查找。

模型文件放置在运行态目录的 models/ 子目录下，多个 .gguf 模型可由应用展示列表供用户选择。选择结果自动写入配置，无需手动编辑配置文件。

qt-llm 的运行时管理引入了智能策略概念。Host App 只需暴露 auto、cpu-only、prefer-gpu 这类高层策略选项，qt-llm 会根据模型文件大小、GPU backend 是否存在、CPU 线程数等自动推导 --gpu-layers、--threads、--ctx-size 等底层参数。

这种设计既保证了普通用户的易用性，又为专家用户保留了手动覆盖的灵活性。开发者无需让用户理解 GPU 层数、上下文长度等晦涩概念，同时高级用户仍可通过专家模式进行微调。

项目提供了丰富的示例代码帮助开发者快速上手：

• simple_chat：最基础的聊天示例，演示 RuntimeFacade 的使用
• multi_client_chat：多客户端并发示例
• mcp_server_manager：MCP 服务管理器示例
• tools_inside：运行观测功能示例
• toolstudio：工具目录管理示例

此外，src/agents/ 目录下还提供了 pdf_translator_agent 作为参考业务 Agent，展示了如何基于 qt-llm 构建实际应用场景。

qt-llm 当前基线采用 Qt + qmake + C++17，这是 Qt 生态最成熟稳定的组合。构建流程简单直接：

qmake qt-llm.pro
nmake /NOLOGO

测试入口位于 tests/qtllm_tests/，运行 qtllm_tests.exe 即可执行单元测试。项目文档使用中文编写，位于 docs/ 目录，包含 Host App 集成指南、本地 llama.cpp 使用指南和故障处理手册等。

qt-llm 的价值在于它提供了一个完整的 LLM 集成解决方案，而非简单的 API 包装。对于正在使用 Qt/C++ 开发桌面应用，并希望集成 AI 能力的团队来说，这个项目可以显著降低技术门槛。其分层架构让不同复杂度的需求都能找到合适的接入点，而智能运行策略则让本地模型部署变得前所未有的简单。