DeepSeek 现在的热度不用多说但很多人还停留在网页对话上。这次我们做一个能直接放进 QQ 群、随叫随回的需求把 DeepSeek 接入 QQ 机器人。文章不涉及本地部署大模型所有推理都走 DeepSeek 官方 API所以没有显卡门槛。你只要有一台能跑 Python 的电脑或云服务器跟着步骤走就能让 QQ 私聊和群聊里的消息自动流到 DeepSeek再把回复发回群里。全文包含两条接入路径先用 NapCat OneBot v11 协议在个人 QQ 号上快速跑通再讲 QQ 官方机器人平台的接入思路。核心代码、环境准备、测试方法和排查清单都会给到可以直接复制。这里不追新版本号重点是把链路跑通版本升级后只要字段和接口名不变代码逻辑不用动。1. 核心能力速览能力项说明项目类型DeepSeek API 接入 QQ 机器人的完整教程模型来源DeepSeek 官方 APIdeepseek-chat、deepseek-reasoner硬件要求无需 GPU2 核 CPU / 4GB 内存即可开发语言Python 3.9核心依赖openai、websockets接路路径NapCat/LLOneBot OneBot v11 协议或 QQ 官方开放平台主要功能私聊回复、群聊回复、/前缀触发、多轮上下文接口支持DeepSeek OpenAI 兼容接口可直接用 chat completions批量能力支持多群消息并发处理需要自行做频率限制适合人群QQ 群管理员、个人 AI 助手、API 集成学习者从材料看这个接入方式最核心的卖点是不挑硬件、不挑网络环境只要 Python 环境能访问外网就能跑。下文默认你使用的是 64 位 Windows/Linux 系统Python 已安装且有最基本的命令行操作经验。2. 两种接入方案选型与使用边界先解决一个问题为什么 QQ 机器人有两条完全不同的接入路线第一条是用 QQ 官方开放平台。你在官方平台注册机器人应用拿到 AppID 和 AppSecret配置好事件订阅平台会把群聊和私聊消息推送到你的服务。优点是完全合规、不会被 QQ 风控适合发布正式产品缺点是创建应用需要审核沙箱环境里只能测试有限场景而且 API 协议和 OneBot 完全不同代码不能通用。第二条是用开源框架接管一个普通 QQ 号。常见的有 NapCat、LLOneBot 这类项目它们把 QQ 客户端协议封装成 OneBot v11 标准接口你通过 WebSocket 收发消息。优点是配置简单、功能全个人号登进去就能当机器人适合自用和内部群缺点是使用个人账号做自动化操作有一定风险消息频率过高可能触发 QQ 风控限制所以不能拿去做营销、轰炸、自动加人这类操作。两条路怎么选想快速自己玩首选方案二从下载框架到第一条回复不到半小时。要做成对外服务、面向大量真实用户必须走方案一合规性才是长期运营的前提。不管用哪种都建议控制回复频率不要在群里刷屏不要收集聊天记录用于其他目的。3. 环境准备与前置条件这个项目不涉及本地大模型所以环境准备比“下载模型权重”简单很多。核心就三块Python 环境、依赖库、DeepSeek API Key。操作系统Windows 10/11、Ubuntu 20.04、CentOS 7 都可以。如果是云服务器记得安全组放开你需要的 WebSocket 端口。Python 版本建议 3.9 到 3.11不要用 Python 2。检查方法python --version python3 --version如果两个命令都提示找不到先去 Python 官网下载安装Windows 安装时勾选“Add Python to PATH”。Python 依赖主要用到两个库一个是 openai 官方 SDK用来调 DeepSeek 的 OpenAI 兼容接口另一个是 websockets用来连接 OneBot 框架。pip install openai1.0.0 websockets如果安装速度慢可以指定国内镜像源pip install openai1.0.0 websockets -i https://pypi.tuna.tsinghua.edu.cn/simpleDeepSeek API Key登录 DeepSeek 开放平台进入 API Keys 页面创建密钥。创建后密钥只会完整显示一次要立即复制保存。这个 Key 就是后续调模型的凭证相当于一段sk-开头的字符串。然后做一次最小连通性测试确保 Key 有效curl https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的密钥 \ -d { model: deepseek-chat, messages: [{role: user, content: 你好只回复两个字正常}] }如果返回内容里有choices[0].message.content说明 API Key 和网络都没问题。这一步先做通后面所有报错都能缩小到 QQ 接入环节。4. DeepSeek API 调用封装不管用哪种 QQ 接入方案最终都要把用户消息发给 DeepSeek再把返回文本发回聊天窗口。所以先封装一个通用的 DeepSeek 调用函数省得后面两个方案各写一遍。import os from openai import OpenAI client OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY, sk-你的密钥), base_urlhttps://api.deepseek.com ) def ask_deepseek(messages: list) - str: 调用 DeepSeek API。 messages 是 OpenAI 格式的对话列表例如 [{role: system, content: 你是QQ机器人}, {role: user, content: 你好}] try: resp client.chat.completions.create( modeldeepseek-chat, messagesmessages, temperature0.7, max_tokens1024, timeout30 ) return resp.choices[0].message.content except Exception as e: return f请求 DeepSeek 出错{e}这里有几个可以按需调整的参数model默认deepseek-chat如果需要强推理能力可以换deepseek-reasoner但思考时间更长。temperature控制在 0.3 到 0.8 之间比较稳妥太低会机械太高容易跑题。max_tokens控制单次回复最大长度群聊建议 512 到 1024太长刷屏。timeout网络不好时避免请求卡死建议设 30 秒。这个函数用同步方式阻塞调用单机单群完全够用。如果后续多个群并发量上来了可以改成await asyncio.to_thread(ask_deepseek, messages)让 API 调用在线程池里执行不阻塞事件循环。5. 快速体验NapCat OneBot 接入个人 QQ这一部分先跑通一条能用的链路。整体流程是启动 NapCat → 开启正向 WebSocket → 用 Python 连接 WebSocket 收消息 → 调 DeepSeek → 用 OneBot action 发消息回去。5.1 部署 QQ 机器人框架NapCat 是目前比较活跃的 QQ 机器人框架之一安装方式在它的官方文档里写得很清楚。通常分几步下载对应平台的 NapCat 压缩包并解压。运行启动脚本Windows 一般是.batLinux 一般是.sh。用手机 QQ 扫码登录一个专门做机器人的 QQ 号。在管理面板中开启“正向 WebSocket 客户端”监听地址填0.0.0.0端口填3001。这一步没有统一命令因为不同版本的管理界面会变。启动后注意看日志确认 WebSocket 服务已经监听在 3001 端口。用下面命令检查netstat -ano | findstr 3001Linux 环境用ss -lntp | grep 3001如果端口没起来回到 NapCat 配置页检查服务开关。5.2 编写 OneBot WebSocket 客户端OneBot v11 是标准的 JSON 协议。客户端连上 WebSocket 后框架会把事件推过来事件里带post_type字段等于message就说明是聊天消息。回复消息时向 WebSocket 发送一个带actionsend_msg的 JSON 对象。新建一个bot.py完整内容如下import asyncio import json import time import collections import websockets from openai import OpenAI # DeepSeek 配置 client OpenAI( api_keysk-你的密钥, base_urlhttps://api.deepseek.com ) SYSTEM_PROMPT 你是QQ机器人助手回复要简洁清晰单次不超过300字。 # 多轮上下文 history_store collections.defaultdict(list) MAX_HISTORY 10 # 每个会话最多保留5轮对话1轮用户助手2条 LAST_REPLY_TIME {} def build_messages(role_id: str, user_input: str) - list: history history_store[role_id] history.append({role: user, content: user_input}) history history[-2 * MAX_HISTORY:] history_store[role_id] history messages [{role: system, content: SYSTEM_PROMPT}] messages.extend(history) return messages def update_history(role_id: str, reply: str): history_store[role_id].append({role: assistant, content: reply}) history_store[role_id] history_store[role_id][-2 * MAX_HISTORY:] def ask_deepseek(messages: list) - str: try: resp client.chat.completions.create( modeldeepseek-chat, messagesmessages, temperature0.7, max_tokens1024, timeout30 ) return resp.choices[0].message.content except Exception as e: return f请求 DeepSeek 出错{e} def can_reply(role_id: str, interval: float 3.0) - bool: 同一个会话两次回复之间至少间隔 interval 秒避免刷屏。 now time.time() last LAST_REPLY_TIME.get(role_id, 0) if now - last interval: return False LAST_REPLY_TIME[role_id] now return True async def handle_message(ws, event: dict): msg_type event.get(message_type) # private 或 group user_id event.get(user_id) group_id event.get(group_id) raw_msg event.get(raw_message, ).strip() # 群聊只响应 /ai 前缀避免机器人接所有话 if msg_type group: if not (raw_msg.startswith(/ai) or raw_msg.startswith(/AI)): return raw_msg raw_msg[3:].strip() if not raw_msg: return role_id str(group_id) if msg_type group else fprivate_{user_id} if not can_reply(role_id): return messages build_messages(role_id, raw_msg) try: reply await asyncio.to_thread(ask_deepseek, messages) except Exception as e: reply f处理出错{e} update_history(role_id, reply) params {message_type: msg_type, message: reply} if msg_type group: params[group_id] group_id else: params[user_id] user_id await ws.send(json.dumps({ action: send_msg, params: params })) async def onebot_client(): url ws://127.0.0.1:3001 async with websockets.connect(url) as ws: print(f已连接到 OneBot WebSocket: {url}) async for raw in ws: event json.loads(raw) if event.get(post_type) ! message: continue await handle_message(ws, event) if __name__ __main__: asyncio.run(onebot_client())代码里已经做了两件工程化的事一是用role_id区分不同群和不同私聊用户每个会话维护独立上下文二是用can_reply做频率限制防止机器人被连续刷屏。第一次跑通时可以直接用不需要再改。如果你的 QQ 号同时需要响应 消息可以把群聊判断改成at_code f[CQ:at,qq{event.get(self_id)}] if at_code not in raw_msg and not raw_msg.startswith((/ai, /AI)): return raw_msg raw_msg.replace(at_code, ).lstrip()注意这里依赖self_id字段如果框架版本不返回该字段需要从事件里另取机器人 QQ 号。5.3 启动与验证启动服务python bot.py看到已连接到 OneBot WebSocket: ws://127.0.0.1:3001后用另一个 QQ 号给机器人发私聊消息“你好”。如果一切正常终端会打印收到的事件机器人账号会在几秒内回复。群聊测试时在群里发/ai 用一句话介绍你自己机器人只认/ai前缀其他群聊消息不会触发。这样做是为了防止机器人在任何话题下都插话实际使用也更克制。如果消息没回复常见原因有三个NapCat 的 WebSocket 端口和代码里不一致、群聊前缀判断没通过、DeepSeek API Key 无效。逐个检查即可。6. 正式发布接入 QQ 官方机器人平台NapCat 方案适合自用但如果你要把机器人做成公开服务或者投放到大量群里建议走 QQ 官方开放平台。6.1 平台侧配置到 QQ 开放平台注册开发者账号创建机器人应用。创建后你会拿到两个关键凭证AppID 和 AppSecret。在应用配置页里选择需要接收的事件类型通常勾选“群聊消息”和“C2C 私聊消息”。然后需要配置回调方式。官方平台支持 WebSocket 或 Webhook 两种这里更推荐 WebSocket。在事件订阅里填好沙箱环境信息提交审核通过后就可以接收真实事件。6.2 回调服务思路官方机器人的消息结构、认证方式和 OneBot 完全不同需要走官方 SDK。下面给出思路代码结构以你创建应用时官方文档提供的示例为准启动时用 AppID AppSecret 换取访问令牌。建立 WebSocket 连接发送包含令牌的认证包。收到消息事件后从事件对象里取出content。调用上文的ask_deepseek(messages)拿到回复。调用官方消息发送接口把回复发送回对应的群或用户。核心逻辑仍然是“收到消息 → 调 DeepSeek → 发回消息”只是事件格式和发送接口的 SDK 方法不同。第一次接入时先在沙箱环境里用测试号把链路跑通再提交审核。审核期间不要刷大量消息保持正常使用频率。7. 功能测试与效果验证整个链路起来后按下面顺序做一轮功能测试比直接扔到群里更稳妥。7.1 测试 DeepSeek API 连通性先不经过 QQ直接跑一段 Pythonfrom openai import OpenAI client OpenAI(api_keysk-你的密钥, base_urlhttps://api.deepseek.com) resp client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: 你好回复测试成功}] ) print(resp.choices[0].message.content)输出“测试成功”说明 API Key 配置正确。7.2 私聊回复测试用另一个 QQ 号给机器人发消息观察三类情况普通问候“你好”“在吗”开放性问题“帮我写一个 Python 快速排序”无意义内容连续刷 10 条同样的话预期结果普通问题正常回复写代码类问题能输出完整可读的 Python 代码连续刷屏时机器人只回复第一条之后被频率限制拦截。判断成功的标准回复内容不是错误提示、代码块完整、刷屏没有导致机器人连续回复。7.3 群聊触发测试在群里发/ai 今天适合学什么新技能预期结果机器人回复一条有逻辑的建议。再发普通消息“你们在聊什么呢”机器人应该保持沉默。判断成功的标准只有带/ai前缀的消息会触发回复其他消息不打扰群聊。7.4 长文本和异常测试让机器人写一篇长文章测试max_tokens1024下是否会被截断再发一个空内容或纯表情消息测试机器人不会报错。如果空消息导致程序崩溃说明if not raw_msg的判断没有覆盖到需要在 handle_message 里补一层防御。还要测试一下上下文连续性先让机器人“记住我叫小王”再隔几条消息问“我叫什么”预期能答出“小王”。如果答不上来大概率是多轮上下文管理里的role_id没有生效检查群聊场景下group_id是否稳定返回。8. 批量任务、定时消息与群管理QQ 机器人不只能做一问一答还能承担群管理任务。这几个功能在实际运营里很常用而且都可以接在同一个 WebSocket 链路上。关键词自动回复在handle_message里先做规则命中再决定是否调 DeepSeek。比如消息包含“群规”直接返回固定文本只有未命中规则时才走模型。这样可以省 API 费用响应也更快。RULES { 群规: 本群禁止广告、引战、刷屏。, 帮助: 发送 /ai 内容即可和 AI 对话。, } def match_rule(msg: str): for key, value in RULES.items(): if key in msg: return value return None定时提醒用asyncio.create_task起一个后台任务每分钟检查一次当前时间到达指定时间就调用send_group_msg发提醒。这里需要注意定时任务的发送同样受频率限制不能一次给多个群同时发。多群并发WebSocket 连接是异步的多个群同时发消息时事件循环会依次处理。因为ask_deepseek放在asyncio.to_thread里模型调用不会阻塞消息接收。但 API 侧有并发限制如果群特别多建议在ask_deepseek外层加一个信号量限制同时调用 DeepSeek 的数量。SEMAPHORE asyncio.Semaphore(5) async def ask_deepseek_with_limit(messages): async with SEMAPHORE: reply await asyncio.to_thread(ask_deepseek, messages) return reply费用控制DeepSeek API 是按 token 计费的群聊场景最容易失控的是上下文无限积累。代码里 MAX_HISTORY 限制到最近 5 轮已经能挡住大部分浪费。更激进的做法是单条消息超过 300 字直接提示用户精简问题不进入模型。9. 资源占用与性能观察这个方案的资源占用集中在两个地方Python 进程和 NapCat 进程本地不跑大模型所以不存在显存问题。内存Python 进程启动后通常占用几十到几百 MB取决于历史上下文字典大小NapCat 进程会占用更多一些但总体对 4GB 内存的小服务器没有压力。如果内存紧张优先检查是不是历史上下文字典没有定期清理。CPU主要消耗在 JSON 编解码和 websockets 库上非常低。如果出现 CPU 飙升优先怀疑循环逻辑里是否有阻塞调用而不是 API 本身。网络延迟一次完整对话的延迟 消息推送到本机的延迟 DeepSeek API 响应时间 消息发送回 QQ 的时间。其中大头在 DeepSeek 的响应时间通常 1 到 3 秒。如果感觉特别慢可以看下服务器到 API 的链路或者把max_tokens调低。观察方法在bot.py里加一行日志打点把收到消息和发送回复的时间差打出来import time start time.time() # ... 调用和发送 ... print(f处理耗时: {time.time() - start:.2f}s)如果同一群连续两条消息都超时再看 DeepSeek 平台的控制台有没有请求失败记录。频繁出现超时就把timeout参数从 30 改成 60或者换成延迟更低的网络环境。10. 常见问题与排查方法问题现象可能原因排查方式解决方案连接不上 WebSocketNapCat 没启动或端口不对运行 netstat 检查端口修正 ONEBOT_WS_URL 端口重启 NapCat启动报错ModuleNotFoundErrorPython 依赖没装pip list 看包是否存在重新执行 pip installAPI 返回 401API Key 错误或过期用 curl 单独测一次在 DeepSeek 平台重新生成 Key私聊能回群聊不回群聊前缀判断没通过打印收到的 raw_msg确认/ai前缀格式或改成 机器人触发回复正常但发不出去QQ 风控或发送频率过高看 NapCat 日志有没有发送失败降低 can_reply 的间隔暂停一段时间再试机器人重复回复同一条消息事件重复推送检查 NapCat 是否开了多条连接只保留一个正向 WebSocket 连接中文乱码文件编码不是 UTF-8查看终端输出在文件开头加# -*- coding: utf-8 -*-文件另存为 UTF-8上下文串群role_id 用错打印 role_id群聊用 group_id私聊用 private_ 加 user_idAPI 调用很慢网络链路或 max_tokens 过大单独测一次 API 耗时减小 max_tokens换更稳定的网络最容易忽略的是端口和防火墙。云服务器上跑的时候很多用户本机能连接但服务器日志没有消息进来就是因为安全组没放行 3001 端口。另外如果用多个脚本同时连接同一个 NapCat 实例OneBot 会重复推送事件机器人就会重复回复这是开发阶段最常遇到的现象。11. 最佳实践与合规提醒接入本身不难难的是稳定跑起来不惹麻烦。下面几个建议直接照做首次上线先小范围测试。先拉一个只有两三个人的测试群测试触发前缀、回复质量、频率限制稳定后再加到真实大群。不要第一天就把机器人丢进 500 人群。机器人账号单独准备。不要拿主号登录 NapCat专门的机器人小号出问题不影响日常使用。机器人账号尽量保持正常的在线时长不要频繁掉线重登。加一层内容安全过滤。DeepSeek 本身有内容安全策略但群聊场景最好再套一层本地敏感词表。命中敏感词的问句直接返回“这个问题我暂时无法回答”不进 API 调用。日志脱敏。日志里不要打印完整 user_id 和聊天正文打一段截断后的摘要即可。聊天内容涉及用户隐私存储和展示都需要谨慎。遵守平台和框架规则。控制消息频率避免机器人刷屏不做自动加人、群发广告、诱导分享等操作不收集聊天记录用于二次营销。NapCat 方案本质是个人号自动化频率控制不好触发风控是大概率事件。批量任务要留退路。如果有定时推送和批量回复一定要在代码里加 try/except 和失败记录。比如定时提醒发失败时打印日志并跳过而不是让整个后台任务崩溃。12. 总结与下一步扩展整个接入流程总结成一句话用 OneBot 协议把 QQ 消息变成标准事件再用 DeepSeek 的 OpenAI 兼容接口做文本生成中间加一层上下文管理和频率控制就够了。最难的部分其实不是代码而是把“消息接收、模型调用、结果发送”这三段的字段对应关系搞清楚。先验证的应该是 DeepSeek API 连通性再验证 OneBot 连接最后才联调聊天。最容易踩的坑是事件字段名对不上以及群聊触发条件写错导致机器人完全沉默。建议把 bot.py 保存为一份最小可运行版本后续加功能时在这个版本上迭代。如果想把项目再往前推一步有几个方向可以继续做给机器人接一个知识库让它基于自己的资料库回答问题接入 DeepSeek 的 deepseek-reasoner 模型在群里做复杂问题推理把回复内容改成支持 Markdown 渲染的卡片消息或者用定时任务做一个每天早晚推送技术资讯的群管机器人。这个链路跑通后再加场景都是在handle_message里加分支的事。