nonebot-plugin-ai-groupmate 2.5.0

✨ nonebot-plugin-ai-groupmate ✨

📖 介绍

2.0 版本更新，轻量化依赖，全部使用 API 进行调用，基本上任何设备都能运行。

本插件主体使用 langchain 的 agent 进行决策，由 langchain 调用 tools 进行一系列任务。

• 群体认知档案：由 bot 在发现值得长期记住的新话题、成员特征、内部梗或氛围变化时自主更新，让 bot 对群文化有持续感知。
• 长记忆（需配置 Qdrant）：RAG 自动存储聊天历史，学习群友发言习惯，使 bot 更像真人。
• 表情包学习（需配置 Qdrant）：使用 qwen-vl-max 理解图片内容，分别索引描述语义与视觉特征，自动从群内偷学表情包；回复时通过 RRF 多路召回，结合当前群的真实使用频率重排，并在发送前按当前对话审核相关性。
• 自定义 Agent Tools：可以注册自己的 LangChain tools 扩展 agent 能力，详见 自定义 Agent Tools。

对于主模型选择：推荐使用支持 Function Calling 的通义千问系列模型（如 qwen-plus、qwen-max）。图片理解固定使用 qwen-vl-max，群档案摘要固定使用 qwen-flash。

💿 安装

nb plugin install nonebot-plugin-ai-groupmate --upgrade

nb plugin install nonebot-plugin-ai-groupmate --upgrade -i "https://pypi.org/simple"

nb plugin install nonebot-plugin-ai-groupmate --upgrade -i "https://pypi.tuna.tsinghua.edu.cn/simple"

uv add nonebot-plugin-ai-groupmate

uv add git+https://github.com/yaowan233/nonebot-plugin-ai-groupmate@master

pdm add nonebot-plugin-ai-groupmate

pdm add git+https://github.com/yaowan233/nonebot-plugin-ai-groupmate@master

poetry add nonebot-plugin-ai-groupmate

poetry add git+https://github.com/yaowan233/nonebot-plugin-ai-groupmate@master

plugins = ["nonebot-plugin-ai-groupmate"]

nbr plugin install nonebot-plugin-ai-groupmate

nbr plugin install nonebot-plugin-ai-groupmate -i "https://pypi.org/simple"

nbr plugin install nonebot-plugin-ai-groupmate -i "https://pypi.tuna.tsinghua.edu.cn/simple"

从旧版本升级

表情包多向量集合 media_collection_v3 从 v2.1.1 开始引入。升级前请按当前版本和向量化模式确认迁移路径：

新版聊天 RAG 会创建 chat_collection_v2，并在启动后于后台从 SQL 历史记录重建干净的 Dense + 稀疏混合索引。升级前需要先执行 nb orm upgrade；旧 chat_collection 会保留且不会阻塞 Bot 启动。待日志显示历史会话向量化完成、RAG 查询正常后，可按需人工删除旧集合。

可用下面的命令确认 v3 集合存在并查看向量数量（请按实际地址修改 Qdrant URL）：

curl http://127.0.0.1:6333/collections/media_collection_v3

迁移依赖原始表情包文件和可用的 Qwen 向量接口。如果旧文件已经丢失，对应数据无法重建到 v3；此时不要删除旧集合，也不要升级到不再读取 media_collection 的版本。完成升级并确认搜索正常后，旧 media_collection 才可以删除。

⚙️ 配置

配置说明

向量功能要求 Qdrant 服务端版本不低于 1.16，因为插件使用 collection metadata 记录并校验 Embedding 模型与维度。

修改 embedding_model 或 embedding_dimension 前，请自行重建聊天与纯文本表情包的 Qdrant 向量。插件不会迁移既有向量；旧文本集合缺少 metadata 且当前模型不是历史默认的 BAAI/bge-m3 时，插件会拒绝使用该集合，避免混用不同模型生成的向量。

如果多个插件共用 nonebot-plugin-orm，建议同时将 SQLAlchemy 连接池设为快速失败，避免外部插件耗尽连接时每条消息卡住 30 秒：

SQLALCHEMY_ENGINE_OPTIONS={"pool_size":5,"max_overflow":10,"pool_timeout":5,"pool_pre_ping":true}

并发限制用于避免本插件耗尽连接池；pool_timeout=5 是其他插件或数据库异常时的快速降级保护，不建议只靠扩大连接池解决泄漏。

用量 WebUI 默认地址为 /ai-groupmate/usage。升级数据库后，页面会额外展示每轮 agent 的 LLM/工具调用次数、平均耗时、工具超时、结果截断与副作用去重情况；旧记录会以 0 显示这些新增指标。

用量统计页及其 JSON 接口可直接访问，不需要 Token。页面右上角的“配置中心”可维护插件运行配置；配置中心使用前必须在环境变量中设置非空的 AI_GROUPMATE__USAGE_WEBUI_TOKEN，并通过独立的 HttpOnly Cookie 登录，不会在页面中回显 API Key。网页保存的值存入插件数据库，加载顺序为“代码默认值 → 环境变量 → 网页覆盖值”；可随时一键恢复环境变量配置。

配置中心顶部的“群聊 API”页面可由 Bot 管理员按群 ID 新增、修改和删除独立主聊天模型，并可随独立 API 配置设置该群的主动发言概率。群级概率范围为 0～0.1，留空则跟随全局值；没有独立大模型 API 的群不能单独调整。新增或修改时会先测试模型连接，成功后立即生效；编辑已有记录时 API Key 留空会保留原 Key。列表与接口只返回脱敏信息，删除后该群立即恢复使用全局主聊天 API 和主动发言概率。启用配置中心后，插件也会自动生成本地群 API 加密密钥，因此即使不启用公网中转也可以使用这个管理页。

针对内网部署 Bot 的会话级自带模型 API（BYOK）能力已经完成端到端实现：群管理员可为群聊配置，私聊用户也可为自己配置；公网配置页生成一次性配置码，插件解密并测试后按群或按用户保存主模型配置。协议与部署说明见 分群模型 API 中转配置设计。配套 FastAPI 中转服务位于 ../backend，Mayumi 配置页位于 ../mayumi-front；生产启用前仍需配置域名、HTTPS 与 Secret。

插件默认使用 https://mayumi.xyz 作为群 API 中转地址，不需要额外配置 URL。只有使用自建中转服务时才需要覆盖：

AI_GROUPMATE__GROUP_API_RELAY_URL=https://relay.example.com
# 仅中转服务器未开放公开注册时需要
AI_GROUPMATE__GROUP_API_RELAY_REGISTRATION_TOKEN=replace-with-issued-token
# 可选；建议生产环境显式限制群管理员可选的模型服务域名
AI_GROUPMATE__GROUP_API_ALLOWED_PROVIDER_HOSTS=["api.openai.com","openrouter.ai","*.example-provider.com"]

使用默认 Mayumi 公开注册服务时，不需要配置 AI_GROUPMATE__GROUP_API_RELAY_REGISTRATION_TOKEN。

插件默认在数据目录生成 group_api_local_encryption.key。请把该文件与数据库一起持久化并备份；丢失后已经保存的群 API Key、实例令牌和私钥均无法恢复。使用 Secret 管理平台时，也可以继续显式设置本地主密钥：

python -c "import base64,secrets; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode().rstrip('='))"

GROUP_API_RELAY_REGISTRATION_TOKEN 只在 Bot 第一次向中转服务注册时使用，注册成功并确认数据库已持久化后可以从环境中移除。上述启动配置不会进入插件配置中心，也不会在 WebUI 回显。

回复概率、Agent 限制、模型与费用配置会在保存后热更新；Qdrant、Embedding、表情包向量化模式、兼容 Qwen Token 和 Rerank 连接配置会标记为“等待重启”。WebUI 开关、访问路径和管理密码属于启动配置，仍需通过环境变量修改。升级后请先执行：

nb orm upgrade

最小配置示例：

AI_GROUPMATE__BOT_NAME=bot
AI_GROUPMATE__LLM_API_KEY=sk-xxxx
AI_GROUPMATE__CHAT_MODEL=qwen3.5-plus

Vertex AI 主模型示例（推荐使用服务账号或其他 ADC，不要把 JSON 内容写进 .env）：

AI_GROUPMATE__CHAT_API_FORMAT=vertex
AI_GROUPMATE__CHAT_MODEL=gemini-3.7-flash
AI_GROUPMATE__VERTEX_PROJECT=your-google-cloud-project
AI_GROUPMATE__VERTEX_LOCATION=global
AI_GROUPMATE__VERTEX_CREDENTIALS_PATH=/app/secrets/vertex-service-account.json

把服务账号 JSON 只读挂载到上述容器路径，并授予服务账号 Vertex AI User （roles/aiplatform.user）角色。也可以不设置 VERTEX_CREDENTIALS_PATH，改用 GOOGLE_APPLICATION_CREDENTIALS、Workload Identity 或运行环境已有的 ADC。插件会自动 刷新 OAuth 凭据。若从 OpenRouter 迁移，google/gemini-... 模型名也会自动移除 google/ 前缀；CHAT_API_KEY 和 CHAT_BASE_URL 在 Vertex 模式下不会使用。

Vertex AI Express Mode API Key 不需要项目 ID 和区域：

AI_GROUPMATE__CHAT_API_FORMAT=vertex
AI_GROUPMATE__CHAT_MODEL=gemini-3.7-flash
# 将 Google 官方示例中 GOOGLE_CLOUD_API_KEY 对应的 Key 值填在这里
AI_GROUPMATE__VERTEX_API_KEY=AIza...

如果 Google 控制台或官方示例将 Express Mode Key 称为 GOOGLE_CLOUD_API_KEY， 直接把它的值填给 AI_GROUPMATE__VERTEX_API_KEY 即可；不需要再配置一个名为 GOOGLE_CLOUD_API_KEY 的环境变量。把上述插件配置直接写入 NoneBot 项目使用的 .env 即可，也不需要在 Docker Compose 中额外声明 environment，或配置 Project ID、Location、服务账号。插件检测到该 Key 后会使用 Express Mode，并忽略 VERTEX_PROJECT 和 VERTEX_LOCATION；认证优先级为服务账号 JSON → Vertex API Key → ADC。AI_GROUPMATE__CHAT_API_KEY 是其他接口使用的聊天模型 Key，在 Vertex 模式下不会读取。

固定知识示例（将群号和入群方式替换为自己的信息）：

AI_GROUPMATE__PERSONALITY_SETTING="【固定知识】当用户询问加群、群号、入群方式或请求拉群时，明确告诉对方：请搜索 QQ 群 123456789 申请加入，验证信息填写‘来自 Bot’。不要编造其他群号或链接。"

修改该配置后需要重启 Bot。固定知识会同时用于群聊和私聊；涉及口令、密钥等敏感内容时不要放在这里。

如果想使用更强的主聊天模型：

AI_GROUPMATE__CHAT_MODEL=qwen3.7-plus

如果要让 qwen3.8-max 使用百炼服务器提供的代码解释器、联网搜索和网页抓取：

AI_GROUPMATE__CHAT_MODEL=qwen3.8-max
AI_GROUPMATE__CHAT_RESPONSES_BUILTIN_TOOLS='["code_interpreter","web_search","web_extractor"]'
AI_GROUPMATE__CHAT_RESPONSES_ENABLE_THINKING=true

这些工具只在官方百炼 OpenAI 兼容地址上生效，配置后会自动使用 Responses API。所有工具默认关闭；工具列表只是授权模型按需调用，并不代表每轮都会执行。web_extractor 依赖 web_search，只填写前者时插件也会自动启用后者。代码解释器因为不能与 Bot 的 Function Calling 同请求，会由插件隔离调用，再把结果交回主 Agent。

华北 2（北京）当前参考工具价为：code_interpreter、web_extractor 限时免工具费，web_search 4 元/千次，web_search_image（文搜图）24 元/千次，image_search（图搜图）48 元/千次；所有工具产生的额外模型 Token 仍收费，实际价格以百炼控制台为准。Token Plan Harness 的 t2i_search / i2i_search 个人版 Key 不可用于机器人后端，因此这里使用普通按量 API 的正式工具名。接口、地域和计费依据见 千问 Responses API 官方工具调研。

插件会尽量复用稳定 system prompt、固定工具 schema，并在连续对话中复用 append-only history，以提高输入缓存命中率。日志中可通过 [LLM缓存] 查看缓存命中 token；如果服务商未返回缓存字段，会显示 缓存命中=未返回。

🎉 使用

@bot 即可触发回复，也会以 reply_probability 的概率主动发言；额度开关默认开启，未配置群聊独立 API 时，每群每天默认可使用公共主模型回复 50 次，私聊则为每位用户每天 10 次，额度按 Bot 本地时间零点重置。额度耗尽后会提示 /配置群API 或 /配置个人API；已配置相应独立大模型 API 的群或私聊用户不受公共额度限制。可在管理界面关闭对应额度开关，关闭后不查询或记录额度。群管理员还可覆盖本群主动发言概率，但用户配置上限为 0.1。Bot 已在当前连续对话窗口参与、随后至少两名不同群友连续发送同一句短文本时，会按 repeat_probability 独立决定是否原样加入队形。reaction 和图片表情不再对未提及 Bot 的普通群消息主动采样；只有当前消息明确呼叫 Bot、回复 Bot、处于同一用户的连续对话窗口，或用户明确要求时，才会交给 Agent 选择或执行。

自定义 Agent Tools

如果你想给 agent 增加自己的工具（例如查询业务系统、控制设备、调用自定义 API），可以参考 自定义 Agent Tools。

内置了好感度系统，增加了趣味性。

以下功能需要配置 Qdrant

配置 Qdrant 后，ai 会自动偷群内使用的表情包并存入向量库，回复时通过 VLM 语义匹配发出，准确率非常高。 发送群内偷学到的表情包 利用 RAG 对聊天历史进行语义检索，可进行总结、查询等功能。

指令表

由于 AI 功能需要记录聊天记录，基于已记录的聊天记录，可以很轻松的做到词频统计，所以顺带加上了。

关系备份保存在 NoneBot 插件数据目录下的 relation_backups 文件夹中。重复执行是安全的；没有负好感度记录时不会创建备份或修改数据库。