> 规范网页：https://docs.tensuu.com/功能模块详解/28_AI%20功能.html ｜ Markdown：/功能模块详解/28_AI%20功能.md ｜ 文档修订：2026.10.26

# AI 功能

这篇帮你做什么：接入自己的模型服务，为聊天、图片文字提取、图片内容理解、语音转文字和群消息总结配置模型。入口是 **AI 管理**，包含**服务设置、提示词设置、消息总结、运行与用量**四页。

## 开始前确认

- 应用不保证自带可用模型、密钥或免费额度。先向所选服务商获取账号、模型名称、接口地址和 API Key（调用服务的密钥），了解收费及余额限制。
- **连接测试和实际任务都可能消耗额度。** 应用中的每日 Token 限额是调用量限制，不是服务商的金额账单；Token 是模型计量输入、输出长度的单位。
- 群消息、图片或语音可能发送到你选择的模型服务。启用前确认测试群授权、服务商隐私政策和所需数据范围，不发送不应外传的内容。
- 控制台没有应用层登录保护，应只在可信网络访问。不要把密钥写进提示词、群消息、截图或普通备注；备份文件也需要妥善保管。
- 模型能聊天，不代表它也支持图片或音频。页面勾选能力只是声明，不能替服务商增加能力。

## 四类对象的关系与选择

AI 管理里的配置分成四层，**上层就绪不等于下层就绪**，一个任务可用需要四层全部到位：

| 对象 | 是什么 | 在哪配 | 就绪条件 |
| --- | --- | --- | --- |
| 模型 | 到某个服务商的一条连接：地址、密钥、能力声明 | 服务设置 → 添加模型 | 已保存、启用、凭据有效 |
| 任务 | 应用内的能力槽位（聊天、图片 OCR、图片理解、语音转文字、群消息总结） | 服务设置 → 任务分配 | 已分配模型并打开"使用此任务" |
| 提示词 | 按任务和版本管理的配置；正文是否发送取决于任务 | 提示词设置 | 已选定生效版本并"启用此任务" |
| 场景 | 任务在哪个功能里实际被触发 | 消息总结页 / 群聊监控 / 群基本设置 | 满足该场景的开关、输入和触发条件 |

选择建议：想让机器人回应群里的提问，用任务"聊天"，在[群基本设置](群基本设置.md)打开 **AI Chat 群级开关**，由成员 **@机器人** 触发；它不是指令目录里的聊天指令。想让机器人看懂图片或语音，用对应媒体任务并在[群聊监控](08_群聊监控.md)开群级识别；想给群消息生成一份回顾，用"群消息总结"并保持"投递到群"关闭，先在控制台看结果。只想回复固定答案、不需要模型时，用[问答](15_问答.md)更省额度。

群开关与模型、任务开关是独立配置：打开模型不会自动打开任何群。AI Chat 和媒体识别的群开关默认关闭；群总结则在每次创建时选择群和范围，没有一个需要常开的群总结开关。

## 额度与数据外传

- **全局额度**约束所有任务向服务商发起的新请求。
- **群级额度**在 **群设置 → 基本设置** 的 AI 用量卡片，只额外约束 **聊天和群消息总结**；未配置时按每日 409600 Token。图片文字提取、图片理解和语音转写只扣全局额度。因此某群额度设为 0 **不能停止该群的媒体识别**。
- **外传内容由任务决定**：群总结发送所选范围内的消息时间、显示名和纯文本；没有显示名时会回退到用户 ID，当前不发送 OCR/语音转写的派生文本。聊天发送对话文本及相应提示词；图片、语音任务会发送所需媒体或内容。总结范围要在创建时核对；其他场景还要核对群开关。
- **费用只在服务商侧发生**：应用只记录调用次数与 Token 估算，"费用未知（不计为 0）"就是字面意思——账单金额到服务商处查询。运行台账中的模型、提示词版本、用量等记录不能当成外发正文的完整副本。

## 通用配置（服务设置页顶部）

- **全局每日 Token 限额**：所有任务共用的每日调用量上限。填 **0** 会冻结需要访问模型服务商的新请求，**不取消已经发出的请求**。图片/语音的已缓存结果、相同群与消息快照及范围模式的历史成功总结仍可能被直接复用，不调用模型、不再次扣额度；因此它是外部调用止损手段，不是停止所有结果输出的总开关。
- **提示词历史版本保留天数**：1–90 天，默认 30 天。超过保留天数的旧提示词版本会被定期清理，正在使用的版本不会被删除。

## 第一步：添加模型连接

1. 打开 **AI 管理 → 服务设置**，在模型区域点 **添加模型**。
2. 如有合适的**服务商**预设，可用它预填地址和接口类型；仍须与服务商当前说明核对。
3. 填好这几项：

   | 字段 | 怎么填 |
   | --- | --- |
   | 显示名称 | 自己容易辨认的名字，用于控制台展示 |
   | 服务商模型名称 | 服务商提供的准确模型标识，不是自取名称 |
   | API 地址 | 完整接口地址，包含所选接口要求的路径；不要只填网站首页 |
   | API Key | 服务商签发的密钥，填到专用密码输入框 |
   | 接口类型 | 与服务商实际支持的接口对应 |
   | 支持的内容类型、适合处理的任务 | 只声明服务商确实支持的能力 |

4. 核对**启用此模型**，点 **保存设置**。输入长度、回复长度等限制应依据模型规格设置，不确定时不要随意抬高。
5. 重新打开模型确认配置已保存。密钥之后只显示已配置或脱敏值，不能通过回读得到原文；编辑时留空保留现有密钥，换密钥则输入新值。
6. 准备好费用与数据授权后，可以执行**连接测试**并查看**连接测试记录**。测试通过也不等于所有任务和群设置都已准备好。

API 地址和接口类型填错时，即使密钥正确也可能失败。不要反复换密钥来掩盖地址问题。

## 第二步：给任务分配模型

1. 在服务设置的**任务分配**中选要启用的任务。
2. 配置**首选模型**；确有需要时添加备用模型。备用模型也必须支持同一任务，并有自己的可用凭据。
3. 核对任务路由参数：

   | 参数 | 取值 | 说明 |
   | --- | --- | --- |
   | 超时 | 1–600 秒 | 等待服务商响应的时长；超时不自动重试 |
   | 单次最大回复长度 | 1–32000 Token | 限制模型单次输出的长度 |
   | 温度 | 0–2（步进 0.1） | 越高输出越发散；追求稳定回复用低值 |

4. 打开 **使用此任务**并保存。

一个模型可以供多个任务使用，但任务不会因为添加了模型就自动完成所有配置。首选模型不可用时可能尝试备用模型；不要把"停用首选模型"当成停止整个任务的办法。

## 第三步：选定并启用提示词

提示词是告诉模型"要做什么、按什么方式回答"的说明，与普通群提示或指令回复模板不同。

1. 打开 **AI 管理 → 提示词设置**，选择与任务分配相同的任务。
2. 查看当前模板；需要修改时保存为提示词版本。首次先保留系统预填内容，避免同时改模型和模板导致难以排查。
3. 在**生效设置**选定要使用的版本，打开 **启用此任务**并保存。
4. 核对页面就绪提示：模型分配与提示词都启用，才具备发起该任务的前提。

只保存新提示词版本，不代表它已成为正在使用的版本。旧版本会按"通用配置"里的保留天数清理；想回退到某个版本时，先确认它仍在版本列表中。不要把普通模板变量直接粘到 AI 提示词里；以该任务允许的变量和界面说明为准。

**不同任务实际使用的正文不同**：聊天使用系统提示词和用户消息模板；群总结只用系统提示词，用户内容由系统按消息生成。图片 OCR、图片理解和语音转写当前仍要求存在并启用提示词版本，但**不会把自定义提示词正文发送给模型**，语音的“转写提示”也不进入转写请求。不要靠修改这些正文来约束媒体识别行为。

## 第四步：配置实际使用场景

- **群消息总结**：打开 **AI 管理 → 消息总结**，点 **创建总结**，选择群、范围模式和 **投递到群** 开关。范围模式二选一：**最近 N 条**（1–1000，默认 100）或 **时间段**。"投递到群"默认关闭，此时只在控制台查看，不会发进群。列表可按状态、触发来源、范围筛选；详情显示实际消息数、缺失情况和错误原因。还需要可读取的消息，不能凭空总结。当前媒体派生文本不进入总结；详情“缺失媒体”为 0 也不能证明图片和语音都已被理解。具体外传内容按上文核对，不要仅凭页面提示推断。
- **图片或语音监控**：按[群聊监控](08_群聊监控.md)检查对应群开关。任务就绪不等于所有群都已开启媒体识别。
- **群内 AI Chat**：在[群基本设置](群基本设置.md)打开 **AI Chat 群级开关**，核对聊天任务就绪，由成员 **@机器人** 触发。无需在指令目录配置聊天关键词；前序指令或监控已受理消息等情况仍会影响实际触发。

先在可控测试群启用一个场景，确认实际输出后再扩大范围。

## 怎样判断成功或失败

依次区分：配置保存、任务就绪、请求完成、消息实际送达。模型生成了内容，不代表机器人已经把它发进群。"已受理不是平台成功、结果未知不重发"的通用判读方法见[结果判断与排障](../核心概念/结果判断与排障.md)。

在 **AI 管理 → 运行与用量** 分三处核对：

- **执行准备**：显示"可执行 / 配置不完整 / 尚未配置模型"、可执行模型数和已覆盖任务类型。不是"可执行"时按页面给出的原因处理（模型未启用、密钥未配置、任务未分配或未启用等），页面通常会给出下一步入口。
- **全局 Token 预算**：显示上限、已用、剩余和预算状态；预算"不可用"或被冻结时，需要访问服务商的新请求会被拒绝，已有结果复用见上文。若页面提示"预算使用记录恢复未完成"，为避免放宽额度，请求同样会被拒绝，系统会继续尝试恢复预算记录，**不是自动重发业务请求**。
- **运行状态与调用诊断**：按模型列出启用、密钥、任务分配情况，以及最近业务调用和向服务商发请求的记录，用于区分"没发起调用""调用失败""调用成功但没发进群"。

页面上的"费用未知（不计为 0）""结果未证实"表示应用只知道发出过请求、不知道服务商实际扣费或最终结果，不要把它们当成零成本或成功；账单金额仍需到服务商处查询。遇到未配置、任务停用、密钥缺失、能力不支持、超时或额度限制时，按具体原因处理，不笼统归为"AI 没反应"。

- 没有可选模型：检查模型是否已保存、启用并声明所需能力。
- 服务商拒绝：核对完整地址、接口类型、密钥权限、模型名称和余额。
- 页面已就绪但群里无输出：检查实际触发入口、群开关、可用消息和平台发送结果。
- 提示预算或计量异常：先停用受影响任务，再检查运行与用量中的原因；不要未经确认就提高额度或反复重试。

## 配置迁移

服务设置提供 **导出脱敏配置**和**导入配置**。导出文件不含 API Key 或敏感请求头明文，迁移后仍需重新配置凭据。导入会在现有配置上**追加**模型记录，不覆盖同名模型；文件会先做格式检查，原配置中使用过密钥的模型和敏感 Header 需要逐项补录凭据后才允许确认导入。它不是完整的数据备份，也不是数据恢复方法。

## 关闭或改回：按想停的范围选手段

**停用某个模型不是停止整个 AI**：停掉的模型退出候选后，配置了备用模型的任务可能继续由备用模型执行；即使没有备用模型，也只是这一个模型不可用。按下表选择正确的停止层级：

| 你想停的是什么 | 做法 | 不会停止什么 |
| --- | --- | --- |
| 某一个任务（如群消息总结） | 任务分配中关闭 **使用此任务**并保存；也可停用该任务提示词 | 其他任务仍正常运行 |
| 某个模型参与执行 | 模型卡片选 **停用模型**，任务分配保持不变；恢复时重新启用 | 有备用模型的任务会改用备用模型继续 |
| 全部向模型服务商发起的新请求 | 服务设置顶部 **全局每日 Token 限额** 改为 0，保存 | 已发请求不取消；缓存/历史结果仍可能复用 |
| 某个群的媒体识别 | 关闭该群在[群聊监控](08_群聊监控.md)的对应开关并保存 | 模型与其他群不受影响 |
| 某个群的自动 AI Chat | 关闭该群基本设置的 **AI Chat 群级开关**并保存 | 群总结、媒体识别与其他群不受影响 |
| 某个群聊天/总结的新外部调用 | 群级每日 Token 额度设为 0 并保存 | 不停止媒体识别，不阻止历史总结复用，其他群不受影响 |

不可逆与副作用：

- **删除模型会连带清理它的任务分配、请求 Header 和密钥，不可恢复**——只想暂停时不要删除。
- **清除密钥**会物理删除凭据记录，绑定该模型的任务会报"凭据未配置"直到重新配置；它不撤销已发送的数据，也不会退款。
- 改回提示词：在生效设置重新选择原版本（确认它仍在保留期内）。
- 停止配置不能撤回服务商已经收到的请求或群里已经发送的回复。费用、历史消息和密钥管理应分别处理。

## 和其他页面的关系

- AI 出错反馈的文案模板在[提示设置](23_提示设置.md)。
- 聊天与群消息总结实际使用的任务提示词在 **AI 管理 → 提示词设置**（见上文"第三步"）；总结投递到群的正文不取自普通提示目录的模板。
- 模板中的变量语法见[变量使用指南](../高级功能/变量使用指南.md)。