最近不少朋友在折腾 QQ 机器人想给群聊里的机器人接上 DeepSeek 的 API让它能在群里查询资料、写代码片段、做翻译甚至闲聊。QQ 机器人的接入本身并不复杂真正麻烦的是“DeepSeek API 调用”“消息事件接收”“消息回复”这三段逻辑怎么拼在一起以及本地调试时回调地址、鉴权、消息格式这些细节怎么处理。这篇文章就围绕“DeepSeek 全过程接入 QQ 机器人”写一份保姆级教学。文章会从 DeepSeek API 的申请讲起再到 QQ 机器人开放平台的创建、事件订阅、本地联调最后给出一个完整的 Python 服务代码可以直接跑通“群里 机器人 - DeepSeek 回答 - 群里展示回复”的全流程。适合刚接触大模型 API 和 QQ 机器人开发的同学也适合想快速在自己群里部署一个 AI 助手的开发者。1. 背景与核心概念1.1 你要做成的效果是什么先明确最终效果在你的 QQ 群里添加一个机器人当群成员在群里发送消息并 机器人时机器人会把消息内容转发给 DeepSeek API拿到模型回复后再把回复发送到群里。整个链路其实可以简化成四个模块模块作用对应技术交互入口用户在群里 机器人QQ 机器人开放平台消息接收机器人收到群消息事件WebSocket 或 HTTP 回调AI 大脑根据用户消息生成回答DeepSeek API消息发送将回答发回群里QQ 机器人开放平台消息接口1.2 DeepSeek API 是什么DeepSeek API 是 DeepSeek 提供的大模型调用接口。开发者通过 HTTP 请求把用户消息发给模型模型会返回一段生成结果。它的接口协议兼容 OpenAI API 格式所以常用的openaiPython SDK 可以直接使用只需要把base_url指向 DeepSeek 的地址即可。常见模型名包括deepseek-chat通用对话模型。deepseek-reasoner带思考过程的推理模型适合逻辑题、复杂分析。具体可用的模型名和价格以 DeepSeek 开放平台文档为准。本文示例默认使用deepseek-chat如果你要尝试推理模型只需要把代码里的模型名替换掉。1.3 QQ 机器人接入的两种路线平时网上搜“QQ 机器人接入”会看到两种完全不同思路官方 QQ 机器人开放平台路线通过 q.qq.com 创建机器人应用平台提供沙箱频道、事件订阅、WebSocket 长连接、消息发送 API。这是官方支持、长期可维护的接入方式。第三方协议实现路线通过社区开源的协议库模拟 QQ 客户端登录操作更多但存在账号风控风险。本文以官方开放平台为主。如果你只是在自己的测试群玩官方沙箱环境就够用如果希望机器人正式发布到更多群官方平台也提供上架流程。第三方方案不在本文展开原因有两点一是稳定性受账号风控影响较大二是平台规则上存在合规风险。1.4 为什么你需要掌握这些大模型 API 本身只是一个 HTTP 接口真正让它在业务场景里产生价值的是“通道能力”。QQ 机器人就是典型的通道用户不需要打开网页不需要复制粘贴直接在聊天界面里就能调用一个大模型。类似的能力也可以延伸到企业微信、飞书、钉钉、Telegram 等平台。学会 QQ 机器人接入之后换一个平台只是换消息接口核心思路是通用的。2. 环境准备与版本说明2.1 本机环境本文示例代码使用 Python 3建议使用 3.9 及以上版本。以下几个环境是跑通示例的前提Python 3.9pip 包管理工具一个 DeepSeek 开放平台账号并创建了 API Key一个 QQ 号用于注册 QQ 机器人开放平台能够访问公网的开发环境因为 QQ 机器人平台需要和你的服务建立连接如果你的开发机在国内云服务器上网络访问 DeepSeek API 没有额外障碍如果使用本地电脑开发需要保证本地环境能访问公网即可。2.2 安装依赖本文核心用到的 Python 库有两个pip install openai websocketsopenai用于调用 DeepSeek API。DeepSeek 兼容 OpenAI 协议所以直接用官方 SDK 最省事。websockets用于接收 QQ 机器人平台的 WebSocket 消息事件。注意openai库只是作为 HTTP 客户端使用你并不需要 OpenAI 的账号只需要把base_url改成 DeepSeek 的地址。2.3 需要准备的账号与密钥内容说明DeepSeek API Key在 DeepSeek 开放平台创建所有 AI 调用都靠它鉴权QQ 机器人 AppID在 QQ 开放平台创建机器人后获得QQ 机器人 AppSecret用于获取 access_token调用消息接口时必须使用这三个值都属于敏感信息建议通过环境变量或本地配置文件管理不要硬编码提交到 Git 仓库。2.4 整体架构图下面用一张简单结构图展示服务运行时的关系QQ 群成员 | | 机器人 v QQ 机器人开放平台 | | WebSocket 推送消息事件 v 本地 Python 服务 | (1) 收到消息 | (2) 组装 prompt v DeepSeek API | | 返回生成结果 v 本地 Python 服务 | | 调用 QQ 开放平台消息接口 v QQ 群内展示回复这个链路里你的 Python 服务承担“桥接层”的工作既连接 QQ 平台也连接 DeepSeek API。3. DeepSeek API 申请与第一次调用3.1 获取 DeepSeek API Key打开 DeepSeek 开放平台登录后进入“API Keys”页面点击创建新的 API Key创建完成后会显示一串sk-开头的密钥。需要注意三点API Key 只在创建时完整展示一次之后无法再次查看。建议先充值少量金额再调用避免因为余额不足而返回 402 错误。API Key 不要提交到公共代码库也不要发给任何人。为了后续步骤方便先在环境变量里配置export DEEPSEEK_API_KEYsk-你的key3.2 使用 OpenAI SDK 调用 DeepSeek先写一个最基础的非流式调用示例。# 文件路径deepseek_basic.py from openai import OpenAI import os client OpenAI( api_keyos.environ.get(DEEPSEEK_API_KEY), base_urlhttps://api.deepseek.com ) response client.chat.completions.create( modeldeepseek-chat, messages[ {role: system, content: 你是一个乐于助人的 AI 助手。}, {role: user, content: 用一句话介绍你自己} ] ) print(response.choices[0].message.content)运行方式python deepseek_basic.py如果一切正常终端会输出模型生成的文本。这个示例里最关键的是base_url和api_key两个参数。base_url指向 DeepSeek 的 API 地址。messages是一个数组system用来设定角色user是用户输入assistant可以存放历史回复用于多轮对话。3.3 流式调用示例在 QQ 群里调用大模型时非流式接口通常够用因为 QQ 机器人平台并不支持逐字渲染消息最终还是要把完整回复一次性发出去。不过流式接口可以让你更快拿到首字也可以用来判断模型是否已经开始输出。下面给出流式调用的参考写法。# 文件路径deepseek_stream.py from openai import OpenAI import os client OpenAI( api_keyos.environ.get(DEEPSEEK_API_KEY), base_urlhttps://api.deepseek.com ) stream client.chat.completions.create( modeldeepseek-chat, messages[ {role: user, content: 用三句话解释 TCP 协议} ], streamTrue ) full_content for chunk in stream: delta chunk.choices[0].delta.content if delta: full_content delta print(delta, end) print(\n完整内容) print(full_content)流式接口每次返回一个增量内容delta.content可能为空所以要做空值判断。QQ 机器人场景下我建议先使用非流式接口把逻辑做得简单直接以后需要再切换。3.4 多轮对话与上下文管理基础调用每次都是“无状态”的。用户发来一句“介绍 TCP”机器人回答一句再问“它和 UDP 的区别”模型并不记得上一句的内容。如果想在 QQ 群里实现多轮对话你需要自己维护会话历史# 文件路径deepseek_context.py from openai import OpenAI import os client OpenAI( api_keyos.environ.get(DEEPSEEK_API_KEY), base_urlhttps://api.deepseek.com ) history [ {role: system, content: 你是一个技术助手回答尽量简洁。} ] def chat(user_message): history.append({role: user, content: user_message}) response client.chat.completions.create( modeldeepseek-chat, messageshistory ) answer response.choices[0].message.content history.append({role: assistant, content: answer}) return answer print(chat(TCP 是什么)) print(chat(它和 UDP 有什么区别))要注意的是history 不能无限增长否则会占用大量 token。实际项目中可以做简单截断比如最多保留最近 20 条对话。4. QQ 机器人开放平台接入4.1 创建机器人应用进入 QQ 机器人开放平台使用 QQ 扫码登录后在“开发者面板”里创建一个新的机器人应用。创建过程需要填写机器人名称、头像、简介等信息。创建完成后你会得到AppIDAppSecret机器人 Token有些场景用于老版鉴权AppID 和 AppSecret 是本文示例要用到的核心凭证。4.2 配置沙箱频道QQ 机器人平台默认提供沙箱环境你可以在沙箱群里测试机器人的消息收发。将机器人添加到自己的测试群时建议先在开发设置中查看沙箱群配置并按照平台引导完成绑定。沙箱环境的目的是让开发者在不干扰正式用户的前提下完成联调所以大多数接口调用在沙箱阶段没有发布审核压力。4.3 事件订阅机器人需要知道“群里有人发消息了”这依赖于事件订阅。在开发者后台设置中可以选订阅事件类型GROUP_AT_MESSAGE_CREATE群内有人 机器人时触发CQ_BOT_EVENT这类老协议事件不同版本开放平台有一定差异以实际后台展示为准事件订阅成功后平台会通过两种方式把事件推送给你HTTP 回调平台把事件 POST 到你配置的公网 URL。WebSocket 长连接平台通过 WebSocket 把事件推送到你的服务端。HTTP 回调需要公网地址本地开发一般搭配内网穿透工具使用。WebSocket 长连接更适合本地开发也是官方文档推荐的接入方式之一。本文采用 WebSocket 方式可以避免公网回调带来的额外配置。4.4 WebSocket 接入原理QQ 机器人开放平台的 WebSocket 接入流程大致如下使用 AppID 和 AppSecret 向平台换取 access_token。调用/gateway/bot接口获取 WebSocket 连接地址。建立 WebSocket 长连接。按照协议发送鉴权数据包。监听服务端推送的消息事件。这个流程和大多数“机器人网关”类产品很像。拿到事件后你的程序解析事件中的d字段里面包含author、content、channel_id、guild_id等信息。然后你就可以根据这些信息调用消息发送接口进行回复。5. 完整实战QQ 群内 DeepSeek 问答机器人这一节完成一个最小可运行的 QQ 机器人服务。为了让代码尽量完整同时不引入过多依赖示例直接使用websockets库实现消息接收使用openai库调用 DeepSeek API。5.1 项目结构qq-deepseek-bot/ ├── config.py # 配置读取 ├── deepseek_client.py # DeepSeek 调用封装 ├── qq_bot.py # QQ 机器人主服务 └── requirements.txt # 依赖列表创建目录mkdir qq-deepseek-bot cd qq-deepseek-bot创建requirements.txtopenai1.0.0 websockets12.0安装依赖pip install -r requirements.txt5.2 配置文件建议用环境变量管理敏感信息这里提供两种方式。第一种是直接在当前终端设置环境变量export DEEPSEEK_API_KEYsk-xxx export QQ_APP_ID你的appid export QQ_APP_SECRET你的appsecret第二种是写一个config.py从环境变量读取配置并提供统一的获取入口。# 文件路径config.py import os DEEPSEEK_API_KEY os.environ.get(DEEPSEEK_API_KEY, ) QQ_APP_ID os.environ.get(QQ_APP_ID, ) QQ_APP_SECRET os.environ.get(QQ_APP_SECRET, ) DEEPSEEK_BASE_URL https://api.deepseek.com DEEPSEEK_MODEL deepseek-chat如果你只是在本地快速测试也可以临时把密钥填在 config.py 里但一定要记得在提交代码前清理掉。5.3 DeepSeek 客户端封装把 DeepSeek 调用封装成一个类内部维护上下文历史。这样 QQ 机器人主程序只需要调用ask(question)就能拿到回复。# 文件路径deepseek_client.py from openai import OpenAI import config class DeepSeekClient: def __init__(self): self.client OpenAI( api_keyconfig.DEEPSEEK_API_KEY, base_urlconfig.DEEPSEEK_BASE_URL ) self.history [ {role: system, content: 你是群里的 AI 助手回答简洁清晰使用简体中文。} ] def ask(self, question: str, max_history: int 20) - str: self.history.append({role: user, content: question}) if len(self.history) max_history: self.history self.history[-max_history:] self.history.insert(0, {role: system, content: self.history[0][content]}) response self.client.chat.completions.create( modelconfig.DEEPSEEK_MODEL, messagesself.history, temperature0.7 ) answer response.choices[0].message.content self.history.append({role: assistant, content: answer}) return answer这里使用全局 history 会有一个问题所有群里的人都共享同一段上下文。实际项目中应该使用“用户 ID 群 ID”作为 key 来隔离会话后面在最佳实践章节再展开。5.4 QQ 机器人主服务主服务要做的事情通过 AppID AppSecret 获取 access_token。获取 WebSocket 地址。建立 WebSocket 连接并鉴权。监听消息事件。如果消息是群内 机器人则提取消息内容调用 DeepSeek。调用 QQ 消息发送接口把回复发回群里。# 文件路径qq_bot.py import asyncio import json import time import uuid from urllib.parse import quote import requests import websockets import config from deepseek_client import DeepSeekClient API_BASE https://api.sgroup.qq.com deepseek_client DeepSeekClient() def get_access_token(app_id: str, app_secret: str) - str: url https://bots.qq.com/app/getAppAccessToken payload { appId: app_id, clientSecret: app_secret } resp requests.post(url, jsonpayload, timeout10) data resp.json() access_token data.get(access_token) if not access_token: raise RuntimeError(f获取 access_token 失败: {data}) return access_token def get_websocket_url(access_token: str) - str: url f{API_BASE}/gateway/bot headers { Authorization: fQQBot {access_token} } resp requests.get(url, headersheaders, timeout10) data resp.json() ws_url data.get(url) if not ws_url: raise RuntimeError(f获取 WebSocket 地址失败: {data}) return ws_url def identify_payload() - dict: return { op: 2, d: { token: f{config.QQ_APP_ID}.{config.QQ_APP_SECRET}, intents: 1 30, shard: [0, 1] } } def extract_message(event: dict) - tuple: try: data event[d] author data[author][id] content data[content] channel_id data[channel_id] guild_id data[guild_id] return author, content, channel_id, guild_id except Exception: return None def clean_content(content: str) - str: # QQ 机器人收到的消息包含 机器人ID 或 !机器人ID 这样的占位符需要去掉 parts content.split() filtered [p for p in parts if not p.startswith()] return .join(filtered).strip() def send_group_message(access_token: str, channel_id: str, guild_id: str, content: str) - bool: # 群聊场景一般使用 channel 消息接口 url f{API_BASE}/channels/{channel_id}/messages headers { Authorization: fQQBot {access_token}, Content-Type: application/json } msg_id f{int(time.time())}{uuid.uuid4().hex[:8]} payload { content: content, msg_type: 0, msg_id: msg_id } resp requests.post(url, headersheaders, jsonpayload, timeout10) if resp.status_code ! 200: print(f发送消息失败: status{resp.status_code}, body{resp.text}) return False return True async def handle_event(event: dict, access_token: str): op event.get(op) if op 0: t event.get(t) if t GROUP_AT_MESSAGE_CREATE: msg extract_message(event) if not msg: return author_id, raw_content, channel_id, guild_id msg question clean_content(raw_content) # 这里可以根据业务需求加一些简单过滤 if not question: return try: reply deepseek_client.ask(question) except Exception as e: reply f调用 DeepSeek 时报错{e} print(f收到来自 {author_id} 的消息{question}) print(f回复内容{reply}) send_group_message(access_token, channel_id, guild_id, reply) elif op 10: # 收到 Hello 包需要发送心跳 heartbeat_interval event[d][heartbeat_interval] return heartbeat_interval async def heartbeat_loop(ws, interval: int): while True: await asyncio.sleep(interval / 1000) await ws.send(json.dumps({op: 1, d: int(time.time())})) async def main(): access_token get_access_token(config.QQ_APP_ID, config.QQ_APP_SECRET) ws_url get_websocket_url(access_token) print(fWebSocket 地址: {ws_url}) async with websockets.connect(ws_url) as ws: await ws.send(json.dumps(identify_payload())) heartbeat_task None async for raw in ws: event json.loads(raw) op event.get(op) if op 10: interval await handle_event(event, access_token) if interval and not heartbeat_task: heartbeat_task asyncio.create_task(heartbeat_loop(ws, interval)) elif op 0: asyncio.create_task(handle_event(event, access_token)) if __name__ __main__: asyncio.run(main())这个代码段里有一些需要注意的细节intents使用1 30表示接收所有事件。如果只关注群消息可以配置得更精准但本地测试时用所有事件更省事。鉴权时发送的 token 由 AppID 和 AppSecret 拼接而成中间用点号分隔。clean_content里过滤机器人的占位符避免把!123456这些内容当成问题发给 DeepSeek。send_group_message使用channel_id发送群聊消息这是群聊场景常用的方式。5.5 运行与验证确保环境变量已配置然后启动服务python qq_bot.py启动日志里会出现 WebSocket 地址服务启动后保持运行。这时候到测试群里发一条消息并 机器人比如机器人 用一句话解释什么是 HTTP 协议正常情况下机器人会在几秒内回复一条 DeepSeek 生成的文本。如果消息没有回复按下面顺序排查终端是否打印了收到来自 xxx 的消息。没有打印说明事件没有收到检查事件订阅和 WebSocket 连接。终端是否打印了调用 DeepSeek 时报错。说明事件收到了、但 AI 调用失败检查 API Key 和余额。终端是否打印了发送消息失败。说明 AI 有回复但消息没发出去检查 access_token 和 channel_id 是否正确。微信中常用msg_id做幂等校验QQ 平台这里用一个随机字符串即可主要是防止同一条回复被重复发送。6. 性能、稳定性与部署建议6.1 消息冷却如果群里有人连续刷屏调用不仅消耗 token还容易触发平台限流。建议在服务里加一个简单的冷却机制同一个用户在固定时间内只能触发一次询问。# 文件路径rate_limit.py import time class RateLimiter: def __init__(self, limit_seconds: int 10): self.limit_seconds limit_seconds self.records {} def is_allowed(self, user_id: str) - bool: now time.time() last self.records.get(user_id, 0) if now - last self.limit_seconds: return False self.records[user_id] now return True使用方式rate_limiter RateLimiter(10) def handle_question(user_id, question): if not rate_limiter.is_allowed(user_id): return 操作太频繁请稍后再试 return deepseek_client.ask(question)6.2 超时与重试DeepSeek API 在高峰时段可能响应较慢。openaiSDK 默认不会无限等待但建议显式设置超时时间避免用户等太久。self.client OpenAI( api_keyconfig.DEEPSEEK_API_KEY, base_urlconfig.DEEPSEEK_BASE_URL, timeout30.0 )另外建议对网络类异常做一次重试。可以参考 OpenAI SDK 的max_retries参数但重试次数不要设置过大一般 2 次即可。6.3 日志记录生产环境下需要记录三类日志消息事件日志谁在什么时间、哪个群、问了什么问题。DeepSeek 调用日志模型名称、耗时、token 消耗、返回状态。发送消息日志是否发送成功、失败原因。最简单的方式是使用 Python 标准库logging把日志输出到文件后续排查问题会方便很多。6.4 后台部署本地电脑运行后关掉终端服务就停了。想让机器人 7x24 小时运行建议部署到云服务器上。推荐的部署方式使用systemd托管 Python 服务崩溃后自动重启。使用nohup快速后台运行适合临时调试。使用 Docker 打包环境一致性更好。以systemd为例创建一个服务文件/etc/systemd/system/qq-deepseek-bot.service[Unit] DescriptionQQ DeepSeek Bot Afternetwork.target [Service] Userubuntu WorkingDirectory/home/ubuntu/qq-deepseek-bot EnvironmentDEEPSEEK_API_KEYsk-xxx EnvironmentQQ_APP_IDxxx EnvironmentQQ_APP_SECRETxxx ExecStart/usr/bin/python3 qq_bot.py Restartalways RestartSec5 [Install] WantedBymulti-user.target然后执行sudo systemctl daemon-reload sudo systemctl enable qq-deepseek-bot sudo systemctl start qq-deepseek-bot7. 常见问题与排查思路问题现象常见原因解决思路获取 access_token 失败AppID 或 AppSecret 配置错误检查环境变量重启服务WebSocket 连接失败网络无法访问平台网关检查公网访问、防火墙规则收不到群消息事件未订阅对应事件类型在后台补充事件订阅配置收到消息但没回复DeepSeek API Key 无效或余额不足检查 API 调用日志、余额回复里包含xxx没有清理用户消息中的 占位符使用 clean_content 清理发送消息返回 400channel_id 错误或消息内容超长检查 channel_id 和内容长度服务运行一段时间后断连心跳没有按约定发送检查心跳逻辑是否正常运行下面再单独展开两个高频问题。7.1 调用 DeepSeek 时报 401 或 402401 表示鉴权失败大概率是 API Key 写错了或者环境变量没有正确加载。先手动在 Python 交互环境里打印一下 API Key 的前几位确认不是空值import os print(os.environ.get(DEEPSEEK_API_KEY))402 表示余额不足。到 DeepSeek 开放平台检查账户余额并确认已开通对应的 API 权限。7.2 群消息事件收到但内容为空QQ 机器人平台推送的content可能包含 XML 风格的富文本占位符比如!123456 hello。如果直接做字符串截取容易得到残缺内容。建议统一用clean_content函数过滤掉...占位符。如果过滤后为空说明用户只 了机器人但没有输入实质内容此时可以直接忽略避免浪费一次 DeepSeek 调用。7.3 思考模型透传参数问题如果你的服务以后要接deepseek-reasoner这类带思考过程的模型在对接其他组件时可能会出现reasoning_content参数透传失败的问题。原因是这类模型在流式输出时会在增量结构中返回额外的reasoning_content字段而某些中间网关或组件要求必须把该字段原样传回后续调用否则会收到 HTTP 400 错误。在 QQ 机器人场景下因为我们是直接调用 DeepSeek API一般不会遇到这个报错。但如果你以后把同一个调用链路接到其他第三方平台或本地代理组件时需要特别注意这个字段。建议关闭流式输出直接获取最终结果。如果必须使用流式做好delta字段的重新组装。遇到 400 且日志中出现reasoning_content字样时优先检查是否有组件丢弃了扩展字段。8. 安全与合规建议8.1 API Key 管理不要在前端代码、Git 仓库、公开笔记中暴露 API Key。生产环境使用密钥管理服务或环境变量注入。给深寻 API Key 设置预算和用量告警避免异常调用产生高额费用。8.2 用户输入安全QQ 群是一个开放环境用户输入不可控。有几点需要特别注意在 system prompt 中约束模型只回答合法、正面的内容。对用户输入做长度限制超长文本直接截断或拒绝。如果机器人需要执行命令或读文件务必做好白名单校验。8.3 用户隐私群聊消息中包含其他用户的 QQ 号、聊天内容和群名这些都属于敏感数据。你的服务端日志里尽量不要记录完整消息建议只记录用户 ID 后几位、问题长度和处理状态。存储聊天记录时要遵循最小化原则用完即删。8.4 平台规则遵守接入 QQ 机器人时必须遵守 QQ 开放平台的服务条款。不要使用机器人发送广告、垃圾信息、诈骗内容也不要利用机器人批量添加好友或骚扰他人。如果机器人要发布到更多群聊需要走正式的发布和审核流程。9. 总结与进阶学习路线本文把 DeepSeek 接入 QQ 机器人的全过程拆成了四个核心环节DeepSeek API 调用、QQ 机器人平台配置、WebSocket 事件接收、群消息回复。通过完整代码示例你可以跑通一个最简单的群内 AI 问答机器人。代码跑通之后如果想继续深入建议按下面几个方向扩展会话隔离把 history 从全局变量改成按“群 ID 用户 ID”维度独立维护让不同群友拥有各自的对话上下文。消息类型扩展除了文本回复可以尝试发送 markdown 模板消息、图片消息。指令系统定义#翻译、#总结、#代码等前缀指令让机器人按不同 prompt 处理不同任务。接入更多模型DeepSeek API 兼容 OpenAI 协议同一个服务可以平滑切换到其他兼容接口。部署容器化把服务 Docker 化配合 docker-compose 管理配置和环境变量。最后提醒一句正式上线前一定要先在沙箱环境和测试群里完整验证消息收发、超时处理、异常日志这三块内容。大模型服务本身存在响应不确定性机器人项目要想稳定运行调试日志和异常兜底比炫酷的功能更重要。