源码系统概览
文章正文
智能客服系统是一套基于 FastAPI 与 RAG 技术构建的开源多模型客服平台。它把大模型对话、知识库检索和网站嵌入能力整合到一个网页管理后台里。
用户不必修改任何配置文件，也不用手写初始化脚本，装好依赖后启动服务，剩下的模型、向量库、客服话术全部在浏览器里点选完成。对于想自己搭建智能问答站点的团队，这套源码提供了一个可以直接落地的起点。
源码简介
本仓库后端使用 FastAPI 框架，搭配 Uvicorn 运行，数据层默认用 SQLite 异步驱动，也可切换到 MySQL。检索增强部分依赖 Chroma 向量库做本地持久化，生产环境可选 Qdrant 或 Milvus。
前端由一个网页管理后台和一段纯 JavaScript 客服挂件组成，挂件无需打包，复制文件或用 CDN 引入即可嵌入任意网站。整套系统通过 OpenAI 兼容协议接入多种大模型，知识库支持结构感知切分，问答策略可在严格 RAG 与允许模型自主回答之间切换。
仓库自带 36 个后端测试与 17 个挂件测试，采用 MIT 协议，对二次开发和商业试用都比较友好。
适用场景
这套系统适合需要把产品文档、帮助中心或内部知识沉淀成可对话入口的场景。企业可以把客服挂件嵌到官网，让访客直接提问获取答案。
教育机构能用它做课程答疑机器人。创业团队可以用它快速验证一个智能问答产品的想法，而不必先搭一整套基础设施。对已经有网站、只想补一个智能客服窗口的站长来说，嵌入挂件是最轻量的用法。
功能亮点
第一大亮点是全网页配置，模型、向量库、客服档案都在后台表单里填，零命令行。第二大亮点是流式对话，基于 SSE 的流式接口让回答逐字输出，体验接近主流聊天产品。
第三是结构感知切分，上传的文档按标题层级切块，检索更准。第四是一键初始化，全新安装打开后台就能引导建表建配置。第五是网站嵌入，挂件复制即用，支持中英双语界面。
截图与演示说明
下面这组后台截图展示了从接入模型到把客服挂件嵌进网站的全过程。模型配置页用来填写要接入的大模型与密钥。RAG 设置页控制检索条数、相似度阈值和切分参数。
向量库配置页选择 Chroma、Qdrant 或 Milvus 并填写连接信息。客服档案页定义这个智能体的名称与身份。对话预览页可以看到真实的多轮问答效果。接入指引页给出把挂件放进网站的代码片段。嵌入效果演示页则展示挂件在真实页面里的样子。
技术架构与部署指南
技术栈与运行环境
后端框架：FastAPI + Uvicorn（Python 3.11 及以上）
数据层：SQLAlchemy 异步，默认 SQLite，可选 MySQL
向量库：Chroma 本地持久化，可选 Qdrant 或 Milvus
大模型接入：OpenAI 兼容协议，支持多家厂商与本地模型
前端：网页管理后台 + 纯 JS 嵌入挂件（无需构建）
安装与部署提示
第一步，进入 backend 目录，用 Python 3.11 创建虚拟环境并安装 requirements.txt。第二步，直接运行 run.py 启动服务，默认监听 8000 端口。
第三步，打开浏览器访问管理后台，按向导填写大模型密钥、选择向量库、上传知识文档。需要嵌入网站时，把 frontend/widget 下的 customer-service.js 通过 CDN 或本地引入，按接入指引填入后端地址即可。
生产部署建议把调试模式关闭，并改用 MySQL 与 Qdrant 这类更稳的组件。
常见问题
问：一定要改配置文件吗？答：不需要，所有配置都在网页后台完成。
问：支持哪些向量库？答：默认 Chroma，生产可选 Qdrant 或 Milvus。
问：能接国产大模型吗？答：只要模型提供 OpenAI 兼容接口就可以接入。
问：挂件要打包吗？答：不用，customer-service.js 直接可用。
问：知识库文档支持什么格式？答：系统提供多种文档解析器，常见文本与办公格式都能处理。
安全风险提示
本项目默认开启调试模式并监听所有网卡，直接暴露到公网有安全风险，上线前务必关闭调试并限制访问来源。大模型密钥写在后台配置里，建议通过环境变量或密钥管理服务保管，不要提交到代码仓库。
知识库会接触业务文档，应注意权限与脱敏，避免把敏感内容纳入可检索范围。系统未内置登录鉴权细节，公网部署需自行补充访问控制。
下载说明
本仓库为开源项目，源码与更新请在 GitHub 获取。下载后按上文三步即可本地运行，所有功能均不收费、无隐藏密码。
请遵守 MIT 协议，在二次分发时保留原作者与许可声明。资源仅供学习与技术研究使用，由此产生的部署与运营风险由使用者自行承担。
GitHub项目开源地址：https://github.com/vfaner/intelligent-customer-service
