突破跨平台壁垒：HeyGem.ai Linux服务端与Windows客户端远程调用全方案

突破跨平台壁垒：HeyGem.ai Linux服务端与Windows客户端远程调用全方案

【免费下载链接】HeyGem.ai 项目地址: https://gitcode.com/GitHub_Trending/he/HeyGem.ai

在数字化转型加速的今天，企业与开发者面临的一大挑战是如何实现AI模型的跨平台高效部署。HeyGem.ai作为开源数字人项目，支持本地部署与API调用，但其跨平台部署过程中常出现服务连接失败、资源路径不兼容等问题。本文将从架构解析、部署步骤、常见问题三个维度，提供Linux服务端与Windows客户端远程调用的完整解决方案，帮助开发者快速实现跨平台协同。

跨平台部署架构解析

HeyGem.ai采用客户端-服务端（C/S）架构，服务端通过Docker容器化部署，客户端提供图形界面操作。Linux服务端与Windows客户端的远程调用依赖Docker网络桥接与API接口通信，核心组件包括：

• 服务端容器集群：由TTS（语音合成）、ASR（语音识别）、视频合成三个容器组成，通过ai_network网络桥接实现内部通信。
• 客户端交互层：Windows客户端通过HTTP协议调用服务端API，完成模型训练与视频生成任务。
• 数据存储层：服务端与客户端通过共享目录同步模型数据，Linux使用~/duix_avatar_data，Windows需指定D盘存储。

核心服务配置文件路径：

• Linux服务端配置：deploy/docker-compose-linux.yml
• Windows服务端配置：deploy/docker-compose.yml
• API实现源码：src/main/service/

Linux服务端部署关键步骤

环境准备与依赖安装

Linux服务端部署需满足以下条件：

• 硬件：NVIDIA显卡（推荐RTX 4070及以上）、32G内存、100G空闲硬盘
• 软件：Docker Engine、NVIDIA Container Toolkit

安装命令序列：

# 安装Docker
sudo apt update && sudo apt install -y docker.io docker-compose

# 配置NVIDIA容器工具包
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt update && sudo apt install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Docker容器部署与网络配置

服务端通过Docker Compose启动三个核心容器，关键配置差异如下：

服务名称	镜像地址	端口映射	数据卷（Linux）
TTS	guiji2025/fish-speech-ziming	18180:8080	~/duix_avatar_data/voice/data
ASR	guiji2025/fun-asr	10095:10095	无
视频合成	guiji2025/duix.avatar	8383:8383	~/duix_avatar_data/face2face

启动命令：

cd deploy && docker-compose -f docker-compose-linux.yml up -d

验证服务状态：

docker ps | grep duix-avatar-*

所有服务状态应为Up，若ASR服务启动缓慢，需等待5-10分钟再进行后续操作。

Windows客户端配置与远程调用

客户端安装与环境配置

Windows客户端需满足以下前置条件：

• 系统：Windows 10 19042.1526及以上版本
• 硬件：D盘空闲空间≥30G，C盘≥100G
• 驱动：NVIDIA显卡驱动（版本需匹配服务端CUDA版本）

客户端安装步骤：

1. 下载最新安装包：GitHub Releases
2. 双击Duix.Avatar-x.x.x-setup.exe，按向导完成安装
3. 首次启动需接受协议并跳过登录

远程服务配置与API调用

客户端默认连接本地服务，需修改配置文件实现远程调用：

1. 打开客户端配置文件：%APPDATA%\Duix.Avatar\config.json
2. 修改服务端地址：

{
  "server": {
    "tts_url": "http://[Linux服务器IP]:18180",
    "video_url": "http://[Linux服务器IP]:8383"
  }
}

3. 重启客户端，通过以下步骤验证连接：

• 创建新模特，上传10秒语音视频
• 检查Linux服务端日志：docker logs duix-avatar-gen-video
• 若显示Preprocess success，表明远程调用成功

常见问题与解决方案

服务连接失败排查

症状：客户端提示"连接超时"，服务端日志无请求记录。

解决方案：

1. 检查Linux防火墙规则，开放18180/8383端口：

sudo ufw allow 18180/tcp
sudo ufw allow 8383/tcp

2. 验证Docker网络配置：

docker network inspect ai_network | grep Subnet

3. 替换国内Docker镜像源（加速容器拉取）：

{
  "registry-mirrors": [
    "https://docker.zhai.cm",
    "https://hub.littlediary.cn"
  ]
}

资源路径不兼容问题

症状：Windows客户端上传文件后，服务端提示"文件不存在"。

解决方案：

1. Linux服务端创建共享目录：

mkdir -p ~/duix_avatar_data && chmod 777 ~/duix_avatar_data

2. 客户端修改上传路径为共享目录映射：

{
  "paths": {
    "upload": "D:\\duix_avatar_data\\upload"
  }
}

性能优化建议

针对远程调用延迟问题，可采取以下优化措施：

1. 网络层面：使用有线连接，MTU值设置为1500
2. 服务端优化：调整Docker资源限制，在docker-compose-linux.yml中增加：

deploy:
  resources:
    limits:
      cpus: '4'
      memory: 16G

3. 客户端缓存：启用模型本地缓存，减少重复下载

总结与扩展

本文详细阐述了HeyGem.ai跨平台部署的架构设计、实施步骤与问题解决。通过Docker容器化部署与API接口标准化，实现了Linux服务端与Windows客户端的高效协同。开发者可进一步扩展以下能力：

• 集群部署：基于Kubernetes实现服务弹性伸缩
• 权限管理：集成OAuth2.0实现API访问控制
• 监控告警：通过Prometheus+Grafana监控服务状态

更多技术细节可参考：

• 官方文档：README_zh.md
• API开发指南：src/main/api/
• 常见问题：doc/常见问题.md

通过本文方案，开发者可快速构建稳定、高效的跨平台数字人应用，推动AI技术在企业级场景的落地应用。

【免费下载链接】HeyGem.ai 项目地址: https://gitcode.com/GitHub_Trending/he/HeyGem.ai