# agent_eval_full **Repository Path**: jasonchan0754/agent_eval_full ## Basic Information - **Project Name**: agent_eval_full - **Description**: 知识问答在线评估工具 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-03-04 - **Last Updated**: 2026-03-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # RAG 评测实验室 (Agent Eval Full) 面向 HiAgent 平台的 **RAG 智能客服全栈评测系统**，集评测、监控、拨测、压测于一体。 ## 功能一览 | 模块 | 说明 | |------|------| | **评测台** | Simple（单分数）/ Complex（四维 TS/GR/SAF/ACT）两种模式，WebSocket 实时推送 | | **数据集管理** | 测试集 & 校准集的上传、预览、编辑、标签管理 | | **评测规则** | Judge 评分规则 CRUD，预置 + 自定义 | | **评测历史** | 运行记录查询、结果分页、逐条回放 | | **会话监控** | HiAgent 线上会话日志、会话详情、检索链路追踪、应用统计仪表盘 | | **拨测** | 多题轮询定时探测 Agent 健康状态，默认 10 分钟间隔 | | **压力测试** | 多阶梯并发压测，自定义题库，FCL/延迟 P50/P90 实时图表 | | **系统设置** | 全部配置项前端可编辑，热更新无需重启 | | **报告导出** | PDF 评测报告 + 调优建议自动生成 | | **CLI 批量评测** | `./run.sh` 命令行评测，适合 CI/CD | --- ## 快速开始 ### 方式一：Docker 一键部署（推荐） ```bash cp .env.example .env # .env 用于 Docker fallback / 初始化，正式运行配置建议在前端「系统设置」页面填写并持久化 # 如需远程浏览器访问，再在 .env 中补充 VITE_API_URL / VITE_WS_URL docker compose up --build -d ``` - 前端：`http://localhost:8080` - 后端：`http://localhost:8001` - API 文档：`http://localhost:8001/docs`（Swagger UI） - Docker 数据目录：默认持久化到宿主机 `./docker-data/backend` ### 方式二：本地开发 ```bash # 后端 python3 -m venv .venv && source .venv/bin/activate python3 -m pip install -r backend/requirements.txt -r backend/requirements-dev.txt uvicorn backend.main:app --reload --port 8001 # 前端（另一个终端） cd frontend && npm install && npm run dev ``` - 前端：`http://localhost:5173` - 后端：`http://localhost:8001` ### 方式三：CLI 批量评测 ```bash cp .env.example .env # 编辑 .env，填写 HIAGENT_AGENT_URL/KEY + SIMPLE_JUDGE_* 配置 ./run.sh --test-set ./test_set.csv --simple-eval ``` --- ## 系统架构 ``` ┌───────────────────────────────┐ │ 浏览器 / CLI 终端 │ └───────┬───────────────┬───────┘ │ │ WebSocket/REST ./run.sh │ │ ┌───────────────────────────▼───────────────▼──────────────────┐ │ FastAPI 后端 (Port 8001) │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐ │ │ │评测引擎 │ │监控引擎 │ │压测引擎 │ │ 设置 / 数据集 │ │ │ │Simple │ │TOP 协议 │ │阶梯并发 │ │ / 规则 Store │ │ │ │Complex │ │Trace 解析 │ │WS 推送 │ │ │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └───────┬────────┘ │ │ │ │ │ │ │ │ ┌────▼────────────▼────────────▼───────────────▼────────┐ │ │ │ SQLite (/app/data/eval.db -> ./docker-data/backend) │ │ │ │ datasets | rulesets | runs | benchmarks | settings │ │ │ └───────────────────────────────────────────────────────┘ │ └──────────┬──────────────────┬────────────────────────────────┘ │ │ ┌──────▼──────┐ ┌──────▼──────┐ │ HiAgent │ │ Judge LLM │ │ 被测智能体 │ │ 评判模型 │ └─────────────┘ └─────────────┘ ``` --- ## 前端页面 | 页面 | 路径 | 说明 | |------|------|------| | 评测台 | `/` | 配置 + 实时评测 + 结果表格 + 诊断面板 | | 评测历史 | `/runs` | 历史记录列表，点击进入详情 | | 数据集管理 | `/datasets` | 上传、预览、编辑、删除测试集/校准集 | | 评测规则 | `/rulesets` | Judge 评分规则管理 | | 会话监控 | `/monitor` | 会话日志、会话详情、消息日志、调试会话、统计仪表盘、压力测试 | | 拨测 | `/smoke-test` | 定时多题轮询探测 Agent 健康 | | 系统设置 | `/settings` | Agent/Judge/Monitor/评测参数 配置 | --- ## 配置说明 所有配置项支持两种设置方式，但职责不同： 1. **前端设置页面**（推荐）：部署后在浏览器 `/settings` 页面填写，保存到 SQLite，后续重启仍生效 2. **`.env` 文件**：适合容器首次启动时的 fallback / 初始化值，或 CI/CD 场景 后端运行时配置优先级： `/settings` 持久化值 > Docker 容器环境变量（通常来自 `.env`）> 代码默认值 前端访问地址是例外： `VITE_API_URL` 和 `VITE_WS_URL` 是前端镜像的构建期变量，不受 `/settings` 热更新控制；修改后需要重新构建前端镜像。 | 配置组 | 关键配置项 | 说明 | |-------|-----------|------| | Agent 连接 | `HIAGENT_AGENT_URL`, `HIAGENT_AGENT_KEY` | 被测智能体的 API 地址和密钥 | | Judge 服务 | `SIMPLE_JUDGE_BASE_URL`, `SIMPLE_JUDGE_API_KEY`, `SIMPLE_JUDGE_MODEL` | LLM 评分服务（OpenAI 兼容） | | Monitor TOP | `MONITOR_TOP_AK`, `MONITOR_TOP_SK`, `MONITOR_TOP_API_TOKEN` | HiAgent 会话监控凭证 | | 评测参数 | `EVAL_AGENT_CALL_MODE`, `EVAL_FAIL_FAST` | 评测行为控制 | | 前端访问地址 | `VITE_API_URL`, `VITE_WS_URL` | 仅前端镜像构建时生效，远程访问时需设置 | 完整配置项列表见 `.env.example` 或 [`docs/api-reference.md` 附录](docs/api-reference.md#附录配置项一览)。 --- ## Docker 部署 ### 生产模式 ```bash docker compose up --build -d ``` - 后端 SQLite 默认映射到宿主机 `${BACKEND_DATA_DIR:-./docker-data/backend}` - 日常重启或 `docker compose down` 不会清空数据 - 不要在生产环境执行 `docker compose down -v` | 服务 | 地址 | |------|------| | 前端 | `http://localhost:8080` | | 后端 | `http://localhost:8001` | ### 开发模式（热更新） ```bash docker compose -f docker-compose.dev.yml up --build ``` | 服务 | 地址 | |------|------| | 前端 | `http://localhost:5173`（Vite HMR） | | 后端 | `http://localhost:8001`（auto-reload） | ### 远程部署 ```bash cp .env.example .env # 编辑 .env，填写： # VITE_API_URL=http://:8001 # VITE_WS_URL=ws://:8001/ws docker compose up --build -d ``` 前端生产镜像当前使用 `node:20-alpine` 构建、`nginx:alpine` 运行，优先兼容受限网络和本地镜像缓存环境。 --- ## 测试 ```bash # 后端测试 python3 -m pip install -r backend/requirements.txt -r backend/requirements-dev.txt python3 -m pytest backend/tests/ -q # 前端构建检查 cd frontend && npm run build ``` --- ## 项目结构 ``` Agent_eval_full/ ├── backend/ # FastAPI 后端 │ ├── main.py # API 入口（34+ 端点 + 2 WebSocket） │ ├── eval_engine.py # Simple 模式评测引擎 │ ├── complex_engine.py # Complex 模式评测引擎 │ ├── monitor_engine.py # 会话监控引擎 │ ├── benchmark_manager.py # 压测管理器 │ ├── smoke_test_engine.py # 拨测引擎（多题轮询） │ ├── top_client.py # HiAgent TOP 协议客户端 │ ├── settings_store.py # 运行时配置管理 │ ├── database.py # SQLite 数据层 │ ├── tests/ # 后端测试（61 tests） │ └── Dockerfile ├── frontend/ # React + Vite + MUI 前端 │ ├── src/pages/ # 8 个页面 │ ├── src/components/ # 20+ 组件 │ └── Dockerfile ├── scripts/ # CLI 评测与工具脚本 │ ├── run_eval.py # CLI 评测入口 │ └── ... ├── docs/ │ ├── api-reference.md # API 参考手册 │ └── plans/ # 设计文档 ├── run.sh # CLI 评测入口 ├── docker-compose.yml # 生产部署 ├── docker-compose.dev.yml # 开发部署 ├── .env.example # 环境变量模板 ├── 用户手册.md # 用户手册（详尽使用指南） └── README.md # 本文件 ``` --- ## 更多文档 - **用户手册**：[`用户手册.md`](用户手册.md) — 完整的使用指南，每个模块的详细操作说明 - **API 参考**：[`docs/api-reference.md`](docs/api-reference.md) — 全部接口说明 - **部署指南**：[`LINUX_DEPLOYMENT_GUIDE.md`](LINUX_DEPLOYMENT_GUIDE.md) — Linux 服务器部署