Instale o Servidor IA 3CX no macOS ou no Debian (com NVIDIA)

Introdução

Este guia explica como instalar o Servidor IA 3CX para um PABX 3CX Versão 20 Update 10 em diante em um Mac com Apple Silicon compatível, como o Mac Mini. O Servidor IA 3CX transcreverá as chamadas do PABX e realizará análises das chamadas.

Requisitos Gerais

  • Você precisa ter acesso ao Console de Admin 3CX e acesso ao shell ou terminal na máquina (macOS ou Debian) que executará o Servidor IA 3CX
  • Você precisará de direitos de administrador local (para elevar usando sudo).
  • Certifique-se de que o Servidor IA 3CX consiga acessar o PABX em sua porta SSL principal, geralmente 443 ou 5001, e que consiga acessar os servidores de download do 3CX.
  • Se a opção “Servidor IA 3CX” não aparecer no PABX, verifique se você está usando a versão correta do 3CX e a licença 3CX adequada e verifique novamente em Admin > Integrações > Transcrição > Servidor IA 3CX.

Requisitos do macOS

  • Somente os Macs com Apple Silicon são compatíveis. Os Macs com processadores Intel não são compatíveis.
  • A memória mínima é de 16 GB de RAM. A meta recomendada é de 24 GB de RAM, e o hardware da linha Mac Mini é a opção inicial esperada para a implantação prática.

Requisitos do Debian

  • Utilize o Debian 12 ou o Debian 13 com uma GPU NVIDIA compatível, de preferência com drivers NVIDIA e bibliotecas CUDA pré-instalados.
  • Os requisitos mínimos de hardware são 16 GB de RAM, 20 GB de espaço livre em disco e 16 GB de VRAM. A configuração recomendada é de 24 GB de RAM e uma GPU da classe RTX com 24 GB.

Confirm your Mac's suitability

Use um Mac com Apple Silicon que tenha espaço livre em disco e memória suficientes para a carga prevista de transcrição e análise.

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

Um resultado válido exibirá o hardware Apple Silicon e o tamanho de memória esperado. Por exemplo:

arm64

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

      Chip: Apple M4 Pro

      Memory: 24 GB

Se o Mac identificar hardware Intel, não detectar o Apple Silicon ou apresentar memória insuficiente, interrompa o processo e transfira a instalação para um Mac compatível, em vez de forçar a implantação em hardware não compatível.

Preparando Seu Host Linux

Atualize o Sistema Operacional

Execute uma atualização e um upgrade dos pacotes antes de instalar o Servidor IA 3CX:

sudo apt-get update

sudo apt-get upgrade

Reinicie a máquina para garantir que o kernel em execução e os cabeçalhos instalados correspondam:

sudo reboot

Instale as ferramentas básicas

Instale os pacotes exigidos pelo instalador:

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

Verifique se os drivers da Nvidia e o CUDA estão instalados:

nvidia-smi

 

Se os drivers estiverem instalados corretamente, você verá uma saída semelhante à seguinte:

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 você não visualizar a saída correta para nvidia-smi, eleve para o usuário root e verifique se nvidia-smi está instalado com as dependências necessárias:

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

Após a reinicialização, verifique se a pilha está funcionando corretamente com nvidia-smi.

Instalando o Servidor IA 3CX

Lado do PABX

  • No PABX, acesse Admin > Integrações > Transcrição.
  • No menu suspenso, selecione Servidor IA 3CX e clique no botão + Adicionar Servidor IA.
  • Copie o comando de instalação gerado usando o botão copiar fornecido.

Comando de instalação do motor de transcrição

Lado do Servidor IA

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

  • No seu terminal, cole e execute o comando copiado anteriormente do PABX.
  • No Debian:

Instalador do Servidor 3CX IA no Debian detectando GPU NVIDIA L4 e solicitando a desativar ECC

  • Se você estiver usando uma GPU de nível empresarial, como uma Nvidia L4, em um provedor de nuvem com 22 GB, pode ser perguntado se deseja desativar o ECC na GPU. Se você aceitar (digite “y”), isso desativará o ECC, recuperando assim 2 GB de memória que, de outra forma, ficariam ociosos. Observação: desativar o ECC provocará imediatamente uma reinicialização, e você terá que voltar à primeira etapa após a reinicialização.

Instalador do Servidor IA 3CX no macOS exibindo especificações de hardware e confirmaçãoInstalador do Servidor IA 3CX exibindo GPU NVIDIA L4 detectada, requisitos de hardware e confirmação de instalação

  • O instalador perguntará então se você deseja instalar e se concorda com os termos e condições; aceite para continuar:

Terminal do instalador do Servidor IA 3CX baixando modelos ggml e gemma4

  • O instalador baixa os componentes necessários, cria a configuração, instala os serviços e registra o Servidor de IA no PABX.

Verifique se o Servidor IA 3CX Está Funcionando

Status do Servidor IA 3CX

  • Volte para Admin > Integrações > Transcrição e verifique se o status do novo Servidor IA aparece em verde  e não em vermelho.

Status das Transcrições Ativas no Servidor IA 3CX

  • Você pode fazer algumas chamadas de teste para confirmar se tudo está funcionando corretamente; quando as gravações estiverem sendo processadas, o Console de Admin exibirá informações sobre a fila e a atividade.

Múltiplos PABXs Utilizando o Mesmo Servidor IA

Configuração de múltiplos PABXs no Servidor IA

Você também pode permitir que vários PABXs utilizem o mesmo servidor de IA. Para isso, basta seguir novamente o guia de instalação acima para o novo PABX.

Por exemplo, você precisaria acessar o novo PABX em Integrações > Transcrição e clicar em  “Adicionar Servidor IA”, então acessar seu Servidor AI e colar o comando e pressionar Enter. Como o Servidor IA já está instalado nesse host, a instalação ignorará os componentes já instalados; isso autorizará efetivamente o novo PABX a usar também o Servidor IA.

Gerenciamento do Servidor IA 3CX

O Servidor IA 3CX instala vários serviços, incluindo o conversor, o transcritor e o serviço Ollama.

Gerenciamento dos Serviços de IA 3CX no macOS

Use launchctl para interagir com os serviços do macOS instalados.

Interrompa (e cancele o registro) dos serviços:

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

Inicie (e registre) os serviços:

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

Gerenciamento dos Serviços de IA 3CX no Debian

Para gerenciar o status de execução dos serviços do 3CX, use os seguintes comandos:

Verificar o status do serviço:

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

Reinicie os serviços:

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

Interromper os serviços:

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

Inicie os serviços:

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

Desinstale o Servidor IA

Para remover o pacote do Servidor IA do host, execute o script de desinstalação incluído no diretório de instalação:

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

Gerenciamento de PABXs Conectados

Para gerenciar os PABXs conectados, você pode usar o script do gerenciador de conexões integrado. Com ele, é possível verificar, desativar, reativar ou excluir as autorizações de PABX armazenadas.

Mostre primeiro a ajuda integrada.

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

Identifique e liste todas as conexões de PABX configuradas e visualize seus UUIDs

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

Desative uma conexão de PABX sem excluí-la.

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

Reative uma conexão de PABX que havia sido desativada anteriormente.

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

Exclua definitivamente uma conexão de PABX salva.

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

Solução de Problemas

As diversas autorizações do PABX, configurações e outras definições do servidor de IA são todas salvas nos seguintes arquivos:

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

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

Você pode solucionar problemas no servidor verificando os logs do servidor localizados no caminho abaixo.

/var/opt/3cx/aiserver/logs

O pacote do Servidor IA é instalado nesses caminhos principais.

/opt/3cx/aiserver

/var/opt/3cx/aiserver

  • O Servidor IA está fora do ar: Verifique se os serviços estão carregados e se o Servidor IA 3CX consegue se conectar ao PABX via HTTPS.
  • O comando de instalação não funciona — Evite usar um comando de instalação de uma configuração anterior; exclua a entrada do Servidor IA 3CX do PABX, crie uma nova e instale usando o comando de instalação para a entrada do Servidor IA 3CX recém-gerada.
  • O nvidia-smi falha (somente no Debian): Corrija o driver da NVIDIA ou o estado do CUDA antes de executar o instalador novamente.
  • O PABX rejeita a conexão: Remova a configuração desatualizada e reinstale usando um comando novo baseado em UUID.

Veja Também

Última atualização

Este documento foi atualizado pela última vez em 30 de julho de 2026

https://www.3cx.com.br/docs/installing-ai-server-macos-debian/