# UniIndex

**Repository Path**: bytesifter/uni-index

## Basic Information

- **Project Name**: UniIndex
- **Description**: Unified Index
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-09
- **Last Updated**: 2026-04-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Uni-Index AI Platform

基于推理的下一代智能文档分析平台，提供完整的PageIndex核心能力集成和标准化的MCP协议接口。

## 🚀 项目定位

**Uni-Index AI Platform** 是一个基于推理的智能文档分析平台，实现了从传统向量检索到推理检索的技术范式革命。平台完整集成了PageIndex的五个核心能力，通过标准化的MCP协议为OpenCode和其他AI应用提供智能文档分析服务。

### 技术范式革命
- **传统RAG**: 基于向量相似度（similarity ≠ relevance）
- **Uni-Index**: 基于推理的相关性（reasoning = relevance）
- **本质区别**: 从"语义匹配"升级为"智能推理"

## ✨ 核心特性

### 🧠 智能推理能力
- **推理式检索**: 基于LLM推理的深度语义理解，而非向量相似度计算
- **向量无关架构**: 无需向量数据库，保持文档自然结构
- **树状索引**: 生成层次化的文档结构，支持精确导航

### 🔍 PageIndex五个核心能力
1. **语义搜索**: 基于LLM推理的深度语义理解搜索
2. **混合搜索**: 关键词+语义+推理的三层混合搜索架构
3. **文档分块**: 基于文档语义结构的智能分块
4. **元数据过滤**: 多维度组合元数据过滤
5. **相关性排序**: 多因素加权智能排序

### 🌐 标准化接口
- **MCP协议**: 完整的Model Context Protocol支持，无缝集成OpenCode
- **REST API**: 标准的RESTful API设计，易于第三方集成
- **WebSocket**: 实时交互和通知接口
- **管理控制台**: 完整的运维管理界面

### 📊 卓越性能
- **准确率**: FinanceBench准确率98.7%（state-of-the-art）
- **响应时间**: < 500ms（P95，包含LLM推理时间）
- **专业文档**: 特别适合金融、法律、学术等专业文档处理
- **可扩展性**: 支持水平扩展和高可用部署

## 🏗️ 系统架构

### 总体架构
```
┌─────────────────────────────────────────────────────┐
│                应用接口层 (Application Layer)        │
│  - MCP协议接口 (OpenCode集成)                       │
│  - REST API接口 (第三方应用集成)                    │
│  - WebSocket接口 (实时交互)                         │
│  - 管理控制台 (运维管理)                            │
└─────────────────────────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────┐
│                业务逻辑层 (Business Logic Layer)     │
│  - 文档管理服务 (上传、索引、版本控制)              │
│  - 智能搜索服务 (五个核心搜索能力)                  │
│  - 分析引擎服务 (问答、摘要、对比)                  │
│  - 用户会话服务 (上下文管理、个性化)                │
└─────────────────────────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────┐
│                核心引擎层 (Core Engine Layer)        │
│  - PageIndex推理引擎 (五个核心能力实现)             │
│  - LLM集成服务 (多模型支持、负载均衡)               │
│  - 缓存管理服务 (Redis缓存、内存缓存)               │
│  - 异步任务队列 (Celery/RQ任务处理)                 │
└─────────────────────────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────┐
│                数据存储层 (Data Storage Layer)       │
│  - 文档存储 (MinIO/S3对象存储)                      │
│  - 索引存储 (PostgreSQL关系数据库)                  │
│  - 缓存存储 (Redis键值存储)                         │
│  - 元数据存储 (Elasticsearch搜索优化)               │
└─────────────────────────────────────────────────────┘
```

### 项目结构
```
uni-index/
├── src/                            # 源代码目录
│   └── pageindex_mcp/
│       ├── __init__.py            # 包初始化
│       ├── models/                # 数据模型层
│       │   └── document.py        # 文档数据模型
│       ├── server/                # HTTP服务器层
│       │   ├── server.py          # HTTP服务器实现
│       │   └── async_server.py    # 异步HTTP服务器
│       └── mcp/                   # MCP协议层
│           ├── __init__.py        # MCP模块初始化
│           ├── models.py          # MCP协议消息模型
│           ├── wrapper.py         # HTTP API包装器
│           └── server.py          # FastAPI MCP服务器
├── scripts/                       # 脚本目录
│   ├── pageindex_mcp.py          # HTTP服务器入口
│   └── mcp_server.py             # MCP服务器入口
├── examples/                     # 示例代码
│   └── basic_usage.py           # 使用示例
├── config/                       # 配置目录
│   └── config.yaml              # 服务器配置
├── docs/                         # 文档目录
│   ├── AD/                       # 应用设计文档
│   │   └── 下一代智能文档分析平台-v1.0.md
│   ├── PLAN/                     # 实施计划
│   │   └── 开发计划-v0.x.x.md
│   ├── archive/                  # 归档文档
│   └── *.md                      # 技术参考文档
├── pyproject.toml               # 项目配置和依赖
├── start_server.py              # 主入口脚本（集成启动HTTP+MCP）
├── opencode.json                # OpenCode MCP配置
└── README.md                    # 项目说明
```

## 🚀 快速开始

### 1. 安装依赖

```bash
# 使用uv安装依赖（推荐）- 现代uv版本使用sync命令
uv sync

# 安装开发依赖（可选）
uv sync --dev

# 旧版uv或备选方案
uv pip install .

# 或使用原生pip（不推荐，仅作备选）
pip install .
```

### 2. 启动服务器（集成启动）

#### 标准启动方式
```bash
# 同时启动HTTP服务器（端口8080）和MCP服务器（端口8000）
python start_server.py

# 指定端口
python start_server.py --http-port 8080 --mcp-port 8000

# 查看帮助信息
python start_server.py --help
```

#### OpenCode配置
启动服务器后，在OpenCode中配置：
```json
{
  "uni-index": {
    "type": "remote",
    "url": "http://localhost:8000/sse",
    "enabled": true
  }
}
```

#### 验证服务
服务器启动后，访问以下URL验证：
- http://localhost:8080/ - HTTP服务器状态
- http://localhost:8000/ - MCP服务器信息
- http://localhost:8000/sse - MCP SSE端点（OpenCode使用）

### 3. 验证服务

服务器启动后，访问以下URL验证：

- http://localhost:8080/ - 服务器状态
- http://localhost:8080/documents - 文档列表

## 📚 API文档

### 基础端点

| 方法 | 端点 | 描述 |
|------|------|------|
| GET | `/` | 服务器状态 |
| GET | `/documents` | 获取文档列表 |
| GET | `/document/{name}` | 获取文档结构 |
| GET | `/document/{name}/search?q={query}` | 搜索文档内容 |

### PageIndex核心能力端点（v1.0新增）

| 方法 | 端点 | 描述 |
|------|------|------|
| POST | `/api/v1/search/semantic` | 语义搜索 |
| POST | `/api/v1/search/hybrid` | 混合搜索 |
| POST | `/api/v1/analyze/chunk` | 文档智能分块 |
| POST | `/api/v1/filter/metadata` | 元数据过滤 |
| POST | `/api/v1/score/relevance` | 相关性评分 |

## 🔧 MCP服务器 (OpenCode集成)

Uni-Index MCP服务器提供符合Model Context Protocol标准的接口，用于OpenCode集成。

### MCP服务器端点

| 方法 | 端点 | 描述 |
|------|------|------|
| GET | `/` | MCP服务器信息 |
| GET | `/health` | 健康检查 |
| GET | `/sse` | Server-Sent Events MCP端点 |
| POST | `/mcp` | HTTP MCP端点 |
| GET | `/tools` | 列出可用MCP工具 |
| POST | `/tools/{name}` | 通过HTTP调用MCP工具 |

### 可用MCP工具

#### 基础工具（已实现）
1. **get_server_status** - 获取服务器状态
2. **list_documents** - 列出所有文档
3. **get_document** - 获取文档详情
4. **search_document** - 搜索文档内容

#### PageIndex核心工具（v1.0新增）
5. **semantic_search** - 语义搜索
6. **hybrid_search** - 混合搜索
7. **chunk_document** - 文档分块
8. **metadata_filter** - 元数据过滤
9. **relevance_score** - 相关性评分

#### 智能分析工具（v1.5计划）
10. **ask_question** - 智能问答
11. **generate_summary** - 文档摘要生成
12. **compare_documents** - 文档对比分析

### 配置OpenCode

1. 复制 `opencode.json` 到OpenCode配置目录：
   - Windows: `%APPDATA%\opencode\`
   - macOS/Linux: `~/.config/opencode/`

2. 启动MCP服务器：
   ```bash
   uv run python scripts/mcp_server.py
   ```

3. 在OpenCode中使用：
   ```
   @uni-index list_documents
   @uni-index semantic_search --query "金融稳定性分析"
   @uni-index hybrid_search --query "货币政策" --search_type balanced
   @uni-index ask_question --document "2023-annual-report" --question "美联储2023年的主要政策目标是什么？"
   ```

## 🛠️ 开发指南

### 代码规范

本项目遵循团队的Python编码规范：

- 使用小写字母和下划线命名文件：`module_name.py`
- 类名使用大驼峰：`ClassName`
- 函数名使用小写字母和下划线：`function_name`
- 常量使用大写字母和下划线：`CONSTANT_NAME`
- 遵循PEP 8规范
- 使用类型注解
- 函数和类需要文档字符串

### 测试

```bash
# 运行测试
pytest tests/

# 带覆盖率
pytest --cov=src tests/
```

### 代码质量

```bash
# 代码格式化
black src/ tests/

# 类型检查
mypy src/

# 代码检查
ruff check src/
```

## 📈 版本演进路线

### v1.0版本（当前开发）
**核心目标**: PageIndex五个核心能力的完整集成
- ✅ 语义搜索、混合搜索、文档分块、元数据过滤、相关性排序
- ✅ 完整的MCP协议支持
- ✅ 基础REST API
- ✅ 管理控制台基础功能

### v1.5版本（计划）
**核心目标**: 智能分析功能扩展
- 🔄 智能问答系统
- 🔄 文档摘要生成
- 🔄 文档对比分析
- 🔄 高级管理功能

### v2.0版本（规划）
**核心目标**: 平台化扩展和生态建设
- 📋 多租户支持
- 📋 工作流引擎
- 📋 插件系统
- 📋 第三方应用市场

## 🔍 性能指标

### 准确性指标
- **FinanceBench准确率**: 98.7%（state-of-the-art）
- **专业文档QA准确率**: > 95%
- **与传统方案对比**: 准确率提升30%+

### 性能指标
- **搜索响应时间**: < 500ms（P95）
- **文档索引时间**: < 30秒/100页（PDF文档）
- **系统可用性**: 99.9%（月度）
- **并发支持**: 1000+ QPS

### 资源效率
- **无向量数据库**: 减少存储和计算开销
- **智能缓存**: Redis缓存优化响应时间
- **异步处理**: 提高吞吐量和资源利用率

## 📖 文档体系

### 核心文档
- **应用设计文档**: `docs/AD/下一代智能文档分析平台-v1.0.md`
- **开发计划**: `docs/PLAN/开发计划-v0.x.x.md`
- **核心能力分析**: `docs/下一代智能文档分析平台-核心能力分析.md`

### 技术参考文档
- PageIndex完整能力分析.md
- PageIndex完整能力详细介绍.md
- PageIndex完整能力技术可行性评估.md
- PageIndex完整能力集成实施计划.md
- MCP协议扩展方案设计.md

### 归档文档
- `docs/archive/` - 历史版本和过时文档

## 🤝 贡献指南

欢迎提交Issue和Pull Request！

### 贡献流程
1. Fork项目仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 开启Pull Request

### 代码审查标准
- 所有代码必须通过测试
- 遵循项目代码规范
- 包含必要的文档和注释
- 通过CI/CD流水线检查

## 📄 许可证

MIT License

## 📞 联系方式

- **项目主页**: https://gitee.com/bytesifter/uni-index
- **问题反馈**: Gitee Issues
- **文档**: https://gitee.com/bytesifter/uni-index

---

**Uni-Index AI Platform** - 重新定义智能文档分析的未来