Spaces:
Sleeping
Sleeping
metadata
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/资料下载/柔鱼数据/搜索
- Logbook：本地需有
安装与配置
1. 克隆项目
cd /your/workspace
git clone <repository-url> testAgent
cd testAgent
2. 创建虚拟环境（推荐）
conda create -n agentproject python=3.12
conda activate agentproject
3. 安装依赖
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 文件顶部的常量：
# 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不支持工具调用。
本地开发启动
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 界面进行查询。
生产环境部署
方式一：直接运行
# 前台运行
python3 app.py
# 后台运行（使用 nohup）
nohup python3 app.py > agent.log 2>&1 &
方式二：Docker 部署
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"]
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 服务
[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（聚合维度）