知识库问答助手 (Knowledge Base QA Agent)

一个基于大模型的智能知识库问答系统，支持文档管理、多轮对话、AI 自动工具调用、长期记忆和 ReAct 推理。

✨ 功能

• 📄 文档知识库：上传 PDF / DOCX / TXT，自动向量化存入本地 ChromaDB，基于文档内容问答
• 🔧 AI 工具调用：AI 根据问题自动判断并调用工具（时间日期、网络搜索、天气查询、新闻、Python 代码执行）
• 🧩 可扩展工具系统：在 src/tools/builtin/ 下新建 .py 文件、继承 BaseTool 即可动态添加工具
• 🧠 长短期记忆：短期对话上下文 + 长期记忆（ChromaDB 持久化），自动提取重要事实，冲突检测与消除
• 🛡️ 代码沙箱：subprocess 隔离执行 Python 代码，超时自动终止，危险模块拦截
• 🔄 ReAct 推理：思考→行动→观察 多轮推理，轮数可配，过程实时可视
• 💾 断点恢复：推理中断后自动保存断点，下次启动提示恢复，API 调用自动重试
• 🌐 中文优化：DeepSeek 大模型 + 中文向量模型，对中文场景深度优化

🚀 快速开始

环境要求

• Python 3.10+
• Windows / macOS / Linux

安装

# 克隆仓库
git clone https://github.com/your-username/knowledge-base-qa.git
cd knowledge-base-qa

# 创建虚拟环境（推荐）
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt

获取 API Key

1. 访问 platform.deepseek.com 注册
2. 在 API Keys 页面创建 Key
3. 复制 Key（格式：sk-xxxxxxxxxxxxxxxx）

启动

streamlit run app.py

浏览器自动打开 http://localhost:8501。

使用步骤

1. 左侧输入 DeepSeek API Key
2. 上传文档（PDF / DOCX / TXT）
3. 点击「向量化全部」
4. 开始提问

📂 项目结构

knowledge_base_qa/
├── app.py                   # Streamlit 主界面
├── requirements.txt         # Python 依赖
├── .env.example             # API Key 模板
├── src/
│   ├── config.py            # 全局配置
│   ├── document_loader.py   # 文档加载（PDF/DOCX/TXT）
│   ├── vector_store.py      # ChromaDB 向量存储
│   ├── qa.py                # 问答编排器
│   ├── memory.py            # 长短期记忆系统
│   ├── sandbox.py           # 代码沙箱
│   ├── react.py             # ReAct 循环 + 断点恢复
│   └── tools/
│       ├── base.py          # 工具基类
│       ├── registry.py      # 工具注册中心
│       └── builtin/         # 内置工具
│           ├── datetime_tool.py  # 时间日期
│           ├── search_tool.py    # 网络搜索
│           ├── weather_tool.py   # 天气查询
│           └── news_tool.py      # 新闻头条
└── data/                    # 运行时数据（自动生成）
    ├── uploads/             # 上传的文档
    ├── chroma_db/           # 知识库向量
    ├── memory_db/           # 长期记忆向量
    └── checkpoints/         # 断点文件

🔧 扩展工具

在 src/tools/builtin/ 下新建 Python 文件，继承 BaseTool：

from src.tools.base import BaseTool

class MyTool(BaseTool):
    name = "my_tool"
    description = "我的自定义工具，用于..."
    parameters = {
        "type": "object",
        "properties": {
            "param1": {"type": "string", "description": "参数说明"},
        },
        "required": ["param1"],
    }

    def execute(self, param1: str = "", **kwargs) -> str:
        # 实现你的逻辑
        return f"结果: {param1}"

重启应用即可自动发现并注册新工具。

🛠️ 技术栈

组件	技术
界面	Streamlit
大模型	DeepSeek (API)
向量数据库	ChromaDB
向量模型	BAAI/bge-small-zh-v1.5
文档解析	PyMuPDF / python-docx
搜索	DuckDuckGo
天气	wttr.in
沙箱	subprocess 隔离

📝 License

MIT