把智能客服
交给网页去配
基于 FastAPI + RAG 的智能客服系统。装完依赖点一下运行， 换模型、调参数、传知识库全部在管理后台完成 —— 不改配置文件，不跑初始化脚本，不重启服务。
不只是能跑，是能交给别人维护
大多数 RAG 项目绕不开「改配置 → 跑脚本 → 重启」。这个项目把这些全搬到了网页上。
15 家厂商，选中就自动填
DeepSeek、通义千问、火山方舟、智谱、Kimi、千帆、OpenAI、Claude、Gemini、Ollama… 选中厂商自动填 Base URL 和模型名，点「🔄」还能拉取你账号真正可用的模型列表。
双协议适配
OpenAI 的 /chat/completions 和 Anthropic 的 /messages 都支持，切协议自动更新地址。认证头两种都发，兼容各家网关的实现差异。
结构感知切分
识别【章节】、Markdown 标题、第X章、Q&A 对、Excel 工作表，沿语义边界切分并保留标题上下文。实测检索得分从 0.719 提升到 0.791。
三种向量库
Chroma（本地文件、零部署）、Qdrant（生产级）、Milvus（含零安装 Lite 模式）。同一套接口，页面上切换。
回答策略可选
默认严格 RAG：资料外一律拒答，每句话都能追溯到你的文档。也可以开关允许 AI 用自身知识补充回答。
组件零依赖
单文件原生 JS，19KB，免构建免打包。内置 Markdown 渲染和链接识别，支持文件上传。丢到任何页面都能跑。
断点续传入库
大知识库入库遇到厂商配额限制会自动降批、退避重试。中断后进度保留，再点「入库」从上次位置继续，不重复消耗配额。
跨平台嵌入
网站、微信小程序 web-view、Electron、Tauri、iOS/Android WebView 全覆盖。三种嵌入方式，代码一键复制。
MIT 协议
完全开源免费，可商用、可二次开发、可闭源分发。代码里留了大量「为什么是这个值」的注释，方便你改。
每个界面都在解决一个具体问题
点击标签切换查看
选厂商就自动填好
15 项厂商预设，选中后 Base URL 和默认模型自动填充，协议下拉按该厂商实际支持的协议动态生成。
- 填完 Key 点「测试连接」，直接看到模型真实回复
- 点「🔄」调厂商接口，拉取你账号能用的模型列表
- 向量模型可一键复用对话模型的 Key 和地址
- 自动探测维度并同步到向量库配置
参数不用猜，能预览
Top-K、相似度阈值、切分策略都在这里。关键是那个「🔍 预览切分效果」按钮。
- 选文档或粘贴文本，立刻看到切成多少片
- 显示每片长度分布和章节归属
- 不用真的入库，不消耗 embedding 配额
- 回答策略开关：严格 RAG / 允许自主回答
三选一，只显示相关字段
选中哪个向量库就只显示它需要的参数，不会让你对着一堆无关配置发愁。
- Chroma — 本地文件持久化，零部署
- Qdrant — Rust 实现，生产级
- Milvus — 填
.db路径即用 Lite 模式，无需 etcd/minio - 维度不匹配时页面会自动同步修正
拖进去，剩下自动做
支持 txt / md / docx / xlsx / pdf，单文件默认上限 20MB，上传后自动解析入库。
- 拖拽上传，实时显示入库进度和分片数
- 遇厂商配额限制会自动降批、退避重试
- 中断后进度保留，再点「入库」从上次位置继续
- 状态标记为就绪才会进入检索
改一次，所有站点生效
名称、头像、欢迎语、联系方式在这里配置。
- 所有已嵌入的组件启动时自动来读这份配置
- 不用去改每个站点的嵌入代码
- 头像支持图片 URL，加载失败自动退回首字
- 联系方式会显示在客服窗口头部
后台里直接测
配完不用切页面，就在管理后台里提问验证效果。
- 用 iframe 内嵌真实组件，与线上表现一致
- Markdown 正常渲染：加粗、列表、代码块
- 文章链接是可点击的超链接
- SSE 流式输出，逐字显示
三种方式，一键复制
不管你的站点是什么技术栈，总有一种能接。
- <script> 标签 — 两行代码，最简单
- iframe — 完全隔离，样式互不影响
- 小程序 web-view — 微信/支付宝/抖音
- 代码里的域名会自动替换成你的实际地址
装到网站上是这样
右下角一个浮动按钮，点开就是聊天窗口。
- 浮动按钮位置可选左右
- 主题色可配，适配你的品牌
- 支持在聊天窗口里直接上传文件
- PC / 平板 / 手机响应式适配
三步跑起来
全程不需要编辑任何配置文件
装依赖
克隆仓库，建虚拟环境，装依赖。
启动
PyCharm 右键 run.py → Run，或者命令行：
网页上配置
访问 localhost:8000/admin/
.env 或执行 init_db.py。🪟 嵌入到你的网站
两行代码，把客服装到任意页面。
?v=1 是缓存版本号，更新组件后递增。
⚙️ 环境要求
门槛很低，不需要 GPU。
| 项目 | 要求 |
|---|---|
| Python | 3.11+（已在 3.14 验证） |
| 数据库 | SQLite（默认，零配置） |
| 向量库 | Chroma（默认，零部署） |
| 模型 | 任一厂商的 API Key |
| GPU | 不需要（推理在厂商侧） |
| Node.js | 仅前端自检需要 |
部署到服务器
两套方案任选，仓库里有完整的 docs/DEPLOYMENT.md
🐳 Docker Compose
环境隔离，一条命令起停，迁移方便。
🔧 systemd + Nginx
不用 Docker，直接在宿主机跑。
⚠️ 三个必须知道的坑
这三条是部署时最容易出问题的地方。
| 问题 | 说明 |
|---|---|
| 只有 Nginx 该暴露公网 | 应用绑 127.0.0.1:8000。管理后台没有内置登录，直接对外等于把 API Key 配置页开放给所有人。推荐用 SSH 端口转发访问后台。 |
| SSE 必须关缓冲 | 不关的话回答不会逐字出现，而是等全部生成完才一次性蹦出来，长回答还可能超时断开。 |
| iframe 尺寸要给够 | 需要 400 × 636，且 background: transparent。给小了面板被裁，不透明会露出白底。 |
APP_SECRET_KEY · APP_DEBUG=false · CORS_ORIGINS 限定域名 · 管理后台加访问控制 · 启用 HTTPS · 不用 root 跑 · 给聊天接口限流 · 定期备份 backend/data/（存着你的 API Key，已被 .gitignore 排除）
你可能会问
真的完全免费吗？可以商用？
是。MIT 协议，可商用、可二次开发、可闭源分发，不用付费也不用署名（保留 LICENSE 即可）。
唯一的成本是模型厂商的 API 费用，这部分直接跟厂商结算，项目本身不收任何费用、不做中间层。
没有 GPU 能跑吗？服务器要什么配置？
不需要 GPU —— 模型推理都在厂商侧，本机只做检索和编排。
小规模（<1 万片段）2 核 2G 就够；中等规模建议 2 核 4G。注意向量数据比想象的占空间：实测 12,596 个片段（2048 维）的 Chroma 目录约 163MB。
支持哪些文档格式？中文效果怎么样？
支持 txt / md / docx / xlsx / pdf，单文件默认上限 20MB。
切分器针对中文做了专门处理：识别【章节】、第X章、中文标点边界，Q&A 问答对不会被拆开。相关性阈值也是按中文 embedding 的实际分数分布调的 —— 中文里即使内容无关相似度也有 0.65 左右，所以单独引入了一个 0.76 的相关性分界线。
问什么都回「知识库中没有相关信息」怎么办？
按顺序检查：① 文档状态是否为就绪且分片数 > 0；② 把相似度阈值调低（默认 0.5）；③ 用「预览切分效果」确认文档被合理切分。
如果希望资料外的问题也能回答，到「RAG 设置」开启自主回答开关。
入库很慢或者中途失败？
多半是 embedding 厂商的配额限制（实测火山方舟的配额是长周期累计的）。
项目已做断点续传：中断后进度保留，再点「入库」从上次位置继续，已完成的片段不会重复消耗配额。大知识库建议用 scripts/ingest_retry.py 挂后台跑。
管理后台有登录吗？部署后安全吗？
目前没有内置登录 —— 这一点必须说清楚。所以千万不要把后台直接暴露在公网。
部署文档里给了三种保护方式，最推荐 SSH 端口转发（后台完全不对外开放）。另外 API Key 目前只做了 base64 混淆不是加密，生产环境应该换成 KMS / Vault。
可以只用某一个厂商吗？会不会绑定？
不绑定。15 项预设只是帮你省去查文档填地址的功夫，随时可以在页面上切换。
还有两个自定义槽位：任何兼容 OpenAI 或 Anthropic 接口的服务都能接 —— 自建 vLLM、one-api、LiteLLM、Ollama 本地模型都可以。
能嵌到微信小程序里吗？
可以，通过小程序的 web-view 组件加载。仓库里的 docs/EMBED_GUIDE.md 有微信/支付宝/抖音各平台的具体做法，以及 Electron、Tauri、iOS/Android WebView 的接入方式。
注意需要在小程序后台把域名加入业务域名白名单。
