# sportJavaRAG

**Repository Path**: wangyaning1130/sport-java-rag

## Basic Information

- **Project Name**: sportJavaRAG
- **Description**: 企业级足球数据应用设计的智能分析平台。它基于Java开发，并深度融合了 RAG和 Spring AI 能力。平台专注于欧洲五大联赛（英超、西甲、意甲、德甲、法甲）的赛事分析与预测，通过结合 MySQL 的结构化存储和 Milvus 向量数据库的高效检索，实现了“数据解析 → 智能预测
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SportJava-RAG

## 一、项目简介

SportJava-RAG 是一个用于足球体育赛事数据处理与分析的 Java 项目。基于 **JDK 17+**开发，它提供从 JSON 文件中提取比赛数据、使用知识库进行分析，并生成基于不同分析风格的比赛分析报告的功能。项目结合了 Milvus 向量数据库进行高效的知识检索，以及 MySQL 存储结构化的比赛知识数据。

项目前端：[SportJava-RAG-FE](https://gitee.com/guan-zhengxi/sport-java-rag-protal)

## 二、核心功能

| 功能模块           | 核心能力                                                     |
| ------------------ | ------------------------------------------------------------ |
| **赛事分析与预测** | 1. 上传 JSON 格式的欧洲五大联赛赛事文件（支持批量处理）。 <br />2. 选择 5 种预设分析风格。 <br />3. 自动生成“赛事数量 × 风格数量”的预测帖子。 <br />4. 支持预测结果复制与批量下载。 |
| **知识库维护**     | 1. 手动上传 JSON 格式的知识库数据。<br />2. 同步存储至 **MySQL** 和 **Milvus**。 <br />3. 支持知识库条目的新增与修改操作。 <br />4. 确保数据一致性与检索可用性。 |

## 三、环境要求

| 依赖工具           | 版本要求                              | 说明                                             |
| ------------------ | ------------------------------------- | ------------------------------------------------ |
| **Docker Engine**  | `26.1.0+`                             | 容器运行环境                                     |
| **Docker Compose** | `3.8.0+`                              | 多容器编排工具                                   |
| **硬件资源**       | 内存 ≥ 2GB，CPU ≥ 2 核，存储  ≥  20GB | 保障 Milvus 与应用稳定运行，需要手动配置日志管理 |

## 四、安装部署

1. **代码拉取**

   ```
   # 克隆项目仓库
   git clone https://gitee.com/guan-zhengxi/sport-java-rag.git
   ```

2. **配置项**

   根据需要在DockerCompose文件中配置




## 五、使用指南

### 模块 1：赛事分析与预测

1. **准备赛事数据文件（JSON 格式）**

   **注意：** 仅支持欧洲五大联赛，字段不可缺失，格式不可修改。建议单次上传不超过 10 条数据。

   ```
   [
     {
       "league": "英超",           // 仅限：英超、西甲、意甲、德甲、法甲
       "match": "曼城VS利物浦",     // 对阵双方（格式：主队VS客队）
       "date": "2025-04-10",       // 比赛日期（格式：YYYY-MM-DD）
       "time": "02:45:00"          // 比赛时间（格式：HH:MM:SS）
     }
   ]
   ```

2. **操作步骤**

    - 进入平台首页，点击「赛事分析」模块。
    - 点击「选择文件」，上传 JSON 文件。
    - 在「风格选择区」勾选预测风格（支持多选，最多 5 种）。
    - 点击「开始生成」，系统将利用 **RAG** 和 **Spring AI** 生成预测结果。
    - 生成后，可复制单条帖子或点击「下载全部」打包下载。

### 模块 2：RAG 知识库维护

1. **准备知识库数据文件（JSON 格式）**

   **注意：** `matchKey` 需唯一，建议格式为 `联赛_主队_vs_客队_日期`。

   ```
   [
     {
       "matchKey": "英超_曼城_vs_利物浦_2025-05-11", // 唯一标识（不可重复）
       "league": "英超",           // 仅限：英超、西甲、意甲、德甲、法甲
       "homeTeam": "曼城",          // 主队名称
       "awayTeam": "利物浦",        // 客队名称
       "content": "英超争冠关键战役。曼城拥有强大的阵容深度和控球能力..." // 分析内容
     }
   ]
   ```

2. **操作步骤**

    - **新增条目：**
        - 进入「知识库管理」模块。
        - 点击「上传知识文件」，选择 JSON 文件。
        - 点击「确认上传」，系统将自动完成数据存储与向量编码。
    - **修改条目：**
        - 在「知识库管理」页面，找到需修改的条目。
        - 点击右侧「编辑」，修改 `content` 或其他字段（`matchKey` 不可修改）。
        - 点击「保存修改」，系统同步更新数据。

3. **分析风格**

   通过 `/sport/styles` 接口可获取支持的分析风格列表，每种风格决定了分析报告的生成方式。

4. **模型与数据结构**

    - `MatchDTO`: 用于描述比赛信息（联赛、比赛名称、日期、时间）
    - `KnowledgeEntry`: 知识库条目，包含比赛关键字段和分析内容
    - `AnalysisStyleDTO`: 描述分析风格的结构化数据
    - `AnalysisStyle`: 枚举类型，表示支持的分析风格

5. **日志与调试**

   项目组件使用 `Logger` 进行调试和追踪数据处理过程。


## 六、关键注意事项

- **适用范围：** 仅支持欧洲足球五大联赛。
- **安全提示：** 本平台暂无完善的安全措施，请勿暴露至公网。
- **数据格式：** 所有 JSON 文件需严格遵循模板，否则上传将失败，或将引发服务异常。
- **性能限制：** 单次分析赛事数据建议不超过 10 条，单次最多产生 50 条报告。
- **数据备份：** 系统不提供自动备份并且数据库通过容器管理，请根据需要自行调试。
- **功能限制：** 当前版本不支持知识库条目删除和查询，需登录配置中的地址手动操作数据库。

## 七、常见问题（FAQ）

| 问题描述                       | 解决方案                                                     |
| ------------------------------ | ------------------------------------------------------------ |
| 上传非五大联赛数据后信息不准确 | 仅支持英超、西甲、意甲、德甲、法甲，请检查 `league` 字段。   |
| 上传 JSON 文件后系统无响应     | 1. 检查文件格式是否正确。2. 检查文件大小。3. 尝试重启服务。  |
| 生成的预测帖子质量较低         | 1. 补充该联赛/球队的知识库条目。2. 优化知识库 `content` 内容。 |
| 如何确认知识库数据已上传成功   | 上传后系统会有对应的提示信息，后续赛事分析会引用新内容。     |