1. 先想清楚要搭什么一份能落地的群聊AI助手架构DeepSeek API 接入 QQ 机器人这件事说穿了就是把消息进来和回复出去这两段管道接好中间塞一个稳定的模型调用层。但真到动手的时候很多人卡在第一步不是写不出代码而是没想清楚整体长什么样——注册完账号、拿到密钥然后对着文档发呆不知道该先写哪一块。我见过不少朋友直接把模型调用糊在消息回调里跑通了 demo一进群就崩消息顺序乱了、超时了、被限流了、成本失控了。先把这个项目是什么讲明白。DeepSeek API 接入 QQ 机器人做的是一个能在 QQ 群里被 之后自动回复的智能助手群成员在群里 机器人提问机器人把问题连同近期上下文一起发给 DeepSeek 的对话接口拿到回复后回到群里。它解决的问题很朴素——把大模型的能力从网页对话框搬到大家日常聊天的地方省掉复制问题、切浏览器、粘贴、再复制回来这一套动作。适合谁看三类人。第一类是完全没接触过机器人开发、但会一点 Python 的朋友跟着做能跑起来第二类是自己搭过简单机器人、想把模型能力接进来的开发者可以直接看上下文管理和限流那几节第三类是准备把它做成长期服务的人部署、监控、成本这几块需要认真对待。全文不涉及任何非官方途径走的是官方开放平台的机器人能力这一点必须先说清楚后面所有代码都基于这套东西。1.1 三条技术路线的取舍以及我为什么选这条动手之前市面上能走的路大概有三种我把它摊开对比一下选型逻辑自然就出来了。路线消息通道稳定性维护成本适用场景官方开放平台 官方 SDK平台推送事件高平台侧保证低升级跟随官方长期跑、要在群里稳定在线官方开放平台 自建 WebhookHTTP 回调中高取决于自己的服务中要处理签名与重试已有 Web 服务、想统一网关其他非官方手段非官方低随时失效高不建议用于任何正式场景表格第三行我故意写得含糊因为它不值得展开。做长期服务的人应该明白一个道理底层通道的稳定性决定了上层所有工作的价值。如果消息通道本身随时可能断你在模型调用、上下文管理、体验优化上做的所有努力都是浮的。所以选型上我毫不犹豫选第一条理由就三条一是通道由平台保证掉线概率极低二是官方 SDK 把连接、心跳、重连、鉴权都封装好了你只需要关心业务逻辑三是权限和额度有明确规则出了问题有地方查。至于 Webhook 那条路等你已经有了一套 HTTP 服务、想把机器人挂在自己网关后面统一管理的时候再考虑。它的好处是易于水平扩展坏处是要自己处理签名校验、重试、幂等一开始就上这个属于给自己加难度。注意机器人能进哪些群、能收到哪类消息取决于你在开放平台上申请的权限范围。群聊场景的权限通常需要单独申请并等待审核不要假设注册完账号就什么都能收。1.2 整体架构与一次对话的完整数据流把架构图画在纸上这里用文字描述不画图大概是四层接入层负责和平台之间维持长连接、接收事件推送。路由层负责判断这条消息该不该理、该走哪条处理分支。模型层负责拼上下文、调 DeepSeek 接口、处理返回。会话层负责存每个群、每个人的近期对话控制长度和过期。一次完整的交互是这样走的群成员 机器人并输入问题 → 平台推一条群 消息事件过来 → 接入层解出事件体 → 路由层做三件判断是不是 我、内容是否为空、这个人是否在冷却期内→ 通过后进入模型层 → 模型层从会话层取出该群最近的若干轮对话拼成 messages 数组 → 调用 DeepSeek 的 chat completions 接口 → 拿到回复文本 → 做长度裁剪和格式清洗 → 回到群里 → 把这一轮问答写回会话层。看起来很简单对吧真正决定质量的是中间两个不起眼的环节上下文怎么拼和回复怎么裁。前者决定了模型能不能听懂那它多少钱这种指代后者决定了你的回复会不会因为超长被平台截断或者发送失败。这两块后面会单独拆。1.3 成本与延迟的粗算先有个心理预期在上线之前我建议每个人都先算一笔账不是为了省钱是为了知道自己会在什么规模上撞墙。Token 估算有个粗糙但够用的经验值中文一个字大概对应 0.6 到 1 个 token英文一个单词大概 1.3 个 token标点、代码、符号会拉高密度。这个值不精确但用来做容量规划足够了真实数字以接口返回的 usage 字段为准。下面是我当时做的一个假设模型你可以把自己的数字代进去单次交互输入约 800 tokens系统提示词 200 历史 400 当前问题 200单次交互输出约 300 tokens假设 20 个活跃群每群每天 100 次交互即 2000 次/天日输入 160 万 tokens日输出 60 万 tokens按月 30 天算输入 4800 万输出 1800 万把这组数字乘上你当前账号对应的单价就是月度成本。假设单价是输入每百万 2 元、输出每百万 8 元那月成本大约是 96 144 240 元。这个单价是示意值实际以官方定价页为准但计算方法是不变的输入量和输出量分开算输出通常更贵所以控制输出长度对成本的影响比控制输入更直接。延迟方面非流式调用下一次 300 tokens 的回复通常在两三秒量级具体受模型负载和输入长度影响。群里有人 你然后等五秒体验已经不太好了。所以后面我会讲两个手段一是把历史长度压下来输入短了首字就快二是设置合理的超时和兜底文案宁可先说一句我看看也不要让群里干等。2. 账号、权限与环境准备这一节全是体力活但每一步都不能跳。我见过太多人在这一步偷懒后面排查问题时多花几倍时间。2.1 开放平台侧创建机器人并拿到凭据流程大致是用开发者身份在开放平台创建应用 → 选择机器人类型 → 填写应用基本信息 → 在能力配置里勾选需要的场景群聊是重点→ 提交审核 → 审核通过后拿到 AppID 和密钥。几个实操细节值钱第一应用名称和介绍认真写。这不是形式主义审核人员判断你要做什么主要看这两段文字。写测试或者留空的被打回的概率很高一来一回就是好几天。第二权限按最小必要申请。你只需要群 消息就别把私聊、频道、表情表态全勾上。权限越多审核问的问题越多而且多出来的权限意味着你要处理更多类型的事件纯属自找麻烦。第三密钥只在服务端保存绝不进代码仓库。这一条我在很多项目里看到被违反后果很严重——密钥泄露意味着任何人都能以你的机器人身份发消息。创建好之后你手上需要有三个东西AppID、AppSecret或者叫密钥/Token具体叫法看平台当前版本的叫法以及机器人被拉进某个群之后的群标识。前两个在应用详情页能看到第三个要等机器人真的进群之后从事件体里拿。注意不同时间点平台的控制台布局会有调整按钮位置可能和我描述的不完全一致但需要填的信息类型是不变的。找不到入口时优先看应用管理能力配置权限管理这几个分区。2.2 服务端环境Python 版本与依赖我推荐 Python 3.10 及以上。理由很实际这个项目重度依赖异步 IO要同时处理多条群消息、同时调模型接口3.10 之后 asyncio 的很多行为更符合直觉而且主流库的新版本基本都不再兼容 3.8。依赖一共就两个核心python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install qq-botpy openaiqq-botpy是官方提供的机器人 SDK封装了连接、鉴权、事件分发。openai这个包不是只能用 OpenAI它是一套通用的客户端实现DeepSeek 的接口与它兼容所以直接拿来用最省事——你不需要自己写 HTTP 请求、重试、超时。依赖装完先别急着写业务跑一个最小连通性测试机器人启动后能连上、能在群里收到一条 消息并打印日志这就说明通道通了。通道不通的情况下写业务代码等于在没通电的房子里装修。2.3 密钥管理一个很多人吃亏的地方密钥管理我只讲一条最实用的做法用环境变量或者独立的配置文件并且把配置文件加进 .gitignore。# .env 文件绝不提交到仓库 DS_APP_ID你的AppID DS_APP_SECRET你的AppSecret DEEPSEEK_API_KEY你的模型密钥import os from dotenv import load_dotenv load_dotenv() APP_ID os.environ[DS_APP_ID] APP_SECRET os.environ[DS_APP_SECRET] DEEPSEEK_KEY os.environ[DEEPSEEK_API_KEY]为什么值得单独开一小节讲这个因为密钥泄露是那种发生一次就没法挽回的问题。密钥进了公开仓库即使你五分钟后就删掉历史提交里还在扫描机器人几秒钟就能捞走。轻则额度被刷光重则机器人被拿去发垃圾消息你的应用直接被封。这种事没有补救手段只能预防。另外建议给模型密钥设置额度上限。大部分平台都支持给单个密钥设置消费上限或告警阈值配上去等于给自己装了个保险丝。3. DeepSeek API 的调用细节不只是换个地址很多人以为接口兼容就等于改个 base_url 就完事实测下来这个认知会让你踩坑。兼容的是请求结构不兼容的是模型特性、参数支持和返回字段的细节。3.1 客户端初始化与参数逐项拆解初始化很简单from openai import OpenAI client OpenAI( api_keyDEEPSEEK_KEY, base_urlhttps://api.deepseek.com, timeout60.0, max_retries2, )base_url写https://api.deepseek.com就行客户端会自动拼接后面的路径。timeout设 60 秒看起来很长但这是给整个请求的上限实际业务里我们会在外层再加一层更短的超时控制——因为群聊场景等不了 60 秒。max_retries设 2 次是为了应对偶发的网络抖动和服务端 5xx但要注意重试只对幂等场景安全这里每次调用都是独立的对话请求重试不会产生副作用所以可以开。真正需要逐项想清楚的是这几个参数参数建议值群聊场景为什么这么设model通用对话模型群聊要的是快和稳不是深度推理temperature0.7 左右太低回答呆板太高容易跑题、编造max_tokens400 ~ 800群里没人看长文且输出直接决定成本top_p保持默认和 temperature 同时调容易失控选一个调streamFalse初期平台侧消息是整条发送的流式收益有限temperature这个参数我建议别一上来就调到 1.0 以上。群里聊天用户期待的是像个正常人回答不是给我十个创意方案。0.7 是一个比较稳的位置有变化但不飘。如果你做的是创意类场景起名、写文案再往上调。max_tokens直接和钱挂钩也和体验挂钩。我一开始设了 2000结果机器人动不动甩出一篇小作文群里没人看完还特别慢。后来压到 500反而好用了——倒逼我在系统提示词里明确要求回答控制在 200 字以内。stream这块要多说一句。非流式拿到的是一条完整回复简单直接流式的优势是首字快但群聊场景里你没法像网页那样逐字往外冒平台的消息接口是按整条内容发的。所以流式在群聊里的实际收益很小除非你在做先发一条占位消息、再编辑更新的玩法那个复杂度会翻好几倍不建议初期做。3.2 系统提示词决定输出质量的那 200 个字我见过太多人把系统提示词写成你是一个有用的助手。这句话几乎没有任何约束力模型会按自己的默认风格回答——往往又长又端着群里看着特别出戏。我的写法是把要求拆成四类身份、边界、格式、风格。SYSTEM_PROMPT 你在一个技术交流群里担任助手。 规则 1. 回答控制在 200 字以内能用一句话说清就不要展开。 2. 不要使用很高兴为您解答希望对您有帮助这类客套话。 3. 不确定的事情直接说不确定不要编造细节、版本号、数字。 4. 涉及具体操作时用短步骤列出不要写成大段散文。 5. 如果问题超出你的知识范围说明原因并建议用户换个问法。 这五条每一条都是踩坑换来的。第二条是因为模型天生爱客套群聊里显得啰嗦第三条最重要因为群里传播快一个编造的版本号可能被转十次第四条是因为群消息展示空间有限大段文字看着累第五条是为了给用户一个明确的失败反馈而不是让模型硬编。3.3 上下文管理让那它多少钱能被听懂单轮问答没什么难度难的是多轮。群里有人说这个库怎么装机器人回答了接着另一个人说那它支持 3.10 吗——这里的它指的是上一轮提到的库。如果每次调用都只发当前这一句模型完全不知道它是什么。所以必须存历史。但存多少是个技术活。我的做法是三层截断第一层按轮数截断。每个群保留最近 6 轮问答12 条 message。超过就丢最早的。6 轮大概能覆盖大部分连续追问场景。第二层按 token 截断。从最新往回累加估算总 token 数超过 3000 就停止加入更早的历史。这一步比按轮数更靠谱因为有些问题本身就很长。第三层按时间过期。超过 30 分钟没有新消息的会话直接清掉。为什么按时间也按因为群里的话题是跳跃的两小时前的对话拿来当上下文八成是干扰。数据结构上用字典就行key 用群标识value 存消息列表和最后活跃时间import time from collections import OrderedDict class SessionStore: def __init__(self, max_turns6, ttl1800, max_chars3000): self.store OrderedDict() self.max_turns max_turns self.ttl ttl self.max_chars max_chars def get(self, key): item self.store.get(key) if not item: return [] if time.time() - item[ts] self.ttl: self.store.pop(key, None) return [] return item[messages] def append(self, key, role, content): item self.store.setdefault(key, {messages: [], ts: time.time()}) item[messages].append({role: role, content: content}) item[ts] time.time() # 按轮数截断 if len(item[messages]) self.max_turns * 2: item[messages] item[messages][-self.max_turns * 2:] # 按字符数截断粗略 token 代理 while sum(len(m[content]) for m in item[messages]) self.max_chars: item[messages].pop(0)这里有个细节值得说我用字符数当 token 的代理指标。不精确但足够快省掉了调用分词器的开销。中文场景下字符数乘以 0.8 大概接近 token 数作为一个防御性的上限完全够用。注意历史消息一定要区分群和群成员。有些场景下你可能想让机器人记住张三说过什么那 key 就要设计成群 人的组合。但要注意跨群共享上下文会带来隐私和串话问题别为了聪明把不同群的对话混在一起。3.4 异常处理模型接口不是永远可用的这一段是我认为最容易被省略、但上线后最需要的部分。模型接口可能返回的错误类型大致有鉴权失败密钥错或过期、限流请求太密、服务端错误5xx、超时、内容被安全策略拦截。每一种的处理方式都不同。import logging from openai import APIError, APITimeoutError, RateLimitError, AuthenticationError logger logging.getLogger(__name__) def ask_model(messages, max_retries2): for attempt in range(max_retries 1): try: resp client.chat.completions.create( modeldeepseek-chat, messagesmessages, temperature0.7, max_tokens600, timeout20, ) return resp.choices[0].message.content.strip() except AuthenticationError: logger.error(密钥无效请检查配置) return None # 这类错误重试无意义 except RateLimitError: logger.warning(触发限流第 %s 次重试, attempt 1) time.sleep(1.5 * (attempt 1)) except APITimeoutError: logger.warning(请求超时第 %s 次重试, attempt 1) except APIError as e: logger.error(接口异常: %s, e) time.sleep(1) return None关键点在于区分可重试和不可重试。鉴权失败重试一百次也没用只会浪费时间限流需要退避而且要带上递增延迟超时可以直接重试一次。返回 None 的时候上层要有兜底文案绝不能把异常栈直接抛到群里。4. 机器人骨架实现从事件到回复这一节是主体工程我会按事件入口、路由、调用、回复的顺序拆每一段都能直接拿来用。4.1 启动与事件订阅用官方 SDK 的写法大致是这样import botpy from botpy.message import GroupMessage class GroupBot(botpy.Client): async def on_ready(self): logger.info(机器人已上线: %s, self.robot.name) async def on_group_at_message_create(self, message: GroupMessage): await handle_group_message(self, message) intents botpy.Intents(public_messagesTrue) bot GroupBot(intentsintents) bot.run(appidAPP_ID, secretAPP_SECRET)几个注意点。Intents里开了哪些开关决定你能收到哪类事件开多了会收到无关事件开少了收不到你要的。on_group_at_message_create这个回调名是固定的对应群里有人 机器人这个事件写错一个字母就永远不触发——这是新手最常见的代码没错但没反应的原因。on_ready里打印机器人名字是一个很实用的自检手段。启动日志里能看到名字说明鉴权和连接都成功了看不到说明问题在网络或凭据层。4.2 消息解析与路由判断该不该理事件对象里最关键的几个字段消息内容、群标识、发送者标识、消息 ID。不同版本 SDK 的字段名可能有细微差异用之前先打印一次完整的事件体看清楚结构再写业务代码。async def handle_group_message(client, message): raw (message.content or ).strip() group_id message.group_openid user_id message.author.member_openid msg_id message.id # 去掉 机器人本身残留的部分 text clean_at(raw) if not text: await reply(client, message, 有什么想问的直接 我并输入问题就行。) return # 指令分支 if text in (重置, 清空, /reset): store.store.pop(group_id, None) await reply(client, message, 本群上下文已清空。) return if text in (帮助, /help): await reply(client, message, 支持我提问发送「重置」清空上下文。) return # 进入模型分支 await call_and_reply(client, message, group_id, user_id, text)clean_at这个函数看着不起眼但很有必要。平台推过来的内容里 的部分可能以不同形式残留不去掉的话会进入模型影响理解甚至干扰输出。路由里要有显式的指令分支。重置和帮助这两个指令成本极低但价值极高前者让用户能自己解决上下文污染问题后者让新进群的人知道怎么用。我一开始没做重置结果有人在群里东拉西扯半小时之后开始问正经问题模型被前面的闲聊带偏答得莫名其妙用户还以为是机器人不行。4.3 调用与回复串起完整链路async def call_and_reply(client, message, group_id, user_id, text): history store.get(group_id) messages [{role: system, content: SYSTEM_PROMPT}] messages.extend(history) messages.append({role: user, content: text}) # 模型调用是阻塞 IO扔到线程池避免卡住事件循环 loop asyncio.get_running_loop() answer await loop.run_in_executor(None, ask_model, messages) if not answer: await reply(client, message, 我这边暂时没响应上来稍后再试一次。) return answer trim_answer(answer) store.append(group_id, user, text) store.append(group_id, assistant, answer) await reply(client, message, answer)这里有一个非常关键但极易被忽略的点模型调用是同步阻塞的而机器人框架跑在异步事件循环上。如果你直接ask_model(messages)而不丢进线程池那么每一次模型调用期间整个机器人对所有其他群的消息都会失去响应。表现就是一个群问问题其他群全部卡住。这个坑我在早期项目里踩过症状特别迷惑——单群测试毫无问题一进多群就现原形。run_in_executor把阻塞调用挪到线程池事件循环立刻释放出来处理下一条消息。线程池默认大小有限如果你预期并发很高可以显式指定ThreadPoolExecutor。trim_answer负责把超长回复截断。做法很简单超过 600 字就截到最后一个句号末尾加一句内容较长已截断。群里没人愿意看滚动三屏的长文。4.4 限流与并发控制防止一个人把机器人打爆群里一定会有那种连续发五六条消息的人也一定会有人闲着没事反复 机器人。没有防护的情况下这些请求会直接打到模型接口上轻则触发限流导致所有人都用不了重则额度被瞬间刷完。我加了两层限流都很简单import time class RateLimiter: def __init__(self, per_user5, window60, per_group20): self.per_user per_user self.window window self.per_group per_group self.user_log {} self.group_log {} def allow(self, user_id, group_id): now time.time() uk user_id gk group_id self.user_log.setdefault(uk, []) self.group_log.setdefault(gk, []) self.user_log[uk] [t for t in self.user_log[uk] if now - t self.window] self.group_log[gk] [t for t in self.group_log[gk] if now - t self.window] if len(self.user_log[uk]) self.per_user: return False, 你问得有点快歇一分钟再来。 if len(self.group_log[gk]) self.per_group: return False, 本群今天太活跃了稍缓一下。 self.user_log[uk].append(now) self.group_log[gk].append(now) return True, None两层限制的意义不同按人限防的是刷屏按群限防的是某个群占用全部配额。只做按人限的话一个 200 人的群同时提问照样能把接口打满。只做按群限的话一个人刷屏就能拖垮整个群。除了限流还有一个单群串行队列的设计。同一个群的消息应该按顺序处理否则用户问A 是什么、机器人还没答完又问那 B 呢两条请求并发出去回复顺序可能是反的群里的对话就乱了。做法是给每个群维护一个 asyncio 队列串行处理。这个复杂度比并发高一点但群聊场景里顺序感很重要。4.5 群聊体验的细节打磨技术通了之后决定好不好用的是这些细节回复方式的选择。被动回复针对某条消息回和主动发消息是两套接口。被动回复最稳额度充足主动推送通常有严格的频次限制。所以设计上要尽量让所有输出都挂在用户 我这个触发上不要设计机器人自己冒出来说话的玩法那种在群聊里既费额度又招人烦。空白与分段。模型有时候会给一段连续文字读起来很累。可以在回复前做一次轻量处理超过三句的句子之间插换行。这个改动看着微小实际感受差异很大。称呼的处理。群聊里用你就够了不要用您。前者是平辈交流后者在群里显得生硬。失败也要有回应。超时、限流、异常都要给一句人话而不是静默。用户看到暂未响应会再试一次看不到任何反应只会觉得机器人坏了。5. 部署、监控与长期维护跑通 demo 和长期稳定运行之间隔着这一节的全部内容。5.1 部署方式从小机器起步资源需求其实很低这个服务的主要消耗是网络 IO 和内存CPU 几乎闲着。1 核 1G 的机器跑几十个群的日常对话绰绰有余即使上到几百个群2 核 2G 也够。内存占用的大头是 Python 运行时加依赖大概 150 到 250 MB。部署首选进程守护。无论是用 systemd 还是容器编排核心诉求是一致的进程挂了能自动拉起来日志能落盘启动参数能版本化。我倾向于用 systemd配置简单、日志直接进 journald排查问题方便。[Unit] DescriptionGroup AI Bot Afternetwork-online.target [Service] Typesimple WorkingDirectory/opt/aibot EnvironmentFile/opt/aibot/.env ExecStart/opt/aibot/venv/bin/python main.py Restartalways RestartSec5 StandardOutputjournal StandardErrorjournal [Install] WantedBymulti-user.targetRestartalways加上RestartSec5是这套配置的灵魂。长连接服务偶发断线是正常现象SDK 内部通常有重连逻辑但进程级崩溃比如内存溢出、未捕获异常就需要外部兜底。5 秒的重启延迟是为了避免疯狂重启打爆日志。千万不要用nohup python main.py 这种跑法上线。SSH 一断、机器一重启服务就没了而且你自己可能好几天都不知道。注意环境变量文件里放着密钥权限设成 600只有服务运行用户可以读。同一台机器上的其他用户不应该能看到它。5.2 日志与监控出问题时你要能查到日志我分成三类格式和用途都不同启动与连接日志记录机器人上线、断线、重连。这类日志量小但出问题时是第一手线索。业务日志每条消息进来记一行群标识后四位、用户标识后四位、输入长度、是否命中限流、处理耗时。不要记录完整内容涉及群里其他人的隐私也不要记录完整标识做个脱敏。错误日志带上异常类型和请求上下文不包含密钥。这类日志要能一眼看出是鉴权问题、限流问题还是网络问题。logger.info( group%s user%s in_len%d cost%.2fs status%s, group_id[-4:], user_id[-4:], len(text), cost, status )监控上初期不需要复杂的指标系统看三个数就够每小时请求量、平均响应耗时、错误率。请求量突增说明有人在刷耗时上升说明模型侧压力大错误率上升通常是密钥或限流的问题。这三个数每天扫一眼大部分问题能在变严重之前发现。5.3 灰度与回滚改提示词也要有节奏这一条可能有点超出预期但确实重要提示词和参数改动要有版本记录并且能被快速回滚。原因很实际。你把温度从 0.7 调到 1.0可能某些群立刻变得啰嗦用户抱怨你把系统提示词改得更简短可能某些类型的提问开始答不全。这类问题不是 bug但影响一样大。如果改动是直接改代码然后重启回滚就要再改一次代码再重启中间可能已经过去半小时。我的做法是把提示词和关键参数抽到一个独立的配置文件里每次改动记一条带日期的注释。回滚就是改回上一行、重启三十秒完成。这个习惯我从第二个项目开始坚持到现在救过好几次场。灰度上如果群多可以按群标识尾号做分批切换先放 10% 的群用新配置观察半天没问题再全量。群少的话这步可以省但版本记录一定要留。6. 常见问题排查实录下面这些坑每一条都是真实花掉时间换来的。6.1 问题速查表现象大概率原因处理方式启动无报错但收不到任何消息事件回调名拼错或权限未申请核对回调函数名检查开放平台权限状态机器人只在部分群有反应该群未完成配置或在灰度范围内检查各群的机器人状态与权限生效时间单群正常多群互相卡住模型调用阻塞了事件循环用线程池执行同步调用回复内容为空或只有符号max_tokens 太小或被截断提高上限检查 trim 逻辑偶发回复超时网络抖动或模型侧波动加超时与重试准备兜底文案群里出现重复回复重试逻辑导致重复发送用消息 ID 做幂等去重上下文明显串了会话 key 设计错误跨群共享用群标识 用户标识组合做 key限额很快被刷完无限流或限流阈值过高按人、按群双层限流表格里重复回复这一条值得单独说。它的成因是模型调用超时后重试第一次的请求实际上成功了只是响应回得慢于是群里收到了两条一样的回复。解决方式是给每条进来的消息做一个处理标记同一个消息 ID 只发送一次。这个去重表用内存字典加过期清理就行不需要持久化。6.2 几个反直觉的坑坑一以为 token 越多回答越好。一开始我把历史设成 20 轮想着记得多就聪明。实测下来完全是反效果输入变长首字延迟从 1 秒多涨到 4 秒而且过期的历史会误导模型——十分钟前在聊 A 库现在问 B 库的问题模型被前面带偏。压到 6 轮之后回答质量和速度同时变好了。上下文不是越多越好是越相关越好。坑二以为限流是别人的问题。我一直觉得自己的群不会有人刷屏结果上线第三天就遇到有人连续 了二十多次。没有限流的那半天其他群的回复全部变慢还有几条直接超时。教训是限流不是防恶意用户是保护正常用户的体验。坑三以为提示词写一次就完事。实际上提示词是需要持续调整的。上线两周后我整理了一下群里的真实提问发现相当一部分是这个报错什么意思于是专门在系统提示词里加了一条遇到报错贴文时先指出错误关键词再给一句原因。这条改动带来的满意度提升比我把模型参数调十遍都大。坑四忘了处理空消息和特殊字符。有人 机器人之后什么也没发有人发一串表情有人发纯链接。这些如果不拦截全部会进模型浪费额度还得不到有用回复。入口处做一次校验去空白后长度为 0、或者全是符号没有文字内容的直接走固定文案不要调模型。坑五把日志写成内容快照。我早期图省事把每条对话完整写进日志方便回看。后来意识到这在群里是个隐私问题——日志服务器上的任何人都能看到群里的所有对话。改成只记录长度和状态后排查问题依然够用。6.3 我个人的几个使用体会段落式的建议不写讲三个具体做法。第一给机器人一个能力边界的自述。在系统提示词里明确写清它能做什么、不做什么比如你不提供实时行情、不查询个人数据。用户在群里问这类问题机器人会直接说做不到而不是硬编。这个改动大幅减少了误导性回答。第二准备一套兜底话术但别太机械。我准备了三句随机取用我这边没响应上来稍等下再问我一次、这个我没处理好换个说法试试、刚才走神了再说一遍。比固定的服务异常请稍后重试自然得多群里不会觉得在跟客服机器人说话。第三定期回看真实提问。每隔一两周把脱敏后的提问样本看一遍你会发现自己对用户到底怎么用这个东西的想象和现实差得很远。我最初以为大家会问技术问题实际上最多的是帮我看看这段话怎么改和这个报错是什么意思。这两个方向的提示词我都是后期才补上的。整个系统跑顺之后你会发现真正花时间的不是写代码而是这些持续的小调整。代码大概两天写完后面两周全在调提示词、调上下文、调限流阈值。这个比例很正常也说明一件事把模型接进群聊技术接入只是起点让它用起来舒服才是主要工作量。