想给 QQ 群接入一个能自动回复的 AI 机器人又不想从零研究协议、消息收发和事件处理这篇文章会分享一条经过验证的快速路线基于 NoneBot2 搭建 QQ 机器人再接入大模型 API实现群聊中的 AI 问答。整个过程没有复杂的前端页面也不需要自建推理服务重点是把消息通道和 AI 调用打通。无论是个人群聊助手还是团队内部的知识问答机器人都可以按这套思路落地。1. QQ 机器人的工作原理与 AI 接入方式1.1 QQ 机器人究竟是什么很多同学第一次接触“QQ 机器人”时会对它的运行方式有误解以为需要一个 24 小时挂着 QQ 的账号来收发消息。实际上主流方案并不直接操作 QQ 客户端。通常的做法是把机器人作为一个后台服务运行在你自己的服务器、云主机甚至本地电脑上。它通过某种方式接收 QQ 群里的消息经过逻辑处理后再以机器人的身份把回复发回群里。消息的发送和接收不一定依赖完整客户端更多是通过协议适配器完成。简单理解QQ 群消息 → 机器人框架NoneBot2→ 插件逻辑 → 大模型 API → 回复内容 → 机器人框架 → QQ 群在这个链条里框架只负责“搬运”消息真正的智能问答能力来自你接入的大模型。这样做的好处是机器人的能力不局限于固定的问答库而是可以借助大模型理解语义、生成回复甚至按你的提示词设定角色。1.2 两种常见的消息通道方案这里要区分一个概念机器人的“身体”和“大脑”是可以拆开的。消息通道负责让机器人出现在 QQ 群里常见有官方机器人平台腾讯官方提供的 QQ 机器人开放接口需要走平台审核流程适合企业级、合规要求高的场景。社区协议方案基于开源社区维护的协议实现开发灵活、上手快但需要自己注意账号风险和使用边界。本文选用 NoneBot2 的原因是它把消息通道和业务逻辑做了很好的解耦。你不需要关心底层协议细节只需要写插件框架会自动把群消息分发到对应的处理器。1.3 AI 模型接入的三种常见路径接入 AI 能力时不同场景有不同的选择接入方式适合场景特点大模型平台 API个人项目、快速验证接入简单按量计费效果稳定私有化部署模型企业内部、数据敏感需要 GPU 资源运维成本高第三方聚合 API多个模型切换统一接口灵活路由但依赖中间服务对于 5 分钟快速制作的目标来说优先推荐第一种开通一个大模型 API用 HTTP 调用返回结果。这样既不需要本地显卡也不用维护推理服务。2. 环境准备与版本说明2.1 开发环境清单为了避免读者因为环境不一致而卡住这里先把推荐环境列出来。版本不需要绝对一致但要保证大版本兼容。组件推荐版本说明Python3.10 及以上NoneBot2 对 Python 3.9 支持良好3.10 更稳NoneBot22.x 系列事件驱动的机器人框架OneBot V11 适配器2.x用于连接 QQ 消息通道大模型 API SDK官方 SDK 或 openai 兼容 SDK根据所选平台调整操作系统Windows / Linux / macOS本文示例以本地开发为主2.2 安装 NoneBot2 脚手架先安装 NoneBot2 的项目脚手架工具它可以帮助我们快速生成项目模板。pip install nb-cli安装完成后使用 nb-cli 创建项目nb create命令行会进入交互式创建流程其中需要选择项目名称例如qq-ai-bot适配器类型这里选择OneBot V11插件加载方式默认即可创建命令执行完毕后你会得到一个结构清晰的 NoneBot2 项目。进入到项目目录cd qq-ai-bot此时目录结构大致如下qq-ai-bot/ ├── .env ├── .env.prod ├── bot.py ├── pyproject.toml └── src/ └── plugins/如果你对命令行交互不熟悉也可以手动创建项目安装核心依赖pip install nonebot2 nonebot-adapter-onebot但更推荐使用 nb-cli它生成的 pyproject.toml 文件已经包含了依赖和入口配置。2.3 准备一个可用的 AI APIAI 能力方面准备一个支持 HTTP 调用的大模型 API。当前主流大模型平台普遍提供 OpenAI 兼容格式的接口这意味着你可以用同一套代码通过修改 Base URL 和模型名称来切换服务商。本文的示例将以 OpenAI 兼容接口为基础编写代码层面不绑定特定厂商。实际使用中你需要准备好API Key也就是密钥用于身份认证Base URL接口地址Model 名称例如gpt-3.5-turbo或服务商对应的模型标识余额充足避免调用失败注意不要把 API Key 硬编码到代码里更不要把密钥提交到公开仓库。3. 核心原理拆解从群消息到 AI 回复3.1 NoneBot2 的事件响应机制NoneBot2 的核心设计是“事件驱动”。你可以把机器人理解成一个一直监听事件的程序。当群里有新消息时适配器会将其包装成一个事件对象并交给框架处理。开发者只需要定义事件响应器Matcher告诉框架“什么样的消息触发什么样的操作”。例如from nonebot import on_command ai_chat on_command(ai, aliases{AI, 机器人}, priority5)这段代码定义了一个事件响应器当用户在群里发送/ai 你好或以/AI 你好、/机器人 你好开头时就会触发ai_chat对应的处理函数。这种设计的好处是典型的“关注点分离”消息从哪个群来、由谁发送框架替你处理插件里只关心消息内容以及如何回复新增功能时新增一个响应器即可不影响旧功能3.2 插件Plugin的工作方式NoneBot2 的插件机制类似其他框架的“模块”。一个插件可以包含一个或多个事件响应器。插件按目录组织每个插件目录下需要有__init__.py文件方便框架加载。插件在src/plugins目录下自动加载。如果你想手动加载某个插件也可以在bot.py中通过nonebot.load_plugin(插件路径)注册。理解插件机制后我们会发现AI 接入本质上就是写一个插件在插件里调用大模型 API然后把返回结果通过matcher.send()发回群里。3.3 大模型 API 调用的基本思路大模型接口的调用流程并不复杂核心是构造一次 HTTP 请求从用户消息中提取问题文本构造 messages 数组包含 system 和 user 消息带上 API Key 和模型参数发起请求解析响应得到模型生成的回复文本将回复发送到群里这里最关键的设计点是“提示词”。你可以通过 system 消息设定机器人的人设例如你是一个乐于助人的QQ群助手回答问题简洁、准确、友好。这样模型生成的回复就会符合设定的语气。4. 完整实战5 分钟让 QQ 机器人接入 AI4.1 确认项目结构先进入我们用 nb-cli 创建的项目确认目录结构。接下来的代码都会放在src/plugins/ai_chat目录下。qq-ai-bot/ ├── .env ├── .env.prod ├── bot.py ├── pyproject.toml └── src/ └── plugins/ └── ai_chat/ ├── __init__.py └── config.py其中__init__.py是插件的核心逻辑config.py负责读取环境变量中的 API 配置。4.2 编写 AI 对话插件先来实现插件逻辑。为了减少第三方 SDK 依赖这里直接使用httpx发起异步请求这也是 NoneBot2 推荐的方式。# 文件路径src/plugins/ai_chat/__init__.py import json import httpx from nonebot import on_command from nonebot.adapters.onebot.v11 import MessageEvent, Message, Bot from .config import ai_config ai_chat on_command(ai, aliases{AI, 机器人}, priority5) ai_chat.__help_name__ AI聊天 ai_chat.__help_info__ 发送/ai 你的问题 ai_chat.handle() async def handle_ai_chat(bot: Bot, event: MessageEvent): # 去掉消息前缀得到用户的问题 plain_text event.get_plaintext().strip() if not plain_text: await ai_chat.finish(请输入问题例如/ai 什么是NoneBot2) # 调用大模型 API reply await call_ai_api(plain_text) # 将回复发送到群里 await ai_chat.finish(Message(reply)) async def call_ai_api(user_message: str) - str: headers { Authorization: fBearer {ai_config.api_key}, Content-Type: application/json, } payload { model: ai_config.model, messages: [ {role: system, content: ai_config.system_prompt}, {role: user, content: user_message}, ], temperature: 0.7, } try: async with httpx.AsyncClient(timeout30) as client: resp await client.post( f{ai_config.base_url}/chat/completions, headersheaders, jsonpayload, ) resp.raise_for_status() data resp.json() return data[choices][0][message][content].strip() except httpx.TimeoutException: return 抱歉AI服务响应超时了请稍后再试。 except Exception as e: return fAI服务调用失败{type(e).__name__}如果你使用的是官网 SDK也可以替换call_ai_api的实现。但使用通用的 HTTP 调用方式兼容性更好切换服务商时只需要修改配置不需要重写代码。4.3 编写模型配置文件为了让 API Key 等信息不写死在代码里我们单独写一个配置读取文件。NoneBot2 可以使用 pydantic 来管理配置。# 文件路径src/plugins/ai_chat/config.py from pydantic import BaseModel class AiConfig(BaseModel): api_key: str base_url: str https://api.example.com/v1 model: str gpt-3.5-turbo system_prompt: str 你是一个乐于助人的QQ群助手回答问题简洁、准确、友好。 ai_config AiConfig()上面这个写法是最基础的版本。如果希望配置项能从.env文件自动读取可以结合 NoneBot2 的全局配置get_driver().config来做。例如# 文件路径src/plugins/ai_chat/config.py from nonebot import get_driver from pydantic import BaseModel class Config(BaseModel): ai_api_key: str ai_base_url: str https://api.example.com/v1 ai_model: str gpt-3.5-turbo ai_system_prompt: str 你是一个乐于助人的QQ群助手回答问题简洁、准确、友好。 driver get_driver() ai_config Config.parse_obj(driver.config)这两种写法各有特点第一种适合快速测试第二种更适合项目化开发。4.4 配置环境变量和启动项在项目根目录的.env文件中添加配置。请根据你的实际环境修改。DRIVER~httpx~websockets HOST127.0.0.1 PORT1024 AI_API_KEY你的APIKey AI_BASE_URLhttps://api.example.com/v1 AI_MODELgpt-3.5-turbo AI_SYSTEM_PROMPT你是一个乐于助人的QQ群助手这里解释一下关键配置DRIVERNoneBot2 的驱动器httpx负责处理 HTTP 请求websockets负责与消息通道建立 WebSocket 连接HOST和PORT机器人的服务监听地址默认即可AI_API_KEY你的模型服务密钥AI_BASE_URL接口地址必须以/v1结尾因为后面拼接了/chat/completionsAI_MODEL模型名称AI_SYSTEM_PROMPT系统提示词4.5 连接消息通道并运行运行机器人前你还需要一个 OneBot V11 协议端也就是消息通道。简单理解它是一个帮助机器人接入 QQ 消息体系的程序对外提供 HTTP 或 WebSocket 接口让 NoneBot2 可以连接。以常见方案为例你需要安装并运行一个基于 OneBot V11 协议的客户端程序在客户端中登录机器人 QQ 账号配置 WebSocket 服务端地址指向 NoneBot2 的监听地址将机器人账号拉入需要服务的 QQ 群通道配置完成后在项目根目录执行nb run看到类似下面的日志时说明机器人服务已经启动10-20 12:00:00 [INFO] nonebot | OneBot V11 适配器已加载 10-20 12:00:00 [INFO] nonebot | 运行速率限制器已启用 10-20 12:00:00 [INFO] nonebot | Scheduler 已启动 10-20 12:00:00 [INFO] nonebot | 当前插件: ai_chat在 QQ 群里发送/ai 你好请介绍一下你自己机器人会调用大模型 API 获取回复并发送到群里。4.6 效果验证与优化如果一切顺利你会看到[用户] /ai 你好请介绍一下你自己 [机器人] 你好我是一个QQ群助手基于大模型驱动可以回答问题、提供帮助。到这里一个最简单的 QQ AI 机器人已经完成。不过这只是开始实际使用中还可以做很多优化比如把长文本回复拆分成多条消息避免刷屏增加提问频率限制防止滥用保存群聊历史让 AI 具备多轮记忆5. 常见问题与排查思路5.1 机器人无法接收群消息问题现象常见原因解决思路群里发消息机器人没反应OneBot 协议端未连接成功检查协议端与 NoneBot2 的 WebSocket 地址是否一致只有特定群能收到消息机器人未被拉入目标群确认机器人账号已在群内消息偶尔丢失网络不稳定或事件处理异常查看日志确认是否有报错信息排查步骤建议按顺序来先看 NoneBot2 控制台有没有收到事件日志再看协议端的连接状态最后确认触发词是否正确。5.2 AI 接口调用报错错误信息常见原因解决思路401 UnauthorizedAPI Key 错误或未填写检查.env中AI_API_KEY是否正确404 Not FoundBase URL 拼接错误确认AI_BASE_URL是否以/v1结尾TimeoutException接口响应超时增大httpx的 timeout 参数或检查网络连通性model not found模型名称不存在修改AI_MODEL为服务商提供的正确名称这类问题有一个通用排查思路先用 Postman、curl 等工具单独测试 API确认接口本身可用再回到机器人代码中检查调用方式。curl https://api.example.com/v1/chat/completions \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-3.5-turbo, messages: [{role: user, content: 你好}] }如果 curl 调用成功说明问题是代码层面的需要重点检查请求头和请求体。5.3 中文乱码或回复格式异常大模型返回的内容有时包含换行、Markdown 标记或特殊字符。如果直接发送到群里可能会显示不佳。解决思路是对回复内容做简单清洗去掉多余的换行将 Markdown 格式转换成纯文本超长内容分段发送import re def clean_reply(text: str) - str: # 去掉Markdown图片等富文本标记 text re.sub(r!\[.*?\]\(.*?\), , text) # 多个连续换行压缩为一个 text re.sub(r\n{3,}, \n\n, text) return text.strip()6. 最佳实践与工程化建议6.1 安全边界与权限控制接入 AI 能力后机器人具备了“自动回复一切”的能力如果不加约束可能会被群成员滥用。推荐设置以下保护明确触发词避免机器人监听所有消息减少接口调用成本对 AI 提问增加频率限制例如单用户每分钟最多 3 次对一些敏感关键词做拦截不把不安全的内容发给模型不要把 API Key 打包进镜像或提交到 Git 仓库6.2 提示词工程同样的大模型提示词不同效果差异会很大。做 QQ 机器人时建议把 system prompt 当作产品的一部分来打磨。一个相对完整的提示词模板如下你是一个QQ群机器人助手。你在回答时需遵守以下规则 1. 回答简洁直接给出结论。 2. 如果问题不明确可以反问澄清。 3. 不回答违法违规、暴力、色情相关内容。 4. 用户可能会输入错别字或口语化表达请自动纠正理解。 5. 结合上下文回答保持对话连贯。通过提示词约束回复风格、边界和语气会让机器人更像一个稳定的助手而不是一个随机发挥的文本生成器。6.3 对话历史的处理到目前为止我们的示例是每次请求都独立调用 API模型不记得之前的对话。实现多轮记忆时需要注意不是所有消息都适合放进上下文上下文过长会增加 token 消耗和响应延迟只需要保留最近几轮消息可以在插件中维护一个简单的消息缓冲按群号或用户 ID 区分from collections import defaultdict, deque chat_history defaultdict(lambda: deque(maxlen6)) def update_history(group_id: str, user_msg: str, reply_msg: str): chat_history[group_id].append({role: user, content: user_msg}) chat_history[group_id].append({role: assistant, content: reply_msg})构建请求时把历史消息和当前问题一起传给模型。这种方案虽然简单但已经能提供不错的多轮对话体验。6.4 异步处理和性能考量NoneBot2 本身是异步框架处理函数中不能使用阻塞式的耗时代码。调用第三方 API 时一定要使用异步 HTTP 客户端例如httpx.AsyncClient。如果 AI 接口响应较慢建议增大逻辑超时时间但不要过长一般 30 秒内比较合适使用asyncio.create_task做异步任务不影响其他消息的处理对回复做缓存相同问题在短时间内直接返回缓存结果6.5 日志与监控机器人上线后日志是排查问题最重要的依据。建议在关键节点补充日志import logging logger logging.getLogger(ai_chat) logger.info(收到用户提问: %s, plain_text) logger.info(AI回复: %s, reply) logger.warning(AI接口调用超时, 用户问题: %s, plain_text)不要用print()输出日志因为异步环境下容易混乱。使用标准 logging 模块可以更方便地按级别过滤和持久化。7. 总结与扩展建议通过前面的步骤你已经拥有了一个可运行的 QQ AI 机器人消息通道由 NoneBot2 和 OneBot V11 协议端负责智能回复能力来自大模型 API两者在插件层完成对接。这个架构最大的价值在于扩展性。接下来可以尝试的方向给机器人增加多个指令例如每日新闻、天气查询、代码解释接入语音识别让机器人理解语音消息使用向量数据库让机器人根据私域知识库回答问题把机器人部署到云服务器实现 7×24 小时在线运行机器人时优先关注三件事API 密钥不要泄露、接口调用成本要可控、回复内容要有边界。只要把第一版跑通后续的优化都是在现有骨架上不断增加肌肉。如果本文对你有帮助可以收藏备用也欢迎在实际开发中按自己的场景调整提示词和插件结构。