基于 LangChain + 阿里云百炼（通义千问） 的企业级 RAG 知识库问答平台。管理员在浏览器中维护商品知识库，普通用户通过浏览器与模型进行知识库问答，回答内容自动标注引用来源（知识库片段）。
- 知识库管理（仅管理员）：文档上传（TXT/Markdown/PDF/Word/Excel/HTML/CSV）、异步解析与向量化、切片预览、重新索引、分类管理、人工问答对（精确命中）、检索效果调试台
- 知识库问答：混合检索（向量 + BM25）→ RRF 融合 → 重排精排 → 带编号引用的流式回答，点击引用可查看来源片段
- 商品图片识别：聊天框可直接上传商品图片（最多 3 张），千问 VL 模型自动识别商品属性并参与知识库检索，答案带引用
- 会话导出：会话菜单一键导出 Markdown 或 JSON，历史对话可离线存档
- 多用户多会话：独立会话、会话重命名/置顶/删除，历史对话持久化，随时找回
- 用户体系：注册 / 登录 / 修改密码，JWT 双令牌认证，角色权限控制（仅管理员可进入知识库管理）
- 企业级优化：语义缓存（相似问题秒回）、SSE 流式输出、异步文档索引队列、限流防滥用、Token 用量统计、操作审计日志、主备 API Key 自动切换
- 模型参数在线配置：管理后台"模型配置"页可在线调整对话/向量/重排/识图模型、温度、检索条数与语义缓存开关，即时生效无需重启
- 存储可插拔：向量库支持本地 Chroma 与阿里云 DashVector；数据库支持 SQLite 与 PostgreSQL，切换只改配置
| 层 | 技术 |
|---|---|
| 后端 | Python 3.11 + FastAPI + LangChain + SQLAlchemy |
| 大模型 | 阿里云百炼 qwen-max（LLM）/ text-embedding-v3（向量）/ gte-rerank-v2（重排） |
| 向量库 | Chroma（本地，默认）/ DashVector（阿里云托管） |
| 数据库 | SQLite（WAL 模式，默认）/ PostgreSQL |
| 前端 | Vue 3 + TypeScript + Vite + Element Plus |
samples\chinese_kb\ 提供了可直接导入的 20 个京东一级类目商品知识库 CSV（共约 1.93 万条真实京东商品名，非合成数据）：
| 类目 | 条数 | 类目 | 条数 |
|---|---|---|---|
| 家用电器 / 手机通讯 / 电脑办公 / 数码 | 各 1000 | 食品饮料 / 生鲜 / 母婴 / 玩具乐器 | 各 1000 |
| 美妆护肤 / 个人护理 / 服饰内衣 / 鞋靴 | 各 1000 | 珠宝首饰 / 箱包皮具 / 钟表 / 运动户外 | 各 1000 |
| 家居日用 / 家具 / 图书 | 各 1000 | 酒类 | 287（开源数据中真实酒类上限） |
数据来源：
- WWW2015 JD.com E-Commerce Data（OpenI 镜像，52.5 万条真实京东商品，含三级类目）；
- jd-dataset（Gitee，13.2 万条京东生鲜商品）。
每个类目按"商品评价数（知名度）"降序取前 1000 条；生成脚本 scripts\generate_jd_kb.py，一键导入脚本 scripts\import_jd_kb.ps1（登录管理员后自动清空旧库、创建 20 个分类并上传）。
说明：数据集无销量字段，故以评价数作为知名度代理；酒类在开源数据中真实商品仅 287 条，未用非酒商品凑数。
双击运行 scripts\start.bat，脚本会自动：
- 创建 Python 虚拟环境并安装后端依赖（清华镜像）
- 安装前端依赖并构建页面（npmmirror 镜像）
- 启动后端服务并自动打开浏览器
停止服务：双击 scripts\stop.bat。
# 1. 后端（项目根目录）
python -m venv .venv
.venv\Scripts\python -m pip install -r backend\requirements.txt
cd backend
..\.venv\Scripts\python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
# 2. 前端（开发模式，另开终端）
cd frontend
npm install
npm run dev # 访问 http://localhost:5173生产模式直接访问 http://localhost:8000（FastAPI 自动托管前端构建产物）。
| 角色 | 用户名 | 密码 | 说明 |
|---|---|---|---|
| 管理员 | admnin |
123456 |
可管理知识库、用户、查看统计与审计日志 |
| 普通用户 | 自行注册 | - | 仅可进行知识库问答 |
管理员账号与密码可在
.env中修改（ADMIN_USERNAME/ADMIN_PASSWORD），修改后重启服务生效。
首次运行前，请确认项目根目录的 .env 文件已配置：
# 阿里云百炼 API Key（主 Key，免费额度）
DASHSCOPE_API_KEY=sk-xxxx
# 备用 Key（免费额度用完后自动切换）
DASHSCOPE_API_KEY_BACKUP=sk-yyyy
# 模型选择（可选）
LLM_MODEL=qwen-max
EMBEDDING_MODEL=text-embedding-v3
RERANK_MODEL=gte-rerank-v2
VISION_MODEL=qwen3.8-max所有密钥仅存于本地 .env，已加入 .gitignore，不会进入版本库。
- 开通阿里云 向量检索服务 DashVector，创建 API Key 并获取 Endpoint；
- 修改
.env：
VECTOR_STORE=dashvector
DASHVECTOR_API_KEY=你的 DashVector API Key
DASHVECTOR_ENDPOINT=你的 DashVector Endpoint（如 https://xxxx.dashvector.cn-hangzhou.aliyuncs.com）
DASHVECTOR_COLLECTION=kb_chunks- 重启服务后，重新上传/重新索引知识文档即可写入 DashVector；系统会自动创建 Collection。
- 安装 PostgreSQL（原生安装包或阿里云 RDS），创建数据库；
- 安装驱动并修改
.env：
pip install asyncpgDATABASE_URL=postgresql+asyncpg://用户名:密码@主机:5432/数据库名- 重启服务即可；系统会自动建表。关键词检索在 PostgreSQL 下自动切换为 ILIKE 子串匹配（可再安装
pg_trgm扩展增强）。
samples\ 目录提供了：
- 3 份示例商品文档（纯棉 T 恤、蓝牙耳机、退换货政策），可用于快速体验上传流程；
chinese_kb\20 类目京东商品 CSV（见上节），可直接批量导入；amazon_kb\英文 Amazon 商品分类 CSV（早期数据，可作对比）。
项目内置 unit-testing 技能（.codex\skills\unit-testing，由鲲鹏记账项目迁移适配），执行方式：
python -m pytest test/ -v # 运行全部测试
python -m pytest test/ --cov=app --cov-report=term-missing # 带覆盖率当前 92 个用例全部通过。测试使用临时 SQLite 库与独立 Chroma 目录，不触碰真实数据；涉及百炼外部 API 的调用均打桩，不消耗额度。详细结果见根目录 test-report.md。
项目内置了一套完整的 Codex 质量门禁体系（从鲲鹏记账项目迁移并适配本技术栈）：
- Agents（
.codex\agents\）：gitcommit-agent（提交管家）、tester（测试专家）、reviewer（代码审查）、quality-engineer（质量工程师）； - Skills（
.codex\skills\）：unit-testing / security-audit / comments-check / code-review / git-save / git-manager / upload-github / generate-docs / project-setup / run-project / packaging-optimizer / repackage-app / claude-vision-skill 等 13 个； - Hooks（
.githooks\+.codex\config.toml）：提交前自动校验"单元测试 + 质量检查"两张通行证，指纹与工作区不一致即拦截提交； - 项目规则（
AGENTS.md）：测试/审查/提交任务自动委派对应 Agent。
对本项目说"提交代码"，会自动执行：单元测试 → 安全与注释检查 → 刷新通行证 → 规范提交；推送后通行证自动清除，下次提交需重新检查。
LangChainRAG/
├── backend/ # FastAPI 后端
│ └── app/
│ ├── rag/ # LangChain RAG 管线（检索/重排/生成/索引）
│ ├── routers/ # API 路由（认证/会话/聊天/知识库/管理）
│ ├── models.py # 数据模型
│ └── main.py # 应用入口
├── frontend/ # Vue 3 前端
├── samples/ # 示例知识文档与 20 类目商品数据 CSV
├── scripts/ # 启动/停止/数据生成/导入脚本
├── test/ # pytest 单元测试（92 个用例）
├── .codex/ # Codex Agents / Skills / Hooks 配置
├── .githooks/ # git 质量门禁钩子（pre-commit 等）
├── AGENTS.md # 项目协作规则
└── .env # 本地密钥配置（勿提交）
- 免费额度用完怎么办：在百炼控制台充值，或更换
.env中的DASHSCOPE_API_KEY；系统已内置主备 Key 自动切换。 - 如何换更大的模型：修改
.env的LLM_MODEL（如qwen-plus、qwen-turbo），重启服务。 - 换 PostgreSQL：安装 PostgreSQL 后，将
.env的DATABASE_URL改为postgresql+asyncpg://user:pass@host:5432/db，并安装asyncpg。 - 控制台中文乱码：仅影响终端显示，不影响系统；日志文件（
logs/app.log）为 UTF-8。