# knowledge-mcp-sever

**Repository Path**: chen-lexiang/knowledge-mcp-sever

## Basic Information

- **Project Name**: knowledge-mcp-sever
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-06-06
- **Last Updated**: 2025-12-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 知识库向量搜索服务器

一个基于 FastAPI 的知识库向量搜索服务，使用 Ollama BGE-M3 模型进行向量化，BGE-Reranker-V2-M3 进行重排序，Milvus 作为向量数据库。

## 🚀 功能特性

- **向量化存储**：使用 Ollama BGE-M3 模型将文档转换为向量并存储到 Milvus
- **语义搜索**：基于向量相似度的语义搜索
- **智能重排序**：使用 BGE-Reranker-V2-M3 模型对搜索结果进行重排序
- **多用户支持**：支持多用户文档管理，记录上传历史
- **文档上传记录**：完整记录用户文档上传过程和分段信息
- **PostgreSQL 存储**：使用 PostgreSQL 存储用户数据和文档记录
- **语义分段**：自动对长文档进行智能分段处理
- **REST API**：完整的 RESTful API 接口
- **Web 测试界面**：内置测试页面，方便调试和演示

## 🏗️ 系统架构

```
用户查询 → 向量化(BGE-M3) → 向量搜索(Milvus) → 重排序(BGE-Reranker) → 返回结果
```

## 📋 环境要求

- Python 3.8+
- Docker & Docker Compose
- PostgreSQL (用于存储用户数据和文档记录)
- Milvus (用于向量存储)
- Ollama (运行 BGE-M3 模型)
- BGE-Reranker-V2-M3 服务

## 🛠️ 安装部署

### 1. 克隆项目

```bash
git clone <repository-url>
cd knowledge-mcp-sever
```

### 2. 安装依赖

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

### 3. 启动数据库服务

```bash
# 启动 PostgreSQL 和 Milvus 数据库
docker-compose up -d
```

这会启动以下服务：
- PostgreSQL (端口 5432) - 用户数据和文档记录
- Milvus (端口 19530) - 向量数据库
- etcd 和 MinIO (Milvus 依赖)

### 4. 配置模型服务

确保以下服务正在运行：

- **Ollama BGE-M3**: `http://192.168.79.122:11434`
  ```bash
  ollama pull bge-m3:latest
  ```

- **BGE-Reranker-V2-M3**: `http://192.168.79.122:9997`

### 5. 启动服务

```bash
python run_server.py
```

服务将在 `http://localhost:8000` 启动。

## 📖 API 文档

启动服务后，访问以下地址：

- **API基础路径**: `/api`
- **API文档**: http://localhost:8000/docs  
- **替代文档**: http://localhost:8000/redoc
- **测试页面**: http://localhost:8000/static/index.html

### 主要接口模块

- **📄 文档管理** (`/api/documents`): 文档上传、处理和管理
- **📁 集合管理** (`/api/collections`): 向量集合的创建和管理  
- **🔍 搜索功能** (`/api/search`): 智能文档搜索
- **👤 用户管理** (`/api/users`): 用户数据和统计
- **⚙️ 系统管理** (`/api/admin`): 系统监控和管理

### 主要 API 端点

#### 创建集合
```http
POST /api/collections
Content-Type: application/json

{
  "name": "my_collection",
  "description": "我的知识库",
  "dimension": 1024
}
```

#### 插入文档（新增用户ID支持）
```http
POST /api/documents/batch
Content-Type: application/json

{
  "collection_name": "my_collection",
  "user_id": "user_123",
  "document_name": "我的文档",
  "documents": [
    {
      "content": "文档内容",
      "metadata": {
        "title": "文档标题",
        "category": "分类"
      }
    }
  ]
}
```

#### 从网页URL插入文档
```http
POST /api/documents/from-url
Content-Type: application/json

{
  "url": "https://example.com/article",
  "collection_name": "my_collection",
  "user_id": "user_123",
  "metadata": {
    "source": "网页抓取"
  }
}
```

#### 获取用户上传记录
```http
GET /api/users/user_123/upload-records?page=1&page_size=20
```

#### 获取用户统计信息
```http
GET /api/users/user_123/statistics
```

#### 搜索文档
```http
POST /api/search
Content-Type: application/json

{
  "collection_name": "my_collection",
  "query": "搜索查询",
  "limit": 5
}
```

## ⚙️ 配置说明

主要配置项在 `app/config.py` 中：

```python
# PostgreSQL 数据库配置
postgres_host: str = "localhost"
postgres_port: int = 5432
postgres_user: str = "postgres"
postgres_password: str = "postgres123"
postgres_db: str = "knowledge_db"

# Milvus 数据库配置
milvus_uri: str = "http://localhost:19530"

# 向量化模型配置
embedding_base_url: str = "http://192.168.79.122:11434"
embedding_model_name: str = "bge-m3:latest"

# 重排序模型配置
reranker_enabled: bool = True
reranker_base_url: str = "http://192.168.79.122:9997"
reranker_model_uid: str = "bge-reranker-v2-m3"
```

## 🔧 使用示例

### Python 客户端示例

```python
import requests

# 创建集合
response = requests.post("http://localhost:8000/api/v1/collections", json={
    "name": "test_kb",
    "description": "测试知识库",
    "dimension": 1024
})

# 插入文档
response = requests.post("http://localhost:8000/api/v1/documents", json={
    "collection_name": "test_kb",
    "user_id": "user_123",
    "document_name": "AI基础知识",
    "documents": [
        {
            "content": "人工智能是计算机科学的一个分支",
            "metadata": {"title": "AI简介", "category": "技术"}
        }
    ]
})

# 搜索文档
response = requests.post("http://localhost:8000/api/v1/search", json={
    "collection_name": "test_kb",
    "query": "人工智能",
    "limit": 5
})

print(response.json())
```

### cURL 示例

```bash
# 搜索文档
curl -X POST "http://localhost:8000/api/v1/search" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_name": "test_kb",
    "query": "人工智能",
    "limit": 5
  }'
```

## 📊 性能特点

- **向量维度**: 1024 (BGE-M3)
- **搜索延迟**: < 100ms (典型场景)
- **重排序**: 智能语义重排序，提升搜索准确性
- **并发支持**: 基于 FastAPI 的异步处理

## 🐛 故障排除

### 常见问题

1. **Milvus 连接失败**
   ```bash
   docker-compose down
   docker-compose up -d
   ```

2. **Ollama 模型未加载**
   ```bash
   ollama pull bge-m3:latest
   ```

3. **重排序服务不可用**
   - 检查 BGE-Reranker-V2-M3 服务状态
   - 确认端口 9997 可访问

### 日志查看

```bash
# 查看服务日志
python run_server.py

# 查看 Milvus 日志
docker-compose logs milvus-standalone
```

## 📝 更新日志

### v2.1.0
- 🎉 **新增多用户支持**：添加用户ID到所有API接口
- 🗄️ **PostgreSQL 集成**：新增用户数据和文档上传记录存储
- 📊 **文档上传记录**：完整记录用户文档上传历史和分段信息
- 📈 **用户统计**：提供用户文档数量和状态统计信息
- 🔍 **记录管理**：支持查看、删除用户上传记录
- 💾 **自动分段记录**：记录每个文档的分段详情和Milvus ID

### v2.0.0
- 简化架构，移除复杂的混合搜索
- 使用单一向量字段进行存储和搜索
- 优化重排序流程
- 修复字段映射问题

## 📋 新增API功能

本次更新新增了完整的用户文档管理功能：

1. **用户上传记录管理**
   - 获取用户所有上传记录（支持分页和状态筛选）
   - 查看单个上传记录的详细信息（包含所有分段）
   - 删除用户上传记录

2. **用户统计信息**
   - 总文档数、成功文档数、总分段数
   - 按状态分布统计（处理中/已完成/失败）

3. **完整的文档生命周期跟踪**
   - 记录文档名称、摘要、原始长度
   - 记录分段数量和每个分段的详细信息
   - 记录上传状态、时间戳、错误信息

详细的API使用示例请参考 `api_examples.md` 文件。

## 📄 许可证

MIT License

## 🐳 生产环境部署

本项目支持 Docker 容器化部署，提供完整的生产环境部署方案。

### 部署架构

```
┌─────────────────────────────────────────────────────────────┐
│                     生产环境架构                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │
│  │  知识库应用      │  │  Milvus 向量库   │  │ PostgreSQL  │ │
│  │  (FastAPI)      │  │  (向量搜索)      │  │ (元数据)     │ │
│  │  Port: 8000     │  │  Port: 19530    │  │ Port: 5434  │ │
│  └─────────────────┘  └─────────────────┘  └─────────────┘ │
│           │                     │                  │        │
│  ┌─────────────────┐  ┌─────────────────┐                  │
│  │  MinIO 存储     │  │  etcd 配置中心   │                  │
│  │  (对象存储)      │  │  (Milvus 依赖)  │                  │
│  │  Port: 9000     │  │  Port: 2379     │                  │
│  └─────────────────┘  └─────────────────┘                  │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### 快速部署

#### 1. 本地构建镜像

```bash
# 进入项目目录
cd /path/to/knowledge-mcp-sever

# 构建 Docker 镜像
docker build -t chuhe2640/knowledge-mcp-server:v1.0.0 .
docker tag chuhe2640/knowledge-mcp-server:v1.0.0 chuhe2640/knowledge-mcp-server:latest

# 推送到 Docker Hub
docker login
docker push chuhe2640/knowledge-mcp-server:v1.0.0
docker push chuhe2640/knowledge-mcp-server:latest
```

#### 2. 服务器部署

```bash
# 创建部署目录
mkdir -p /opt/knowledge-mcp-server
cd /opt/knowledge-mcp-server

# 下载部署文件
wget https://raw.githubusercontent.com/your-repo/knowledge-mcp-server/main/docker-compose.prod.yml

docker compose -f docker-compose.prod.yml pull

# 启动所有服务
docker compose -f docker-compose.prod.yml down
docker compose -f docker-compose.prod.yml up -d

# 验证部署
docker-compose -f docker-compose.prod.yml ps
curl http://localhost:8000/health
```

### 核心特性

- **🚀 一键部署**: 完整的 Docker Compose 编排
- **🔧 官方镜像**: 使用 Docker 官方镜像源
- **🔒 安全配置**: 非 root 用户运行，健康检查
- **📊 资源控制**: CPU/内存限制和监控
- **🔄 高可用**: 自动重启和健康检查

### 配置说明

**重要**: 所有配置都已在相关文件中写死，无需环境变量
- 服务端口：应用(8000)、PostgreSQL(5434)、Milvus(19530)、MinIO(9000/9001)
- 数据库密码：默认为 `root`（生产环境建议修改 `docker-compose.prod.yml`）
- 应用业务配置在源码 `app/config.py` 中管理，包括：
  - 模型服务地址 (`embedding_base_url`, `reranker_base_url`, `llm_api_base`)
  - 分段和搜索参数 (`chunk_size`, `similarity_threshold` 等)
  - 其他业务逻辑配置

**生产部署前需要修改：**
1. `docker-compose.prod.yml` 中的镜像名称和数据库密码
2. `app/config.py` 中的模型服务地址等业务配置

### 日常运维

```bash
# 查看服务状态
docker-compose -f docker-compose.prod.yml ps

# 查看日志
docker-compose -f docker-compose.prod.yml logs -f

# 重启服务
docker-compose -f docker-compose.prod.yml restart

# 数据备份
docker exec knowledge-postgres-prod pg_dump -U root postgres > backup.sql

# 更新服务
docker-compose -f docker-compose.prod.yml pull
docker-compose -f docker-compose.prod.yml up -d
```

### 常见问题

1. **服务启动失败**
   ```bash
   # 查看详细日志
   docker-compose -f docker-compose.prod.yml logs knowledge-app
   
   # 检查端口占用
   netstat -tulpn | grep :8000
   ```

2. **数据库连接失败**
   ```bash
   # 检查 PostgreSQL 状态
   docker-compose -f docker-compose.prod.yml logs postgres
   
   # 测试数据库连接
   docker exec -it knowledge-postgres-prod pg_isready -U root
   ```

3. **Milvus 连接失败**
   ```bash
   # 检查 Milvus 状态
   docker-compose -f docker-compose.prod.yml logs milvus
   
   # 测试 Milvus 连接
   curl http://localhost:19530/health
   ```

---

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License