{"id":28403763,"url":"https://github.com/zysyy/gadgetguide_ai-","last_synced_at":"2025-06-27T08:30:56.694Z","repository":{"id":292312606,"uuid":"980376790","full_name":"zysyy/GadgetGuide_AI-","owner":"zysyy","description":"一个基于自定义知识库的实用型电子产品AI问答与推荐系统，使用Python FastAPI后端和Vue.js前端。","archived":false,"fork":false,"pushed_at":"2025-06-13T05:41:06.000Z","size":7297,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-13T06:37:31.193Z","etag":null,"topics":["ai","chatbot","faiss","fastapi","gadget-advisor","knowledge-base","langchain","llm","nlp","ollama","python","question-answering","rag","vuejs"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zysyy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-09T03:07:11.000Z","updated_at":"2025-06-13T05:41:10.000Z","dependencies_parsed_at":"2025-06-13T06:29:18.804Z","dependency_job_id":"99e44899-c74e-4572-880b-9bdd5c4c14f2","html_url":"https://github.com/zysyy/GadgetGuide_AI-","commit_stats":null,"previous_names":["zysyy/gadgetguide_ai-"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/zysyy/GadgetGuide_AI-","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zysyy%2FGadgetGuide_AI-","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zysyy%2FGadgetGuide_AI-/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zysyy%2FGadgetGuide_AI-/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zysyy%2FGadgetGuide_AI-/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zysyy","download_url":"https://codeload.github.com/zysyy/GadgetGuide_AI-/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zysyy%2FGadgetGuide_AI-/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262222152,"owners_count":23277370,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","chatbot","faiss","fastapi","gadget-advisor","knowledge-base","langchain","llm","nlp","ollama","python","question-answering","rag","vuejs"],"created_at":"2025-06-01T19:08:49.501Z","updated_at":"2025-06-27T08:30:56.685Z","avatar_url":"https://github.com/zysyy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GadgetGuide AI\n\n## 项目说明\n\n本项目为个人学习和研究用途，聚焦于大语言模型与知识库问答系统的工程实现。通过完整开发一个智能电子产品问答平台，系统性实践了前后端分离架构设计、现代前端开发（Vue 3 + Element Plus）、后端 API 构建（FastAPI）、向量检索（FAISS）、语义嵌入（Ollama Embedding 模型）、以及调用云端大语言模型 API（DeepSeek）。\n\n本项目同时也探索了如何集成用户身份系统、对话管理、知识库动态索引更新、热词统计等功能模块，旨在提升对实际场景中 RAG 技术落地的理解能力，并积累完整的项目开发经验。项目仍在持续完善中，欢迎同行交流探讨。\n\n---\n\n## 项目简介\n\nGadgetGuide AI 是一个基于自定义知识库的电子产品问答与推荐系统，用户可通过自然语言提问获取关于产品的技术规格、功能差异、使用建议等信息。系统结合语义检索（RAG）与大语言模型生成能力，能够提供基于文档内容的专业回答，同时支持多产品特性对比。\n\n项目目前以苹果系列产品为初始知识库示例，支持上传 PDF/TXT 文档进行动态扩展。系统包含用户登录注册、聊天对话、知识库文档管理、会话记录管理、热词分析等完整功能模块，并通过管理员端接口支持索引刷新与用户数据管理。前端界面简洁实用，具备基础的交互优化体验。\n\n本项目作为智能问答系统的工程化实践范例，具备良好的拓展潜力，可应用于教育问答、产品推荐、政策咨询等多个垂直场景。\n\n\n\n**当前版本:** `v0.3.0-beta`（Beta 测试版，支持知识库管理、管理员功能与对话记录系统）\n\n* 后端核心 RAG 流程已实现并稳定运行，支持基于向量检索的知识问答与产品信息对比生成。\n* 前端基于 Vue 3 构建，已完成与后端的集成，可进行自然语言提问与 AI 答复交互。\n* 支持 Markdown 格式的回答展示（含表格、列表、代码块等），提升信息呈现的可读性。\n* 新增知识库文档管理系统，支持上传、删除、刷新索引等操作，便于知识内容的迭代更新。\n* 引入用户会话记录系统，支持多轮对话保存与切换，提升用户体验与交互连贯性。\n* 管理员可访问后台查看用户列表、会话历史与系统热词统计，用于优化问答系统内容。\n\n---\n\n## 主要功能与特性（v0.3.0-beta）\n\n### 💬 智能问答系统\n- 用户可通过自然语言提问系统内置的电子产品知识（目前以苹果产品为主）。\n- 支持基于自定义知识库的检索增强生成（RAG）方式回答，确保答案可追溯。\n- 自动标注答案来源（“参考信息生成”或“AI自由回答”），提升透明度。\n\n### 🔍 产品对比能力\n- 系统可识别对比类查询（如“iPhone 14 与 iPhone 15 有何不同”），对不同产品分别检索信息。\n- 对比答案以标准 Markdown 表格格式返回，便于用户直观查看差异。\n\n### 📚 知识库管理（仅管理员）\n- 支持上传 `.txt` 和 `.pdf` 文档，作为问答系统的知识源。\n- 支持规范化文件名、删除文档、主动刷新向量索引等操作。\n- 所有文档存储于本地 `uploads/` 目录，索引基于 FAISS 构建并持久化。\n\n### 👤 用户与会话管理\n- 用户登录后可查看、切换历史会话，支持重命名、新建、删除会话等操作。\n- 所有消息自动关联会话记录，支持滚动查看和持续提问。\n\n### 🛠 管理员后台功能\n- 查看所有注册用户信息及其对话记录。\n- 热词统计模块基于消息内容自动分词并统计高频词，辅助分析用户关注重点。\n\n### 🌗 界面交互与体验优化\n- “AI 正在输入...” 动画提示，模拟真实对话过程。\n- 自适应暗/亮主题切换。\n- 所有操作状态反馈明确（如上传进度、索引刷新结果、异常提示等）。\n\n---\n\n## 技术栈\n\n### 🧠 后端技术\n\n- **Python 3.9+**：主要开发语言，结合 FastAPI 与 LangChain 构建 AI 应用后端。\n- **FastAPI**：高性能 Web API 框架，提供接口服务。\n- **LangChain**：用于构建 RAG（检索增强生成）问答流程。\n- **Ollama + bge-m3**：本地部署的文本嵌入模型，用于生成向量。\n- **FAISS**：Facebook 提供的高效向量索引与相似度搜索引擎。\n- **DeepSeek API**：调用远程大语言模型，为用户问题生成自然语言回答。\n- **SQLite**：轻量级数据库，管理用户、会话与消息等数据。\n- **pypdf / TextLoader**：加载并解析 PDF 与 TXT 格式文档作为知识库内容。\n- **Uvicorn**：ASGI 服务器，搭配 FastAPI 启动服务。\n- **python-dotenv**：用于读取和管理 `.env` 环境变量配置。\n\n### 💻 前端技术\n\n- **Vue 3**：构建现代化、响应式用户界面。\n- **Element Plus**：Vue 3 UI 组件库，提供丰富的前端组件支持。\n- **Axios**：发送异步请求，与后端 API 进行数据通信。\n- **Marked + DOMPurify**：解析并安全渲染 AI 回复中的 Markdown 内容。\n- **主题切换机制**：支持亮色 / 暗色主题，改善用户体验。\n\n### 🛠 开发环境与工具\n\n- **Visual Studio Code (VSCode)**：主力开发工具，支持前后端代码高效编写与调试。\n- **Node.js LTS**：前端构建与运行环境，推荐使用稳定版。\n- **Conda / pip**：管理 Python 依赖环境。\n- **Git \u0026 GitHub**：版本控制与协作开发平台。\n\n---\n\n## 项目结构\n\n```\nGadgetGuide_AI_Project/\n├── backend/                  # 后端 FastAPI 应用\n│   ├── main.py               # 应用入口\n│   ├── config.py             # 配置信息\n│   ├── database.py           # 数据库连接与初始化\n│   ├── init_admin.py         # 初始管理员创建脚本\n│   ├── knowledge_base_processor.py  # 知识库构建与管理模块\n│   ├── qa_handler.py         # 问答处理逻辑（包含上下文检索、对比问答等）\n│   ├── qa_schemas.py         # 问答接口的数据模型定义\n│   ├── uploads/              # 用户上传的知识库文档\n│   ├── faiss_index/          # FAISS 索引文件存储位置\n│   ├── users.db              # SQLite 数据库文件\n│   ├── auth/                 # 用户认证模块\n│   │   ├── routes.py         # 注册、登录等 API 路由\n│   │   ├── models.py         # 用户数据模型\n│   │   ├── crud.py           # 数据库操作函数\n│   │   ├── schemas.py        # 请求/响应数据结构定义\n│   ├── chat/                 # 聊天记录系统\n│   │   ├── routes.py         # 会话与消息 API\n│   │   ├── models.py         # 会话与消息数据库模型\n│   │   ├── crud.py           # 聊天记录相关数据库操作\n│   ├── admin/                # 管理员功能模块\n│   │   └── routes.py         # 用户管理、文件管理、索引刷新、热词统计等\n│   └── requirements.txt      # Python 依赖列表\n\n├── frontend/                 # 前端 Vue 3 应用\n│   ├── index.html            # 入口 HTML 文件\n│   ├── package.json          # 项目依赖配置\n│   ├── src/\n│   │   ├── App.vue           # 应用主组件\n│   │   ├── main.ts           # 应用入口逻辑\n│   │   ├── assets/           # 样式与资源（如主题切换样式等）\n│   │   ├── components/       # 页面组件（聊天窗、消息气泡、动画等）\n│   │   ├── views/            # 路由视图（聊天页、后台管理页等）\n│   │   ├── router/           # Vue Router 配置\n│   │   ├── stores/           # Pinia 状态管理模块（如用户状态、会话管理）\n│   │   └── types/            # 类型定义\n│   └── vite.config.ts        # 前端构建配置\n\n├── LICENSE\n├── README.md\n└── structure.txt             # 项目结构导出（仅文档用）\n```\n\n---\n\n## 环境搭建与运行指南\n\n### 1. 先决条件\n\n请确保你的开发环境已具备以下组件：\n\n- **Python ≥ 3.9**（建议使用 Conda 管理虚拟环境）\n\n- **Node.js ≥ 18.x**（建议通过 NVM 安装 LTS 版本）\n\n- **Ollama**（本地嵌入模型，已拉取 bge-m3）\n\n- **DeepSeek API Key**（需要提前申请并配置）\n\n- **Git**（用于克隆项目）\n\n### 2. 后端设置与启动\n\n1. **克隆仓库/准备项目文件**\n   ```bash\n   git clone https://github.com/zysyy/GadgetGuide_AI-.git\n   cd GadgetGuide_AI-\n    ```\n2. **Conda 环境激活**\n    ```bash\n    conda activate aihomework  # (或使用你的 Conda 环境名)\n    ```\n3. **安装 Python 依赖**\n    ```bash\n    cd backend\n    pip install -r requirements.txt\n    ```\n4. **创建并配置 .env 文件**\n    在 backend/ 目录下创建 .env 文件，内容如下（替换为你自己的 API Key）：\n    ```env\n    DEEPSEEK_API_KEY=\"your_actual_deepseek_api_key\"\n    ```\n5. **准备知识库源文件**\n    将你的 .txt 或 .pdf 格式知识文件放入以下目录中：\n    ```bash\n    backend/uploads/\n    ```\n6. **启动 FastAPI 后端服务**\n    回到项目根目录，运行：\n    ```bash\n    uvicorn backend.main:app --reload --port 8000\n    ```\n    成功后，API 文档地址为： http://127.0.0.1:8000/docs\n7. **构建知识库索引**\n   ✅ 方式一（推荐）：上传文档触发索引\n\n        打开 http://127.0.0.1:8000/docs\n\n        使用 POST /admin/upload-documents/ 接口上传文档，即可自动建立或刷新索引。\n\n    ⚙️ 方式二（快速测试）：直接构建索引\n\n        调用 POST /admin/refresh-index 接口（无需传参），系统将基于当前 uploads/ 文件夹中全部文件进行索引重建。\n\n    构建完成后，控制台将输出日志确认处理状态。\n\n### 3. 前端设置与启动\n\n1. **进入前端项目目录**\n   ```bash\n   cd frontend\n   ```\n2. **安装依赖**\n    项目基于 Vue 3 + Vite 开发，使用以下命令安装所需依赖：\n    ```bash\n    npm install\n    # 或使用 yarn（如果已安装）\n    # yarn install\n   ```\n3. **运行开发服务器**\n    启动前端开发服务器：\n    ```bash\n    npm run dev\n    # 或 yarn dev\n    ```\n4. **访问页面**\n    在浏览器中访问：\n    ```\n    http://localhost:5173\n    ```\n    默认界面为登录界面\n5. **其他说明**\n    - 若你修改了 API 地址或端口（如后端部署在远程服务器），请在 frontend/src/config.ts 中调整 API_BASE 常量；\n\n    - 系统支持亮暗主题切换，可通过右上角按钮快速切换界面风格；\n\n    - 管理员可通过前端导航进入“后台管理”模块，上传知识文档、查看热词、管理用户数据等。\n## API 端点（通过 FastAPI `/docs` 页面可交互测试）\n\n系统提供以下主要 API 接口，前后端交互及管理员操作均基于这些端点实现：\n\n### 用户问答相关（公开接口）\n- `POST /ask`  \n  用户提问主接口，接收自然语言问题并返回基于知识库或 AI 的回答。\n\n- `POST /retrieve_context`  \n  （调试用）仅返回知识库检索到的上下文内容，用于排查问题或优化回答。\n\n\n\n### 文件上传与知识库管理（需管理员权限）\n- `POST /admin/upload-documents/`  \n  上传新的 `.pdf` / `.txt` 文档，并重建知识库索引。\n\n- `POST /admin/refresh-index`  \n  不上传文件，仅基于当前 `uploads/` 目录中所有文件刷新知识库索引。\n\n- `GET /admin/uploaded-files`  \n  获取所有已上传文档的列表（含文件名、大小与上传时间）。\n\n- `DELETE /admin/uploaded-files/{filename}`  \n  删除指定上传文档，并刷新索引。\n\n\n\n### 会话与聊天记录管理（需登录）\n- `GET /admin/users`  \n  获取所有注册用户列表（仅管理员）。\n\n- `GET /admin/users/{user_id}/conversations`  \n  查看某个用户的所有会话（仅管理员）。\n\n- `GET /admin/conversations/{conversation_id}/messages`  \n  获取指定会话中的所有消息内容（仅管理员）。\n\n\n\n### 统计分析（需管理员权限）\n- `GET /admin/hot-words?top_n=30`  \n  统计当前所有聊天记录中的高频词（用于知识库补全参考）。\n\n---\n\n## 未来工作 (TODO)\n\n- **知识库多格式支持：** 当前系统支持 `.txt` 与 `.pdf` 格式文档上传，未来计划扩展至 `.docx`、`.md` 等主流文档类型，增强文档兼容性与来源多样性。\n- **知识自动补全机制：** 基于热词统计结果，智能分析用户关注高频词与知识盲区，辅助管理员自动推荐/抓取外部资料，提升知识覆盖率。\n- **大模型调用接口抽象化：** 当前系统使用 DeepSeek API 提供问答能力，后续计划抽象模型调用接口，允许用户自由选择本地部署模型或其他云端大模型（如 ChatGLM、通义千问等），提升灵活性与可扩展性。\n- **垂直场景拓展：** 除电子产品外，可逐步扩展至教育问答、法律咨询、医学导诊等垂直领域，通过更换知识源构建模块化智能问答平台。\n- **图像与语音输入支持：** 为提升多模态交互能力，系统计划引入图像上传识别与语音识别功能，拓展用户输入方式，优化用户体验。\n- **前端界面优化与适配：** 持续优化响应式布局与用户交互动画，提升在不同分辨率设备上的可用性；引入主题个性化设置与快捷操作组件。\n- **用户权限与日志系统：** 加强用户权限控制体系（如多级管理员支持）与日志审计功能，便于系统运维与安全管理。\n- **性能与稳定性提升：** 进一步优化嵌入生成、索引构建等流程的性能表现，支持更大规模文档的处理与更高并发访问。\n\n---\n\n作者：The_Riddler\n日期：2025年6月16日 ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzysyy%2Fgadgetguide_ai-","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzysyy%2Fgadgetguide_ai-","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzysyy%2Fgadgetguide_ai-/lists"}