RAG-system

一个面向本地文档问答的轻量化 RAG 系统。项目支持上传 PDF、Word、Excel 文档，自动完成文本解析、清洗分块、向量化入库、语义检索，并通过本地 Ollama 大模型生成基于文档内容的回答。

功能特性

• 多格式文档解析：支持 PDF、DOCX、XLSX/XLS 文件。
• 文本预处理：自动清洗空白、控制字符和无效内容，并按语义边界分块。
• 本地向量检索：使用 BAAI/bge-small-zh-v1.5 生成文本向量，使用 Chroma 持久化存储。
• 本地大模型问答：通过 Ollama 调用 qwen3:4b 生成回答。
• 防幻觉机制：相似度阈值过滤 + 严格系统提示词，减少脱离文档的回答。
• 来源追踪：回答会展示参考来源，便于核对依据。
• Web 交互界面：基于 Streamlit，支持文档上传、参数调整、多会话管理、FAQ 管理和检索详情展示。
• 命令行入口：保留 CLI 版本，方便调试和基础演示。

技术栈

模块	技术
Web 界面	Streamlit
PDF 解析	pdfplumber
Word 解析	python-docx
Excel 解析	openpyxl
文本向量	sentence-transformers
嵌入模型	BAAI/bge-small-zh-v1.5
向量数据库	ChromaDB
大模型调用	Ollama
默认生成模型	qwen3:4b

系统流程

flowchart LR
    A[上传文档] --> B[文档解析]
    B --> C[文本清洗]
    C --> D[语义分块]
    D --> E[向量化]
    E --> F[Chroma 向量库]
    G[用户提问] --> H[问题向量化]
    H --> F
    F --> I[相似片段检索]
    I --> J{相似度达标?}
    J -- 否 --> K[拒答]
    J -- 是 --> L[构建 Prompt]
    L --> M[Ollama 大模型]
    M --> N[返回答案与来源]

Loading

目录结构

RAG-system/
├── app.py              # Streamlit Web 应用入口
├── main.py             # 命令行版本入口
├── config.py           # 模型、检索、分块、路径等集中配置
├── file_parser.py      # PDF / Word / Excel 文档解析
├── text_processor.py   # 文本清洗与分块
├── vector_store.py     # 向量化、Chroma 存储与语义检索
├── generator.py        # Ollama 调用与回答生成
├── faq.json            # 预置 FAQ 数据
├── requirements.txt    # Python 依赖
├── data/               # 示例文档
├── chroma_db/          # 本地向量数据库，默认不提交
└── chat_histories/     # 会话历史，默认不提交

环境要求

• Python 3.10 或更高版本
• Ollama
• 已下载本地大模型：qwen3:4b

安装 Ollama 后执行：

ollama pull qwen3:4b

安装步骤

1. 克隆项目：

git clone https://github.com/study-yang/RAG-system.git
cd RAG-system

2. 创建并激活虚拟环境：

python -m venv .venv

Windows PowerShell：

.\.venv\Scripts\Activate.ps1

macOS / Linux：

source .venv/bin/activate

3. 安装依赖：

pip install -r requirements.txt

使用方式

启动 Web 界面

streamlit run app.py

启动后浏览器会打开 Streamlit 页面，默认地址通常是：

http://localhost:8501

在页面中可以上传文档、管理已入库文件、调整检索参数、查看检索片段和继续多轮对话。

启动命令行版本

python main.py

命令行版本提供文档上传、提问、查看已入库文件、查看问答历史和删除文件数据等基础功能。

核心配置

主要配置集中在 config.py：

配置项	默认值	说明
MODEL_NAME	qwen3:4b	Ollama 本地生成模型
EMBEDDING_MODEL	BAAI/bge-small-zh-v1.5	文本嵌入模型
VECTOR_DB_DIR	chroma_db	Chroma 本地持久化目录
TOP_N	3	检索返回的相关片段数量
SIMILARITY_THRESHOLD	0.35	相似度拒答阈值
CHUNK_SIZE	400	文本分块目标长度
OVERLAP	50	相邻文本块重叠字符数
MAX_FILE_SIZE_MB	50	单个上传文件大小限制

防幻觉设计

项目采用两层约束：

1. 检索层约束：如果最高相似度低于 SIMILARITY_THRESHOLD，系统直接返回“根据已上传的文档，未找到相关内容。”
2. Prompt 层约束：系统提示词要求大模型只能依据参考资料回答，禁止猜测、编造或补充参考资料之外的信息。

这种设计可以让系统更适合课程项目、企业内部资料查询和本地知识库问答等需要可追溯答案的场景。

数据与隐私

• 文档向量默认存储在本地 chroma_db/。
• 会话历史默认存储在本地 chat_histories/。
• 上传文件默认存储在本地 uploads/。
• 上述目录已在 .gitignore 中忽略，不会默认提交到 GitHub。
• 生成回答依赖本地 Ollama 服务，文档内容不需要发送到第三方在线大模型接口。

常见问题

第一次运行很慢

第一次初始化嵌入模型时会下载 BAAI/bge-small-zh-v1.5，下载完成后会缓存在本地，后续启动会更快。

Ollama 调用失败

请确认 Ollama 服务已经启动，并且已经执行：

ollama pull qwen3:4b

如果更换了模型名称，需要同步修改 config.py 中的 MODEL_NAME。

Word 文档无法解析

当前仅支持 .docx 格式。老版本 .doc 文件需要先用 Word 或 WPS 另存为 .docx。

检索不到答案

可以检查以下内容：

• 文档是否已经成功入库。
• 问题是否确实能在文档中找到答案。
• SIMILARITY_THRESHOLD 是否设置过高。
• TOP_N 是否需要适当调大。

许可证

本项目目前未声明开源许可证。如需公开复用或二次分发，建议先补充明确的 License 文件。