Spaces:
Sleeping
Sleeping
| 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`（聚合维度） | |