在 macOS 或 Debian（需配备 NVIDIA 显卡）系统上安装 3CX AI 服务器
介绍
本指南说明如何在受支持的 Apple Silicon Mac（例如 Mac Mini）上为 3CX PBX 版本 20 Update 10 及更高版本 安装 3CX AI 服务器。3CX AI 服务器将转写 PBX 通话并执行通话分析。
一般要求
- 您需要能够访问 3CX 管理控制台，并在将要运行 3CX AI 服务器的机器（macOS 或 Debian）上具有 shell 或终端访问权限。
- 您需要本地管理员权限（以便使用 sudo 提权）。
- 确保 3CX AI 服务器能够通过 PBX 的主 SSL 端口（通常为 443 或 5001）访问 PBX，并且能够访问 3CX 下载服务器。
- 如果 PBX 中未显示 3CX AI 服务器选项，请确认您使用的是正确的 3CX 版本和 3CX 许可证，然后在“管理 → 集成 → 转写 → 3CX AI 服务器”下再次检查。
macOS 要求
- 仅支持 Apple Silicon Mac。不支持基于 Intel 的 Mac。
- 最低内存为 16 GB RAM。建议目标为 24 GB RAM，Mac Mini 级硬件是预期的入门级实际部署路径。
Debian 要求
- 使用 Debian 12 或 Debian 13，并配备受支持的 NVIDIA GPU，最好预装 NVIDIA 驱动程序和 CUDA 库。
- 最低硬件为 16 GB RAM、20 GB 可用磁盘空间和 16 GB VRAM。建议目标为 24 GB RAM 和 24 GB RTX 级 GPU。
确认您的Mac是否适用
使用具有足够可用磁盘空间和内存的 Apple Silicon Mac，以应对预期的转写和分析负载。
uname -m ; system_profiler SPHardwareDataType | egrep 'Chip|Memory'
正常结果将显示 Apple Silicon 硬件和预期的内存大小。例如：
arm64
2026-07-10 16:35:56.134 system_profiler[2278:79797] hw.cpufamily: 0x17d5b93a
Chip: Apple M4 Pro
Memory: 24 GB
如果 Mac 报告 Intel 硬件、未显示 Apple Silicon，或显示内存过小，请停止安装并将安装移至受支持的 Mac，而不是强行部署到不受支持的硬件上。
准备 Linux 主机
更新操作系统
在安装 3CX AI 服务器之前，执行软件包更新和升级：
sudo apt-get update
sudo apt-get upgrade
重新启动机器以确保正在运行的内核和已安装的头文件匹配：
sudo reboot
安装基础工具
安装安装程序所需的软件包：
sudo apt -y install curl apt-transport-https gnupg gpg wget
检查是否已安装 Nvidia 驱动程序和 CUDA：
nvidia-smi
如果驱动程序安装正确，您将获得类似以下内容的输出：
user@aiserver:~$ nvidia-smi
Mon Jan 26 09:04:40 2026
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 590.48.01 Driver Version: 590.48.01 CUDA Version: 13.1 |
+-----------------------------------------+------------------------+----------------------+
| GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. |
| | | MIG M. |
|=========================================+========================+======================|
| 0 NVIDIA L4 On | 00000000:00:03.0 Off | 0 |
| N/A 40C P8 12W / 72W | 0MiB / 23034MiB | 0% Default |
| | | N/A |
+-----------------------------------------+------------------------+----------------------+
+-----------------------------------------------------------------------------------------+
| Processes: |
| GPU GI CI PID Type Process name GPU Memory |
| ID ID Usage |
|=========================================================================================|
| No running processes found |
+-----------------------------------------------------------------------------------------+
如果您没有看到 nvidia-smi 的正确输出，请切换到 root 用户，并确保已安装 nvidia-smi 及其所需依赖项：
apt -y install linux-headers-$(uname -r)
DEB_VERSION=$(VERSION_ID=; . /etc/os-release; echo "$VERSION_ID")
wget "https://developer.download.nvidia.com/compute/cuda/repos/debian${DEB_VERSION}/x86_64/cuda-keyring_1.1-1_all.deb"
dpkg -i cuda-keyring_1.1-1_all.deb
apt update
apt -y install nvidia-open
apt -y install nvidia-driver-cuda nvidia-kernel-open-dkms
reboot
重启后，使用 nvidia-smi 确认堆栈已成功运行。
安装 3CX AI 服务器
PBX 端
- 在PBX中，转到管理 > 集成 > 转写。
- 从下拉菜单中选择 3CX AI 服务器，然后单击+ 添加 AI 服务器 按钮。
- 使用提供的命令复制生成的安装命令。复制 按钮。
AI 服务器端
curl -fsSL https://wmr-cdn.3cx.net/templates/install.sh | sudo bash -s -- mypbx.example.com 22334455-6677-8899-aabb-ccddeeff0011
- 在您的终端中，粘贴并运行先前从 PBX 复制的命令。
- 在 Debian 上：
- 如果您使用的是企业级 GPU（例如云提供商上的 Nvidia L4，具有 22GB 显存），系统可能会询问您是否要禁用 GPU 上的 ECC。如果您接受（输入“y”），则会禁用 ECC，从而回收 2GB 原本不会被使用的内存。请注意，禁用 ECC 将立即触发重启，重启后您必须返回第一步。
- 然后安装程序会询问您是否要安装以及是否同意条款和条件；接受以继续：
- 安装程序将下载所需组件、创建配置、安装服务，并将 AI 服务器注册到 PBX。
确认 3CX AI 服务器正常工作
- 返回管理 > 集成 > 转写并确认新的 AI 服务器状态显示为：绿色的 而且不是红色。
- 您可以拨打一些测试通话来确认功能正常；当录音正在处理时，管理控制台将显示队列和活动信息。
多个 PBX 使用同一 AI 服务器
您也可以允许多个 PBX 使用同一台 AI 服务器。为此，只需为新 PBX 再次按照上述安装指南操作即可。
例如，您需要转到新 PBX 的 集成 → 转写，然后单击“添加 AI 服务器”，然后转到您的 AI 服务器并粘贴命令并按回车键。由于该主机上已安装 AI 服务器，安装将跳过已安装的组件；这将有效地授权新 PBX 也可以使用该 AI 服务器。
管理 3CX AI 服务器
3CX AI 服务器安装多个服务，包括转换器、转写器和 Ollama 服务。
管理 macOS 3CX AI 服务
使用 launchctl 与已安装的 macOS 服务进行交互。
停止（并注销）服务：
sudo launchctl bootout system/com.3cx.converter
sudo launchctl bootout system/com.3cx.transcriber
sudo launchctl bootout system/com.3cx.logrotate
sudo launchctl bootout system/com.ollama.serve
启动（并注册）服务：
sudo launchctl bootstrap system /Library/LaunchDaemons/com.3cx.converter.plist
sudo launchctl bootstrap system /Library/LaunchDaemons/com.3cx.transcriber.plist
sudo launchctl bootstrap system /Library/LaunchDaemons/com.3cx.logrotate.plist
sudo launchctl bootstrap system /Library/LaunchDaemons/com.ollama.serve.plist
管理 Debian 3CX AI 服务
要管理 3CX 服务的运行状态，请使用以下命令：
检查服务状态：
sudo systemctl status 3cxai-converter 3cxai-transcriber 3cxai-ollama
重启服务：
sudo systemctl restart 3cxai-converter 3cxai-transcriber 3cxai-ollama
停止服务：
sudo systemctl stop 3cxai-converter 3cxai-transcriber 3cxai-ollama
启动服务：
sudo systemctl start 3cxai-converter 3cxai-transcriber 3cxai-ollama
卸载 AI 服务器
要从主机中移除 AI 服务器软件包，请从安装目录运行捆绑的卸载脚本：
sudo /opt/3cx/aiserver/setup/3cxai-uninstall.sh
管理已连接的 PBX
为了管理已连接的 PBX，您可以使用内置的连接管理器脚本。通过它，您可以检查、禁用、重新启用或删除存储的 PBX 授权。
首先显示内置帮助：
sudo /opt/3cx/aiserver/setup/3cxai-connection-manager.sh --help
识别并列出所有已配置的 PBX 连接，并查看其 UUID：
sudo /opt/3cx/aiserver/setup/3cxai-connection-manager.sh
禁用某个 PBX 连接但不删除：
sudo /opt/3cx/aiserver/setup/3cxai-connection-manager.sh --disable <UUID>
重新启用之前禁用的 PBX 连接：
sudo /opt/3cx/aiserver/setup/3cxai-connection-manager.sh --enable <UUID>
永久删除存储的 PBX 连接：
sudo /opt/3cx/aiserver/setup/3cxai-connection-manager.sh --delete <UUID>
故障排除
各种 PBX 授权、配置和其他 AI 服务器设置均保存在以下文件中：
/opt/3cx/aiserver/setup/connections.json
/opt/3cx/aiserver/setup/config.json
您可以通过检查位于以下路径的服务器日志来排查服务器问题：
/var/opt/3cx/aiserver/logs
AI 服务器软件包安装到以下主要路径：
/opt/3cx/aiserver
/var/opt/3cx/aiserver
- AI服务器宕机了：确认服务已加载，并且 3CX AI 服务器可以通过 HTTPS 连接到 PBX。
- 安装命令不起作用- 避免使用先前配置中的安装命令；从 PBX 中删除 3CX AI 服务器的条目，创建一个新的条目，并使用新生成的 3CX AI 服务器条目的安装命令进行安装。
- nvidia-smi 失败（仅限 Debian 系统）：请先修复 NVIDIA 驱动程序或 CUDA 状态，然后再重新运行安装程序。
- PBX拒绝连接：删除过时的配置，并使用新的基于 UUID 的命令重新安装。
另请参阅
最后更新时间
本文件最后更新日期为2026年7月30日。
版权所有 三思客软件（深圳）有限公司