# knowledge_qa

**Repository Path**: karentwan/knowledge_qa

## Basic Information

- **Project Name**: knowledge_qa
- **Description**: 基于LangChain+MCP+RAG的知识问答系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-24
- **Last Updated**: 2025-12-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 知识问答系统 (Knowledge QA System)

基于 **LangChain + MCP + RAG** 架构的智能知识问答系统。

## 系统架构

```
┌─────────────────────────────────────────────────────────────┐
│                      用户接口层                              │
├─────────────┬─────────────┬─────────────┬──────────────────┤
│  CLI 命令行 │  REST API   │  MCP 服务   │    交互式对话     │
└─────────────┴─────────────┴─────────────┴──────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                      RAG 核心层                              │
├─────────────────────────────────────────────────────────────┤
│  文档加载器 → 文本分割 → 向量嵌入 → 相似度检索 → LLM 生成   │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                      存储层                                  │
├──────────────────────┬──────────────────────────────────────┤
│   ChromaDB / FAISS   │        知识库文档                    │
│     (向量存储)        │    (PDF/Word/MD/TXT)                │
└──────────────────────┴──────────────────────────────────────┘
```

## 功能特性

- 📚 **多格式文档支持**: PDF、Word (.docx)、Markdown、TXT
- 🔍 **智能语义检索**: 基于向量相似度的精准检索
- 🤖 **多 LLM 支持**: OpenAI、Ollama (本地部署)
- 🔧 **MCP 协议支持**: 可作为 AI 工具被调用
- 🌐 **REST API**: 完整的 HTTP 接口
- 💬 **多轮对话**: 支持上下文的连续对话
- ⚡ **高性能**: 支持 ChromaDB 和 FAISS 向量数据库

## 快速开始

### 1. 安装依赖

```bash
cd /opt/inference/knowledge_qa
pip install -r requirements.txt
```

### 2. 配置系统

复制配置模板并修改：

```bash
cp .env.example .env
# 编辑 .env 文件，配置 LLM 和其他参数
```

主要配置项：

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `LLM_PROVIDER` | LLM 提供商 | `ollama` |
| `OLLAMA_MODEL` | Ollama 模型 | `qwen2.5:7b` |
| `OPENAI_API_KEY` | OpenAI API Key | - |
| `EMBEDDING_MODEL` | 嵌入模型 | `paraphrase-multilingual-MiniLM-L12-v2` |
| `CHUNK_SIZE` | 文本分块大小 | `500` |
| `TOP_K` | 检索结果数量 | `4` |

### 3. 添加知识库文档

将文档放入 `knowledge_base` 目录：

```bash
mkdir -p knowledge_base
cp your_documents.pdf knowledge_base/
```

### 4. 构建索引

```bash
python main.py build
```

### 5. 开始使用

```bash
# 查询问答
python main.py query "你的问题"

# 交互式对话
python main.py chat

# 启动 API 服务
python main.py server
```

## 使用方式

### 命令行 (CLI)

```bash
# 查看帮助
python main.py --help

# 构建/重建索引
python main.py build
python main.py build --rebuild  # 重建

# 问答查询
python main.py query "什么是机器学习？"
python main.py query "什么是深度学习？" --no-llm  # 仅检索
python main.py query "问题" --show-sources  # 显示来源

# 搜索
python main.py search "关键词"

# 交互式对话
python main.py chat

# 查看状态
python main.py status
```

### REST API

启动 API 服务：

```bash
python main.py server
```

API 端点：

| 端点 | 方法 | 说明 |
|------|------|------|
| `/` | GET | API 信息 |
| `/health` | GET | 健康检查 |
| `/query` | POST | 知识问答 |
| `/search` | POST | 知识库搜索 |
| `/chat` | POST | 多轮对话 |
| `/documents/add` | POST | 添加文档 |
| `/documents/upload` | POST | 上传文档 |
| `/index/build` | POST | 构建索引 |
| `/index/status` | GET | 索引状态 |

示例请求：

```bash
# 问答
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"question": "什么是机器学习？"}'

# 搜索
curl -X POST http://localhost:8000/search \
  -H "Content-Type: application/json" \
  -d '{"query": "机器学习", "top_k": 5}'
```

API 文档访问: http://localhost:8000/docs

### MCP 服务

启动 MCP 服务（用于 AI 工具调用）：

```bash
python main.py mcp
```

MCP 提供的工具：

- `search_knowledge_base`: 搜索知识库
- `add_document`: 添加文档
- `list_knowledge_sources`: 列出文档来源
- `rebuild_index`: 重建索引

在 Claude Desktop 或其他支持 MCP 的客户端中配置：

```json
{
  "mcpServers": {
    "knowledge-qa": {
      "command": "python",
      "args": ["/opt/inference/knowledge_qa/mcp_server.py"]
    }
  }
}
```

## 项目结构

```
knowledge_qa/
├── config.py            # 配置管理
├── document_loader.py   # 文档加载和分割
├── vector_store.py      # 向量存储管理
├── rag_chain.py         # RAG 问答链
├── mcp_server.py        # MCP 服务器
├── api_server.py        # REST API 服务
├── main.py              # 主程序入口
├── requirements.txt     # Python 依赖
├── .env.example         # 配置模板
├── knowledge_base/      # 知识库文档目录
└── vector_store/        # 向量索引存储目录
```

## 进阶配置

### 使用 vLLM (推荐，GPU 加速)

vLLM 是高性能的 LLM 推理引擎，支持 GPU 加速，推荐用于生产环境。

**1. 启动 vLLM 服务：**

```bash
# 使用提供的启动脚本
chmod +x start_vllm.sh
./start_vllm.sh

# 或手动启动
python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-7B-Instruct \
    --host 0.0.0.0 \
    --port 8080 \
    --gpu-memory-utilization 0.9
```

**2. 配置 .env：**

```env
LLM_PROVIDER=vllm
VLLM_BASE_URL=http://localhost:8080/v1
VLLM_MODEL=Qwen/Qwen2.5-7B-Instruct
VLLM_API_KEY=EMPTY
VLLM_MAX_TOKENS=2048
VLLM_TEMPERATURE=0.7

# 嵌入模型也使用 GPU
EMBEDDING_MODEL=BAAI/bge-base-zh-v1.5
EMBEDDING_DEVICE=cuda
```

**支持的模型：**
- Qwen/Qwen2.5-7B-Instruct (推荐中文)
- meta-llama/Llama-3.1-8B-Instruct
- mistralai/Mistral-7B-Instruct-v0.3
- 其他 HuggingFace 上的开源模型

### 使用 OpenAI

```env
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-api-key
OPENAI_MODEL=gpt-4
```

### 使用本地 Ollama

1. 安装 Ollama: https://ollama.ai
2. 下载模型: `ollama pull qwen2.5:7b`
3. 配置:

```env
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen2.5:7b
```

### GPU 加速配置

系统默认使用 GPU 加速：

```env
# 嵌入模型使用 GPU
EMBEDDING_DEVICE=cuda

# 向量数据库使用 GPU 版本 FAISS
VECTOR_DB_TYPE=faiss
```

### 更换向量数据库

```env
# 使用 FAISS-GPU (更快的检索)
VECTOR_DB_TYPE=faiss

# 使用 ChromaDB (默认，支持元数据过滤)
VECTOR_DB_TYPE=chroma
```

## 常见问题

### Q: 索引构建很慢？
A: 首次运行需要下载嵌入模型，请耐心等待。后续会使用缓存。

### Q: LLM 连接失败？
A: 检查 LLM 配置，确保 Ollama 服务已启动或 OpenAI API Key 正确。

### Q: 检索结果不准确？
A: 尝试调整 `CHUNK_SIZE` 和 `CHUNK_OVERLAP` 参数，或增加 `TOP_K` 值。

### Q: 如何添加新文档？
A: 将文档放入 `knowledge_base` 目录，然后运行 `python main.py build --rebuild`。

## 许可证

MIT License