先交代一下背景我平时大部分碎片时间都泡在 QQ 里群里经常有人问各种问题、让我帮忙查资料、甚至临时让我整一个方案。以前我只能切到浏览器打开某个 AI 网页版复制问题、等回答、再把答案贴回 QQ来回切换几次就懒得搞了。后来我把 Deepseek 接进 QQ搭了一个 24 小时在线的私人智能体所有对话直接在聊天窗口里完成——我有空的时候真人回没空的时候机器人顶上体验完全是两个级别。这篇文章就是来复盘整个搭建过程的。核心思路是Deepseek 负责“大脑”Lighthouse 作为消息调度层负责“神经中枢”QQ 机器人则是“手和嘴”。只要把 Deepseek API Key、QQ 机器人凭证、消息转发服务这三样准备好约 5 分钟就能跑通最小可用版本。如果你也受够了网页版 AI 的“一次性体验”想拥有一个随时在线的智能体这篇可以直接照着抄。1. 为什么要把 AI 搬进 QQ网页版解决不了的三件事先说结论网页版 AI 本身没有问题问题出在“网页这个容器”。它适合你专门抽出一段时间去研究问题但不适合做 24 小时在线的私人助理。想把 AI 变成“随时可用、随叫随到”的存在IM 入口比网页入口天然高效得多。1.1 网页版的“一次性体验”和上下文断裂网页版 AI 的典型使用路径是打开网页、登录、新建对话、输入问题、等回答、复制结果、关闭页面。这中间任何一步被打断体验就会断掉。尤其是“上下文断裂”——你上午在网页里问过某件事下午再打开往往已经忘了要延续哪些背景信息就算网页端有历史会话也不会主动提醒你可以继续聊你还是得手动补一句“我上午说的那个项目是……”QQ 场景完全不同。你每天都在 QQ 里和同一个人、同一群人聊很多话题对话是连续发生的。AI 接进来之后你可以直接说“刚那个方案再细化一下”它知道“刚那个方案”指的是什么因为历史消息就在上下文里。这种连续性网页版做不到因为网页版的产品逻辑是“会话制”而 IM 的产品逻辑是“全天候在线制”。1.2 多端触达消息入口才是最高频入口网页版 AI 还有一个隐性成本它的触点是“浏览器”不是“你的设备”。在办公室电脑上打开过的对话换到手机上要重新登录手机上查的资料回到电脑上又要重新找。所以网页版使用频率天然受限只有当你专门想起“我要去问 AI”的时候它才被打开。QQ 则是常驻的。电脑端、手机端、平板端消息实时同步机器人在线就等于你随时有一个能对话的入口。这个入口不会因为换设备、换网络、临时有事就断掉。把 AI 放进 QQ等于把“提问”这个动作变成了发消息而发消息是人的本能操作不需要额外学习。1.3 从“问答工具”到“24小时值班智能体”把 AI 接进 QQ 之后它的角色会从“问答工具”悄然变成“值班助理”。比如我搭好之后的第一天群里就有人半夜十二点问“明天下午客户来帮我看看议程怎么安排”机器人直接给出了整个流程草稿第二天我把它复制出来改了几行就用上了。再往后你可以让它每天早上给群友推送天气可以让它在新人进群时自动发一份群规和 FAQ可以让它把每天群里的重要讨论整理成摘要。这些流程网页版完全做不到因为网页是被动打开、用完即走的QQ 是常驻的、有事件通知的、能主动触达的。这其实就是“智能体”和“聊天机器人”的最大区别聊天机器人等你问智能体可以值班、可以主动、可以做事。2. 系统架构拆解Deepseek 负责聪明Lighthouse 负责连接整套系统拆开看其实就三个角色分工非常清晰。组件角色核心职责你不需要操心的Deepseek API大脑理解用户输入、生成自然语言回复模型训练、算力、推理Lighthouse神经中枢接收 QQ 消息事件、调用 Deepseek、回传结果消息格式转换、会话管理、并发调度QQ 机器人感官 / 口舌接收用户消息、下发回复在 QQ 平台侧稳定收发消息2.1 三个组件的职责边界最底层的 QQ 机器人解决“怎么把消息拿出来、怎么把回复塞回去”。它本身不产生智能只是一套 API 封装。最顶层的 Deepseek 解决“怎么把一句人话变成一段有信息量的回答”。它是整个系统的大脑所有技巧都要围绕它来调。中间层就是 Lighthouse这是整套链路里最容易被忽略、却最关键的组件。它解决的问题是QQ 机器人吐出来的是带有平台痕迹的原始事件Deepseek 工商要的是结构化的 messages 数组QQ 机器人要求收到消息后尽快响应Deepseek 生成一段长回答可能要十几秒QQ 平台有频率限制Deepseek 接口也有并发限制。这些矛盾全部靠 Lighthouse 在中间消化。2.2 Lighthouse 在这一链路中解决的核心问题我给 Lighthouse 的定义是一个负责“接入、调度、会话”的消息网关。它的核心能力有三个。第一协议转换。QQ 机器人推过来的事件可能是 JSON字段命名、嵌套结构都是平台定的。Lighthouse 会把它们转成统一的消息结构谁发的、哪个群、内容是什么、还有什么附加字段。这样就算你后来想把入口从 QQ 换成飞书或企业微信调度逻辑可以完全复用只要换掉接入适配层。第二会话管理。Deepseek API 本身是不带记忆的每次请求都是独立的。要让 AI 记住你们上一轮聊了什么就必须由调用方把历史消息带上去。Lighthouse 充当那个“带记忆的人”把每个用户最近聊过的内容维护在内存或 Redis 里下次请求时拼进 messages。第三并发与重试控制。多个群、多个人同时在用的时候请求会瞬间挤到一起。Lighthouse 可以在前面加队列、限速器还可以对 Deepseek 的临时报错做重试。这种稳定性问题因为没有中间层你写脚本直接调 API 是根本扛不住的。2.3 为什么不用现成的对话平台而要自己搭市场上确实有很多低成本方案比如直接用各种对话机器人平台零代码就能配置。但它们的通病是入口和流程都被平台绑定提示词放在别人服务器上、会话记录由别人保管、消息频率受别人限制想定制一个特殊行为往往要按“平台支持的方式”来做而不是按你想要的方式做。自己搭一套 Lighthouse 中间层的价值恰恰在于“完全可控”。你的系统提示词想怎么改就怎么改会话记录存在自己的服务器想发给谁、在哪个群生效由白名单决定Deepseek API Key 也是自己的不存在平台抽成或限流上限。对于真正打算把智能体当作长期基础设施的人来说这种掌控感是值得付出的代价。3. 起步准备申请 Deepseek API 和创建 QQ 机器人动手配置前先把三样东西准备好Deepseek API Key、QQ 机器人凭证、一台能长期运行的服务器。标题里说“5分钟”指的是这三样都就绪之后搭建过程确实很快如果是从零开始申请账号、过审、配环境完整流程大概需要一个下午。3.1 获取 Deepseek API Key先去 Deepseek 开放平台注册账号完成实名认证后进入控制台在左侧菜单找到 API Keys点击“新建 API Key”复制保存。注意API Key 只会在创建时完整展示一次之后再也看不到了务必要放在安全的地方。Deepseek 的接口兼容 OpenAI 的格式base_url 是https://api.deepseek.com模型名默认用deepseek-chat。所以在后面的 Python 代码里可以直接用 OpenAI 的 Python SDK 来对接只是把 api_key 和 base_url 换掉就行。充值方面按量付费单个个人项目日常使用充几十块能用很久。提示不建议把 Key 硬编码在代码里。用环境变量或者.env文件管理这样代码传到公开仓库或者换机器部署时不会泄露凭证。3.2 创建 QQ 机器人QQ 机器人要走官方开放平台目前主要是 q.qq.com / bot.q.qq.com 这个入口。注册开发者账号后在控制台创建一个机器人应用创建完成会拿到 AppID 和 AppSecret这是机器人的身份凭证。接着按平台文档配置。最核心的一步是“消息接收方式”有两种模式可选一种是回调地址模式平台把用户消息 POST 到你配置的 HTTPS 地址上另一种是 WebSocket 长连接模式主动从平台接收消息。对个人项目来说如果你的服务器不好配置公网 HTTPS 证书WebSocket 模式更省事如果你打算把 Lighthouse 网关架在一个有域名的服务器上回调模式更直观。这里必须多说一句QQ 机器人的权限和审核是逐步放开的不同时间段、不同账号能申请到的事件订阅范围可能不一样。最稳妥的做法是先用官方文档确认当前支持的机器人类型和消息事件字段再决定代码怎么写。网上流传的各种“非官方协议”接入方式虽然短期内可能跑通但随时面临封号风险不建议碰。3.3 本地开发环境准备不建议把服务放在自己的笔记本电脑上因为 24 小时智能体的前提是 24 小时在线。一台云服务器2 核 4G 就够用内存大户主要是 Deepseek 服务本身并不在本地跑所以资源占用其实很低或者家里搭一台长期开机的迷你主机都可以。软件层面需要准备Python 3.11 及以上跑 FastAPI 网关Docker部署 Redis 等中间件不是必须但强烈推荐Git拉取代码用如果你用的是云服务器记得在防火墙和安全组里放行需要用到的端口比如 8000FastAPI 默认端口。4. 用 Lighthouse 打通 QQ 与 Deepseek 的核心链路所谓“5分钟跑通”指的是下面这套链路QQ 用户发消息 → 平台把事件推送到 Lighthouse → Lighthouse 带上上下文调 Deepseek → Deepseek 返回回复 → Lighthouse 把回复通过 QQ 机器人 API 发送回去。下面给的是一个最小可用实现思路核心代码用 Python FastAPI 来写。开发环境里装好fastapi、uvicorn、openai这几个依赖就能跑。4.1 Lighthouse 的配置项解析不管 Lighthouse 是开箱即用的开源编排平台还是你自己用 FastAPI 写的一个小服务它的核心配置都不外乎三块。第一块是接入配置QQ 机器人的 AppID、AppSecret、消息回调 Token用于校验事件真实性。第二块是模型配置Deepseek API Key、base_url、模型名、system prompt。第三块是路由规则触发前缀比如只有“机器人”才算消息、白名单哪些 QQ 号、哪些群允许使用、超时时间、并发上限。配置建议集中放在一个config.py或者 YAML 文件里避免散落得到处都是。4.2 最小可用代码接收 QQ 消息并转发给 Deepseek先看完整代码import os from fastapi import FastAPI, Request from openai import OpenAI app FastAPI() client OpenAI( api_keyos.environ.get(DEEPSEEK_API_KEY), base_urlhttps://api.deepseek.com, ) # 简化版会话存储生产环境建议换 Redis conversations {} SYSTEM_PROMPT 你是一个友好的私人助理。回答要简洁、准确不要过度发散。 def parse_qq_event(data: dict): 把 QQ 平台推送的事件解析成统一结构实际字段以官方协议为准。 return { user_id: data.get(openid, default_user), group_id: data.get(group_id, default_group), message: data.get(message, ).strip(), } def trim_history(history, max_tokens6000): 按 token 数粗略截断历史避免超出上下文窗口。 trimmed [] used 0 for item in reversed(history): tokens len(item[content]) // 2 # 中文粗略按字符数/2估算 if used tokens max_tokens: break trimmed.insert(0, item) used tokens return trimmed app.post(/qq/webhook) async def qq_webhook(req: Request): data await req.json() event parse_qq_event(data) history conversations.get(event[user_id], []) history.append({role: user, content: event[message]}) history trim_history(history) resp client.chat.completions.create( modeldeepseek-chat, messages[ {role: system, content: SYSTEM_PROMPT}, *history, ], temperature0.7, ) answer resp.choices[0].message.content history.append({role: assistant, content: answer}) conversations[event[user_id]] history return {data: {content: answer}}这段代码的逻辑非常简单QQ 平台事件 POST 到/qq/webhook解析出用户 ID 和消息文本从conversations里取出该用户的历史对话列表把新消息追加进去调用 Deepseek API连同 system prompt 和历史消息一起发送收到回复后把它写进历史列表并返回给 QQ 平台。这个最小版本已经能跑通“QQ 聊一句话 → AI 回一句话”。不要小看这个版本它已经具备了一个智能体的雏形有 system prompt 控制人格、有历史记忆、有模型返回。剩下的优化都是在它的骨架上加肉。4.3 上下文管理怎样让 AI 记住十几轮对话上面代码里最容易被忽略的是trim_history这个函数它其实是上下文管理的核心。Deepseek 虽然有很长的上下文窗口但 24 小时挂机意味着对话会无限积累。如果每次请求都把全部历史带上去很快就达到 token 上限报context_length_exceeded错误如果完全不带历史AI 就失去记忆。权衡的办法是只保留最近若干轮。实际测试下来一个日常聊天场景保留最近 10-20 轮已经足够再早的信息对当前回复影响很小。如果你希望 AI 的“长期记忆”更强可以考虑把更早的对话定期做摘要然后以摘要文本的形式放在 system prompt 里让 AI 始终知道自己之前干过什么。这里的trim_history用的是最朴素的按字符估算 token 的方式。如果你用的是 OpenAI SDK更精确的办法是调用 tokenizer 来数但个人项目没必要这么较真估算够用。4.4 流式输出让回复像打字机一样最小版本用的是阻塞调用等 Deepseek 整段回答全部生成完毕一次性返回给 QQ。这样做的后果是遇到长回答时用户会在 QQ 里看到一个“正在输入”状态持续十几秒体验很差。进阶做法是流式输出。调用模型时加上streamTrue服务端会不断收到增量内容Lighthouse 再把增量内容通过 QQ 消息接口逐段推送过去用户在聊天窗口里看到的回复就像打字机一样滚动出现响应时间缩短到 1 秒内。这个改动对体验的提升非常明显也是把智能体做成“像真人聊天”的关键。第一版不建议直接上流式先把链路跑通、把上下文管理调好再考虑流式否则中间多出来很多状态同步问题。5. 实测中的三个坑QQ侧、模型侧、网关侧真实跑起来之后你会发现“能通”和“能用”之间隔着一堆坑。下面这几个是我实际踩过以后觉得最有代表性的按排查的完整链路来讲。5.1 QQ 机器人的消息频率限制与被动回复时限QQ 机器人并不是一个“随便发”的通道。平台侧对消息频率有严格限制秒级、分钟级、日级都有额度同时被动回复也要求在收到消息后的限定时间内完成响应超时会被判定失败。我最初遇到的现象是机器人偶发不回复日志里也没有报错。排查了很久才发现不是 Deepseek 没返回而是 QQ 平台侧因为响应超时主动丢弃了。更麻烦的是如果占位消息发太多、或者回复频次太高会被平台风控轻则限流重则短时间封禁。解决思路分两层。第一层对耗时操作做异步化收到消息后先立即回一个“正在思考”的占位消息把用户请求塞进队列AI 生成完毕后再调用主动发送接口把结果发出去。第二层发送端做限速维护一个简单的令牌桶控制每秒钟最多发出的消息数量。这个限速器放在 Lighthouse 网关里对模型侧和平台侧都有保护作用。5.2 Deepseek 接口报错、token 超限与超时Deepseek API 本身很稳定但调用方式不对会踩到几个经典报错401 是 API Key 错误或未充值429 是超出并发限制400 里最常见的是 messages 格式不对比如混入了非法的 rolecontext_length_exceeded则是历史消息超长。这类问题的排查建议在 Lighthouse 网关层做统一异常捕获把错误码、错误信息和发生时间记到日志里同时把错误信息转换成用户可读的话术返回。比如“抱歉对话有点长我记不住了我们重新开始吧。”这样用户不会收到一串莫名其妙的英文报错。有一个容易被忽略的点Deepseek 的 API 对输入和输出都算 token如果你在 system prompt 里塞了很长的企业知识库文本历史还没多长token 就已经很高了。所以如果打算挂知识库最好在网关层做检索式问答——只有用户问到了才注入相关内容而不是一股脑全塞进去。5.3 Lighthouse 重试与并发控制网络总是会抖的Deepseek API 偶尔也会 5xx。网关里加重试是常规操作但重试要非常小心如果用户消息已经被 AI 正确处理了只是回传时网络断了你再重试一次就等于让 AI 重复答了一遍用户会收到两条一样的回复。更稳的做法是在事件里带上seq或消息 ID网关层基于消息 ID 做去重同时重试次数最多 2-3 次且采用递增间隔比如第一次等 1 秒、第二次等 3 秒。并发控制同样重要尤其是当 QQ 群里多人同时 机器人时一瞬间会产生大量请求。我的做法是在 Lighthouse 里设置一个信号量限制同时调用 Deepseek 的最大并发数其余请求排队等待。这样虽然响应时间会稍微变长但能保证服务不崩溃。6. 从“会聊天”到“24小时私人智能体”的进阶玩法链路跑通、坑也填完之后你手里的系统已经是一个可以正常值班的聊天机器人。但要称得上“私人智能体”还得给它加三样东西长期记忆、工具调用、访问控制。6.1 加记忆Redis 持久化会话上下文用内存字典存会话服务一重启所有用户的记忆全没了。对 24 小时在线来说这是不可接受的。升级方案是用 Redis 做会话存储key 建议按“群 用户”维度设计比如qq:{group_id}:{user_id}值存该用户最近若干轮对话历史。这样带来的好处是第一网关重启不丢记忆第二可以给不同群配置不同的 system prompt实现“一个网关、多个机器人人格”第三后续如果想做用户画像分析数据都在直接查。6.2 加工具让智能体查天气、定提醒、访问知识库只会聊天的 AI价值很有限。真正让它从“聊天机器人”升级成“智能体”的是给它装工具。Deepseek API 支持 function calling过程很简单在 API 请求里定义一个工具列表每个工具包含名称、描述、参数 JSON Schema模型判断用户意图后会返回一个“应该调用哪个工具、参数是什么”的请求你的网关收到这个请求后真正去执行函数比如查天气、查数据库再把结果拼接回 messages让模型生成最终回复。这个机制的本质是把 AI 从“只会说”变成“会说 会做”。我在群里启用了一个get_weather(city)工具之后机器人从“能聊天气”直接升级成“能报实时天气”体感差距非常大。Lighthouse 网关在这里只需要维护一个工具注册表按 JSON Schema 动态绑定函数即可。6.3 加门禁白名单、热点话题过滤、敏感内容自检私人智能体不是公共服务不需要对所有人开放。强烈建议在网关层加白名单只有指定的 QQ 号、指定的群里才能触发机器人回答。别等到有人骚扰了再想起来。同时输入输出两侧都要加内容自检。输入侧过滤明显违规的文本避免触发平台风控输出侧校验 AI 生成的回复避免模型被诱导生成禁止内容。这些检测最简单的方式就是用正则加敏感词列表更复杂的方式可以再调用一次大模型做内容安全审核。合规永远是第一位机器人一旦被封前面所有工作都白费。最后说点个人体会。我第一次跑通这条链路大概花了一个下午真正让我觉得值回票价的是把它接进常驻群之后的事新人进群问常见问题机器人能第一时间给出标准答案半夜有人临时找我出主意AI 能先打一版草稿我起床复制改一下就能用。它不是万能的但确实是“低成本的 24 小时在线助理”。如果你想长期跑记住两件事第一把日志做好别等出了事再靠猜第二时刻记得加白名单别把私人智能体变成公共入口。基础设施搭好之后剩下的就是慢慢喂数据、调提示词让它越来越像你。
