AI

Antimatter 的 AI 功能使用您选择的模型：云服务商，或您自己网络上的服务器。在配置模型之前，不会向任何地方发送数据。本页介绍模型连接、各项功能、其发送的数据以及如何关闭它们。

AI 功能

“兼容 OpenAI”是指提供与 OpenAI 相同 HTTP API 的服务器。大多数您可以自行运行的模型服务器都支持（例如 Ollama、vLLM、llama.cpp 的服务器，或 Whisper 和文本转语音服务器），许多云服务商和网关（如 LiteLLM 或 OpenRouter）也支持。使用这些功能均无需许可证。

内置功能（改写、摘要、翻译和朗读）不需要 Agents 应用：它们使用您在系统控制台中添加的模型连接。

模型连接

模型连接是 Antimatter 可以调用的 AI 提供商：其地址、密钥及其模型。您只需添加一次，然后为需要使用它的每项功能进行选择。有两种类型：

• 服务器级连接，由系统管理员在系统控制台 › AI › 模型连接中管理。只有它们才能为内置功能提供服务。应用也可以为获许可的人员使用它们。
• 社区连接，由社区管理员在其社区设置中为其社区添加（见下文）。应用为社区成员使用它们。它们绝不为内置功能提供服务。

系统控制台的AI部分显示给可以管理服务器级连接的人员：默认情况下是系统管理员。其模型连接页面列出服务器级连接以及所有社区的连接。

添加连接

在系统控制台 › AI › 模型连接中，点击添加连接，然后填写表单：

测试连接 检查地址和密钥：服务器向端点请求其模型列表，或发送一个单 token 的聊天。修改后的地址仅在保存后，或重新输入密钥后，才会使用已保存的密钥进行测试。点击 添加连接 保存。

服务器会自行发起请求，因此必须能够访问 API：可以是同一 compose 项目中的模型服务器，也可以是位于您的网络或互联网上的服务器。出站请求会遵循 HTTP_PROXY 和 HTTPS_PROXY 变量。

删除连接会使其密钥失效。使用过该连接的功能将停止使用 AI，直到您选择另一个连接。

限制与预算

每个连接都有四项限制。留空或设为 0 表示无限制。

• 每分钟请求数 和 每人每分钟请求数。它们由每台服务器单独计数：由三台服务器组成的集群允许通过的速率最高可达单台的三倍。
• 每月令牌数 和 每人每月令牌数：按日历月（UTC）计算的令牌预算，在整个集群的数据库中计数。同时运行的多个请求可能会略微超出预算。

每人限制也适用于改写和回顾：它们计入执行改写的人或拥有回顾的人。

使用情况

列表显示每个连接本月的使用情况。使用情况 可打开详细信息：输入和输出的令牌数、请求数、每月预算、按天（UTC）和按用途（改写、回顾、自动翻译、文本转语音、人员，通过应用，或某个应用）的使用情况。

人员或应用通过连接进行的每次调用都会写入一条审计记录：包括谁、连接、用途、模型、令牌数量以及是否成功，但绝不会记录说了什么。内置功能仅计入使用情况：仅翻译功能会为每条消息和每种语言生成一次调用。

社区连接

社区管理员在社区设置的 模型连接 选项卡中添加其社区自己的连接。表单相同，但没有 社区：社区连接仅在其自己的频道中工作，仅为其自己的成员服务，且其受众只能指定其自己的团队。拥有 管理模型连接 权限的角色也可以管理它们。默认情况下，社区管理员拥有此权限。

社区连接无法访问私有或回环地址（例如您网络上的 Ollama 服务器），除非 系统控制台 › 环境 › 开发人员 › 允许不受信任的内部连接到（ServiceSettings.AllowedUntrustedInternalConnections）列出了这些地址。服务器范围的连接可以访问。

请参阅 社区设置 了解社区管理员一侧的内容。

加密密钥

模型连接的密钥和附加请求头使用单一加密密钥在数据库中加密（AES-256-GCM）。仅备份数据库不会泄露它们。服务器按以下顺序查找密钥：

1. AM_AI_ENCRYPTION_KEY 变量：32 个随机字节，以 base64 编码。可使用 openssl rand -base64 32 生成。
2. 否则，使用服务器数据目录（FileSettings.Directory，默认为 ./data/）根目录下的 ai-encryption.key 文件。服务器会在首次有连接需要该密钥时创建此文件，且仅自身可读。应用、导出文件和文件归档均无法读取它。

何时设置该变量：

• 使用站点的 compose 文件。 compose.yaml 会从 .env 传递 AM_AI_ENCRYPTION_KEY，并在该变量为空时将密钥文件保留在 data 卷中。设置该变量更好：这样 .env 的备份就会包含密钥，且与数据库分开。将其添加到 .env 并运行 docker compose up -d：

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

  如果服务器已经创建了密钥文件，请将其中包含的密钥放入 .env，以便已保存的密钥保持可读：docker compose exec antimatter cat /antimatter/data/ai-encryption.key 会打印出该密钥。
• 文件位于 S3 的集群。 由于这些服务器不共享目录，因此服务器不会创建该文件：请在每个服务器上设置相同的变量。在设置之前，连接无法保存密钥。
• 如果使用发布包或软件包，文件位于 data/（对于软件包为 /var/lib/antimatter/data）。您可以将其保留在那里，或在您的环境文件中设置该变量。

若要更改密钥，请将新密钥设置在 AM_AI_ENCRYPTION_KEY 中，将旧密钥设置在 AM_AI_ENCRYPTION_PREVIOUS_KEYS 中（多个密钥用逗号分隔）：使用旧密钥保存的密钥仍然可读。当您重新输入连接的密钥时，该密钥会使用新密钥进行加密。请在所有连接的密钥都重新输入之前，将旧密钥保留在列表中。

内置功能

在 系统控制台 › AI › 内置功能 中，为每个功能选择服务器范围的连接及其模型，或选择 关闭。未选择连接的功能将不使用 AI。加载模型 会列出该连接的所有模型；默认情况下，每个功能使用连接的聊天模型。

每个设置都有一个 ConnectionId 和一个 Model 键，例如 AISettings.Rewrite.ConnectionId（AM_AISETTINGS_REWRITE_CONNECTIONID）。空的 Model 使用连接的默认模型。

内置功能使用连接的限额，但不使用其受众：任何可以使用该功能的人都可以使用其连接。如果连接需要关注或被删除，该功能将失败，直到你选择另一个连接：页面会说明这一点。

AI 智能体

Agents 应用（id mattermost-ai）默认开启。设置它需要两个步骤：添加一个服务（与模型提供商的连接），然后创建智能体（使用服务的机器人）。

1. 添加服务

前往 系统控制台 › 插件 › 智能体，在 AI 服务 下点击 添加 AI 服务。选择 服务类型：

• OpenAI 兼容：适用于您自行运行的模型服务器，或任何提供 OpenAI 风格 API 的服务提供商。填写 API URL（例如 http://ollama:11434/v1 或 http://vllm.internal:8000/v1），仅当服务器需要时才填写 API 密钥。如果服务器仅支持 Chat Completions API，请关闭 使用 Responses API。
• OpenAI、Anthropic、Google Gemini、Google Vertex AI、AWS Bedrock、Azure、Cohere、Mistral：托管服务提供商。每个都需要其 API 密钥（Bedrock：需要 AWS 区域和凭据或 IAM 角色；Vertex AI：需要项目、区域和服务账号；Azure：还需要 API URL）。

然后设置默认模型（如果提供商可以报告其模型列表，则从列表中选择；否则，请输入名称），以及（如果提供商未报告）输入令牌限制和输出令牌限制。当此服务失败时，备用服务可以接管。保存。

服务器会自行发起这些请求，因此必须能够访问 API：可以是同一 compose 项目中的模型服务器、您网络上的服务器，或互联网上的服务器。出站请求会遵循 HTTP_PROXY 和 HTTPS_PROXY 变量。

2. 创建智能体

智能体在网页应用的智能体页面创建：打开智能体面板中的智能体选择器，点击管理（在经典界面中，也可从产品菜单进入）。其地址为 https://chat.example.com/plug/mattermost-ai/agents。每个智能体都有一个显示名称、一个智能体用户名（用于提及该智能体）、一个服务，以及可选的模型、自定义指令，还有用于启用视觉功能（图像）和工具的开关。其访问选项卡用于限制可以在哪些频道中使用该智能体，以及哪些用户可以使用它。在系统控制台的AI 功能中，默认机器人用于选择未指定智能体时所使用的智能体，例如用于通话摘要。

智能体应用的可选功能

• 嵌入搜索（实验性，默认关闭）：对消息进行语义搜索。需要支持 pgvector 扩展的 PostgreSQL 以及一个嵌入模型（OpenAI 或兼容 OpenAI 的模型）。它会将所有消息（包括私有频道和私信）发送到嵌入模型。
• 网络搜索（默认关闭）：允许智能体通过 Google、Brave 或您自行运行的 SearXNG 服务器搜索网络。
• 原生工具：对于提供这些功能的提供商，智能体可以使用提供商自身的网络搜索（对于新智能体，若受支持则默认开启）、网页抓取和代码执行。这些操作在提供商端运行。可按智能体关闭这些功能。
• 模型上下文协议 (MCP)：将智能体连接到您信任的 MCP 服务器，以获取额外工具。
• 调试：跟踪输出（默认关闭，输出到服务器日志或 OpenTelemetry 端点）和启用令牌使用日志，后者会将令牌计数写入 logs/agents/token_usage.log。

语音转文字：通话转录和实时字幕

通话可以通过提供兼容 OpenAI 的 /v1/audio/transcriptions 端点的语音转文本服务器进行转录，并支持实时字幕。相关设置位于通话与语音中。开启转录摘要后，默认智能体还会发布每条转录内容的摘要。

文本转语音：朗读

开启文本转语音后，每条消息的菜单中都会显示朗读：服务器会将消息文本发送至文本转语音 API 并播放音频。设置位于系统控制台 › 集成 › 文本转语音：

若要使用模型连接代替上述地址和密钥，请在AI › 内置功能中为文本转语音选择该连接。页面随后会提示消息将通过该连接朗读：API 基础 URL和API 密钥将不再使用，声音仍会生效，如果连接未指定模型，模型也会生效。朗读消息必须保持开启状态。

发送前，服务器会移除代码块、链接、表情符号代码和格式，并保留最多 4000 个字符。它请求 MP3 音频，并在内存中保留最近 64 个结果，因此同一条消息被朗读两次时只会发送一次。

自动翻译

自动翻译功能会以每位读者自己的语言显示频道中的消息。请在系统控制台 › 站点配置 › 本地化下的自动翻译中进行配置：

每个提供商都有各自的字段：

• 模型连接：服务器范围的连接及其模型，与AI › 内置功能中的自动翻译设置相同（AISettings.AutoTranslation）。专用的翻译模型速度快且准确；通用 LLM 也可以使用。
• LibreTranslate：LibreTranslate API 端点和LibreTranslate API 密钥（AutoTranslationSettings.LibreTranslate.URL、.APIKey）。LibreTranslate 服务器可以在您自己的网络上运行。
• 兼容 OpenAI 的 API：API 基础 URL（包含 /v1；服务器使用其聊天补全端点）、模型和API 密钥（AutoTranslationSettings.OpenAI.URL、.Model、.APIKey）。在本地运行的小型翻译模型效果良好。
• AI 聊天应用的服务（旧版）：0.9.0 之前配置的服务器所使用的提供商，当时使用的是智能体应用的服务。它不再需要该应用：它使用在AI › 内置功能中为自动翻译选择的连接进行翻译，或者使用升级时从应用服务复制的连接。切换到模型连接会将设置迁移到推荐的提供商。

启用后，频道管理员可在频道的设置中为该频道开启翻译（自动翻译），每位成员也可在频道菜单中选择不翻译（翻译消息）。在私信和群组消息中，任何成员均可开启翻译；若启用了限制，则在这些场景中不可用。翻译后的消息会显示“从……翻译而来”，并附带指向原文的链接。

在发送文本之前，代码、链接、提及和表情符号会被替换为占位符，发送后再还原。

数据流向何处

要将所有数据保留在您的网络内，请将每项功能指向您自行运行的服务器。如果使用云服务商，请查看其数据保留条款，并告知用户哪些功能会将消息发送到外部。

关闭 AI 功能

没有统一的开关：每项功能都有各自的开关。

• 重写和摘要：在系统控制台 › AI › 内置功能中将其设置为关闭。用户会持续阅读已有的摘要。
• 模型连接：删除连接即可停止其所有使用。如果没有连接，内置功能和应用程序都无法通过服务器使用 AI。
• 智能体：在系统控制台 › 插件 › 插件管理中禁用智能体应用。这也会移除通话摘要。
• 转录和实时字幕：AM_CALLS_ENABLE_TRANSCRIPTIONS=false 和 AM_CALLS_ENABLE_LIVE_CAPTIONS=false（默认值）。
• 朗读：关闭朗读消息（AM_TEXTTOSPEECHSETTINGS_ENABLE=false，默认值），无论其是否使用连接。
• 翻译：关闭自动翻译（AM_AUTOTRANSLATIONSETTINGS_ENABLE=false，默认值）。

禁用智能体应用不会关闭其他功能：它们使用模型连接或各自的 API。