文章摘要
一、效果预览1.1 模型配置：选厂商就自动填好
15 项厂商预设。选中厂商后 Base URL 和默认模型自动填充，协议下拉按该厂商实际
支持的协议动态生成。填完 Key 点「测试连接」，直接看到模型的真实回复。
右边还有个「🔄」按钮 —— 点它会调厂商的 /models 接口，拉取你这个账号真正能用的
模型列表，而不是让你对着文档猜模型名。拉不到就自动回退到内置推荐列表，不会卡住。
1.2 RAG 设置：参数不用猜，能预览
Top-K、相似度阈值、切分策略都在这里。关键是那个「🔍 预览切分效果」按钮 ——
选一份已上传的文档或直接粘贴文本，立刻看到会被切成多少片、每片多长、
归属哪个章节，不用真的入库消耗 embedding 配额。
调参数这件事，能看到结果和纯靠猜，完全是两种体验。
1.3 向量库：三选一，只显示相关字段
Chroma（默认，本地文件零部署）/ Qdrant / Milvus 三选一。选中哪个就只显示它需要的
字段 —— 选 Chroma 不会让你看到一堆 Qdrant 的连接参数。
Milvus 支持 Milvus Lite：Base URI 填个 .db 文件路径就能跑，不用装 etcd 和 minio。
1.4 信息：改一次，所有站点生效
名称、头像、欢迎语、联系方式。这里改完，所有已经嵌入到各个网站的组件都会同步 ——
因为组件启动时会自己来读这份配置，不需要你去改每个站点的嵌入代码。
1.5 聊天预览：后台里直接测
配完不用切页面，就在后台里问。答案里的 Markdown 会正常渲染（加粗、列表、代码块），
文章链接是可点击的超链接而不是一串纯文本。
1.6 嵌入指南：三种方式，一键复制
<script> 标签 / iframe / 小程序 web-view，代码直接复制。
1.7 装到网站上是什么样
嵌入代码就这么几行：
<script src=”https://你的域名/widget/customer-service.js?v=1″></script><script> CustomerService.init({ apiUrl: ‘https://你的域名’ });</script>
组件是单文件、零依赖、免构建的原生 JS，19KB。不用 npm，不用打包，
丢到任何页面都能跑。
4.2 三步跑起来
① 装依赖
git clone https://github.com/vfaner/intelligent-customer-service.git
cd intelligent-customer-service/backendpython3 -m venv .venvsource .venv/bin/activate # Windows: .venv\Scripts\activatepip install -r requirements.txt
② 启动
PyCharm 用户：右键 backend/run.py → Run
命令行：
python run.py
③ 打开管理后台配置
浏览器访问 http://localhost:8000/admin/
[td]
| 顺序 | 做什么 |
| 1️⃣ | 顶部若有横幅 → 点「🚀 一键初始化」 |
| 2️⃣ | 「模型配置」→ 选厂商 → 填 API Key → 「🔌 测试连接」→「💾 保存」 |
| 3️⃣ | 同页「🧬 向量模型」→「⬆︎ 复用对话模型的 Key/URL」→「🔌 测试并探测维度」 |
| 4️⃣ | 「知识文档」→ 拖入 txt/md/docx/xlsx/pdf → 自动解析入库 |
| 5️⃣ | 「聊天预览」→ 直接提问验证 |
全程不需要编辑任何文件。
4.3 环境要求[td]
| 项目 | 要求 |
| Python | 3.11+（已在 3.14.5 上验证） |
| 数据库 | SQLite（默认，零配置）或 MySQL |
| 向量库 | Chroma（默认，零部署）/ Qdrant / Milvus |
| 模型 | 任意一个厂商的 API Key |
| Node.js | 仅跑前端自检时需要，运行项目不需要 |
文档[td]
| 文档 | 内容 |
| README.md | 中文总览、页面导览、配置项参考、FAQ |
| README.en.md | English version |
| docs/API.md | 24 个接口的详细说明 |
| docs/DEPLOYMENT.md | 服务器部署完整步骤 |
| docs/EMBED_GUIDE.md | 嵌入网站/小程序/桌面端 |
