# OSAgentSearchEngine

**Repository Path**: AINative/osagent-search-engine

## Basic Information

- **Project Name**: OSAgentSearchEngine
- **Description**: OSagent信息查询模块
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-02-28
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OS Agent Search Engine

**信息查询模块 (os_agent_search_engine)** - OS Agent 核心功能模块

自然语言驱动的多维度信息检索系统，支持系统信息、文件内容、图片内容（含OCR）的智能查询。

## 项目概述

OS Agent 信息查询模块是一个功能完整的本地化检索引擎，支持用户通过日常语言（如"昨天的预算文件"）查询本地系统中的文件、图片、OCR内容等多维度信息，无需掌握专业语法。

### 核心特性

- **多维度检索**: 支持系统信息、文件内容、图片内容（含OCR）的混合检索
- **自然语言解析**: 支持日常语言表达，无需专业语法
- **多条件组合**: 支持时间、文件类型、内容等多条件智能组合查询
- **全流程本地化**: 所有处理均在本地完成，无外部依赖，保障数据隐私
- **模块化设计**: 支持后续新增索引/检索能力
- **容错机制**: 完整的重试、超时、资源监控和故障恢复机制
- **事件驱动架构**: 异步事件总线，支持模块解耦和弹性扩展

### 技术架构

```
用户查询 -> NLU层 -> 检索层 -> 数据存储层 -> 结果处理层 -> 返回结果
            ↓         ↓           ↓              ↓
        查询改写   DSL生成   Milvus混合检索   标准化/排序/优化
        实体抽取   DSL解析   BM25+向量      智能优化
        逻辑解析
```

### 核心组件

| 组件 | 用途 | 关键特性 |
|------|------|----------|
| NLU层 | 自然语言理解 | 查询改写、实体抽取、逻辑解析 |
| 检索核心层 | DSL生成/解析、Milvus混合检索 | 统一DSL v1.0、多集合检索 |
| 数据存储层 | 索引持久化与快速查询 | Milvus-Lite、本地db文件、BM25+向量检索 |
| 解析层 | 文档/图片解析与OCR | 本地化处理、支持多格式、gRPC通信 |
| 向量服务 | 文本/视觉向量化 | gte-onnx模型（768维）、CLIP模型（512维） |
| 结果处理层 | 结果标准化/排序/优化 | 统一输出Schema、智能优化 |
| 状态管理层 | 查询任务状态追踪与控制 | 状态机管理、进度查询、任务取消 |
| 容错层 | 异常处理与故障恢复 | 重试机制、超时控制、资源监控 |

## 安装

### 环境要求

- Python 3.9+
- 推荐使用虚拟环境

### 安装步骤

```bash
# 克隆项目
git clone https://github.com/your-org/os-agent-search-engine.git
cd os-agent-search-engine

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

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

# 或使用 setup.py 安装
pip install -e .
```

### 开发环境安装

```bash
# 安装开发依赖
pip install -e ".[dev,observability]"

# 安装 NLP 相关依赖（可选）
pip install -e ".[nlp]"
```

## 快速开始

### 基本使用

```python
from src.engine.search_engine import OSAgentInfoQueryEngine

# 初始化搜索引擎
engine = OSAgentInfoQueryEngine(config_path="config/app_config.yaml")

# 执行查询
result = engine.query("昨天的预算Excel文件")

# 查看结果
print(f"找到 {result.total_results} 条结果")
for item in result.results:
    print(f"[{item.score:.2f}] {item.metadata.file_name}: {item.content[:100]}...")
```

### 文件入库

```python
# 文件入库
engine.ingest_file("/path/to/document.pdf")

# 图片入库（含OCR）
engine.ingest_image("/path/to/image.jpg")

# 批量入库
engine.ingest_directory("/path/to/directory")
```

### 查询状态管理

```python
# 查询状态
query_id = engine.async_query("昨天的会议记录")

# 查询进度
status = engine.get_query_status(query_id)
print(f"当前状态: {status.status}, 进度: {status.progress}%")

# 取消查询
engine.cancel_query(query_id)
```

## 配置

### 应用配置 (config/app_config.yaml)

```yaml
# Milvus配置
milvus:
  db_path: "data/milvus/milvus.db"
  text_vector_dimension: 768
  vision_vector_dimension: 512

# 服务地址
services:
  document_processing:
    sync_socket: "unix:///tmp/document_service_sync_{uid}.sock"
    async_socket: "unix:///tmp/document_service_async_{uid}.sock"
  vectorization:
    base_url: "http://localhost:5000"
    text_endpoint: "/api/v1/embedding/text"
    image_endpoint: "/api/v1/embedding/image"

# 检索配置
retrieval:
  default_top_k: 20
  hybrid_weights:
    file_index:
      vector_weight: 0.5
      fulltext_weight: 0.5
    image_index:
      ocr_vector_weight: 0.3
      vision_vector_weight: 0.3
      fulltext_weight: 0.4
```

## 项目结构

```
os_agent_search_engine/
├── README.md                  # 项目说明文档
├── requirements.txt           # 项目依赖包
├── setup.py                   # 项目打包配置
├── config/                    # 配置文件目录
│   ├── app_config.yaml        # 系统应用配置
│   ├── rewrite_rules.yaml     # 查询改写规则配置
│   ├── entity_patterns.yaml   # 实体抽取规则配置
│   ├── retry_policy.yaml      # 重试策略配置
│   ├── timeout_config.yaml    # 超时配置
│   └── resource_limits.yaml   # 资源限制配置
├── data/                      # 数据文件目录
│   └── milvus/                # Milvus本地数据库
├── src/                       # 核心源码目录
│   ├── common/                # 公共基础模块
│   ├── nlu/                   # NLU层模块
│   ├── base_service/          # 基础服务层模块
│   ├── retrieval/             # 检索层模块
│   ├── result_processing/     # 结果处理层模块
│   ├── status_management/     # 状态管理层模块
│   ├── fault_tolerance/       # 容错层模块
│   ├── messaging/             # 消息与事件层模块
│   ├── resilience/            # 弹性架构层模块
│   ├── observability/         # 可观测性层模块
│   ├── adapters/              # 模块适配器层
│   └── engine/                # 整体入口模块
├── tests/                     # 测试目录
└── docs/                      # 详细文档目录
```

## 开发

### 运行测试

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

# 运行特定模块测试
pytest tests/test_nlu.py -v

# 生成覆盖率报告
pytest tests/ --cov=src --cov-report=html
```

### 代码格式化

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

# 代码检查
flake8 src/ tests/
pylint src/
mypy src/
```

## 文档

详细设计文档请参考：
- [技术设计文档](docs/design-doc/information-query-module.md)
- [NLU层设计](src/nlu/README.md)
- [检索层设计](src/retrieval/README.md)
- [Milvus集合设计](docs/storage_layer.md)
- [容错机制文档](docs/fault_tolerance.md)

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！