IA

As funcionalidades de IA do Antimatter utilizam modelos à sua escolha: um prestador de serviços na nuvem ou um servidor na sua própria rede. Nada é enviado para qualquer lado até configurar um modelo. Esta página aborda as ligações de modelos, cada funcionalidade, os dados que envia e como as desativar.

As funcionalidades de IA

"Compatível com OpenAI" significa um servidor que oferece a mesma API HTTP que a OpenAI. A maioria dos servidores de modelos que pode executar por sua conta cumpre este requisito (por exemplo, Ollama, vLLM, o servidor do llama.cpp, ou servidores de Whisper e de texto para fala), tal como muitos prestadores de serviços na nuvem e gateways, como o LiteLLM ou o OpenRouter. Não é necessária qualquer licença para nenhuma destas funcionalidades.

As funcionalidades integradas (reescrita, resumos, tradução e leitura em voz alta) não necessitam da aplicação Agentes: utilizam as ligações de modelos que adiciona na Consola do sistema.

Ligações de modelos

Uma ligação de modelo é um prestador de serviços de IA que o Antimatter pode chamar: o seu endereço, a sua chave e os seus modelos. Adiciona-a uma vez e, em seguida, seleciona-a para cada funcionalidade que deve utilizá-la. Existem dois tipos:

• Ligações a nível do servidor, geridas pelos administradores do sistema na Consola do sistema › IA › Ligações de modelos. Apenas estas podem servir as funcionalidades integradas. As aplicações também as podem utilizar, para as pessoas autorizadas.
• Ligações da comunidade, que os administradores de uma comunidade adicionam para a sua própria comunidade nas definições da comunidade (ver abaixo). As aplicações utilizam-nas para as pessoas da comunidade. Nunca servem as funcionalidades integradas.

A secção IA da Consola do sistema é visível para as pessoas que podem gerir as ligações a nível do servidor: por omissão, os administradores do sistema. A sua página Ligações de modelos lista as ligações a nível do servidor e as de todas as comunidades.

Adicionar uma ligação

Na Consola do sistema › IA › Ligações de modelos, clique em Adicionar uma ligação e, em seguida, preencha o formulário:

Testar ligação verifica o endereço e a chave: o servidor pede ao endpoint os seus modelos, ou envia um chat de um único token. Um endereço alterado é testado com a chave guardada apenas após guardar, ou se escrever a chave novamente. Clique em Adicionar ligação para guardar.

O servidor faz as pedidos por si, pelo que tem de conseguir aceder à API: um servidor de modelos no mesmo projeto compose, na sua rede ou na Internet. Os pedidos de saída respeitam as variáveis HTTP_PROXY e HTTPS_PROXY.

Ao eliminar uma ligação, a respetiva chave é eliminada. As funcionalidades que a utilizavam deixam de usar IA até escolher outra ligação.

Limites e orçamentos

Cada ligação tem quatro limites. Um valor vazio ou 0 significa que não há limite.

• Pedidos por minuto e Por pessoa, pedidos por minuto. São contados separadamente por cada servidor: um cluster de três servidores permite até três vezes a taxa.
• Tokens por mês e Por pessoa, tokens por mês: orçamentos de tokens, por mês civil (UTC), contados na base de dados para todo o cluster. Vários pedidos em execução ao mesmo momento podem exceder ligeiramente um orçamento.

Os limites por pessoa aplicam-se também à reescrita e aos resumos: são contados para a pessoa que reescreve ou que é proprietária do resumo.

Utilização

A lista mostra a utilização de cada ligação neste mês. Utilização abre os detalhes: tokens de entrada e saída, pedidos, o orçamento mensal, utilização por dia (UTC) e por utilização (Reescrever, Resumos, Tradução automática, Texto para fala, Pessoas, através de aplicações ou uma aplicação).

Cada chamada que uma pessoa ou uma aplicação faz através de uma ligação também escreve um registo de auditoria: quem, a ligação, a utilização, o modelo, as contagens de tokens e se teve sucesso, nunca o que foi dito. As funcionalidades integradas são apenas contadas na utilização: a tradução sozinha faz uma chamada por mensagem e por idioma.

Ligações da comunidade

Os administradores da comunidade adicionam as ligações próprias da comunidade nas definições da comunidade, na separação Ligações de modelos. O formulário é o mesmo, sem Comunidades: a ligação de uma comunidade só funciona nos seus próprios canais, para os seus próprios membros, e o seu público só pode nomear as suas próprias equipas. Os papéis com a permissão Gestão de ligações de modelos também podem geri-las. Por omissão, os administradores da comunidade têm-na.

A ligação de uma comunidade não pode aceder a endereços privados ou de loopback (por exemplo, um servidor Ollama na sua rede), a menos que Consola do sistema › Ambiente › Desenvolvedor › Permitir ligações internas não fiáveis a (ServiceSettings.AllowedUntrustedInternalConnections) os liste. As ligações de todo o servidor podem.

Consulte Definições da comunidade para o lado dos administradores da comunidade.

A chave de encriptação

As chaves e os cabeçalhos adicionais das ligações de modelos são criptografadas na base de dados (AES-256-GCM) com uma única chave de criptografia. Uma cópia de segurança da base de dados por si só não as revela. O servidor procura a chave nesta ordem:

1. A variável AM_AI_ENCRYPTION_KEY: 32 bytes aleatórios, em base64. Crie uma com openssl rand -base64 32.
2. Caso contrário, o ficheiro ai-encryption.key na raiz do diretório de dados do servidor (FileSettings.Directory, ./data/ por omissão). O servidor cria-o, legível apenas por si próprio, na primeira vez que uma ligação o necessita. As aplicações, as exportações e os arquivos de ficheiros não o podem ler.

Quando definir a variável:

• Com o ficheiro compose do site. O compose.yaml passa AM_AI_ENCRYPTION_KEY a partir de .env e mantém o ficheiro da chave no volume data quando a variável está vazia. Definir a variável é melhor: a cópia de segurança de .env passa então a conter a chave, separada da base de dados. Adicione-a a .env e execute docker compose up -d:

  echo "AM_AI_ENCRYPTION_KEY=$(openssl rand -base64 32)" >> .env

  Se o servidor já criou o seu ficheiro de chave, coloque a chave que ele contém em .env em vez disso, para que as chaves guardadas permaneçam legíveis: docker compose exec antimatter cat /antimatter/data/ai-encryption.key mostra-a.
• Um cluster cujos ficheiros estão no S3. Os seus servidores não partilham um diretório, pelo que o servidor não cria o ficheiro: defina a mesma variável em todos os servidores. Até que seja definida, as ligações não podem guardar chaves.
• Com o arquivo de lançamento ou os pacotes, o ficheiro está em data/ (/var/lib/antimatter/data para os pacotes). Pode mantê-lo aí, ou definir a variável no seu ficheiro de ambiente.

Para alterar a chave, defina a nova em AM_AI_ENCRYPTION_KEY e a antiga em AM_AI_ENCRYPTION_PREVIOUS_KEYS (várias chaves separadas por vírgulas): as chaves guardadas com a antiga ainda podem ser lidas. A chave de uma ligação é criptografada com a nova chave quando a introduzir novamente. Mantenha a chave antiga na lista até que a chave de todas as ligações tenha sido introduzida novamente.

As funcionalidades integradas

Em Consola do sistema › IA › Funcionalidades integradas, escolha para cada funcionalidade uma ligação a nível de servidor e o respetivo modelo, ou Desligado. Uma funcionalidade sem ligação não utiliza IA. Carregar modelos lista todos os modelos da ligação; por omissão, cada funcionalidade utiliza o modelo de conversa da ligação.

Cada definição tem uma chave ConnectionId e uma chave Model, por exemplo AISettings.Rewrite.ConnectionId (AM_AISETTINGS_REWRITE_CONNECTIONID). Um Model vazio utiliza o modelo predefinido da ligação.

As funcionalidades integradas utilizam os limites da ligação, mas não o respetivo público: qualquer pessoa que possa utilizar a funcionalidade pode utilizar a sua ligação. Uma ligação que precise de atenção, ou que tenha sido eliminada, faz com que a funcionalidade falhe até escolher outra: a página indica-o.

Agentes de IA

A aplicação Agentes (id mattermost-ai) está ativada por omissão. A configuração requer duas etapas: adicionar um serviço (uma ligação a um prestador de modelos) e, em seguida, criar agentes (bots que usam um serviço).

1. Adicionar um serviço

Vá a Consola do sistema › Plugins › Agentes e, em Serviços de IA, clique em Adicionar um serviço de IA. Escolha o Tipo de serviço:

• Compatível com OpenAI: para um servidor de modelos que executa por sua conta, ou qualquer prestador com uma API ao estilo OpenAI. Preencha o URL da API (por exemplo, http://ollama:11434/v1 ou http://vllm.internal:8000/v1) e a Chave da API apenas se o servidor a necessitar. Se o servidor só suportar a API de Completions de Conversa, desative Usar API de Respostas.
• OpenAI, Anthropic, Google Gemini, Google Vertex AI, AWS Bedrock, Azure, Cohere, Mistral: prestadores de serviços alojados. Cada um necessita da respetiva Chave da API (Bedrock: uma região AWS e credenciais ou um papel IAM; Vertex AI: um projeto, uma região e uma conta de serviço; Azure: também o URL da API).

Defina em seguida o Modelo predefinido (uma lista, se o provedor puder reportar os seus modelos; caso contrário, escreva o nome) e, se o provedor não os reportar, o Limite de tokens de entrada e o Limite de tokens de saída. Um Serviço de recurso pode assumir o controlo quando este falhar. Guarde.

O servidor faz estas solicitações por sua conta, pelo que tem de conseguir aceder à API: um servidor de modelos no mesmo projeto compose, na sua rede ou na Internet. As solicitações em saída respeitam as variáveis HTTP_PROXY e HTTPS_PROXY.

2. Criar agentes

Os agentes são criados na página Agentes da aplicação web: abra-a com Gerir no seletor de agentes do painel de Agentes (na interface clássica, também a partir do menu do produto). O seu endereço é https://chat.example.com/plug/mattermost-ai/agents. Cada agente tem um Nome de apresentação, um Nome de utilizador do agente (como as pessoas o mencionam), um Serviço e, opcionalmente, um modelo, Instruções personalizadas e interruptores para Ativar visão (imagens) e Ativar ferramentas. A sua separação Acesso limita em que canais pode ser utilizado e que utilizadores o podem usar. Em Funções de IA no Consola do sistema, Bot predefinido escolhe o agente utilizado quando nenhum é selecionado, por exemplo para resumos de chamadas.

Funcionalidades opcionais da aplicação Agentes

• Pesquisa por incorporação (experimental, desativada): pesquisa semântica sobre mensagens. Requer PostgreSQL com a extensão pgvector e um modelo de incorporação (OpenAI ou compatível com OpenAI). Envia todas as mensagens para o modelo de incorporação, incluindo canais privados e mensagens diretas.
• Pesquisa na web (desativada): permite aos agentes pesquisar na web através do Google, do Brave ou de um servidor SearXNG que executar.
• Ferramentas nativas: com provedores que as oferecem, os agentes podem usar a pesquisa na web própria do provedor (ativada por predefinição para novos agentes, onde suportado), a obtenção de conteúdo da web e a execução de código. Estas são executadas no provedor. Desative-as por agente.
• Protocolo de contexto de modelo (MCP): ligue agentes a servidores MCP em que confia, para obter ferramentas adicionais.
• Depuração: Saída de rastreamento (desativada, registos do servidor ou um endpoint OpenTelemetry) e Ativar registo de utilização de tokens, que escreve as contagens de tokens em logs/agents/token_usage.log.

Conversão de voz em texto: transcrições e legendas de chamadas

As chamadas podem ser transcritas, com legendas em direto, por um servidor de reconhecimento de voz que ofereça um ponto de extremidade /v1/audio/transcriptions compatível com a OpenAI. A configuração está em Chamadas e voz. Com Resumir transcrições ativado, o agente predefinido também publica um resumo de cada transcrição.

Texto para fala: ler em voz alta

Com o texto para fala ativado, o menu de cada mensagem inclui Ler em voz alta: o servidor envia o texto da mensagem para uma API de texto para fala e reproduz o áudio. Definições, em Consola do sistema › Integrações › Texto para fala:

Para usar uma ligação de modelo em vez do endereço e da chave acima, seleccione-a para Texto para fala em IA › Funcionalidades integradas. A página indica então que as mensagens são lidas em voz alta com essa ligação: URL base da API e Chave da API não são usadas, Voz continua a ser, bem como Modelo quando a ligação não especifica um modelo. Ler mensagens em voz alta tem de estar ativado.

Antes de enviar, o servidor remove blocos de código, ligações, códigos de emoji e formatação, e mantém no máximo 4000 caracteres. Pede áudio em MP3 e mantém os últimos 64 resultados na memória, pelo que uma mensagem lida duas vezes só é enviada uma vez.

Tradução automática

A tradução automática mostra as mensagens de um canal na língua de cada leitor. Configure-a em Consola do sistema › Configuração do site › Localização, em Tradução automática:

Cada provedor tem os seus próprios campos:

• Ligação de modelo: uma ligação a nível de servidor e o seu modelo, a mesma definição que Tradução automática em IA › Funcionalidades integradas (AISettings.AutoTranslation). Um modelo de tradução dedicado é rápido e preciso; um LLM genérico também funciona.
• LibreTranslate: Ponto de extremidade da API do LibreTranslate e Chave de API do LibreTranslate (AutoTranslationSettings.LibreTranslate.URL, .APIKey). Um servidor LibreTranslate pode ser executado na sua própria rede.
• API compatível com a OpenAI: URL base da API (até e incluindo /v1; o servidor utiliza o seu ponto de extremidade de conclusões de conversa), Modelo e Chave da API (AutoTranslationSettings.OpenAI.URL, .Model, .APIKey). Um pequeno modelo de tradução executado localmente funciona bem.
• Serviço da aplicação de chat de IA (mais antigo): o provedor dos servidores configurados antes da 0.9.0, que usavam um serviço da aplicação Agentes. Já não necessita da aplicação: traduz com a ligação selecionada para a tradução automática em IA › Funcionalidades integradas, ou, caso contrário, com a ligação copiada do serviço da aplicação na atualização. Mudar para Ligação de modelo move a definição para o provedor recomendado.

Quando ativada, os administradores do canal ativam a tradução para um canal nas respetivas definições (Tradução automática), e cada membro pode desativá-la no menu do canal (Traduzir mensagens). Em mensagens diretas e de grupo, qualquer membro pode ativá-la; com a restrição ativada, a tradução não está disponível nesses contextos. As mensagens traduzidas mostram “Traduzido de …” com um link para a original.

O código, os links, as menções e os emojis são substituídos por marcadores antes de o texto ser enviado, e repostos depois.

Para onde vai cada tipo de dados

Para manter tudo na sua rede, aponte cada funcionalidade para servidores que gere por si próprio. Com um provedor de nuvem, verifique os termos de retenção de dados e informe os utilizadores que funcionalidades enviam as suas mensagens para o exterior.

Desativar a IA

Não existe um único interruptor: cada funcionalidade tem o seu próprio.

• Reescrita e resumos: defina-os como Desligado em Consola do sistema › AI › Funcionalidades integradas. As pessoas continuam a ler os resumos que já têm.
• Ligações de modelos: elimine uma ligação para interromper todo o seu uso. Sem qualquer ligação, nem as funcionalidades integradas nem as aplicações podem utilizar IA através do servidor.
• Agentes: desative a aplicação Agentes em Consola do sistema › Plugins › Gestão de Plugins. Isto também remove os resumos de chamadas.
• Transcrição e legendas: AM_CALLS_ENABLE_TRANSCRIPTIONS=false e AM_CALLS_ENABLE_LIVE_CAPTIONS=false (os valores predefinidos).
• Ler em voz alta: desligue Ler mensagens em voz alta (AM_TEXTTOSPEECHSETTINGS_ENABLE=false, o valor predefinido), independentemente de utilizar uma ligação.
• Tradução: desative a tradução automática (AM_AUTOTRANSLATIONSETTINGS_ENABLE=false, o valor predefinido).

Desativar a aplicação Agentes não desliga as outras funcionalidades: estas utilizam ligações de modelos ou as suas próprias APIs.