NOTES · 学习笔记
项目介绍:基于腾讯开源的 WeKnora 接入 Agent 系统中
框架介绍
大模型不知道我们文档里的内容,直接问它,它就会乱编。所以要靠 RAG:先查资料,再回答。
RAG 的流程是这样的:把文档切成一小段一小段,然后建立索引,这样用户提问的时候才能搜到相关的知识,大模型照着搜到的资料回答。
但这一整套自己搭起来很麻烦。有了 WeKnora 就简单了,我们直接调用它就行:文档丢给它,它帮我们切片、帮我们建索引;我们提问的时候,它帮我们搜索资料,把最相关的几段返回给大模型。
而且它是腾讯开源的,检索的时候关键词和语义两种方式一起用上,找出来的内容比自己从零搭的 RAG 更准。目前在 GitHub 已经 27.1K stars。
这是我开源的一个学习版客服 Agent 项目:项目本身只负责用户登录、权限、Agent 配置、聊天接口和业务工具编排。默认示例是一个电商客服「极客商城小极」,改改配置文件和提示词,就能变成其他行业的助手。
最开始做这个项目只是想练手:RAG、Function Calling、权限这些 Agent 的零件单看教程都懂,拼成一个完整能跑的系统才知道坑在哪。所以 v1.0 就是个电商客服学习版,订单、商品、物流全是演示数据,不连真实电商——先把流程跑通,再谈别的。
所以我照着这个思路自己搭了一个可配置的客服 agent,知识库这一层就是用 WeKnora 做的:文档解析、切片、向量化、混合检索全交给它,我只管调接口。如果你觉得还不错,能给我一个 star 吗?
项目介绍
这是整个项目的架构图,用单 Agent 完成所有任务。
主流程:用户提问 → 对话前端(Vue 3)→ 后端服务(FastAPI)→ 大模型做 Function Calling 分流。
大模型会把问题分成两类:知识型问题交给 WeKnora 知识库;业务型问题交给业务工具,去查 PostgreSQL。
旁边还有 Redis 做会话缓存,知识文档由管理员在后台上传。
系统数据流
展开到组件级别,整个系统的数据流是这样的:
用户 → Vue 3 前端 → FastAPI
├─ JWT:登录和权限
├─ Agent Chat:多轮记忆、工具调用、回复整理
├─ WeKnora:文档解析、切片、向量、混合检索
├─ PostgreSQL:用户、会话、消息和业务数据
├─ Redis:共享登录限流和缓存状态
├─ MCP:扩展工具调用(可选)
└─ OpenAI 兼容模型:生成回答接入过程与边界
接 WeKnora 的过程不算复杂,但 API Key 那一步稍微有点麻烦(要在管理后台生成 scoped key,再配到环境变量里)。过了这关,后面的调用都挺顺的:管理员在后台上传企业相关的 PDF 问题文档,WeKnora 负责解析、切片、向量化。我的后端只需要调它的检索接口,把用户问题发过去,拿回最相关的几段。
我给自己定了一条规矩:不复制 WeKnora 的源码,也不重复实现它的能力。它的内部数据库和 Redis 也是独立的,我不碰也不共用——两边各自演进,互不影响。
Function Calling 和 RAG 怎么配合
这是整个项目我觉得最值得说的设计。整个系统是单 Agent 架构:只有一个大模型,每一轮由它自己决定下一步干什么——是查知识库、查订单、查物流,还是直接回答。
用户问“退货政策是什么”,这是知识型问题,走 WeKnora;用户问“我的订单到哪了”,这是业务型问题,走 Function Calling 调工具,去查 PostgreSQL。两条路最后汇合,把答案返回给用户。
业务工具一共五个:订单、商品、物流、退款、人工转接。工具层支持 MCP 2.0 扩展——MCP 没启动或连接失败时,Agent 自动回退到本地业务工具,后端日志记一笔,用户端完全无感。兜底思路很简单:扩展能力是可选的,核心业务永远本地可得。
还有一个细节:对话历史由上层注入,Agent 本身不维护状态,历史存在 Redis 里,24 小时自动过期。这样 Agent 是无状态的,以后要水平扩展也不用操心会话粘性。
为什么叫“可配置”
因为我没有把它写死成“电商客服”。同一个系统,管理员换成医疗领域的文档,它就是医疗客服;换成金融文档,它就是金融客服。名字、知识库、工具都可以按场景配置,换赛道不用改代码。
落地层面:每个 Agent 一份配置文件(configs/agents/ 目录),管理员在后台配置名称、角色、Prompt、可用工具和知识库。权限模型刻意简单:普通用户只能选用公开的 Agent、建会话、提问;Prompt、模型、知识库这些配置只有管理员能碰。
工程化与压测
测试用 pytest 覆盖接口、工具、数据库和 WeKnora 适配器;质量检查一条链:uv sync → pytest → compileall → docker compose config → 前端 build。另外专门做了一套隔离的 Locust 压测环境(load_tests/ 目录,独立 compose),跑分不污染开发库。
版本从 v1.0 的电商学习版,到 v2.0 的通用化 + 权限 + WeKnora 接入,再到 v2.1 的 Agent 权限隔离。最有价值的一次演进就是 v2:把 v1 里自己搭的简易 RAG 整个拆掉,换成调 WeKnora 的接口,代码少了一大坨,检索质量反而上去了;同时把权限从「一个 Agent 用到底」改成「管理员配置、普通用户使用」——Agent 这才真正称得上「可配置」。
部署
两个独立项目分开起:先起 WeKnora(官方仓库 docker compose),再到本仓库的 .env 填模型和 WeKnora 的 Key,docker compose up --build 拉起 PostgreSQL、Redis、后端和前端。管理员不能用注册页创建,要用 api/admin_setup 命令——这是故意的设计,注册页只该出普通用户。
还有一个局限:现在是单 Agent,问题简单的时候够用,但任务一复杂——比如要先查订单、再对照退款政策、再综合着回答——提示词就会越写越长,越来越难维护。业界现在也在往 multi-agent 走,把不同职责拆给不同的 Agent 协作。怎么把单 Agent 演进成 multi-agent,是我下一步想改造的方向。