# 个人知识库 AI 问答助手

**Repository Path**: kngines/ai-knowledge-agent

## Basic Information

- **Project Name**: 个人知识库 AI 问答助手
- **Description**: 「个人知识库 AI 问答助手」
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-27
- **Last Updated**: 2026-04-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🤖 AI 知识库问答助手

> 基于 RAG（检索增强生成）技术的本地知识库问答系统，支持上传文档后用自然语言提问。

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://python.org)
[![LangChain](https://img.shields.io/badge/LangChain-0.3+-green.svg)](https://langchain.com)
[![Ollama](https://img.shields.io/badge/LLM-Ollama-orange.svg)](https://ollama.com)
[![ChromaDB](https://img.shields.io/badge/VectorDB-ChromaDB-purple.svg)](https://chromadb.com)
[![Gradio](https://img.shields.io/badge/UI-Gradio-yellow.svg)](https://gradio.app)

## ✨ 功能特性

- 📄 **多格式文档支持**：PDF、TXT、Markdown、Word (.docx)
- 🔍 **语义检索**：基于 BGE 中文向量模型，理解语义而非关键词匹配
- 🤖 **智能问答**：接入 Ollama 本地 LLM，完全离线运行，无需 API Key
- 💾 **持久化存储**：ChromaDB 本地向量库，重启不丢失
- 🌐 **Web 界面**：Gradio 搭建的简洁 UI，开箱即用
- 📜 **多轮对话**：支持上下文关联的连续对话
- ⚡ **流式输出**：打字机效果，实时显示回答生成过程


## 🏗️ 技术架构

```
用户提问
   ↓
BGE Embedding 向量化问题
   ↓
ChromaDB 向量相似度检索
   ↓
召回最相关的 Top-K 文档块
   ↓
构建 RAG Prompt（文档 + 问题）
   ↓
Ollama LLM 生成回答（本地运行）
   ↓
返回答案 + 来源标注
```

## 📁 项目结构

```
ai-knowledge-agent/
├── app.py                  # Gradio 主程序入口
├── requirements.txt        # 依赖清单
├── .env.example            # 环境变量示例
├── .gitignore
├── src/
│   ├── config.py           # 配置管理
│   ├── document_loader.py  # 文档加载与分块
│   ├── knowledge_base.py   # ChromaDB 向量知识库
│   ├── llm.py              # DeepSeek LLM 封装
│   └── agent.py            # RAG Agent 核心逻辑
├── data/
│   ├── uploads/            # 上传的原始文档
│   └── vectordb/           # ChromaDB 向量数据库
└── docs/                   # 项目文档
```

## 🚀 快速开始

### 1. 克隆项目

```bash
git clone https://gitee.com/your-username/ai-knowledge-agent.git
cd ai-knowledge-agent
```

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

> 💡 首次运行会自动下载 BGE Embedding 模型（约 100MB）

### 3. 安装 Ollama（如未安装）

**Windows 系统：**
1. 访问 [https://ollama.com/download](https://ollama.com/download)
2. 下载安装程序并安装
3. 下载模型：`ollama pull qwen:7b`
4. 启动服务：`ollama serve`

**Linux / macOS：**
curl -fsSL https://ollama.com/install.sh | sh 
ollama pull qwen:7b 
ollama serve


### 4. 配置环境变量
cp .env.example .env

编辑 `.env` 文件（如需自定义配置）：

OLLAMA_BASE_URL=http://localhost:11434 
LLM_MODEL=qwen:7b

> 💡 默认配置已就绪，通常无需修改
> 
> 🔑 可选模型：`qwen:3b`, `qwen:7b`, `llama2`, `mistral`, `gemma:7b` 等

## 📖 使用说明

1. **启动 Ollama 服务**（如未启动）
   ollama serve

2. **启动应用**
   python app.py

   浏览器自动打开 `http://localhost:7860`

3. **上传文档**：在左侧选择文件（支持多选），点击「添加到知识库」
4. **等待索引**：系统会自动对文档进行向量化处理（显示进度）
5. **开始提问**：在右侧输入框输入问题，回车发送
6. **查看来源**：回答末尾会标注参考的文档来源
7. **管理知识库**：支持刷新状态、删除文档、清空知识库


## ⚙️ 配置说明

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama 服务地址 |
| `LLM_MODEL` | `qwen:7b` | 使用的 Ollama 模型 |
| `EMBEDDING_MODEL` | `BAAI/bge-small-zh-v1.5` | Embedding 模型 |
| `TOP_K` | `5` | 检索返回的文档块数量 |
| `CHUNK_SIZE` | `500` | 文档分块大小（字符数） |
| `CHUNK_OVERLAP` | `50` | 相邻块重叠字符数 |

## ❓ 常见问题

### Q: 提示 "model not found"？
A: 使用 `ollama pull <模型名>` 下载模型，或修改 `.env` 中的 `LLM_MODEL`

推荐模型：
- `qwen:7b` - 通义千问 7B（中文效果好，推荐）
- `qwen:3b` - 通义千问 3B（速度快）
- `llama2` - Llama 2（英文效果好）

### Q: Embedding 模型下载失败？
A: 会自动降级使用备用模型，或使用代理加速下载

### Q: 如何清空知识库？
A: 点击界面上的「🗑️ 清空知识库」按钮

### Q: 支持哪些文件格式？
A: PDF、TXT、Markdown (.md)、Word (.docx)

### Q: 可以联网使用吗？
A: 完全本地运行，无需联网（除首次下载模型外）

## 🛠️ 开发计划

- [ ] 支持网页 URL 作为知识来源
- [ ] 添加文档标签和分类管理
- [ ] 支持 Ollama 本地模型（离线使用）
- [ ] 添加问答历史导出功能
- [ ] 多知识库切换支持
- [ ] Docker 一键部署

## 🤝 贡献

欢迎提交 Issue 和 PR！

1. Fork 本仓库
2. 创建功能分支：`git checkout -b feature/your-feature`
3. 提交更改：`git commit -m 'feat: add some feature'`
4. 推送分支：`git push origin feature/your-feature`
5. 提交 Pull Request

## 📄 License

MIT License © 2026

---
> 💡 **学习资源**：[LangChain 文档](https://python.langchain.com) | [Ollama 官网](https://ollama.com) | [ChromaDB 文档](https://docs.trychroma.com)