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

请求格式:

{
  "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数
• 其他任意模型生成参数

响应格式（非流式）:

{
  "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

{
    "字段名": {
        "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 部署

# 构建镜像
docker build -t qwen-agent .

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

Docker Compose 部署

docker-compose up -d

本地开发部署

# 安装依赖
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/            # 工作空间

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