SmartServe

SmartServe 的愿景是构建开源的 OpenHarmony 推理开放平台，推动鸿蒙智能应用生态的繁荣，具体而言：

• 通过全栈开源打破技术壁垒，加速大模型推理技术普惠化；
• 协同智能体、具身智能业务，赋能 toB 场景应用智能化升级，支撑业务智能化转型；
• 协同社区 & 高校 & 企业，推动技术标准统一和生态繁荣。

---

总体架构

---

SmartServe 架构设计

---

📂 项目结构

.
├── applications/       # 应用
├── cmake/              # CMake 配置
├── config/             # 模型配置
├── deps/               # 依赖管理配置
├── docs/               # 说明文档
├── etc/init/           # 服务启动配置
├── interfaces/         # Client SDK（SmartServeClient）
├── patches/            # 系统及三方库适配补丁
├── plugin/             # 推理引擎插件
├── sa_profile/         # SystemAbility 配置文件
├── scripts/            # 脚本
│   ├── android/        # Android 构建与打包脚本
│   ├── harmonyos/      # HarmonyOS SDK 构建脚本
│   ├── ios/            # iOS 构建脚本
│   ├── init_submodules.sh      # 按需初始化 submodule
│   ├── build_and_test.sh       # macOS/Linux 构建、测试和应用冒烟
│   ├── test/internal/          # 测试入口的内部实现
│   └── whole_build_and_test.sh # macOS/Linux 三引擎回归矩阵
├── sdk/                # SDK
├── services/           # SmartServe 服务端实现
├── third-party/        # 第三方库
├── test/               # 单元测试
├── toolchains/         # 交叉编译工具链配置
├── utils/              # 通用工具
└── README.md

---

⚙️ 环境要求

💡 提示： 本节环境要求主要针对 OpenHarmony 平台的开发与构建环境。其他支持平台（macOS / Linux / Android / iOS）的环境要求，请参考下一节「构建步骤」。

系统要求

• OpenHarmony 版本: 6.0 及以上（推荐 6.0 Release）
• 构建环境（针对构建 OpenHarmony 的宿主机）:
  • 操作系统：Ubuntu 20.04 及以上
  • 磁盘空间：≥ 170 GB
  • 内存空间：≥ 16 GB

编译工具链

• gn - 构建配置工具，用于生成 Ninja 构建文件
• ninja - 轻量级构建系统，专注于构建速度
• clang - C/C++ 编译器

第三方依赖

构建与推理依赖

依赖	类型	版本	说明
curl	基础依赖	8.12.0 (commit 34cf9d54a4)	跨平台数据传输库
nlohmann-json	基础依赖	v3.11.3 (commit 3946872265)	C++ JSON 解析与序列化库
cpp-httplib	基础依赖	v0.38.0	C++ HTTP/HTTPS 单头文件库
openssl	可选依赖	3.5.4	提供 TLS 和 SHA256校验等特性支持
googletest	测试依赖	v1.14.0 (commit d72f9c8aea)	Google C++ 测试框架
llama.cpp	可选引擎	b9484	一个高效且高性能的 C/C++ 推理框架
MNN	可选引擎	3.5.0	Alibaba 开源的轻量级深度学习推理引擎
executorch	可选引擎	release/1.1 (commit d386a0482c)	Meta 推出的开源端侧 AI 推理框架
onnx runtime	可选引擎	65fb61b159	Microsoft 开源的跨平台高性能机器学习推理与训练加速库
stb	可选引擎辅助依赖	28d546d	ExecuTorch 图像加载路径使用的单文件 C/C++ 库集合

按需初始化 Submodule

SmartServe 使用 Git Submodule 管理部分第三方依赖。为了避免一次性下载所有可选推理引擎，建议先 Clone 仓库，再按实际需求初始化依赖：

git clone https://gitcode.com/openharmony-robot/smartserve.git
cd smartserve

# 默认只拉取基础依赖：curl、nlohmann-json、cpp-httplib
./scripts/init_submodules.sh

init_submodules.sh 支持组合参数，建议按实际要构建的功能一次性声明所需依赖。多次调用该脚本是增量初始化：后续执行只会补齐本次指定的 submodule，不会删除或清理此前已经下载的其他依赖源码。常用场景：

# 基础依赖 + 测试依赖 + llama.cpp 引擎
./scripts/init_submodules.sh --base --tests --engine llamacpp

# 只使用 llama.cpp 引擎
./scripts/init_submodules.sh --base --engine llamacpp

# 同时使用 llama.cpp 和 MNN（以下写法等价）
./scripts/init_submodules.sh --base --engine llamacpp --engine mnn
./scripts/init_submodules.sh --base --engine llamacpp,mnn
./scripts/init_submodules.sh --base --engine llamacpp, mnn
./scripts/init_submodules.sh --base --engine "llamacpp, mnn"
./scripts/init_submodules.sh --base --engine=llamacpp,mnn

# 按需增加 ExecuTorch / ONNX Runtime
./scripts/init_submodules.sh --base --engine executorch,onnxruntime

# 确认需要完整开发环境时再全量初始化
./scripts/init_submodules.sh --all

--with-openssl 是独立开关，用于初始化openssl依赖。

如果不使用脚本，也可以直接用 git submodule 指定要初始化的目录，例如：

git submodule update --init third-party/curl third-party/nlohmann-json third-party/cpp-httplib
git submodule update --init third-party/llama.cpp
git submodule update --init --recursive third-party/executorch

Web 演示页依赖

SmartServe Chat 界面的 Markdown 渲染依赖（浏览器运行时从 CDN 加载，见 applications/http_server/index.html）：

依赖	版本	说明
marked	18.0.5	JavaScript Markdown 解析库，用于渲染助手回复
DOMPurify	3.4.8	HTML 净化库，防止助手回复渲染时的 XSS 攻击

上述库在页面打开时从 CDN（jsdelivr / unpkg）拉取。设备访问 Chat 页面时需能访问外网 CDN，否则助手回复将降级为纯文本显示。

---

🔨 构建步骤

SmartServe 当前支持 OpenHarmony、macOS、Linux、Android 和 iOS 平台，具体构建方式请参考以下文档。

• OpenHarmony 平台构建指南
• 跨平台 SDK 构建指南：面向 Android AAR / iOS XCFramework，供移动端 App 集成。
• 跨平台二进制构建指南：面向 macOS / Linux，直接构建并运行命令行工具、HTTP 服务和测试程序。

---

🔩 引擎支持

平台	llama.cpp	MNN	ExecuTorch	ONNX Runtime
OpenHarmony	✅ 完全支持	⚠️ 有限支持	⚠️ 有限支持	⚠️ 有限支持
macOS	✅ 完全支持	✅ 支持	❌ 暂不支持	❌ 暂不支持
Linux	✅ 完全支持	✅ 支持	❌ 暂不支持	❌ 暂不支持
Android	✅ 完全支持	✅ 支持	❌ 暂不支持	❌ 暂不支持
iOS	❌ 暂不支持	⚠️ 可选支持	❌ 暂不支持	❌ 暂不支持

---

📋 模型支持

SmartServe 的模型支持取决于所选推理引擎、模型格式、平台适配状态以及对应插件实现。models.json 中的 engine 字段用于指定某个模型由哪个引擎加载和运行。当前支持范围如下：

引擎	支持模型	适用平台	说明
llama.cpp	Qwen 系列 GGUF 模型，包括 Qwen2.x、Qwen3 等文本模型，以及 Qwen2.5-VL、Qwen3.5 等视觉语言模型	OpenHarmony、macOS、Linux、Android	当前主力 LLM/VLM 路径；模型需转换或下载为 llama.cpp 可加载的 GGUF / mmproj 格式。
MNN	MNN 引擎本身支持的模型	macOS、Linux、Android、iOS	SmartServe 侧按 MNN 模型目录加载，实际模型范围以 MNN Runtime 支持能力为准；当前不支持 OpenHarmony 平台。
Onnx Runtime	Pi-0	OpenHarmony	当前 Pi-0 样例仅支持 OpenHarmony 平台，并通过 ONNX Runtime 引擎运行。

示例模型配置可参考 config/model_config/models.json。

---

▶️ 运行方法（OpenHarmony 平台）

本节说明适用于 OpenHarmony 平台的部署后运行方式。

其他平台直接运行二进制的方法与示例，请参阅 跨平台二进制构建指南；移动端 SDK 接入请参阅 跨平台 SDK 构建指南。

如果推送后执行文件时遇到权限错误，请运行：

# 为目录下所有文件添加可执行权限
cd /data/smart_serve
chmod +x *

API 使用示例

推理 API 的详细说明（请求/响应格式、参数说明与示例）请参阅 SmartServe 推理 API 设计文档。

单元测试说明： smart_serve_test、multi_session_test 等属于可选编译目标，详见 OpenHarmony 平台构建指南 中的 build-target 说明。只有构建时包含对应 unittest 组件并成功产出、推送可执行文件后，设备上才会存在这些程序；若未编测或未部署，请跳过下列测试命令。

# 1. 通过 hdc 连接到开发板
hdc shell

# 2. 进入工作目录
cd /data/smart_serve

# 3. （可选）运行单元测试，仅在上一步已编译并推送对应测试组件时可用
./smart_serve_test
./multi_session_test
./test_executorch

# 4. 启动交互式聊天工具
./chatbox_cli

# 5. 启动 HTTP 演示服务（提供 Web 界面，支持 LLM/VLM 推理）
./http_server -p 8080
# 在浏览器访问 http://<设备IP>:8080

# 6. 退出连接
exit

smart_serve_test 运行输出示例：

Chatbox 交互式命令行工具：

HTTP 服务演示 - LLM 文本推理：

HTTP 服务演示 - VLM 视觉语言推理：

---

📖 文档

设计

• SmartServe 设计文档
• SmartServe 推理 API 设计文档

构建部署

• OpenHarmony 平台构建指南
• 跨平台 SDK 构建指南
• 跨平台二进制构建指南
• 常见编译问题和解决方法

引擎集成

• ExecuTorch 集成指南
• ONNX Runtime 集成指南

开发规范

• C/C++ 安全编码指南
• 项目编码规范指南（C++）

---

🤝 贡献指南

欢迎提交 issue 和 PR！

请参考 design.md 获取开发指南。

代码风格遵循 OpenHarmony 通用规范。

---

📜 License

本项目采用 Apache 2.0 License。