我们最早那个版本其实算不上一个真正的 AI 助手。它是一个挺标准的 AI 获客工具——输入产品介绍自动生成客户画像、销售话术、批量打招呼内容。上线第一周数据不错注册量涨得很快但第二周我就开始慌用户的会话时长极短打开一次生成完东西就走没有人回来。这个现象逼着我们去回答一个问题用户缺的到底是一次性生成答案的功能还是缺一个可以长期停留的 AI 交互层带着这个问题我们把这个项目整个推翻重写成一个开源的 Web AI 助手。核心理念不再是一个页面而是一个连接用户、知识库、工具链和数据系统的交互层。下面我会把从获客工具到交互层重写过程中的思考、选型、代码和踩坑记录都摊开讲涉及 AI 助手、Web、开源、交互层四件事的完整落地路径。适合正在纠结要不要从单点 AI 功能升级成平台型 AI 助手、或者想在企业内部落地本地知识库助手的团队参考。1. 重写的起点为什么一个 AI 获客工具不够用了1.1 获客工具做了一个一次性的伪需求AI 获客工具的本质是把大模型当成一个高级文案生成器来用。前端收集产品资料后端拼 Prompt调一次大模型接口吐出一段客户分层、几句开场白、一封开发信模板。技术实现很简单但产品上有一个致命缺陷用户用完即走。我当时统计过后台行为数据超过七成的新用户当天只发起一到两次会话之后就不再回来了。为什么会这样因为获客工具把价值藏在了结果里而结果是一次性消费的。用户拿到 20 条销售话术之后他没有任何理由再打开你的页面。更麻烦的是这些结果没有上下文关联。他昨天已经让工具调过一次客户画像今天想继续优化系统完全不记得他生成了一条很有效的开场白想把它沉淀到团队的素材库里做不到。这套逻辑放在早几年可能还行但企业客户越来越聪明他们真正要的不是一两个AI 生成内容的功能页面而是一个能嵌进自己业务流程和知识库的 AI 助手。获客工具做得再好也只是把 AI 能力做成了一次性道具没有沉淀没有记忆没有权限体系更没办法和企业现有的 CRM、工单系统、知识库打通。这就是我们要重写的第一个理由产品形态已经跟不上需求了。1.2 重写不是重做功能而是重构产品形态想清楚这个问题后我们没有在原有代码基础上打补丁而是把产品定位从AI 获客工具改成Web AI 交互层。什么叫交互层简单说它就是用户和你的系统之间那层持续的智能会话入口。就像浏览器之于互联网用户访问的不是某个网页的打开结果而是希望浏览器能随时带他去任何地方。在 AI 助手这个场景里交互层意味着这么几件事所有交互都发生在同一条对话流里而不是散落在一个个孤立页面AI 能记住你是谁、你之前聊过什么、你的搜索习惯AI 不只是聊天它还能调用工具去查知识库、创建工单、查询数据库然后把结果带回来继续对话企业内部还要考虑权限不是所有人都能看所有知识最后为了保证数据可控整个系统必须可以本地部署代码开源而不是被绑定在一个闭源平台上。我把两种形态的差异整理成了一张对比表每次和团队讨论都会拿出来看对比维度单页 AI 获客工具Web AI 交互层用户生命周期用完即走会话短持续对话可长留存上下文记忆单次请求无记忆跨会话、长短期记忆数据流生成结果即结束结果流入 CRM/工单/知识库扩展性页面级功能扩展工具调用、插件机制、API 开放权限控制基本没有按用户、角色、部门控制数据可见性部署方式只能在云端跑支持内网、私有化、本地模型这张表也成了我们重写时的需求清单。核心目标很明确把这个产品做成一个让用户每天都愿意回来的 Web AI 交互层而不是一个用完就丢的获客工具。2. 技术选型先想清楚为什么再动键盘2.1 为什么一定要开源而且要坚持开源有人问你们内部做一个私有的 AI 助手不是更省事吗为什么要开源这里有一个很现实的商业逻辑企业客户对 AI 助手的最大顾虑就是数据安全。对话记录往往带着客户资料、内部方案、业务数据没有哪家企业敢随随便便把它发给第三方平台。开源意味着客户可以自己部署可以审代码可以对接自己的本地模型数据完全不出内网。从我们团队自己的角度讲开源也不是做慈善而是一种借力。真正的开源项目管理并不是把代码丢到仓库里就完了它逼着我们把文档写清楚、把架构讲明白、把接口做稳定。没有文档和社区的开源项目跟晒代码没区别过三个月连自己都看不懂。另外开源还能吸引外部贡献者尤其是安全方向的反馈这一点在后面我会详细讲。当然开源不是免费的代名词。它的意思是把定制权交还给用户。很多团队拿我们的代码去改接入自己的企业知识库助手甚至换掉底层模型这恰恰是我们希望看到的结果。2.2 为什么选 Web 而不是原生客户端交互层的第一载体我们几乎没有犹豫就选了 Web。理由很直接跨平台、免安装、好嵌入。企业里用户分布在 Windows、macOS、Linux 甚至移动设备上你不可能要求所有人都装一个原生客户端但一个浏览器地址栏谁都能打开。Web 前端和后端的方案我们也比较过。后端最初在 Flask 和 FastAPI 之间纠结最后选了 FastAPI。原因有三一是原生异步面对流式输出和多路请求时表现稳定二是自动生成 OpenAPI 文档前端对接接口省掉大量沟通成本三是类型校验顺手参数错了能直接返回可读错误不需要我们写一堆 if else。前端用了 React组件生态成熟WebSocket 和状态管理都能找到现成方案。整体架构用文字概括就是浏览器端 React 应用通过 HTTP/WebSocket 访问网关层网关层再把请求分发给会话服务、模型网关、知识库检索和各个工具服务。模型网关做成统一接口上游可以接 OpenAI 兼容的云端服务也可以接本地部署的 Ollama、vLLM 等推理服务。这样切模型不影响业务代码这是企业 AI 助手能够落地的一个关键前提。2.3 本地模型接入的企业级实践现在大家聊 AI 助手已经默认要支持本地模型了。企业内网或者数据敏感场景根本不可能把对话抛给外部 API本地化推理是刚需。我们重写时做了一个模型网关层统一暴露 OpenAI 兼容的/v1/chat/completions接口上游默认接到 Ollama 本地服务。这个设计最大的好处是上层业务代码只需要对接一套协议下游模型随便换。模型从 Llama 换成 Qwen从 Ollama 换成 vLLM网关层改一行配置就行不用动会话管理和工具调用的逻辑。# app/gateway.py 节选 from fastapi import FastAPI, HTTPException, Request import httpx app FastAPI() UPSTREAM http://127.0.0.1:11434/v1 # Ollama 的 OpenAI 兼容端点 app.post(/v1/chat/completions) async def chat_completions(request: Request): payload await request.json() # 注入系统提示词防止前端绕过角色设定 payload.setdefault(messages, []) payload[messages].insert(0, { role: system, content: 你是企业内部知识库 AI 助手只依据可访问的文档回答不确定时直接说明不知道。 }) async with httpx.AsyncClient(timeout120) as client: resp await client.post(f{UPSTREAM}/chat/completions, jsonpayload) if resp.status_code ! 200: raise HTTPException(status_code502, detail模型服务异常) return resp.json()注意这个代码里有个细节系统提示词是在网关层注入的而不是让前端传进来。为什么要这样做因为前端是可以被篡改的如果系统提示词由前端控制用户完全可以绕过你的角色设定让助手说一些不该说的话。网关层强制注入系统提示词是 AI 助手安全的第一道防线。3. 重写过程的核心细节与实操要点3.1 会话上下文管理别让你的 AI 变成金鱼AI 助手和普通对话页面最大的区别就是它必须记得住事。我们在重写时把会话数据单独建了一套表设计得尽量简单方便后面迁移到 PostgreSQL。CREATE TABLE conversations ( id TEXT PRIMARY KEY, user_id TEXT NOT NULL, title TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE messages ( id INTEGER PRIMARY KEY AUTOINCREMENT, conversation_id TEXT NOT NULL REFERENCES conversations(id), role TEXT NOT NULL CHECK(role IN (user, assistant, system, tool)), content TEXT NOT NULL, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP );这里有个容易踩坑的地方上下文不能无限往模型里塞。对话越长Token 消耗越大响应越慢而且很多模型对超过窗口的内容会直接报错。我们参考常见方案做了一个截断策略保留系统提示词和最近 N 轮对话超出窗口的早期内容用上一轮的总结替代工具调用结果只保留关键字段避免把一整个知识库片段灌进历史。简化的实现思路大致是这样def truncate_messages(messages, max_tokens6000): # 保留系统提示词 system_messages [m for m in messages if m[role] system] others [m for m in messages if m[role] ! system] # 从后往前截断始终保留最近的上下文 candidates [] total sum(len(m[content]) for m in system_messages) for m in reversed(others): if total len(m[content]) max_tokens: break candidates.insert(0, m) total len(m[content]) return system_messages candidates这个方案实测下来比较稳但它不解决长期记忆的问题。想记住用户跨会话的偏好还是得把关键信息单独抽出来存比如用户画像表、偏好表然后在对话开始时动态注入提示词。这个就属于进阶功能了重做项目时不建议第一版就上先跑通核心链路更重要。3.2 工具调用与意图路由让 AI 从会聊变成会干活重写时我们做了一个很重要的决定不让大模型天生拥有执行能力而是给它一套明确的工具清单它只能通过函数调用去触碰外部系统。这样 AI 就被限制在理解意图、选择合适的工具、组织结果这层真正的写库、发请求、删数据仍然由我们的代码控制。一个工具的定义长这样{ type: function, function: { name: search_kb, description: 检索企业知识库返回相关文档片段, parameters: { type: object, properties: { query: { type: string }, top_k: { type: integer, default: 5 } }, required: [query] } } }模型如果判断用户想查知识库就会返回一个结构化请求而不是直接输出一段话。我们的后端解析这个请求执行对应工具再把结果塞回对话上下文。这样做的好处很多工具白名单可控不会让模型乱调接口每个工具都可以单独加鉴权出了问题可以定位到具体是哪一步执行失败。实操中还有一个很容易忽略的坑工具调用必须有最大步数和超时控制。如果不加限制Agent 可能会在两个工具之间来回猜测甚至陷入死循环。我们是这么写的max_tool_calls 5 tool_history [] for step in range(max_tool_calls): if not need_tool_call(response): break tool_result execute_tool(response) tool_history.append({tool: response.tool_call, result: tool_result}) response call_model_with_tool_history(prompt, tool_history) else: return 抱歉这个问题处理起来太复杂了请稍后再试。给模型一个明确的步数上限而不是让它无限运行这是所有 Agent 类产品稳定性的底线。3.3 权限过滤与多租户AI 再聪明也不能越权企业知识库助手里最容易被忽略但又最要命的问题是权限。用户输入一个问题如果知识库检索不过滤文档权限AI 就可能把其他部门的人事制度、薪资策略当作参考内容答出来这就是一次安全事故。我们做的方案其实不复杂每篇知识文档带一个visible_to字段记录哪些角色和部门能看到。检索前先把用户可见的文档集合过滤出来再交给向量检索和模型生成。def allowed_docs(user): scopes set(user.roles) | set(user.departments) return [doc for doc in kb_docs if set(doc.visible_to) scopes]这里要注意权限过滤必须放在检索前不能检索完再过滤。如果检索阶段就把不该看的文档向量拉出来了哪怕模型最后没有引用中间链路也存在泄露风险。另外所有工具调用都应该带上发起人身份后端在工具侧再做一次二次校验。AI 助手只是执行层权限判定的最终解释权必须握在我们自己的服务里。4. 项目上线后遇到的几个头疼问题实操排查实录4.1 Service Worker 注册失败的 InvalidStateError重写时我们给 Web 前端加了 PWA 能力想着离线时也能看历史会话。本地开发一切正常但部署到客户内网后控制台一直报错could not register service worker: InvalidStateError。排查到最后才发现Service Worker 要求页面必须在安全上下文里运行。本地 localhost 被浏览器视为安全来源但内网 HTTP 地址不是。客户内网没有上 HTTPS所以 Service Worker 注册直接被浏览器拒绝。解决办法是注册前先判断协议if (serviceWorker in navigator) { if (location.protocol https: || location.hostname localhost || location.hostname 127.0.0.1) { navigator.serviceWorker.register(/sw.js).catch((err) { console.error(SW 注册失败:, err); }); } else { console.warn(非 HTTPS 环境跳过 Service Worker 注册); } }如果你的内网场景确实需要离线能力建议用 mkcert 或者内部 CA 把 HTTPS 配上。没有证书的情况下不如直接把 PWA 去掉用浏览器普通缓存代替硬上 Service Worker 只会带来排查成本的负担。4.2 Web 视图加载出错与 CLI 自动打开浏览器失败我们的项目配套了一个运维命令行工具名字就叫dsh。它有一个dsh web子命令作用是启动一个本地 Web 面板来管理会话和模型参数。这个功能在开发机上很好用但在远程服务器上经常报错。典型的报错是opening the default browser; pass --no-open to disable。原因是服务器没有桌面环境代码里却调用了open/start去打开浏览器直接失败。还有一次更隐蔽报的是authentication required; reopen the url printed by dsh web因为我们给面板加了一个一次性 Token 认证但用户看到的 URL 是旧的没有带上 Token。解决方案很直接给命令行加--no-open参数默认不主动开浏览器只打印 URL认证信息放进 URL 参数并明确提示用户复制重新打开。如果你的产品也带 CLI 和 Web 面板这个教训值得提前踩永远不要假设你的 CLI 运行在有浏览器、有图形界面的机器上。4.3 WebSocket 断线导致流式回复丢一半AI 助手的交互要顺滑流式输出必不可少。我们最初用的是 WebSocket体验很好但上线后发现在网络不稳的环境下WebSocket 连接频繁断开用户只看到回复的一半另一半永远不来了。后来我们做了一层断线重连和消息补偿。前端在收到最后一条完整消息之前如果连接断了重连后主动向后端请求从某条消息 ID 开始补拉内容。代码核心就是重连时用last_received_id做续传let ws null; let retry 0; function connectWS() { ws new WebSocket(${location.protocol https: ? wss : ws}://${location.host}/ws/chat); ws.onopen () { retry 0; }; ws.onclose () { retry Math.min(retry 1, 10); setTimeout(connectWS, 1000 * retry); }; ws.onmessage (event) { const msg JSON.parse(event.data); renderMessage(msg); lastReceivedId msg.id; }; }如果项目对实时性要求没那么高也可以直接换成 SSE服务端单向推送天然支持断线重试实现更简单。目前新项目我们优先推荐 SSE除非需要双向控制类功能才上 WebSocket。4.4 公网部署之前安全功夫要补齐有一段时间我们把演示环境放到了公网结果第二天就被人刷了几千次接口差点把模型服务打挂了。复盘下来是我们没做好最基础的安全防护。现在我们的 Web 服务器固定有这几道配置第一CORS 必须明确允许的域名列表不能简单用*第二所有会话接口必须带 Token第三对所有请求做频率限制尤其是模型生成接口因为一次生成成本高恶意刷的话财务和算力都会很痛第四输入内容要做长度校验防止有人把整本书塞进 Prompt 触发超时。说到安全我们后来还遇到一个有意思的贡献者他是研究 CTF Web 解题的喜欢在各种比赛里找 Flag。他用那套思路来测我们的 AI 助手还真帮忙找到了一个越权漏洞普通用户可以通过伪造conversation_id读到别人的会话记录。后来我们给所有会话操作都加了只能操作当前登录用户自己的会话的强制校验这个坑才算填上。做 Web AI 交互层安全测试不能用常规思路得有对抗思维。5. 开源之后如何让项目真正活起来5.1 文档、README 和第一印象项目开源的第一个月star 涨得并不快真正让我们意识到问题的是有人提 issue 说按 README 装了三遍都没跑起来。我们仔细看README 里只写了安装命令没写 Python 版本要求也没说明依赖下载需要配置镜像源。后来我们花了整整一周重写文档。README 必须包含项目能干什么给第一次来的访客看、快速开始给赶时间的人看、架构原理给想改代码的人看、Roadmap给想参与贡献的人看。同时补了 CONTRIBUTING 文档和 issue 模板把 bug、feature request、question 分开避免所有问题都堆在同一个 issue 列表里。这里特别提一句开源镜像站。国内开发者在部署依赖时直接从默认源拉包经常很慢我们就在安装文档里写了一段建议配置让用户把 PyPI 和 npm 的 registry 切换到国内开源镜像。就这一个改动后台数据显示安装失败率直接降了一半。开源项目能不能顺利落地往往不是功能不够而是交付体验太差。5.2 社区运营和生态接入开源项目要活起来不能靠一个人写代码得靠社区一起推。我们的做法是建首批 good first issue专门挑那种改动小、说明清晰、适合新人的任务比如补语言包、优化按钮文案、增加单元测试用例。这类任务门槛低比较容易收到第一个 PR。CI 在项目开放第一天就接上了所有 PR 自动跑检查和测试减少维护者重复劳动。生态接入方面我们把重点放在和本地模型、企业知识库的对接上。现在项目支持 Ollama、vLLM 等本地推理服务也支持接入企业内网的向量数据库。很多用户反馈说他们就是冲着本地部署的企业级知识库助手这个场景来的。还有一些团队没有开发人力我们会建议他们先去用扣子这类低代码平台搭一个原型验证流程真到需要私有化和深度集成时再用我们的开源方案做底层。低代码平台解决有没有开源交互层解决能不能按你自己的想法改。项目的 Roadmap 也完全公开。社区反馈最多的需求之一是希望加语音回复能力我们就把开源的 TTS 项目比如 MultiTTS接入排进了计划而不是自己从零写语音合成。开源项目的正确姿势是连接生态不是重复造轮子。6. 重写之后的一些真心话6.1 重写这件事最大的收益是什么如果用一句话总结我觉得是产品思维从做一个功能变成了做一层地基。在只做 AI 获客工具的时候我们每天都在想怎么让 Prompt 更精准、怎么让生成的话术更像人类重写成 Web AI 交互层之后我们想的变成了怎么让用户每天都有理由回到这个对话流里。真实的数据也支撑了这个判断。重写前用户平均会话长度是 3 条消息不到重写后技术人员可以在同一个对话里完成知识库检索、日志查询、工单创建平均会话长度能到 19 条。为什么差这么多因为获客工具只回答怎么写一句话而交互层回答的是怎么帮你做完一整件事。这个价值完全不在同一个量级。6.2 给准备重写同类项目的团队三个建议第一重写之前先把交互层边界画清楚哪些数据可以进来哪些工具能力可以出去第三方系统如何接入。不要一上来就写代码边界不清的 Agent 项目后面接企业知识库时改动成本是几何级增长的。第二模型网关要独立一层不要和业务代码耦合。我们最开始图省事把所有模型调用都写在会话服务里后来换本地模型时改到崩溃。抽出网关层之后换模型就像换一个数据库连接串省掉大量返工。第三开源不是发布那一刻就结束而是项目生命周期的开始。你需要回答的不是代码怎么写而是别人拿到代码之后怎么快速跑起来、怎么改、怎么用。文档维护和代码维护同样重要我甚至建议前期投入一点先把安装和快速开始部分打磨得彻底这比功能列表多一两个亮点更能留住人。最后再分享一个小技巧重写完了别急着对外宣传先让团队内部把它当成日常工具用两周。自己人用得顺的 AI 助手用户大概率也会喜欢自己人都嫌慢嫌笨的工具上线之后只能收获一堆差评。
我们最早那个版本其实算不上一个真正的 AI 助手。它是一个挺标准的 AI 获客工具——输入产品介绍自动生成客户画像、销售话术、批量打招呼内容。上线第一周数据不错注册量涨得很快但第二周我就开始慌用户的会话时长极短打开一次生成完东西就走没有人回来。这个现象逼着我们去回答一个问题用户缺的到底是一次性生成答案的功能还是缺一个可以长期停留的 AI 交互层带着这个问题我们把这个项目整个推翻重写成一个开源的 Web AI 助手。核心理念不再是一个页面而是一个连接用户、知识库、工具链和数据系统的交互层。下面我会把从获客工具到交互层重写过程中的思考、选型、代码和踩坑记录都摊开讲涉及 AI 助手、Web、开源、交互层四件事的完整落地路径。适合正在纠结要不要从单点 AI 功能升级成平台型 AI 助手、或者想在企业内部落地本地知识库助手的团队参考。1. 重写的起点为什么一个 AI 获客工具不够用了1.1 获客工具做了一个一次性的伪需求AI 获客工具的本质是把大模型当成一个高级文案生成器来用。前端收集产品资料后端拼 Prompt调一次大模型接口吐出一段客户分层、几句开场白、一封开发信模板。技术实现很简单但产品上有一个致命缺陷用户用完即走。我当时统计过后台行为数据超过七成的新用户当天只发起一到两次会话之后就不再回来了。为什么会这样因为获客工具把价值藏在了结果里而结果是一次性消费的。用户拿到 20 条销售话术之后他没有任何理由再打开你的页面。更麻烦的是这些结果没有上下文关联。他昨天已经让工具调过一次客户画像今天想继续优化系统完全不记得他生成了一条很有效的开场白想把它沉淀到团队的素材库里做不到。这套逻辑放在早几年可能还行但企业客户越来越聪明他们真正要的不是一两个AI 生成内容的功能页面而是一个能嵌进自己业务流程和知识库的 AI 助手。获客工具做得再好也只是把 AI 能力做成了一次性道具没有沉淀没有记忆没有权限体系更没办法和企业现有的 CRM、工单系统、知识库打通。这就是我们要重写的第一个理由产品形态已经跟不上需求了。1.2 重写不是重做功能而是重构产品形态想清楚这个问题后我们没有在原有代码基础上打补丁而是把产品定位从AI 获客工具改成Web AI 交互层。什么叫交互层简单说它就是用户和你的系统之间那层持续的智能会话入口。就像浏览器之于互联网用户访问的不是某个网页的打开结果而是希望浏览器能随时带他去任何地方。在 AI 助手这个场景里交互层意味着这么几件事所有交互都发生在同一条对话流里而不是散落在一个个孤立页面AI 能记住你是谁、你之前聊过什么、你的搜索习惯AI 不只是聊天它还能调用工具去查知识库、创建工单、查询数据库然后把结果带回来继续对话企业内部还要考虑权限不是所有人都能看所有知识最后为了保证数据可控整个系统必须可以本地部署代码开源而不是被绑定在一个闭源平台上。我把两种形态的差异整理成了一张对比表每次和团队讨论都会拿出来看对比维度单页 AI 获客工具Web AI 交互层用户生命周期用完即走会话短持续对话可长留存上下文记忆单次请求无记忆跨会话、长短期记忆数据流生成结果即结束结果流入 CRM/工单/知识库扩展性页面级功能扩展工具调用、插件机制、API 开放权限控制基本没有按用户、角色、部门控制数据可见性部署方式只能在云端跑支持内网、私有化、本地模型这张表也成了我们重写时的需求清单。核心目标很明确把这个产品做成一个让用户每天都愿意回来的 Web AI 交互层而不是一个用完就丢的获客工具。2. 技术选型先想清楚为什么再动键盘2.1 为什么一定要开源而且要坚持开源有人问你们内部做一个私有的 AI 助手不是更省事吗为什么要开源这里有一个很现实的商业逻辑企业客户对 AI 助手的最大顾虑就是数据安全。对话记录往往带着客户资料、内部方案、业务数据没有哪家企业敢随随便便把它发给第三方平台。开源意味着客户可以自己部署可以审代码可以对接自己的本地模型数据完全不出内网。从我们团队自己的角度讲开源也不是做慈善而是一种借力。真正的开源项目管理并不是把代码丢到仓库里就完了它逼着我们把文档写清楚、把架构讲明白、把接口做稳定。没有文档和社区的开源项目跟晒代码没区别过三个月连自己都看不懂。另外开源还能吸引外部贡献者尤其是安全方向的反馈这一点在后面我会详细讲。当然开源不是免费的代名词。它的意思是把定制权交还给用户。很多团队拿我们的代码去改接入自己的企业知识库助手甚至换掉底层模型这恰恰是我们希望看到的结果。2.2 为什么选 Web 而不是原生客户端交互层的第一载体我们几乎没有犹豫就选了 Web。理由很直接跨平台、免安装、好嵌入。企业里用户分布在 Windows、macOS、Linux 甚至移动设备上你不可能要求所有人都装一个原生客户端但一个浏览器地址栏谁都能打开。Web 前端和后端的方案我们也比较过。后端最初在 Flask 和 FastAPI 之间纠结最后选了 FastAPI。原因有三一是原生异步面对流式输出和多路请求时表现稳定二是自动生成 OpenAPI 文档前端对接接口省掉大量沟通成本三是类型校验顺手参数错了能直接返回可读错误不需要我们写一堆 if else。前端用了 React组件生态成熟WebSocket 和状态管理都能找到现成方案。整体架构用文字概括就是浏览器端 React 应用通过 HTTP/WebSocket 访问网关层网关层再把请求分发给会话服务、模型网关、知识库检索和各个工具服务。模型网关做成统一接口上游可以接 OpenAI 兼容的云端服务也可以接本地部署的 Ollama、vLLM 等推理服务。这样切模型不影响业务代码这是企业 AI 助手能够落地的一个关键前提。2.3 本地模型接入的企业级实践现在大家聊 AI 助手已经默认要支持本地模型了。企业内网或者数据敏感场景根本不可能把对话抛给外部 API本地化推理是刚需。我们重写时做了一个模型网关层统一暴露 OpenAI 兼容的/v1/chat/completions接口上游默认接到 Ollama 本地服务。这个设计最大的好处是上层业务代码只需要对接一套协议下游模型随便换。模型从 Llama 换成 Qwen从 Ollama 换成 vLLM网关层改一行配置就行不用动会话管理和工具调用的逻辑。# app/gateway.py 节选 from fastapi import FastAPI, HTTPException, Request import httpx app FastAPI() UPSTREAM http://127.0.0.1:11434/v1 # Ollama 的 OpenAI 兼容端点 app.post(/v1/chat/completions) async def chat_completions(request: Request): payload await request.json() # 注入系统提示词防止前端绕过角色设定 payload.setdefault(messages, []) payload[messages].insert(0, { role: system, content: 你是企业内部知识库 AI 助手只依据可访问的文档回答不确定时直接说明不知道。 }) async with httpx.AsyncClient(timeout120) as client: resp await client.post(f{UPSTREAM}/chat/completions, jsonpayload) if resp.status_code ! 200: raise HTTPException(status_code502, detail模型服务异常) return resp.json()注意这个代码里有个细节系统提示词是在网关层注入的而不是让前端传进来。为什么要这样做因为前端是可以被篡改的如果系统提示词由前端控制用户完全可以绕过你的角色设定让助手说一些不该说的话。网关层强制注入系统提示词是 AI 助手安全的第一道防线。3. 重写过程的核心细节与实操要点3.1 会话上下文管理别让你的 AI 变成金鱼AI 助手和普通对话页面最大的区别就是它必须记得住事。我们在重写时把会话数据单独建了一套表设计得尽量简单方便后面迁移到 PostgreSQL。CREATE TABLE conversations ( id TEXT PRIMARY KEY, user_id TEXT NOT NULL, title TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE messages ( id INTEGER PRIMARY KEY AUTOINCREMENT, conversation_id TEXT NOT NULL REFERENCES conversations(id), role TEXT NOT NULL CHECK(role IN (user, assistant, system, tool)), content TEXT NOT NULL, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP );这里有个容易踩坑的地方上下文不能无限往模型里塞。对话越长Token 消耗越大响应越慢而且很多模型对超过窗口的内容会直接报错。我们参考常见方案做了一个截断策略保留系统提示词和最近 N 轮对话超出窗口的早期内容用上一轮的总结替代工具调用结果只保留关键字段避免把一整个知识库片段灌进历史。简化的实现思路大致是这样def truncate_messages(messages, max_tokens6000): # 保留系统提示词 system_messages [m for m in messages if m[role] system] others [m for m in messages if m[role] ! system] # 从后往前截断始终保留最近的上下文 candidates [] total sum(len(m[content]) for m in system_messages) for m in reversed(others): if total len(m[content]) max_tokens: break candidates.insert(0, m) total len(m[content]) return system_messages candidates这个方案实测下来比较稳但它不解决长期记忆的问题。想记住用户跨会话的偏好还是得把关键信息单独抽出来存比如用户画像表、偏好表然后在对话开始时动态注入提示词。这个就属于进阶功能了重做项目时不建议第一版就上先跑通核心链路更重要。3.2 工具调用与意图路由让 AI 从会聊变成会干活重写时我们做了一个很重要的决定不让大模型天生拥有执行能力而是给它一套明确的工具清单它只能通过函数调用去触碰外部系统。这样 AI 就被限制在理解意图、选择合适的工具、组织结果这层真正的写库、发请求、删数据仍然由我们的代码控制。一个工具的定义长这样{ type: function, function: { name: search_kb, description: 检索企业知识库返回相关文档片段, parameters: { type: object, properties: { query: { type: string }, top_k: { type: integer, default: 5 } }, required: [query] } } }模型如果判断用户想查知识库就会返回一个结构化请求而不是直接输出一段话。我们的后端解析这个请求执行对应工具再把结果塞回对话上下文。这样做的好处很多工具白名单可控不会让模型乱调接口每个工具都可以单独加鉴权出了问题可以定位到具体是哪一步执行失败。实操中还有一个很容易忽略的坑工具调用必须有最大步数和超时控制。如果不加限制Agent 可能会在两个工具之间来回猜测甚至陷入死循环。我们是这么写的max_tool_calls 5 tool_history [] for step in range(max_tool_calls): if not need_tool_call(response): break tool_result execute_tool(response) tool_history.append({tool: response.tool_call, result: tool_result}) response call_model_with_tool_history(prompt, tool_history) else: return 抱歉这个问题处理起来太复杂了请稍后再试。给模型一个明确的步数上限而不是让它无限运行这是所有 Agent 类产品稳定性的底线。3.3 权限过滤与多租户AI 再聪明也不能越权企业知识库助手里最容易被忽略但又最要命的问题是权限。用户输入一个问题如果知识库检索不过滤文档权限AI 就可能把其他部门的人事制度、薪资策略当作参考内容答出来这就是一次安全事故。我们做的方案其实不复杂每篇知识文档带一个visible_to字段记录哪些角色和部门能看到。检索前先把用户可见的文档集合过滤出来再交给向量检索和模型生成。def allowed_docs(user): scopes set(user.roles) | set(user.departments) return [doc for doc in kb_docs if set(doc.visible_to) scopes]这里要注意权限过滤必须放在检索前不能检索完再过滤。如果检索阶段就把不该看的文档向量拉出来了哪怕模型最后没有引用中间链路也存在泄露风险。另外所有工具调用都应该带上发起人身份后端在工具侧再做一次二次校验。AI 助手只是执行层权限判定的最终解释权必须握在我们自己的服务里。4. 项目上线后遇到的几个头疼问题实操排查实录4.1 Service Worker 注册失败的 InvalidStateError重写时我们给 Web 前端加了 PWA 能力想着离线时也能看历史会话。本地开发一切正常但部署到客户内网后控制台一直报错could not register service worker: InvalidStateError。排查到最后才发现Service Worker 要求页面必须在安全上下文里运行。本地 localhost 被浏览器视为安全来源但内网 HTTP 地址不是。客户内网没有上 HTTPS所以 Service Worker 注册直接被浏览器拒绝。解决办法是注册前先判断协议if (serviceWorker in navigator) { if (location.protocol https: || location.hostname localhost || location.hostname 127.0.0.1) { navigator.serviceWorker.register(/sw.js).catch((err) { console.error(SW 注册失败:, err); }); } else { console.warn(非 HTTPS 环境跳过 Service Worker 注册); } }如果你的内网场景确实需要离线能力建议用 mkcert 或者内部 CA 把 HTTPS 配上。没有证书的情况下不如直接把 PWA 去掉用浏览器普通缓存代替硬上 Service Worker 只会带来排查成本的负担。4.2 Web 视图加载出错与 CLI 自动打开浏览器失败我们的项目配套了一个运维命令行工具名字就叫dsh。它有一个dsh web子命令作用是启动一个本地 Web 面板来管理会话和模型参数。这个功能在开发机上很好用但在远程服务器上经常报错。典型的报错是opening the default browser; pass --no-open to disable。原因是服务器没有桌面环境代码里却调用了open/start去打开浏览器直接失败。还有一次更隐蔽报的是authentication required; reopen the url printed by dsh web因为我们给面板加了一个一次性 Token 认证但用户看到的 URL 是旧的没有带上 Token。解决方案很直接给命令行加--no-open参数默认不主动开浏览器只打印 URL认证信息放进 URL 参数并明确提示用户复制重新打开。如果你的产品也带 CLI 和 Web 面板这个教训值得提前踩永远不要假设你的 CLI 运行在有浏览器、有图形界面的机器上。4.3 WebSocket 断线导致流式回复丢一半AI 助手的交互要顺滑流式输出必不可少。我们最初用的是 WebSocket体验很好但上线后发现在网络不稳的环境下WebSocket 连接频繁断开用户只看到回复的一半另一半永远不来了。后来我们做了一层断线重连和消息补偿。前端在收到最后一条完整消息之前如果连接断了重连后主动向后端请求从某条消息 ID 开始补拉内容。代码核心就是重连时用last_received_id做续传let ws null; let retry 0; function connectWS() { ws new WebSocket(${location.protocol https: ? wss : ws}://${location.host}/ws/chat); ws.onopen () { retry 0; }; ws.onclose () { retry Math.min(retry 1, 10); setTimeout(connectWS, 1000 * retry); }; ws.onmessage (event) { const msg JSON.parse(event.data); renderMessage(msg); lastReceivedId msg.id; }; }如果项目对实时性要求没那么高也可以直接换成 SSE服务端单向推送天然支持断线重试实现更简单。目前新项目我们优先推荐 SSE除非需要双向控制类功能才上 WebSocket。4.4 公网部署之前安全功夫要补齐有一段时间我们把演示环境放到了公网结果第二天就被人刷了几千次接口差点把模型服务打挂了。复盘下来是我们没做好最基础的安全防护。现在我们的 Web 服务器固定有这几道配置第一CORS 必须明确允许的域名列表不能简单用*第二所有会话接口必须带 Token第三对所有请求做频率限制尤其是模型生成接口因为一次生成成本高恶意刷的话财务和算力都会很痛第四输入内容要做长度校验防止有人把整本书塞进 Prompt 触发超时。说到安全我们后来还遇到一个有意思的贡献者他是研究 CTF Web 解题的喜欢在各种比赛里找 Flag。他用那套思路来测我们的 AI 助手还真帮忙找到了一个越权漏洞普通用户可以通过伪造conversation_id读到别人的会话记录。后来我们给所有会话操作都加了只能操作当前登录用户自己的会话的强制校验这个坑才算填上。做 Web AI 交互层安全测试不能用常规思路得有对抗思维。5. 开源之后如何让项目真正活起来5.1 文档、README 和第一印象项目开源的第一个月star 涨得并不快真正让我们意识到问题的是有人提 issue 说按 README 装了三遍都没跑起来。我们仔细看README 里只写了安装命令没写 Python 版本要求也没说明依赖下载需要配置镜像源。后来我们花了整整一周重写文档。README 必须包含项目能干什么给第一次来的访客看、快速开始给赶时间的人看、架构原理给想改代码的人看、Roadmap给想参与贡献的人看。同时补了 CONTRIBUTING 文档和 issue 模板把 bug、feature request、question 分开避免所有问题都堆在同一个 issue 列表里。这里特别提一句开源镜像站。国内开发者在部署依赖时直接从默认源拉包经常很慢我们就在安装文档里写了一段建议配置让用户把 PyPI 和 npm 的 registry 切换到国内开源镜像。就这一个改动后台数据显示安装失败率直接降了一半。开源项目能不能顺利落地往往不是功能不够而是交付体验太差。5.2 社区运营和生态接入开源项目要活起来不能靠一个人写代码得靠社区一起推。我们的做法是建首批 good first issue专门挑那种改动小、说明清晰、适合新人的任务比如补语言包、优化按钮文案、增加单元测试用例。这类任务门槛低比较容易收到第一个 PR。CI 在项目开放第一天就接上了所有 PR 自动跑检查和测试减少维护者重复劳动。生态接入方面我们把重点放在和本地模型、企业知识库的对接上。现在项目支持 Ollama、vLLM 等本地推理服务也支持接入企业内网的向量数据库。很多用户反馈说他们就是冲着本地部署的企业级知识库助手这个场景来的。还有一些团队没有开发人力我们会建议他们先去用扣子这类低代码平台搭一个原型验证流程真到需要私有化和深度集成时再用我们的开源方案做底层。低代码平台解决有没有开源交互层解决能不能按你自己的想法改。项目的 Roadmap 也完全公开。社区反馈最多的需求之一是希望加语音回复能力我们就把开源的 TTS 项目比如 MultiTTS接入排进了计划而不是自己从零写语音合成。开源项目的正确姿势是连接生态不是重复造轮子。6. 重写之后的一些真心话6.1 重写这件事最大的收益是什么如果用一句话总结我觉得是产品思维从做一个功能变成了做一层地基。在只做 AI 获客工具的时候我们每天都在想怎么让 Prompt 更精准、怎么让生成的话术更像人类重写成 Web AI 交互层之后我们想的变成了怎么让用户每天都有理由回到这个对话流里。真实的数据也支撑了这个判断。重写前用户平均会话长度是 3 条消息不到重写后技术人员可以在同一个对话里完成知识库检索、日志查询、工单创建平均会话长度能到 19 条。为什么差这么多因为获客工具只回答怎么写一句话而交互层回答的是怎么帮你做完一整件事。这个价值完全不在同一个量级。6.2 给准备重写同类项目的团队三个建议第一重写之前先把交互层边界画清楚哪些数据可以进来哪些工具能力可以出去第三方系统如何接入。不要一上来就写代码边界不清的 Agent 项目后面接企业知识库时改动成本是几何级增长的。第二模型网关要独立一层不要和业务代码耦合。我们最开始图省事把所有模型调用都写在会话服务里后来换本地模型时改到崩溃。抽出网关层之后换模型就像换一个数据库连接串省掉大量返工。第三开源不是发布那一刻就结束而是项目生命周期的开始。你需要回答的不是代码怎么写而是别人拿到代码之后怎么快速跑起来、怎么改、怎么用。文档维护和代码维护同样重要我甚至建议前期投入一点先把安装和快速开始部分打磨得彻底这比功能列表多一两个亮点更能留住人。最后再分享一个小技巧重写完了别急着对外宣传先让团队内部把它当成日常工具用两周。自己人用得顺的 AI 助手用户大概率也会喜欢自己人都嫌慢嫌笨的工具上线之后只能收获一堆差评。
