# weaviate

**Repository Path**: chen-lexiang/weaviate

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-02
- **Last Updated**: 2025-09-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 知识库向量检索服务

基于 PostgreSQL + Weaviate + BGE-M3 的企业级知识库向量检索和语义检索服务。

## 🚀 项目特色

### 🏗️ 技术架构
- **数据存储**: PostgreSQL 15 (集合元数据) + Weaviate 1.25.6 (向量数据)
- **Web 框架**: FastAPI (高性能异步 API)
- **向量模型**: BGE-M3 (1024维向量，支持中文)
- **重排序**: BGE-Reranker-V2-M3 (提升搜索精度)
- **容器化**: Docker + Docker Compose (一键部署)

### ✨ 核心功能

#### 📚 集合管理
- ✅ 创建/更新/删除文档集合
- ✅ 集合列表查询和分页
- ✅ 基于名称和描述的全文搜索
- ✅ 软删除和一键恢复
- ✅ 实时统计信息（文档数量、创建时间等）

#### 🔍 智能搜索
- ✅ **文本语义搜索** - BM25 算法，支持关键词匹配
- ✅ **向量相似度搜索** - 基于 BGE-M3 的语义理解
- ✅ **混合搜索模式** - 结合文本和向量检索优势
- ✅ **跨集合搜索** - 一次搜索多个知识库
- ✅ **高级过滤搜索** - 按来源、分片索引等条件过滤
- ✅ **搜索建议** - 智能推荐相关搜索词

#### 🩺 系统监控
- ✅ 多层健康检查（数据库、向量库、外部服务）
- ✅ 详细服务状态监控
- ✅ 实时性能指标
- ✅ 异步任务监控

## 🎯 适用场景

- **企业知识库** - 内部文档、技术资料、政策制度的语义搜索
- **客服系统** - 智能问答、知识推荐、相似问题匹配
- **内容管理** - 新闻、文章、报告的智能分类和检索
- **研发支持** - 代码文档、API 文档、技术规范的快速查找
- **合规审计** - 法规条文、合规文件的精准检索

## 🛠️ 快速开始

### 环境要求

- **操作系统**: Linux / macOS / Windows (WSL2)
- **运行时**: Docker >= 20.10, Docker Compose >= 2.0
- **硬件**: 内存 >= 4GB, 磁盘 >= 5GB
- **网络**: 需访问外部 BGE-M3 和重排序服务

### 1️⃣ 克隆项目

```bash
git clone <repository-url>
cd weaviate
```

### 2️⃣ 配置环境

```bash
# 复制环境变量模板
cp .env.example .env

# 编辑配置文件
nano .env
```

**关键配置项：**
```bash
# 外部 AI 服务（必须配置）
OLLAMA_BASE_URL=http://192.168.79.122:11434
RERANKER_BASE_URL=http://192.168.79.122:9997

# 数据库配置
POSTGRES_USER=knowledge_user
POSTGRES_PASSWORD=knowledge_pass
POSTGRES_PORT=5436  # 避免与本地 PostgreSQL 冲突

# 服务端口
API_PORT=8001
WEAVIATE_PORT=8090
```

### 3️⃣ 启动基础服务

```bash
# 启动数据库和向量库（开发环境）
docker-compose up -d postgres weaviate

# 可选：启动 pgAdmin 数据库管理界面
docker-compose up -d pgadmin
```

### 4️⃣ 启动 API 服务

**方式1: IDE 开发模式 (推荐)**
```bash
# 在 IDE 中直接运行
python run.py
# 或
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

**方式2: Docker 生产模式**
```bash
# 构建并启动完整服务栈
docker build -t knowledge-base-api .
docker-compose -f docker-compose.prod.yml up -d
```

### 5️⃣ 验证部署

```bash
# 检查服务健康状态
curl http://localhost:8000/api/v1/health

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

# 访问数据库管理界面 (可选)
open http://localhost:5050
```

## 📖 API 接口

### 健康检查
- `GET /api/v1/health` - 基本健康检查
- `GET /api/v1/health/detailed` - 详细健康状态
- `GET /api/v1/health/status` - 服务组件状态

### 集合管理
- `POST /api/v1/collections/` - 创建新集合
- `GET /api/v1/collections/` - 获取集合列表（支持分页）
- `GET /api/v1/collections/{id}` - 获取集合详情
- `PUT /api/v1/collections/{id}` - 更新集合信息
- `DELETE /api/v1/collections/{id}` - 软删除集合
- `POST /api/v1/collections/{id}/restore` - 恢复已删除集合
- `GET /api/v1/collections/search/` - 搜索集合

### 向量检索
- `GET /api/v1/search/collections/{id}` - 在指定集合中搜索
- `GET /api/v1/search/collections` - 跨多个集合搜索
- `POST /api/v1/search/collections/{id}/advanced` - 高级搜索（支持过滤条件）
- `GET /api/v1/search/suggestions` - 获取搜索建议

**完整 API 文档**: `http://localhost:8000/docs`

## 🖥️ 使用示例

### 创建集合

```bash
curl -X POST "http://localhost:8000/api/v1/collections/" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "企业技术文档",
    "description": "包含所有技术规范、API文档和开发指南",
    "vector_model": "bge-m3:latest"
  }'
```

### 搜索文档

```bash
# 基本搜索
curl "http://localhost:8000/api/v1/search/collections/{collection_id}?q=API接口设计&limit=10"

# 高级搜索
curl -X POST "http://localhost:8000/api/v1/search/collections/{collection_id}/advanced" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "用户认证",
    "search_type": "hybrid",
    "limit": 10,
    "filters": {
      "source": "auth-guide.pdf",
      "min_chunk_index": 0
    }
  }'
```

## 🗂️ 数据架构

### 数据库表结构

**collections 表**:
```sql
CREATE TABLE collections (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL UNIQUE,
    description TEXT,
    vector_model VARCHAR(100) NOT NULL DEFAULT 'bge-m3:latest',
    vector_dimension INTEGER NOT NULL DEFAULT 1024,
    document_count INTEGER NOT NULL DEFAULT 0,
    search_vector TSVECTOR,  -- 全文搜索向量
    is_deleted BOOLEAN NOT NULL DEFAULT FALSE,
    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
    deleted_at TIMESTAMP WITH TIME ZONE
);
```

### 向量存储架构

**Weaviate Schema**:
- **class**: 动态生成（基于集合 UUID）
- **properties**: 
  - `content` (text) - 文档内容
  - `metadata` (object) - 元数据信息
  - `chunk_index` (int) - 分片索引
  - `source` (text) - 文档来源
- **vector**: 1024维 BGE-M3 向量

## 🔧 开发指南

### 项目结构

```
weaviate/
├── app/                    # FastAPI 应用
│   ├── api/               # API 路由
│   │   ├── health.py      # 健康检查接口
│   │   ├── collections.py # 集合管理接口
│   │   └── search.py      # 搜索接口
│   ├── core/              # 核心配置
│   │   ├── config.py      # 应用配置
│   │   └── database.py    # 数据库连接
│   ├── models/            # SQLAlchemy 模型
│   │   └── collection.py  # 集合数据模型
│   ├── schemas/           # Pydantic 模式
│   │   └── collection.py  # 数据验证模式
│   ├── services/          # 业务逻辑层
│   │   ├── weaviate_service.py    # Weaviate 操作
│   │   ├── collection_service.py  # 集合业务逻辑
│   │   └── search_service.py      # 搜索业务逻辑
│   └── main.py            # FastAPI 应用入口
├── docker-compose.yml     # 开发环境配置
├── docker-compose.prod.yml # 生产环境配置
├── Dockerfile             # API 服务镜像
├── requirements.txt       # Python 依赖
├── .env.example          # 环境变量模板
└── README.Docker.md      # Docker 部署指南
```

### 开发流程

1. **环境准备**
   ```bash
   # 启动基础服务
   docker-compose up -d postgres weaviate
   
   # 安装 Python 依赖
   pip install -r requirements.txt
   ```

2. **数据库初始化**
   ```bash
   # 应用启动时自动创建表，无需手动操作
   python run.py
   ```

3. **开发调试**
   ```bash
   # 热重载模式
   python -m uvicorn app.main:app --reload
   ```

4. **代码检查**
   ```bash
   # 类型检查
   mypy app/
   
   # 代码格式化
   black app/
   isort app/
   ```

### 添加新功能

1. **添加新的 API 端点**
   - 在 `app/api/` 中创建新的路由文件
   - 在 `app/main.py` 中注册路由

2. **扩展数据模型**
   - 修改 `app/models/` 中的 SQLAlchemy 模型
   - 更新 `app/schemas/` 中的 Pydantic 模式

3. **添加业务逻辑**
   - 在 `app/services/` 中实现业务逻辑
   - 保持控制器层的简洁

## 🌐 生产部署

详细的生产环境部署指南请参考：**[README.Docker.md](README.Docker.md)**

### 部署选项

- **离线部署** - 适用于内网环境，无需外网访问
- **容器化部署** - 基于 Docker Compose 的一键部署
- **负载均衡** - 支持多实例横向扩展
- **数据持久化** - PostgreSQL 和 Weaviate 数据持久存储

### 监控运维

- **健康检查** - 自动检测服务状态
- **日志管理** - 结构化日志输出
- **性能监控** - 资源使用情况跟踪
- **备份恢复** - 数据库和向量数据备份方案

## 🔒 安全注意事项

- 修改默认数据库密码
- 限制数据库访问权限
- 使用内网部署，避免公网暴露
- 定期更新依赖包版本
- 启用 HTTPS（生产环境）

## 🤝 技术支持

### 常见问题

1. **数据库连接失败** - 检查 PostgreSQL 服务状态和连接参数
2. **Weaviate 连接超时** - 确认向量库服务正常启动
3. **外部服务不可达** - 验证 BGE-M3 和重排序服务地址
4. **端口冲突** - 修改 `.env` 中的端口配置

### 获取帮助

- 查看详细错误日志: `docker-compose logs -f`
- 检查服务健康状态: `curl http://localhost:8000/api/v1/health/detailed`
- 参考 Docker 部署指南: [README.Docker.md](README.Docker.md)

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件