一、软件面向的行业和业务场景
本项目是一款专为 Windows 环境设计的完全本地化 AI 智能助手，核心特点是无需网络连接、数据全程在本地处理，能保障用户隐私与数据安全。
其面向的行业和业务场景主要包括：
企业内部办公场景：企业员工可利用该助手进行内部文档的智能问答（如快速检索合同条款、项目方案细节）、基于对话内容生成汇报用的 Markdown 或 PPTX 文件，提升办公效率。
个人知识管理场景：个人用户可通过上传各类文档（PDF、Word、PowerPoint 等）构建私人知识库，实现对知识的快速查询与整理，满足学习、研究过程中的信息检索需求。
对数据安全要求高的领域：如金融、医疗等行业，由于其数据敏感性，需在本地处理信息，该助手可在不泄露数据的前提下，提供智能问答与文档处理服务。
二、项目功能模块及具体功能
1. 前端功能模块
核心视图模块：以 MainView.vue 作为单页面主界面，整合 “智能问答” 和 “知识库问答” 模式，支持模式切换，动态展示不同 UI 组件。
对话历史管理模块：通过 SidebarHistory.vue 组件展示和管理对话历史，借助 historyStorage.js 脚本将对话历史以 JSON 格式存储在浏览器 localStorage 中，确保用户关闭或刷新浏览器后历史记录不丢失。
功能操作模块：提供 FunctionButtons.vue 组件，支持 “生成 PPTX”“生成 MD” 等文件生成功能，用户可在对话后一键生成并下载相应格式文件。
文件上传模块：在 “知识库问答” 模式下支持上传 PDF、Word、PowerPoint 等格式文档，用于构建知识库。
2. 后端功能模块
API 服务模块：基于 FastAPI 构建，定义 /chat、/upload 等 API 路由和端点，处理前端的请求交互。
RAG 与聊天核心服务模块（rag_service.py）：实现文档处理（调用 document_service.py 将上传文档解析为纯文本并分块）、向量化（调用向量服务将文本块转换为向量存储到 Qdrant 数据库）、RAG 查询（用户提问时，将问题向量化并检索相关文档片段，结合问题生成回答）、流式响应（实时返回思考过程和最终答案，降低用户感知延迟）等核心功能。
Ollama 模型服务模块（ollama_model_service.py）：封装与本地 Ollama 服务的 HTTP 交互，提供流式聊天（chat_completion_stream）和文本嵌入（create_embeddings）方法，支持通过配置文件灵活切换聊天模型和嵌入模型。
文档解析服务模块（document_service.py）：利用 pypdf、python-docx、python-pptx 等库，提取 PDF、Word、PowerPoint 等格式文档的文本内容。
向量数据库服务模块（vector_service.py 和 large_file_vector_service.py）：封装与 Qdrant 向量数据库的交互，提供添加向量、检索向量、删除集合等操作，其中 large_file_vector_service.py 专为大文件设计，避免与标准文档相互干扰。
文件生成服务模块（file_generation_service.py）：从对话历史中提取关键信息和结构，使用 python-pptx 和 markdown 库生成 PPTX 或 Markdown 文件，保存至 backend/outputs 目录并供前端下载。
3. 数据管理模块
数据存储模块：负责管理各类数据的存储位置，如用户上传的临时文件存于 backend/uploads，解析后的文档纯文本缓存于 backend/text_storage，向量数据存于 qdrant/storage，AI 生成文件存于 backend/outputs 等。
数据备份与恢复模块：提供 备份数据.bat 脚本，可一键备份向量数据、生成文件、日志等关键数据到 bf/ 目录，支持手动恢复操作。
三、项目的技术选型和架构特点
1. 技术选型
前端：
核心框架：Vue 3.3.8
构建工具：Vite 4.5.0
UI 组件库：Element Plus 2.4.2
路由：Vue Router 4.2.5
HTTP 请求：axios 1.6.2
后端：
Web 框架：FastAPI 0.104.1（Python）
ASGI 服务器：Uvicorn 0.24.0
实时通信：WebSockets 12.0
AI / 模型层：
模型服务：Ollama（运行和管理本地大语言模型）
聊天模型：deepseek-r1:8b（通过 Ollama 调用）
嵌入模型：dengcao/Qwen3-Embedding-4B:Q4_K_M（通过 Ollama 调用）
向量数据库：Qdrant 1.9.0（本地部署）
文档解析：pypdf 4.0.1、python-docx 1.1.0、python-pptx 0.6.23
文件生成：python-pptx、markdown
2. 架构特点
完全本地化架构：所有数据处理（文档解析、模型推理、向量存储等）和存储均在本地完成，无需网络连接，保障用户隐私与数据安全，且不依赖外部 API 或云服务，实现自主可控。
前后端分离架构：前端基于 Vue3 构建用户交互界面，通过 axios 与后端 API 通信；后端基于 FastAPI 提供服务，实现业务逻辑与数据处理，两者松耦合，便于独立开发与维护。
模块化设计：项目按功能划分为前端视图组件、后端服务模块、AI / 模型层模块等，各模块职责清晰，内聚性高，如后端 services 目录集中处理核心业务逻辑，便于代码复用与扩展。
高性能优化：通过动态调整 RAG 上下文长度和搜索参数、优化 API 通信（使用相对路径解决跨域问题）、模型输出净化（移除冗余标签和思考过程）等策略提升性能；Ollama 支持 GPU 加速，可显著提升模型推理速度。
健壮性设计：采用多层容错机制和多重回退策略确保系统稳定运行；配置中心化（集中于 backend/app/core/config.py），便于管理模型路径、加载参数等关键配置；完善的日志系统（backend/logs/app.log）便于问题排查。
便捷部署与迁移：提供 一键启动.bat 脚本，自动按顺序启动所有服务；项目采用完全集成化设计，运行环境（Python、Node.js）和数据（Qdrant）内置于目录中，迁移过程简单，类似 “绿色软件” 的复制粘贴。
