253 lines
7.3 KiB
Markdown
253 lines
7.3 KiB
Markdown
# 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/ # 工作空间
|
||
```
|
||
|
||
此系统提供了完整的智能数据检索解决方案，支持动态数据集加载和高效的查询处理，适用于各种数据分析和检索场景。
|