Installare 3CX AI Server su macOS o Debian (con NVIDIA)

Introduzione

Questa guida spiega come installare i server 3CX IA per un centralino 3CX V20 Update 10 o successive, su un Mac con Apple Silicon supportato, come ad esempio un Mac Mini. Il server 3CX IA trascriverà le chiamate del centralino ed eseguirà l’analisi delle chiamate.

Requisiti generali

  • È necessario disporre dell’accesso alla console di amministrazione 3CX e all’accesso alla shell o al terminale sul computer (macOS o Debian) su cui verrà eseguito il server 3CX IA.
  • Sono necessari i diritti di amministratore locale (per elevare i privilegi utilizzando sudo).
  • Assicurarsi che il server 3CX IA Server possa raggiungere il centralino sulla sua porta SSL principale, solitamente la 443 o la 5001, e che possa raggiungere i server di download 3CX.
  • Se l’opzione server 3CX IA Server non è visualizzata nel centralino, verificare di utilizzare la build 3CX e la licenza 3CX corrette e ricontrollare in Amministrazione > Integrazioni > Trascrizione > 3CX AI Server.

Requisiti per macOS

  • Sono supportati solo i Mac con Apple Silicon. I Mac basati su Intel non sono supportati.
  • La memoria minima richiesta è di 16 GB di RAM. Il valore consigliato è di 24 GB di RAM e l’hardware della classe Mac Mini rappresenta il percorso di implementazione pratico iniziale previsto.

Requisiti per Debian

  • Utilizzare Debian 12 o Debian 13 con una GPU NVIDIA supportata, preferibilmente con driver NVIDIA e librerie CUDA preinstallati.
  • I requisiti hardware minimi sono 16 GB di RAM, 20 GB di spazio libero su disco e 16 GB di VRAM. Il valore consigliato è di 24 GB di RAM e una GPU di classe RTX da 24 GB.

Verifica che il tuo Mac sia compatibile

Utilizza un Mac con Apple Silicon dotato di spazio libero su disco e memoria sufficienti per il carico di lavoro previsto in termini di trascrizione e analisi.

uname -m ; system_profiler SPHardwareDataType | egrep 'Chip|Memory'

Un risultato corretto mostrerà l'hardware Apple Silicon e la dimensione prevista della memoria. Ad esempio:

arm64

2026-07-10 16:35:56.134 system_profiler[2278:79797] hw.cpufamily: 0x17d5b93a

      Chip: Apple M4 Pro

      Memory: 24 GB

Se il Mac rileva hardware Intel, non riconosce Apple Silicon o mostra una quantità di memoria insufficiente, interrompi l'operazione e trasferisci l'installazione su un Mac supportato, anziché forzare l'implementazione su hardware non supportato.

Preparazione dell'host Linux

Aggiorna il sistema operativo

Esegui l'aggiornamento dei pacchetti e l'upgrade prima di installare 3CX AI Server:

sudo apt-get update

sudo apt-get upgrade

Riavvia il sistema per assicurarti che il kernel in esecuzione e le intestazioni installate corrispondano:

sudo reboot

Installa gli strumenti di base

Installa i pacchetti richiesti dal programma di installazione:

sudo apt -y install curl apt-transport-https gnupg gpg wget

Verifica se i driver Nvidia e CUDA sono installati:

nvidia-smi

 

Se i driver sono installati correttamente, dovresti ottenere un output simile al seguente:

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                                                             |

+-----------------------------------------------------------------------------------------+

Se non viene visualizzato il risultato corretto per nvidia-smi, passare all'utente root e assicurarsi che nvidia-smi sia installato con le dipendenze richieste:

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

Dopo il riavvio, verificare che lo stack funzioni correttamente utilizzando nvidia-smi.

Installazione del server IA 3CX

Lato centralino

  • Nel centralino, vai su Admin > Integrazioni > Trascrizione.
  • Dal menu a tendina, seleziona server IA 3CX e clicca sul pulsante + Aggiungi server IA.
  • Copia il comando di installazione generato utilizzando il pulsante di copia fornito.

Lato server IA

curl -fsSL https://wmr-cdn.3cx.net/templates/install.sh | sudo bash -s -- mypbx.example.com 22334455-6677-8899-aabb-ccddeeff0011

  • Nel tuo terminale, incolla ed esegui il comando precedentemente copiato dal centralino.
  • Su Debian:

  • Se si utilizza una GPU di livello aziendale come una Nvidia L4 su un provider cloud con 22 GB, potrebbe essere richiesto di disabilitare l’ECC sulla GPU. Se si accetta (digitando “y”), l’ECC verrà disabilitato, recuperando così 2 GB di memoria che altrimenti rimarrebbero inutilizzati. Si noti che la disabilitazione dell’ECC provocherà immediatamente un riavvio e, dopo il riavvio, sarà necessario tornare al primo passo.

  • Il programma di installazione chiederà quindi se si desidera procedere con l’installazione e se si accettano i termini e le condizioni; accettare per continuare:

  • Il programma di installazione scarica i componenti necessari, crea la configurazione, installa i servizi e registra il server IA sul centralino.

Verifica il corretto funzionamento del server AI 3CX

  • Torna su Admin > Integrazioni > Trascrizione e verifica che lo stato del nuovo server IA sia verde e non rosso.

  • Puoi effettuare alcune chiamate di prova per verificare il corretto funzionamento; quando le registrazioni sono in fase di elaborazione, la console di amministrazione mostrerà le informazioni relative alla coda e all’attività.

Più centralini che utilizzano lo stesso server IA

È inoltre possibile consentire l’utilizzo dello stesso server IA da parte di più centralini. Per farlo, è sufficiente seguire nuovamente la guida all’installazione sopra riportata per il nuovo centralino.

Ad esempio, dovrai accedere al nuovo centralino in Integrazioni > Trascrizione, cliccare su Aggiungi server IA, quindi accedere al tuo server IA, incollare il comando e premere Invio. Poiché il server IA è già installato su quell’host, l’installazione salterà i componenti già installati; ciò autorizzerà di fatto il nuovo centralino a utilizzare anch’esso il server IA.

Gestione del server IA 3CX

Il server IA 3CX installa diversi servizi, tra cui il convertitore, il trascrittore e il servizio Ollama.

Gestione dei servizi AI 3CX su macOS

Utilizza launchctl per interagire con i servizi installati su macOS.

Arresta (e annulla la registrazione) dei servizi:

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

Avvia (e registra) i servizi:

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

Gestione dei servizi 3CX IA su Debian

Per gestire lo stato di funzionamento dei servizi 3CX, utilizzare i seguenti comandi:

Verifica dello stato del servizio:

sudo systemctl status 3cxai-converter 3cxai-transcriber 3cxai-ollama

Riavviare i servizi:

sudo systemctl restart 3cxai-converter 3cxai-transcriber 3cxai-ollama

Arresta i servizi:

sudo systemctl stop 3cxai-converter 3cxai-transcriber 3cxai-ollama

Avvia i servizi:

sudo systemctl start 3cxai-converter 3cxai-transcriber 3cxai-ollama

Disinstallazione di AI Server

Per rimuovere il pacchetto server IA dall'host, eseguire lo script di disinstallazione incluso nella directory di installazione:

sudo /opt/3cx/aiserver/setup/3cxai-uninstall.sh

Gestione dei centralini collegati

Per gestire i centralini collegati, è possibile utilizzare lo script di gestione delle connessioni integrato. Con esso è possibile visualizzare, disabilitare, riabilitare o eliminare le autorizzazioni dei centralini memorizzate.

Visualizza prima la guida integrata.

sudo /opt/3cx/aiserver/setup/3cxai-connection-manager.sh --help

Identifica ed elenca tutte le connessioni del centralino configurate e visualizzarne l'UUID

sudo /opt/3cx/aiserver/setup/3cxai-connection-manager.sh

Disattiva una connessione del centralino senza eliminarla.

sudo /opt/3cx/aiserver/setup/3cxai-connection-manager.sh --disable <UUID>

Riattiva una connessione del centralino precedentemente disattivata.

sudo /opt/3cx/aiserver/setup/3cxai-connection-manager.sh --enable <UUID>

Elimina definitivamente una connessione del centralino salvata.

sudo /opt/3cx/aiserver/setup/3cxai-connection-manager.sh --delete <UUID>

Risoluzione dei problemi

Le varie autorizzazioni del centralino, le configurazioni e le altre impostazioni del server IA sono tutte salvate nei seguenti file:

/opt/3cx/aiserver/setup/connections.json

/opt/3cx/aiserver/setup/config.json

È possibile risolvere i problemi del server controllando i log del server che si trovano nel percorso indicato di seguito.

/var/opt/3cx/aiserver/logs

Il pacchetto server IA viene installato in questi percorsi principali.

/opt/3cx/aiserver

/var/opt/3cx/aiserver

  • Il server IA è inattivo: Verificare che i servizi siano caricati e che il server AI 3CX possa raggiungere il centralino tramite HTTPS.
  • Il comando di installazione non funziona: Evitare di utilizzare un comando di installazione proveniente da una configurazione precedente; eliminare la voce relativa al server IA 3CX dal centralino, crearne una nuova e procedere all’installazione utilizzando il comando di installazione corrispondente alla voce del server IA 3CX appena generata.
  • Errore di nvidia-smi (solo Debian): Correggere il driver NVIDIA o lo stato di CUDA prima di rieseguire il programma di installazione.
  • Il centralino rifiuta la connessione: Rimuovere la configurazione obsoleta e reinstallare utilizzando un comando nuovo basato su UUID.

Per saperne di più

Ultimo aggiornamento

Questo documento è stato aggiornato il 4 agosto 2026

https://www.3cx.it/doc/installing-ai-server-macos-debian/