README.md

---
title: Myspace
emoji: 📊
colorFrom: yellow
colorTo: blue
sdk: gradio
sdk_version: 6.20.0
python_version: '3.13'
app_file: app.py
pinned: false
license: mit
short_description: 测试空间
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

# 渔业数据智能查询代理

基于 Hugging Face **smolagents** 框架构建的自然语言查询智能代理，面向渔业科研数据场景，支持查询 logbook 捕捞日志可用性、以及 GFW 渔船作业努力量检索，通过 Gradio Web 界面提供交互式体验。

## 主要功能

- **自然语言查询**：用户以中文自然语言描述需求，代理自动提取参数并调用对应工具
- **Logbook 可用性查询**：按海区、年份范围、物种、数据类型筛选捕捞日志数据
- **GFW 作业努力量查询**：按时间（2012-2024）、空间范围、船旗国、渔具类型检索渔船作业数据
- **CPUE 文献查询**：查询单位捕捞努力量渔获量相关研究文献，支持按海区、年份、物种等筛选
- **SPRFMO 数据查询**：查询南太平洋区域渔业管理组织数据，支持捕捞量/努力量查询和聚合统计
- **交互式 Web 界面**：基于 Gradio 的 Chat 界面，支持流式输出和步骤可视化

## 目录结构

```
myspace/
├── app.py                         # 主程序入口，包含 Agent 定义、Tool 类、Web 界面启动
├── query_tools/                   # 查询工具模块目录
│   ├── __init__.py                # 模块初始化文件
│   ├── logbook_availability_query.py  # Logbook 数据可用性查询函数
│   ├── query_gfw.py               # GFW 渔船作业努力量查询函数（2012-2024）
│   ├── literature_cpue_query.py   # 文献 CPUE 数据查询函数
│   └── query_sprfmo.py            # SPRFMO 南太平洋数据查询函数
├── requirements.txt               # Python 依赖清单
└── .gradio/                       # Gradio 自动生成的 SSL 证书目录
    └── certificate.pem
```

| 文件/目录 | 说明 |
|------|------|
| `app.py` | 项目核心文件，包含 5 个 Tool 类（参数提取、Logbook 查询、GFW 查询、CPUE 文献查询、SPRFMO 查询）、Agent 工厂函数和 GradioUI 启动入口 |
| `query_tools/` | 查询工具模块目录，统一管理所有数据查询工具 |
| `query_tools/logbook_availability_query.py` | Logbook 查询模块，读取本地 CSV 数据并支持多维度筛选与文件输出 |
| `query_tools/query_gfw.py` | GFW 查询模块，从嵌套 ZIP 中提取月度 CSV 数据并按时空范围筛选（仅支持 2012-2024 年数据） |
| `query_tools/literature_cpue_query.py` | 文献 CPUE 数据查询模块，已集成到 Agent |
| `query_tools/query_sprfmo.py` | SPRFMO 南太平洋数据查询模块，已集成到 Agent |
| `requirements.txt` | 项目 Python 依赖包清单 |

## 技术栈

| 类别 | 技术 | 用途 |
|------|------|------|
| Agent 框架 | smolagents | 智能代理核心框架（ToolCallingAgent） |
| LLM 接入 | OpenAIServerModel / DeepSeek API | 大语言模型推理，支持工具调用 |
| Web 界面 | GradioUI (Gradio) | 交互式 Chat 界面，流式输出 |
| 数据处理 | pandas | 数据读取、筛选、格式转换 |
| 数据源 | Hugging Face Datasets | 远程数据集下载（huggingface_hub） |
| 文件解析 | zipfile / openpyxl / csv | ZIP 解压、Excel/CSV 解析 |
| 模块组织 | Python Package (query_tools) | 查询工具统一管理 |
| 编程语言 | Python 3.12+ | 项目开发语言 |

## 环境要求与前置条件

- **Python**：3.12 或更高版本
- **Hugging Face Token**：拥有 HF 账号并在 Settings 中申请 Read 权限的 Access Token（用于访问数据集）
- **LLM API Key**：DeepSeek API Key 或其他 OpenAI 兼容服务的 API Key
- **数据文件**（Logbook/GFW 查询需要）：
  - Logbook：本地需有 `../data/logbook_availability.csv` 数据文件
  - GFW：本地需有 GFW ZIP 数据包，或自动从 `~/Desktop/资料下载/柔鱼数据/` 搜索

## 安装与配置

### 1. 克隆项目

```bash
cd /your/workspace
git clone <repository-url> testAgent
cd testAgent
```

### 2. 创建虚拟环境（推荐）

```bash
conda create -n agentproject python=3.12
conda activate agentproject
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

依赖清单：

| 包名 | 最低版本 | 用途 |
|------|---------|------|
| `smolagents[gradio]` | >=1.0.0 | Agent 框架 + Gradio 集成 |
| `requests` | >=2.31.0 | HTTP 请求 |
| `pandas` | >=2.0.0 | 数据处理 |
| `huggingface_hub` | >=0.23.0 | HF 数据集 API |
| `openpyxl` | >=3.1.0 | Excel 文件解析 |
| `openai` | >=2.0.0 | OpenAI 兼容 LLM 接入 |

### 4. 配置常量

编辑 `readData.py` 文件顶部的常量：

```python
# Hugging Face 数据集访问 Token
HF_TOKEN = "hf_你的Token"

# LLM API 配置
OPENAI_API_KEY = "sk-你的APIKey"
OPENAI_API_BASE = "https://api.deepseek.com/v1"  # API 地址
MODEL_ID = "deepseek-chat"                        # 模型 ID

# DeepSeek 思考模式
THINKING_MODE_ENABLED = True   # True 启用，False 禁用
THINKING_EFFORT = "high"       # low/medium/high/max
```

**常见 API 地址配置**：

| 服务 | `OPENAI_API_BASE` | `MODEL_ID` |
|------|-------------------|------------|
| DeepSeek | `https://api.deepseek.com/v1` | `deepseek-chat` |
| OpenAI | `https://api.openai.com/v1` | `gpt-4o-mini` |
| 本地 Ollama | `http://localhost:11434/v1` | 模型名称 |
| 智谱 GLM | `https://open.bigmodel.cn/api/paas/v4` | `glm-4-flash` |

> **注意**：使用 DeepSeek 思考模式时必须选择 `deepseek-chat`，`deepseek-reasoner` 不支持工具调用。

## 本地开发启动

```bash
cd /your/workspace/myspace
python3 app.py
```

启动后终端将输出：

```
正在启动 GradioUI Web 界面...
Running on local URL:  http://127.0.0.1:7860
Running on public URL: https://xxxxx.gradio.live  (72小时有效)
```

浏览器打开上述地址即可使用 Chat 界面进行查询。

## 生产环境部署

### 方式一：直接运行

```bash
# 前台运行
python3 app.py

# 后台运行（使用 nohup）
nohup python3 app.py > agent.log 2>&1 &
```

### 方式二：Docker 部署

```dockerfile
FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

# 暴露 Gradio 默认端口
EXPOSE 7860

CMD ["python3", "app.py"]
```

```bash
docker build -t fishery-agent .
docker run -d -p 7860:7860 \
  -e HF_TOKEN=hf_你的Token \
  -e OPENAI_API_KEY=sk_你的Key \
  fishery-agent
```

### 方式三：Systemd 服务

```ini
[Unit]
Description=Fishery Data Query Agent
After=network.target

[Service]
Type=simple
User=your_user
WorkingDirectory=/your/workspace/myspace
ExecStart=/your/venv/bin/python3 app.py
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
```

## 使用示例

### 示例 1：查询 Logbook 数据可用性

```
用户：2010到2020年东南太平洋有哪些鱿鱼捕捞日志数据？
```

代理将调用 `logbook_query` 工具，参数提取为 `region="东南太平洋"`, `year_start=2010`, `year_end=2020`, `species="鱿鱼"`。

### 示例 2：查询 GFW 渔船作业努力量

```
用户：查询2012年1月太平洋区域中国渔船的作业努力量
```

代理将调用 `gfw_query` 工具，参数提取为 `year=2012`, `month=1`, `flag="CN"`，以及对应的经纬度范围。

注意：GFW 查询仅支持 **2012-2024 年** 的数据，超出范围会返回错误。

### 示例 3：无明确工具指向的查询

```
用户：帮我查一下有什么数据可以用
```

代理将根据系统提示词中加载的数据集文件列表，告知用户可用的数据和查询方式。

## Agent 工具一览

| 工具名 | 类名 | 功能 | 必填参数 |
|--------|------|------|---------|
| `parameter_extractor` | `ParameterExtractionTool` | 从自然语言提取数据集查询参数 | `user_input` |
| `logbook_query` | `LogbookQueryTool` | 查询 Logbook 捕捞日志可用性 | 无（均为可选） |
| `gfw_query` | `GfwQueryTool` | 查询 GFW 渔船作业努力量（2012-2024） | `year`, `month`, `lat_min`, `lat_max`, `lon_min`, `lon_max` |
| `literature_cpue_query` | `LiteratureCpueQueryTool` | 查询 CPUE 相关文献数据 | 无（均为可选） |
| `sprfmo_query` | `SprfmoQueryTool` | 查询 SPRFMO 南太平洋数据 | `data_type` |

**注意：**
- `logbook_query` 支持可选参数：`region`（海区）、`year_start`（起始年份）、`year_end`（结束年份）、`species`（物种）、`data_type`（数据类型）
- `gfw_query` 仅支持查询 **2012-2024 年**的数据，超出范围会返回错误
- `gfw_query` 支持可选参数：`flag`（船旗国）、`geartype`（渔具类型）、`min_fishing_hours`（最小捕捞小时数）
- `literature_cpue_query` 支持可选参数：`region`（海区）、`year_start`、`year_end`、`species`、`response_variable`（响应变量）、`paper_type`（论文类型）
- `sprfmo_query` 必须指定 `data_type`（'catch' 或 'effort'），支持可选参数：`country`（国家）、`year_start`、`year_end`、`species`（仅捕捞量）、`gear_type`（仅努力量）、`group_by`（聚合维度）