wehub-resource-sync
89 lines
3.8 KiB
Markdown
89 lines
3.8 KiB
Markdown
# 智能体评估
|
||
|
||
Yuxi 的智能体评估用于回答一个具体问题：某个 Agent 在一组固定任务上能不能稳定完成工作。它不在 Yuxi 内部维护评估数据集、评分规则或对比报表，而是把这些能力交给 Langfuse；Yuxi 只负责按真实 Agent 运行链路执行每条样例，并把结果回写到 Langfuse experiment。
|
||
|
||
## 适用边界
|
||
|
||
这个功能面向 Agent 端到端行为评估，不是知识库检索指标评估。如果你要评估 RAG 检索召回、答案准确率和知识库基准，请使用「知识库评估」。如果你要评估一个 Agent 在编程、研究、工具调用、规划或多步骤任务上的真实表现，则使用本页介绍的 Langfuse dataset experiment 流程。
|
||
|
||
评估链路保持三个边界：
|
||
|
||
- Langfuse 负责 dataset、experiment、score、对比和可视化。
|
||
- Yuxi 后端负责创建正常 conversation 和 AgentRun，并复用 worker 执行链路。
|
||
- `yuxi` CLI 只负责读取 Langfuse dataset、运行 experiment、调用 Yuxi eval API，不负责创建或上传 dataset。
|
||
|
||
## 前置条件
|
||
|
||
1. Yuxi 后端已经启用 Langfuse tracing，并在 `.env` 中配置：
|
||
|
||
```bash
|
||
LANGFUSE_PUBLIC_KEY=...
|
||
LANGFUSE_SECRET_KEY=...
|
||
LANGFUSE_BASE_URL=https://cloud.langfuse.com
|
||
```
|
||
|
||
2. 本机 CLI 环境也能读取同一组 Langfuse 环境变量。`yuxi agent eval` 需要直接调用 Langfuse SDK 读取 dataset 和创建 experiment。
|
||
|
||
3. 已经登录 Yuxi CLI：
|
||
|
||
```bash
|
||
yuxi remote add local http://localhost:5173
|
||
yuxi login --browser
|
||
```
|
||
|
||
评估命令必须使用当前 remote 的登录态，不支持在 `yuxi agent eval` 上直接传 token。CI 环境也必须先执行登录步骤，例如：
|
||
|
||
```bash
|
||
yuxi login --api-key "$YUXI_API_KEY"
|
||
```
|
||
|
||
4. 要评估的 Agent 已经存在，并且当前 CLI 登录用户有权限访问该 Agent。命令使用的是 Agent slug，例如 `default-chatbot`。
|
||
|
||
## 准备 Langfuse Dataset
|
||
|
||
评估数据集必须先在 Langfuse 中准备好。CLI 不提供上传能力，避免把数据集管理职责混进运行命令。
|
||
|
||
Dataset item 的 `input` 推荐使用下面任一字段承载任务文本：
|
||
|
||
```json
|
||
{"input": "请用 Python 完成任务并给出最终答案：..."}
|
||
```
|
||
|
||
也兼容 `query`、`question`、`prompt`。`expected_output` 可以写标准答案，后续在 Langfuse UI 或 evaluator 中使用。
|
||
|
||
## 运行评估
|
||
|
||
上传 dataset 后，用 dataset name 运行：
|
||
|
||
```bash
|
||
yuxi agent eval \
|
||
--dataset-name yuxi-python-tasks-20260619-demo \
|
||
--agent-slug default-chatbot \
|
||
--experiment-name default-chatbot-python-tasks-20260619 \
|
||
--max-concurrency 1 \
|
||
--timeout-seconds 900
|
||
```
|
||
|
||
命令执行流程：
|
||
|
||
1. 从 Langfuse 读取 dataset。
|
||
2. 对每条 dataset item 提取任务文本。
|
||
3. 调用 `POST /api/agent-invocation/eval/runs`。
|
||
4. Yuxi 后端创建正常 conversation 和 AgentRun。
|
||
5. worker 按真实 Agent 链路执行任务。
|
||
6. 接口阻塞到 run 终态后返回最终 assistant output。
|
||
7. CLI 将 output 写回 Langfuse experiment item。
|
||
|
||
`--max-concurrency` 控制 Langfuse experiment runner 的并发数。复杂 Agent 或本地开发环境建议从 `1` 开始，避免同时压垮模型服务、worker 或沙盒。
|
||
|
||
## 查看结果
|
||
|
||
评估完成后，在 Langfuse 控制台打开对应 dataset，可以看到刚创建的 experiment run。每条 item 会保存本次 Yuxi Agent 的最终输出。Yuxi 后端会在运行内部使用 `agent_invocation_meta.evaluation` 保存评估上下文，并给 Langfuse trace 写入 `agent_evaluation` 标记，方便筛选：
|
||
|
||
- `source=agent_evaluation`
|
||
- `evaluation_dataset_name=<dataset name>`
|
||
- `evaluation_dataset_item_id=<item id>`
|
||
- `evaluation_experiment_name=<experiment name>`
|
||
|
||
如果没有看到 experiment，先确认 CLI 环境中的 Langfuse key 和 dataset name 是否正确。如果 experiment 有记录但 Yuxi trace 缺失，检查 `api-dev` 容器是否读取到了同一组 Langfuse 配置。
|