# markdown_qa

**Repository Path**: mxyym/markdown_qa

## Basic Information

- **Project Name**: markdown_qa
- **Description**: Markdown知识库问答系统
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-25
- **Last Updated**: 2025-08-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: RAG

## README

# Markdown知识库问答系统

基于向量检索的智能文档问答系统，支持Markdown文件上传和URL导入。采用混合架构：本地中文嵌入模型 + 云厂商大模型 + TF-IDF快速备选方案，确保系统高可用性和响应速度。

## 核心特性

- 📚 **智能文档处理**: 支持Markdown文件上传和URL导入，自动分块（1000字符块，200字符重叠）
- 🔍 **多级检索策略**: 语义向量检索 + 关键词匹配 + 智能重排序
- 🤖 **混合AI架构**: 硅基流动云模型 + 阿里云通义千问 + TF-IDF快速备选
- 🏠 **本地嵌入优先**: 使用BGE-small-zh-v1.5预训练模型，支持离线运行
- ⚡ **高可用设计**: 云模型失败时自动切换到快速模式，确保系统可用性
- 💾 **高性能存储**: 基于ChromaDB的向量数据库，支持增量更新和持久化
- 🎨 **友好交互界面**: 基于Gradio的Web界面，支持实时对话和文档管理
- 🔧 **工厂模式架构**: 可扩展的多模型架构，易于集成新的AI提供商

## 快速开始

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

### 2. 配置环境变量
创建 `.env` 文件并配置：

```bash
# 本地嵌入模型配置
LOCAL_EMBEDDING_MODEL_PATH=models/bge-small-zh-v1.5

# 硅基流动云模型
SILICON_API_KEY=your_api_key
SILICON_API_URL=https://api.siliconflow.com/v1/chat/completions
SILICON_MODEL_NAME=silicon-llm

# 阿里云通义千问
ALIYUN_API_KEY=your_api_key
ALIYUN_API_BASE=https://dashscope.aliyuncs.com/api/v1
ALIYUN_MODEL_NAME=qwen2.5-7b-instruct
```

> ⚠️ **重要提醒**: 
> - 请将 `.env` 文件添加到 `.gitignore` 中，避免将敏感信息上传到版本库
> - 可以复制 `.env.example` 文件（如果存在）作为配置模板
> - 确保API密钥等敏感信息的安全性

### 3. 启动系统

#### 使用硅基流动云模型（推荐）
```bash
python start.py --provider silicon
```

#### 使用阿里云通义千问
```bash
python start.py --provider aliyun
```

#### 指定端口启动
```bash
python start.py --port 8080 --provider silicon
```

## 配置说明

### 启动参数

| 参数 | 说明 | 可选值 | 默认值 |
|------|------|--------|--------|
| `--provider` | 选择AI模型提供商 | `silicon`, `aliyun` | `silicon` |
| `--port` | 指定端口号 | 任意可用端口 | 7860 |
| `--host` | 服务器地址 | 任意IP地址 | 127.0.0.1 |

### 环境变量

| 变量名 | 说明 | 必需 | 默认值 |
|--------|------|------|--------|
| `LOCAL_EMBEDDING_MODEL_PATH` | 本地嵌入模型路径 | 是 | `models/bge-small-zh-v1.5` |
| `SILICON_API_KEY` | 硅基流动API密钥 | 是 | - |
| `SILICON_API_URL` | 硅基流动API地址 | 是 | `https://api.siliconflow.com/v1/chat/completions` |
| `SILICON_MODEL_NAME` | 硅基流动模型名称 | 否 | `silicon-llm` |
| `ALIYUN_API_KEY` | 阿里云API密钥 | 否 | - |
| `ALIYUN_API_BASE` | 阿里云API地址 | 否 | `https://dashscope.aliyuncs.com/api/v1` |
| `ALIYUN_MODEL_NAME` | 阿里云模型名称 | 否 | `qwen2.5-7b-instruct` |
| `QA_PROVIDER` | 默认AI提供商 | 否 | `silicon` |
| `PRELOAD_MODEL` | 是否预加载模型 | 否 | `true` |
| `FAST_MODE` | 是否启用快速模式 | 否 | `false` |
| `USE_LOCAL_EMBEDDINGS` | 是否使用本地嵌入 | 否 | `true` |

## 安全配置说明

### 环境变量保护
- `.env` 文件已添加到 `.gitignore`，不会被上传到版本库
- 请确保包含API密钥的配置文件不会意外提交
- 建议使用环境变量或安全的配置管理工具

### 敏感信息
- API密钥（SILICON_API_KEY, ALIYUN_API_KEY）
- 数据库连接字符串
- 服务器配置信息

## 项目结构

```
markdown_qa/
├── start.py              # 统一启动脚本
├── app.py                # 主程序（Gradio界面）
├── config.py             # 系统配置文件
├── deploy.py             # 部署脚本
├── requirements.txt      # Python依赖包
├── modules/              # 核心模块
│   ├── qa_factory.py     # 模型工厂（支持多种AI提供商）
│   ├── qa_silicon.py     # 硅基流动云模型实现
│   ├── qa_aliyun.py      # 阿里云通义千问实现
│   ├── qa_fast.py        # 快速模式（TF-IDF备选方案）
│   ├── document.py       # 文档处理（Markdown/URL解析）
│   └── vector.py         # 向量存储（ChromaDB + 本地嵌入）
├── models/               # 本地预训练模型
│   └── bge-small-zh-v1.5/  # 中文嵌入模型
└── vector_store/         # 向量数据库存储目录（运行时创建）
```

## 核心模块说明

### 文档处理模块 (`document.py`)
- **Markdown解析**: 支持.md和.markdown文件
- **智能分块**: 1000字符块大小，200字符重叠
- **URL导入**: 支持网页内容抓取和解析
- **文本清理**: 自动移除HTML标签，提取纯文本

### 向量存储模块 (`vector.py`)
- **本地嵌入**: 支持BGE-small-zh-v1.5预训练模型
- **TF-IDF备选**: 网络不可用时的本地向量化方案
- **ChromaDB**: 高性能向量数据库，支持持久化
- **智能检索**: 语义相似度 + 关键词匹配 + 重排序

### AI模型模块
- **硅基流动**: 高性能云模型，响应速度快
- **阿里云通义千问**: 支持qwen2.5-7b/14b-instruct模型
- **快速模式**: TF-IDF + 模板生成，确保系统可用性

### 工厂模式 (`qa_factory.py`)
- **动态选择**: 根据环境变量自动选择AI提供商
- **错误处理**: 自动回退到快速模式
- **扩展性**: 易于添加新的AI提供商

## 常见问题

### Q: 如何获得更好的中文嵌入效果？
A: 下载 `BAAI/bge-small-zh-v1.5` 模型并设置环境变量 `LOCAL_EMBEDDING_MODEL_PATH`

### Q: 如何添加新的云厂商？
A: 参考 `modules/qa_silicon.py` 实现，在工厂中添加新分支

### Q: 云模型API调用失败怎么办？
A: 系统会自动切换到快速模式，确保可用性

### Q: 支持哪些阿里云模型？
A: 支持qwen2.5-7b-instruct和qwen2.5-14b-instruct模型

### Q: 如何优化检索效果？
A: 调整文档块大小、重叠度，或使用更高质量的嵌入模型

## 许可证

MIT License