每天在网页版AI里复制粘贴、来回切换标签页说实话挺累的。手机端就算装了APP也得专门点开、等加载、再手动输入。后来我想明白了一件事既然日常聊天都在QQ上那为什么不能把AI直接塞进QQ里这样随时随地发条消息就能用拉个群还能让朋友一起用。于是就有了这个项目——用Lighthouse做消息接入用DeepSeek做大脑通过QQ当入口5分钟搭出一个24小时在线的私人智能体。整个过程不复杂也不涉及服务端那些让人头疼的部署细节。这篇文章我会把完整思路、代码、参数调优、防坑经验全部拆开讲清楚感兴趣的可以直接照着做。这个项目适合几类人一是受够了网页版AI切换成本的日常用户二是想给团队、社群搞一个统一AI入口的管理者三是想入门智能体开发的技术爱好者。无论哪一类只要会基本的Python语法能跟着命令行操作就能复现。不需要高配服务器一台能跑Windows/Linux的小主机、一个QQ号、一个DeepSeek的API Key就够了。1. 整体设计与思路拆解1.1 为什么入口选QQ而不是自建网页很多人第一反应是要做一个AI智能体那不应该做个网页、小程序或者APP吗我的观点刚好相反——AI对话本身就是一个高频、碎片化的操作用户需要的不是多一个入口而是少一个切换成本。网页和小程序的问题在于它们都是“被动等用户来”的模式用户得先打开、再进入、再输入操作链路长而QQ是用户本来就在的地方消息通知本来就在输入框本来就在把AI的消息流接入QQ等于把AI变成了一个联系人直接发消息就能对话。QQ做入口还有两个实际好处一是好友关系链和群聊天然支持多人共享一个人搭好智能体拉进群里就是团队助手二是QQ消息支持文本、图片、文件后续如果要让智能体解析图片或者接收文件接入层几乎不用改消息里都能带。网页版方案在这两件事上都要额外做很多工作。1.2 为什么选Lighthouse做消息接入层Lighthouse在这个项目里扮演的是“消息通道”的角色。你可以把它理解成一根水管一端接QQ的实时消息流另一端接你的处理代码。它处理了QQ协议里最烦人的那些事——登录、心跳、消息事件收发、群消息、私聊消息、图片和文件的上传下载。如果没有这层封装你得自己去跟QQ的私有协议打交道光是把登录保住、消息不漏不重就够折腾一两周了。选Lighthouse还有一个原因它把消息事件做成了Webhook风格的回调模型。也就是说你不需要写一个循环去轮询有没有新消息只要在框架里注册一个函数有QQ消息来了这个函数就会被自动调用参数里带着发送人、群号、消息内容。这种事件驱动模型对新手非常友好对后续扩展也方便——想加一个新指令就是在回调函数里多加一个分支仅此而已。提示Lighthouse本身不自带AI能力它只负责“接消息”和“发消息”。真正回答问题的是DeepSeek两者通过代码串起来。理解这个分工后面所有步骤都不会乱。1.3 为什么选DeepSeek而不是其他大模型选模型这件事我主要考虑三点接口兼容性、成本、中文能力。DeepSeek的API接口兼容OpenAI格式这意味着所有基于OpenAI SDK的代码几乎可以直接换Base URL就能跑通不用改调用逻辑。这一点在项目里价值很大因为后续如果想换成其他模型代码改动极小。价格方面DeepSeek目前对个人开发者非常友好日常高频使用成本也压得很低这决定了“24小时在线、随叫随到”的智能体真的能长期跑下去而不是体验几天就烧钱劝退。中文理解能力就不多吹了从我实际体验来看日常问答、文案改写、逻辑推理、甚至角色扮演输出质量都够用而且回复风格能通过提示词调得很自然符合QQ这种日常聊天场景。整体架构上这个项目的链路很简单QQ消息 → Lighthouse框架 → Python处理函数 → DeepSeek API → 处理结果 → Lighthouse → QQ回复全链路下来没有任何自建模型服务器的负担DeepSeek官方API既负责推理也负责存储会话状态通过传入历史消息实现项目要做的只是在中间做消息透传和逻辑控制。下面我按从零开始的顺序把每步操作讲清楚。2. 环境准备与基础组件部署2.1 前置条件与工具清单动手之前先把需要准备的东西列个清单避免做到一半发现缺依赖。项目要求说明Python3.9及以上建议3.10/3.11新版库兼容性更好操作系统Windows/Linux/macOS均可长期运行推荐Linux服务器或低功耗小主机QQ号一个正常使用的邮箱/手机号注册的QQ建议用小号避免影响日常账号DeepSeek API Key在官网注册后获取需要在DeepSeek开放平台申请有免费额度Lighthouse通过pip安装框架本身是Python包后面会详细说明这里多说一句为什么建议用小号。因为智能体是24小时在线的QQ会持续有活跃会话而且可能被拉进群、频繁收发消息这类行为对于日常使用的账号来说容易触发账号保护甚至限制。用专门的小号跑就算出了问题也不影响个人社交通讯。2.2 DeepSeek API Key申请与调用地址确认DeepSeek开放平台的申请流程很简单注册账号、实名认证、在控制台创建API Key。创建的时候可以选择设置额度上限建议第一次先设一个小额度比如10块钱防止因为测试代码里循环调用出问题烧掉太多。拿到Key之后需要确认三个信息API Base URLhttps://api.deepseek.com或者是https://api.deepseek.com/v1具体看官方文档模型名一般用deepseek-chat如果要用更强推理能力就选对应的reasoner模型认证方式在HTTP请求头里加Authorization: Bearer 你的Key先不用写代码可以在终端里用一个简单的curl命令测试连通性确认这个步骤通过再继续。curl https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的APIKey \ -d { model: deepseek-chat, messages: [{role: user, content: 你好}] }如果返回里带有content字段说明Key有效、网络正常、账号额度OK可以进入下一步。这一步能提前排除掉80%后面可能遇到的问题。2.3 安装Lighthouse框架并完成基础配置Lighthouse的安装很直接就是一个Python包pip install lighthouse-framework装完后需要初始化一个配置文件用来告诉框架要监听哪个QQ号、用哪种登录方式、回调入口在哪个函数。不同版本的Lighthouse配置方式略有差异但核心配置项基本一致。典型的配置思路是这样创建一个项目目录例如qq-ai-bot/在目录下创建config.yaml或.env文件写入QQ号、登录凭据、回调地址等创建main.py在里面定义收到消息后要执行的函数以我常用的方式为例在main.py里先导入框架、注册消息处理器import os from lighthouse import create_app from openai import OpenAI # DeepSeek客户端兼容OpenAI SDK只改base_url和api_key client OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY), base_urlhttps://api.deepseek.com ) app create_app(config.yaml) app.on_qq_private_message() async def handle_private_message(event): user_id event.user_id text event.message_text reply chat_with_deepseek(text) event.reply(reply) def chat_with_deepseek(prompt): resp client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: prompt}] ) return resp.choices[0].message.content if __name__ __main__: app.run()这段代码是完整可运行的骨架。create_app负责读取配置并启动消息监听app.on_qq_private_message()注册私聊消息处理函数收到消息后调用chat_with_deepseek获取模型回复再通过event.reply发回QQ。整个流程没有任何多余的中间件。配好之后第一次运行会弹出二维码用你的QQ小号扫码登录登录成功后Lighthouse会保存登录状态。之后重启服务就不需要再扫码了。注意如果运行环境是服务器没有显示器看不到二维码需要通过tty或转发二维码图片的方式完成登录。建议先在本地跑通登录流程再把整个目录拷贝到服务器上运行。3. 核心代码实现与参数解读3.1 消息处理函数从“单轮问答”升级到“多轮对话”上面的骨架代码做到的是“单轮问答”每次收到QQ消息只把当前这一句发给DeepSeek不带历史上下文。这样会有个明显问题——你问“它是谁”模型不知道“它”指什么。要让智能体真正好用必须实现多轮对话也就是把最近几轮的消息一起发给模型。我的做法是用字典按QQ号暂存每个人的历史消息每次收到新消息把历史追加进去再一次性发给DeepSeek同时只保留最近10条防止历史太长占用Token。from collections import defaultdict session_history defaultdict(list) def chat_with_deepseek(user_id, prompt): history session_history[user_id] history.append({role: user, content: prompt}) # 只保留最近10条消息 if len(history) 10: history history[-10:] session_history[user_id] history resp client.chat.completions.create( modeldeepseek-chat, messageshistory, temperature0.7, max_tokens1024 ) reply resp.choices[0].message.content history.append({role: assistant, content: reply}) session_history[user_id] history return reply这段代码的核心是session_history这个字典它负责给每个QQ用户维护独立的上下文。用字典而不是数据库的原因是这个项目的并发量本身不大内存方案够用而且代码最简洁。如果以后要支持多实例部署或者服务重启不丢记忆再换成Redis即可。对绝大多数个人和社群场景内存方案完全够用。3.2 关键参数选择temperature、max_tokens、top_p在配置DeepSeek调用时有三个参数直接影响回复质量这里逐个讲清楚。temperature控制随机性取值范围0~2默认1。数值越低回复越稳定、越保守数值越高回复越发散、越有创意。QQ聊天场景我建议设置0.7左右。原因很实际太低容易像复读机显得死板太高容易跑题一个不小心的回复就偏了。如果做的是知识问答类的智能体可以下调到0.3追求准确如果是闲聊陪伴型可以上调到1.0以上让回复更活泼。max_tokens限制单次回复的最大长度。QQ场景建议1024也就是大概几百个汉字日常聊天足够了。设得太大有两个坏处一是单次响应时间变长模型要生成更多字二是API成本上升。如果智能体要用来写长文、出方案再考虑调到2048或更高。top_p核采样参数默认1一般保持默认即可。它和temperature有一定重复实际项目中调一个就行没必要两个一起折腾。我习惯只调temperaturetop_p保持默认。这几个参数用表格总结如下参数推荐值作用调参方向temperature0.7控制随机性低稳定高创意max_tokens1024单次回复长度上限按场景调整top_p1默认核采样通常不需要动3.3 用System Prompt把智能体调教成“有人味”模型输出自然不自然很大程度上取决于你在System Prompt里写了什么。System Prompt是发给模型的一段系统级指令它不会被用户看到但会时刻影响模型的回答风格。我一开始图省事只写了“你是一个智能助手”结果回复全是“您好请问有什么可以帮您”这种客服腔放在QQ里别提多违和了。后来我把System Prompt改成了这样你是我的私人智能助手住在QQ里。 你的性格直接、幽默、靠谱。 回复要求 1. 像朋友聊天一样自然不要用“你好请问”这种客服腔 2. 短句子为主一般不超过100字 3. 不知道的事直接说不知道不要瞎编 4. 如果用户发的是闲聊就跟用户闲聊如果发的是问题就认真回答问题。同样的模型同样的参数只改这一段话输出效果天壤之别。这个项目的核心可玩性就在这你可以尝试不同的System Prompt做出客服型、学霸型、吐槽型、冷知识型等各种性格的智能体。我把这个配置单独放在一个环境变量或者配置项里方便随时调整。3.4 群聊接入让整个群共用同一个智能体私聊跑通之后把智能体拉进群其实改动很小。Lighthouse同样提供了群消息事件的处理器app.on_qq_group_message() async def handle_group_message(event): group_id event.group_id user_id event.user_id text event.message_text # 可选只有机器人时才回复避免每条消息都触发 if not event.is_at_me(): return reply chat_with_deepseek(user_id, text) event.reply(f{user_id} {reply})这里有一个细节值得注意群聊里如果不做任何过滤智能体会被群里消息淹没每次有人说话它都想回既浪费Token又吵。我采用的做法是判断is_at_me()只有被艾特的时候才回复。这种做法适合消息频繁的大群。如果是一个安静的讨论群想让它自动参与所有对话那就不加这个判断让它旁听并适时回复效果也很神奇。这两种模式我都在用看群的活跃度切换。3.5 扩展能力接入Dify或Coze类智能体平台的思路如果你的需求不只是“问答机器人”而是想要一套完整的智能体工作流——比如让AI能查数据库、调用外部工具、多步规划——那可以在这个项目中间加一层Dify或Coze。思路也很简单Lighthouse收到QQ消息后不直接调DeepSeek而是把消息发到Dify/Coze提供的API接口上把返回结果发回QQ。def chat_with_agent(prompt): # 伪代码向Dify/Coze的工作流API发请求 resp requests.post(https://api.agent-platform.example.com/chat, json{query: prompt}) return resp.json().get(answer)这样一来QQ只是入口智能体本身由专业平台来驱动能力边界大幅扩展。Lighthouse在这里的角色始终不变——解决“消息从哪来、回哪去”的问题这是整个架构里最稳定的部分。4. 部署为24小时在线服务4.1 进程常驻nohup、systemd还是Docker代码写完跑通了接下来要解决一个问题退出终端服务就停了怎么让它一直挂后台跑我试过三种方式从简到繁分别是方式一nohup最快适合临时跑nohup python main.py bot.log 21 这样进程就在后台运行日志输出到bot.log。优点是一行命令搞定缺点是进程管理能力弱崩了不会自动重启。方式二systemd推荐Linux服务器首选在/etc/systemd/system/qq-bot.service里写[Unit] DescriptionQQ AI Bot Afternetwork.target [Service] WorkingDirectory/opt/qq-bot ExecStart/usr/bin/python main.py Restartalways RestartSec5 EnvironmentFile/opt/qq-bot/.env [Install] WantedBymulti-user.target然后执行sudo systemctl daemon-reload sudo systemctl enable --now qq-bot它的好处是开机自启、崩溃自动重启、统一查看日志journalctl -u qq-bot -f。这是我最推荐长期运行的方式。方式三Docker适合已经用容器管理的机器如果环境里已经在跑Docker也可以用容器方式。把Lighthouse和代码打成镜像用--restartalways参数保证容器挂了自动拉起来。这种方式隔离性最好但对新手来说调试稍麻烦主要多了一层镜像构建和端口映射。4.2 环境变量管理与安全边界配置文件里最敏感的就是DEEPSEEK_API_KEY和QQ登录凭据。我强烈建议不要硬编码在Python文件里而是放在.env文件或环境变量里面。# .env 示例 DEEPSEEK_API_KEYsk-xxxxxxxxxxxxxxxx BOT_QQ123456789然后通过python-dotenv加载from dotenv import load_dotenv load_dotenv()这样做的目的有两个一是防止代码不小心传到Git仓库导致Key泄露二是以后换号、换Key只需要改配置文件不用动代码。关于安全边界有三条经验值得写下来API Key额度限制一定要设。DeepSeek控制台支持设置月度额度上限设好之后就算代码出了bug导致无限循环调用最多也就消耗到这个上限不会出现一夜烧掉大几百的情况。群聊场景做好关键字过滤。如果智能体被拉进一个讨论敏感话题的群它可能生成不适合的内容。我的做法是在发送之前过一遍本地敏感词列表命中就直接拒绝回复。私聊也可以做白名单。在代码里加一个allowed_users列表只允许指定的QQ号跟智能体对话其他私聊消息一律忽略。适用于个人使用场景。5. 常见问题排查技巧实录5.1 排查流程速查表这套架构虽然链路短但任何一个环节出问题都会导致“机器人不回复”。我把实际中遇到的高频问题和排查方法整理成一张表现象可能原因排查方法机器人完全不回复进程没跑/挂了看日志journalctl -u qq-bot -f或tail -f bot.log机器人收到消息但无响应DeepSeek API Key失效/额度用尽在终端重新curl一次API确认返回200回复特别慢生成内容太长或网络波动调低max_tokens检查服务器和API之间的网络延迟群里艾特机器人没反应群消息事件没触发/艾特判断出错先去掉is_at_me()判断确认群消息能收到重启后要重新扫码登录态没有保存成功检查登录后是否有持久化文件权限是否可写消息偶尔重复回复Webhook回调重试机制在回调函数里加简单幂等记录最近消息ID已处理就跳过5.2 我踩过的几个坑这个项目从零到跑通我也踩了几次坑挑三个最典型的分享出来。第一个坑把max_tokens设太大导致响应超时。最开始我图省心把max_tokens设成了4096结果在QQ里问个天气都要等十几秒才回。后来发现是模型把回复写长了。调整到1024之后响应基本都是两三秒内体感好了很多。QQ聊天场景讲究的是轻量快速不是写论文。第二个坑忘记做无上下文判断。系统刚上线时很多人加了好友后发的第一句话是“在吗”或者“你好”我的代码会把这句原样发给DeepSeekDeepSeek往往会回一句特别正式的问候。后来我在System Prompt里加了“如果用户只是打招呼直接回个简短的‘在的有什么事儿’”这个问题立刻解决。第三个坑API Key明文存在代码里。有一次我想把项目分享给朋友直接把Git仓库链接发过去了幸好后来发现代码里带着API Key赶紧去控制台吊销重换。从那以后所有敏感信息全部走.envgitignore里写好排除规则这在多人协作或者公开分享时尤其重要。最后再补充一个使用上的小技巧因为QQ有“正在输入”状态Lighthouse实际上可以在回复前先发一条“正在思考中…”的占位消息然后异步更新内容这样体验上会更像真人聊天。实现思路是在收到消息后先event.reply(让我想想...)然后再调用DeepSeek最后再发真正的回复。在慢网络或者复杂问题场景下这个细节会让用户体验提升不少。我做了几十个智能体之后最大的感受是决定智能体好不好用的其实不是模型有多强而是消息通路有多顺、交互细节有没有打磨到位。