# Qwen Agent - 智能数据检索专家系统

## 项目概述

Qwen Agent 是一个基于 FastAPI 构建的智能数据检索专家系统，专门用于处理和分析结构化数据集。系统通过无状态的 ZIP 项目加载机制，支持动态加载多种数据集，并提供类似 OpenAI 的聊天接口，便于与现有 AI 应用集成。

## 核心功能

### 1. 智能数据检索
- 基于倒排索引和多层数据架构的专业数据检索
- 支持复杂查询优化和自主决策能力
- 动态制定最优检索策略

### 2. 无状态项目加载
- 通过 ZIP URL 动态加载数据集
- 自动缓存和解压，提高性能
- 支持多种数据结构和文件格式

### 3. 多层架构数据处理
- **文档层** (document.txt): 原始文本内容，提供完整上下文
- **序列化层** (serialization.txt): 结构化数据，支持高效匹配
- **索引层** (schema.json): 字段定义、枚举值映射、文件关联关系

## API 接口协议

### Chat Completions 接口

**端点**: `POST /api/v1/chat/completions`

**请求格式**:
```json
{
  "messages": [
    {
      "role": "user",
      "content": "HP Elite Mini 800 G9ってノートPC？"
    }
  ],
  "model": "qwen3-next",
  "model_server": "https://openrouter.ai/api/v1",
  "api_key": "your-api-key",
  "zip_url": "http://127.0.0.1:8080/all_hp_product_spec_book2506.zip",
  "stream": false,
  "max_input_tokens": 58000,
  "top_p": 0.8,
  "temperature": 0.7,
  "max_tokens": 2000
}
```

**参数说明**:
- `messages`: 聊天消息列表
- `model`: 模型名称（默认: "qwen3-next"）
- `model_server`: 模型服务器地址（必须）
- `api_key`: API 密钥（可通过 Authorization header 传入）
- `zip_url`: ZIP 数据集的 URL（必需）
- `stream`: 是否流式响应（默认: false）
- `max_input_tokens`: 最大输入tokens数
- `top_p`: 核采样参数
- `temperature`: 温度参数
- `max_tokens`: 最大生成tokens数
- 其他任意模型生成参数

**响应格式**（非流式）:
```json
{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "HP Elite Mini 800 G9はノートPCではなく、小型のデスクトップPCです。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 18,
    "total_tokens": 43
  }
}
```

**流式响应**: 使用 Server-Sent Events (SSE) 格式，每个数据块采用 OpenAI 格式。

### 系统管理接口

#### 健康检查
- `GET /api/health` - 系统健康状态检查

#### 系统状态
- `GET /system/status` - 获取系统状态和缓存统计信息

#### 缓存管理
- `POST /system/cleanup-cache` - 清理所有缓存
- `POST /system/cleanup-agent-cache` - 清理助手实例缓存
- `GET /system/cached-projects` - 获取所有缓存的项目信息
- `POST /system/remove-project-cache` - 移除特定项目缓存

## ZIP_URL 数据包结构

### 压缩包内容要求

ZIP 压缩包应包含以下目录结构：

```
dataset_name/
├── README.md              # 数据集说明文档
├── dataset/
│   └── data_collection/
│       ├── document.txt      # 原始文本内容
│       ├── serialization.txt # 序列化结构数据
│       └── schema.json       # 字段定义和元数据
├── mcp_settings.json      # MCP 工具配置
└── system_prompt.md       # 系统提示词（可选）
```

### 文件详细说明

#### 1. document.txt
- 包含原始 Markdown 文本内容
- 提供数据的完整上下文信息
- 检索时需要包含前后行的上下文才有意义

#### 2. serialization.txt
- 基于 document.txt 解析的格式化结构数据
- 每行格式：`字段1:值1;字段2:值2;...`
- 支持正则高效匹配和关键词检索
- 单行内容代表一条完整的数据

#### 3. schema.json
```json
{
    "字段名": {
        "txt_file_name": "document.txt",
        "serialization_file_name": "serialization.txt", 
        "enums": ["枚举值1", "枚举值2"],
        "description": "字段描述信息"
    }
}
```
- 定义字段名、枚举值映射和文件关联关系
- 提供 serialization.txt 中所有字段的集合
- 用于字段预览和枚举值预览

#### 4. MCP 工具配置 (mcp_settings.json)
- 配置 Model Context Protocol 工具
- 支持数据检索和处理的工具集成
- 可包含 JSON reader、多关键词搜索等工具

### 示例数据集

项目中包含的 HP 产品规格书数据集示例：

```
all_hp_product_spec_book2506/
├── document.txt        # HP 产品完整规格信息
├── serialization.txt   # 结构化的产品规格数据
└── schema.json         # 产品字段定义（类型、品牌、规格等）
```

数据包含：
- 商用/个人笔记本电脑 (EliteBook/OmniBook)
- 台式机 (Elite/OMEN)
- 工作站 (Z系列)
- 显示器 (Series 3/5/OMEN)
- Poly 通信设备
- HyperX 游戏配件

## 技术特性

### 智能检索策略
- **探索性查询**: 结构分析 → 模式发现 → 结果扩展
- **精确性查询**: 目标定位 → 直接搜索 → 结果验证
- **分析性查询**: 多维度分析 → 深度挖掘 → 洞察提取

### 专业工具体系
- **结构分析工具**: json-reader-get_all_keys, json-reader-get_multiple_values
- **搜索执行工具**: multi-keyword-search, ripgrep-count-matches, ripgrep-search
- **智能路径优化**: 根据查询复杂度选择最优搜索路径

### 缓存机制
- ZIP 文件基于 URL 的 MD5 哈希值进行缓存
- 助手实例缓存，提高响应速度
- 支持缓存清理和管理

## 部署方式

### Docker 部署
```bash
# 构建镜像
docker build -t qwen-agent .

# 运行容器
docker run -p 8001:8001 qwen-agent
```

### Docker Compose 部署
```bash
docker-compose up -d
```

### 本地开发部署
```bash
# 安装依赖
pip install -r requirements.txt

# 启动服务
python fastapi_app.py
```

## 系统要求

- Python 3.8+
- FastAPI
- Uvicorn
- Qwen Agent 库
- Requests（用于 ZIP 下载）
- 足够的磁盘空间用于缓存

## 注意事项

1. **必需参数**: 所有请求都必须提供 zip_url 参数
2. **API 密钥**: 可通过 Authorization header 或请求参数传入
3. **URL 格式**: zip_url 必须是有效的 HTTP/HTTPS URL 或本地路径
4. **文件大小**: 建议 ZIP 文件不超过 100MB
5. **安全性**: 确保 ZIP 文件来源可信
6. **网络**: 需要能够访问 zip_url 指向的资源

## 项目结构

```
qwen-agent/
├── fastapi_app.py          # FastAPI 主应用
├── gbase_agent.py          # 助手服务逻辑
├── zip_project_handler.py  # ZIP 项目处理器
├── file_loaded_agent_manager.py  # 助助实例管理
├── agent_pool.py           # 助手池管理
├── system_prompt.md        # 系统提示词
├── requirements.txt        # 依赖包列表
├── Dockerfile             # Docker 构建文件
├── docker-compose.yml     # Docker Compose 配置
├── mcp/                   # MCP 工具配置
├── projects/              # 项目目录
│   ├── _cache/           # ZIP 文件缓存
│   └── {hash}/           # 解压后的项目目录
├── public/               # 静态文件
└── workspace/            # 工作空间
```

此系统提供了完整的智能数据检索解决方案，支持动态数据集加载和高效的查询处理，适用于各种数据分析和检索场景。