内容
# AgentOps EvalBench MCP
> 基于MCP的LLM评估和可观测性平台，用于测试RAG和自主AI系统，涵盖扎实性、幻觉风险、检索质量、延迟和成本。
**AgentOps EvalBench MCP** 是一个用于LLM应用的质量控制平台。它帮助开发者通过运行评估测试用例、评分生成的答案、突出显示失败的案例、比较提示/模型版本和导出报告来测试RAG或自主AI系统是否可靠。
本项目专注于AI系统的生产层：**评估、调试、可观测性和质量门控**。
## 亮点
- RAG评估工作流程，包括文档加载、检索、生成和评分
- 衡量扎实性、幻觉风险、相关性、检索质量、延迟、token使用和估计成本的指标
- 用于结果、失败案例、比较和报告的高级Streamlit仪表盘
- 用于项目、测试案例、评估运行、结果和导出的FastAPI后端
- 用于本地开发者工作流程和CI使用的Typer CLI
- 通过标准工具接口公开评估工具的MCP服务器
- 使用`DATABASE_URL`仅作为托管的PostgreSQL
- SQLite和离线备用模式，用于没有密钥的本地演示
- GitHub Actions质量门控，用于自动化检查
## 演示截图
### 仪表盘首页
<img width="900" height="890" alt="仪表盘首页" src="https://github.com/user-attachments/assets/aaed705b-a30f-42a1-a90a-72768de21772" />
### 结果仪表盘
<img width="1747" height="872" alt="结果仪表盘" src="https://github.com/user-attachments/assets/3698461e-270f-4d54-8394-56a98989654b" />
### 失败案例
<img width="1675" height="892" alt="失败案例" src="https://github.com/user-attachments/assets/65362519-f38e-48d0-ae5e-dd8931687737" />
### 比较运行
<img width="865" height="875" alt="比较运行" src="https://github.com/user-attachments/assets/efbcb741-f2d9-49d3-a805-b5bc2febcda3" />
### 导出报告
<img width="606" height="873" alt="导出报告" src="https://github.com/user-attachments/assets/7fe77ae2-aa93-44b5-a2ca-f79d079ccccf" />
## 工作原理
```text
1. 创建项目
2. 加载文档或使用附带的示例文档
3. 创建或导入评估测试案例
4. 运行RAG管道
5. 检索上下文并生成答案
6. 使用评估指标评分每个答案
7. 审查失败的案例和指标分解
8. 比较提示/模型版本
9. 导出Markdown或JSON报告
10. 通过仪表盘、API、CLI或MCP工具运行工作流程
```
每次评估运行都会存储问题、检索的上下文、生成的答案、预期的答案、指标分数、延迟、token使用、估计成本、提示版本、模型配置、通过/失败状态和失败原因。
## 结果
AgentOps EvalBench MCP通过软件测试和小规模的人工标注评估者研究进行了验证。
### 软件验证
| 检查 | 结果 |
|---|---:|
| 自动化测试 | 31通过 |
| CLI烟雾测试 | 通过 |
| FastAPI烟雾测试 | 通过 |
| Streamlit仪表盘烟雾测试 | 通过 |
| 示例评估套件 | 8个案例 |
### 评估者验证
为了测试自动评估者是否与人工判断一致，我创建了一个包含40个示例的标注RAG验证集，涵盖了扎实的答案、幻觉的答案、部分扎实的答案、不相关的答案和弱检索案例。
| 指标 | 结果 |
|---|---:|
| 验证集大小 | 40个示例 |
| 通过/失败协议 | 87.5% |
| 扎实度协议 | 90.0% |
| 幻觉精度 | 1.000 |
| 幻觉召回率 | 0.882 |
| 幻觉F1 | 0.938 |
这些结果表明，评估者不仅在软件上是功能性的，而且在专注的验证集上与人工审查也相当吻合。
验证可以复制：
```bash
python -m agentops_evalbench.evaluation.validation
```
## 架构
```text
┌────────────────────────────────────┐
│ 接口 │
│ │
│ Streamlit UI FastAPI CLI MCP │
└────────┬──────────┬───────┬───────┘
│ │ │
▼ ▼ ▼
┌────────────────────────────────────┐
│ 共享服务层 │
│ 项目/文档/测试/运行/ │
│ 报告/跟踪 │
└─────────────────┬──────────────────┘
│
┌────────────────────────────┼────────────────────────────┐
▼ ▼ ▼
┌──────────────────┐ ┌────────────────────┐ ┌───────────────────┐
│ RAG管道 │ │ 评估引擎 │ │ 持久化 │
│ 文档 → 分片 → │ │ 扎实度/ │ │ SQLAlchemy → │
│ 检索 → LLM │───────►│ 幻觉/ │───────►│ PostgreSQL │
│ 答案 │ │ 相关性/成本 │ │ SQLite备用 │
└──────────────────┘ └────────────────────┘ └───────────────────┘
│
▼
┌────────────────────┐
│ 报告 + CI门控 │
│ Markdown / JSON │
└────────────────────┘
```
## 技术栈
| 层 | 技术 |
|---|---|
| 仪表盘 | Streamlit, Plotly, Pandas |
| 后端API | FastAPI, Pydantic, SQLAlchemy, Uvicorn |
| 数据库 | PostgreSQL, Supabase作为托管的PostgreSQL, SQLite备用 |
| RAG管道 | OpenAI, LangChain, LangGraph, ChromaDB, PyPDF |
| 评估 | 自定义Python评估器, RAGAS/DeepEval兼容设计 |
| CLI | Typer, Rich |
| MCP服务器 | Python MCP SDK |
| 报告 | Markdown, JSON |
| 测试 | Pytest, HTTPX |
| 代码质量 | Ruff, Black |
| DevOps | Docker, Docker Compose, GitHub Actions |
## 项目结构
```text
Agentops-Evalbench-MCP/
├── src/
│ └── agentops_evalbench/
│ ├── api/ # FastAPI应用和路由
│ ├── cli/ # Typer CLI
│ ├── dashboard/ # Streamlit仪表盘
│ ├── evaluation/ # 指标, 评估器, 成本跟踪
│ ├── mcp_server/ # MCP工具
│ ├── rag/ # 文档加载, 向量存储, RAG管道
│ ├── reports/ # Markdown / JSON导出器
│ ├── config.py
│ ├── database.py
│ ├── models.py
│ ├── schemas.py
│ └── services.py
├── data/
│ ├── sample_docs/
│ ├── sample_evals/
│ └── reports/
├── docs/screenshots/
├── tests/
├── .github/workflows/
├── .streamlit/
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── requirements.txt
├── .env.example
└── README.md
```
## 设置
需要 **Python 3.10+**。
```bash
git clone https://github.com/AbhinavVarma02/Agentops-Evalbench-MCP.git
cd Agentops-Evalbench-MCP
python -m venv .venv
```
激活环境：
```bash
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate
```
安装依赖：
```bash
# 完整安装
pip install -r requirements.txt
# 或开发安装
pip install -e ".[db,dev]"
```
创建本地环境文件：
```bash
# Windows
copy .env.example .env
# macOS/Linux
cp .env.example .env
```
在`.env`中添加您的值：
```env
OPENAI_API_KEY=
DATABASE_URL=
```
`DATABASE_URL`对于本地测试是可选的。如果它缺失，应用程序将使用SQLite备用。
## 环境变量
| 变量 | 是否需要 | 目的 |
|---|---:|---|
| `OPENAI_API_KEY` | 用于实时LLM运行 | OpenAI聊天和嵌入 |
| `DATABASE_URL` | 推荐 | PostgreSQL连接字符串 |
| `DEFAULT_MODEL` | 可选 | 默认`gpt-4o-mini` |
| `DEFAULT_EMBEDDING_MODEL` | 可选 | 默认`text-embedding-3-small` |
| `CHROMA_PERSIST_DIR` | 可选 | 本地向量存储路径 |
| `EVAL_MIN_GROUNDEDNESS` | 可选 | 扎实度通过阈值 |
| `EVAL_MAX_HALLUCINATION_RISK` | 可选 | 幻觉风险阈值 |
| `EVAL_MIN_RETRIEVAL_SCORE` | 可选 | 检索质量阈值 |
| `EVAL_MAX_LATENCY_SECONDS` | 可选 | 延迟阈值 |
| `LANGSMITH_API_KEY` | 可选 | 跟踪支持 |
| `LANGSMITH_TRACING` | 可选 | 启用或禁用跟踪 |
Supabase仅通过`DATABASE_URL`用作托管的PostgreSQL。Supabase Auth、Storage、anon密钥和服务角色密钥不需要。
## 运行后端
```bash
python -m uvicorn agentops_evalbench.api.main:app --reload --port 8000
```
打开：
```text
http://127.0.0.1:8000/
http://127.0.0.1:8000/docs
http://127.0.0.1:8000/health
http://127.0.0.1:8000/meta
```
## 运行仪表盘
```bash
streamlit run src/agentops_evalbench/dashboard/streamlit_app.py
```
打开：
```text
http://localhost:8501
```
如果后端离线，仪表盘会显示一个友好的离线消息，并附上启动API的命令。
## 运行CLI
```bash
agentops-eval --help
agentops-eval init
agentops-eval run --project-id 1 --run-name baseline
agentops-eval results --run-id 1
agentops-eval failed --run-id 1
agentops-eval compare --baseline 1 --candidate 2
agentops-eval export --run-id 1 --format markdown
agentops-eval gate --run-id 1 --min-score 0.80
```
## 运行MCP服务器
```bash
python -m agentops_evalbench.mcp_server.server
```
可用的MCP工具：
```text
run_eval
score_answer
compare_runs
export_report
list_eval_runs
get_failed_cases
```
示例MCP服务器配置：
```json
{
"mcpServers": {
"agentops-evalbench": {
"command": "python",
"args": ["-m", "agentops_evalbench.mcp_server.server"]
}
}
}
```
## API端点
| 端点 | 目的 |
|---|---|
| `GET /` | HTML首页 |
| `GET /docs` | Swagger API文档 |
| `GET /health` | JSON健康检查 |
| `GET /meta` | API元数据 |
| `POST /projects` | 创建项目 |
| `GET /projects` | 列出项目 |
| `POST /projects/{project_id}/documents/load-sample` | 加载示例文档 |
| `POST /projects/{project_id}/test-cases` | 创建测试案例 |
| `GET /projects/{project_id}/test-cases` | 列出测试案例 |
| `POST /projects/{project_id}/eval-runs` | 运行评估 |
| `GET /eval-runs/{run_id}` | 获取运行摘要 |
| `GET /eval-runs/{run_id}/results` | 获取详细结果 |
| `GET /eval-runs/{run_id}/failed-cases` | 获取失败案例 |
| `GET /eval-runs/{run_id}/export` | 导出报告 |
| `POST /eval-runs/compare` | 比较运行 |
## 运行测试
```bash
pytest
ruff check .
black --check .
```
当前验证：
```text
31 passed
ruff clean
black clean
```
## GitHub Actions质量门控
存储库包含一个轻量级的CI工作流，安装依赖、运行测试和运行示例评估门控。
```text
.github/workflows/eval-gate.yml
```
## 本项目展示的内容
- LLM评估和可靠性工程
- RAG管道设计
- AI可观测性和质量门控
- MCP工具集成
- FastAPI后端开发
- Streamlit仪表盘
- 开发者工作流的CLI工具
- 使用SQLAlchemy的PostgreSQL持久化
- 安全的环境变量处理
- 可测试和离线友好的AI系统设计
## 未来改进
- 为更大的测试集添加异步/批处理评估
- 通过可插拔的模型接口添加更多提供商适配器
- 添加更丰富的代理跟踪可视化
- 为托管的多用户使用添加用户帐户
- 添加轻量级的VS Code扩展作为单独的阶段
- 完成云部署后添加部署的演示链接
## 许可证
该项目根据MIT许可证授权。
