企业官网建设流程全解析

Yuxi 智能体评估指南：用 Langfuse Dataset 驱动真实 AgentRun 的实验流程

【免费下载链接】Yuxi可私有部署的多租户知识智能体平台：统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi

导读

本文讲解 Yuxi（可私有部署的多租户知识智能体平台）中"评估智能体"的标准做法：在 Langfuse 中维护一组固定任务（Dataset），再通过yuxi-cli让 Yuxi 按照真实的 AgentRun、worker 与工具调用链路逐条执行，最后把结果写回 Langfuse experiment 供打分与对比。读完本文，你将掌握从环境准备、Dataset 构造、实验运行到结果排查的完整闭环，并理解其底层调用链与实现细节。本文不涉及知识库的recall@K与答案指标评估，那部分见 知识库评估。

评估智能体解决什么问题

智能体与普通问答接口的区别在于：它会编排多步推理、调用工具、读写文件、操作沙盒，最终输出可能依赖大量中间状态。仅靠单条对话的成功与否，难以衡量一个智能体在研究、编程、文件处理或多步骤任务上的真实表现。

Yuxi 的智能体评估方案因此遵循"固定任务 + 真实链路 + 可复现对比"三原则：

• 固定任务：评估样本保存在 Langfuse Dataset 中，与模型版本、Agent 配置解耦，保证多次实验使用同一组输入；
• 真实链路：每条样本都通过真实的POST /api/agent-invocation/eval/runs入口创建临时 Conversation 和 AgentRun，由 worker 调度执行，与生产路径完全一致；
• 可复现对比：每次实验写入独立的 experiment，便于比较同一 Dataset 在不同模型、工具、知识库或外部服务状态下的表现差异。

从源码结构看，评估入口与普通对话入口共用 agent_request_service.py 的submit_agent_request，只是把origin.source固定为agent_evaluation，因此评估结果能反映生产级行为，而非模拟结果。

环境准备

运行智能体评估需要满足以下前提：

1. Yuxi 已配置 Langfuse tracing。API 与 worker 的运行环境需要包含三组变量：

   LANGFUSE_PUBLIC_KEY=<your-public-key> LANGFUSE_SECRET_KEY=<your-secret-key> LANGFUSE_BASE_URL=https://cloud.langfuse.com

   LANGFUSE_BASE_URL用于自托管或指定区域，留空时使用 Langfuse SDK 默认地址；需要显式关闭时可设置LANGFUSE_ENABLED=false（不填写时默认开启，但只有公钥、密钥齐备且已安装 SDK 时才会真正启用 tracing）。修改环境变量后需重新创建 API 和 worker 容器：

   docker compose up -d --force-recreate api worker

   更多细节见 Langfuse 集成。

2. 本机 CLI 能读取同一 Langfuse 项目变量。CLI 进程会直接读取LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY与LANGFUSE_BASE_URL来连接 Dataset 并创建 experiment——注意这与 API/worker 的 tracing 配置相互独立，两侧都要配置。

3. 已安装yuxi-cli并登录目标实例：

   yuxi remote add local http://localhost:5173 yuxi login --browser

   CI 或没有浏览器时，可以使用 API Key 登录：

   yuxi login --api-key "$YUXI_API_KEY"

4. 目标智能体已存在且当前登录用户有权访问。命令中使用 Agent slug 定位智能体，例如default-chatbot；CLI 从本地ConfigStore读取 remote 与 API Key，未登录时会直接报错remote 尚未登录。

准备 Dataset

在 Langfuse 中创建 Dataset，为每个 item 的input字段提供任务文本：

{"input":"请整理这份资料，并列出三个需要核实的事实。"}

CLI 的任务文本提取逻辑（见 agent_eval.py 的extract_query）依次兼容四种字段：input、query、question、prompt；item 直接传字符串也可以。其余字段会被判定为无法提取并报错。

expected_output可以保存参考答案，具体评分规则由 Langfuse evaluator 或人工评审负责。

需要特别强调的是：Yuxi 不负责创建或上传 Dataset。先在 Langfuse 中检查任务文本、参考输出和数据集版本，再运行实验——这保证了"输入可审计、版本可追溯"。

运行实验

准备好 Dataset 后，执行：

yuxi agent eval \ --dataset-name demo-dataset \ --agent-slug default-chatbot \ --experiment-name default-chatbot-demo \ --max-concurrency 1 \ --timeout-seconds 900

命令定义在 main.py 的eval_agent中，参数如下：

执行流程

CLI 对 Dataset 中的每条 item 依次执行：

1. 从 Dataset 读取任务文本（通过extract_query从input/query/question/prompt中提取）；
2. 调用 Yuxi 的POST /api/agent-invocation/eval/runs（客户端实现见 client.py 的run_agent_eval，请求体包含query、agent_slug、evaluation、meta、image_content、model_spec等字段）；
3. 由 Yuxi 创建临时 Conversation 和 AgentRun；
4. 通过 worker 执行真实智能体；
5. 等待 Run 进入终态；
6. 把最终输出写回 Langfuse experiment item。

实验的metadata会记录source=agent_evaluation、agent_slug、dataset_name与remote名称（见 agent_eval.py），便于在 Langfuse 中按元数据筛选整批实验。

并发与超时参数的选择

• --max-concurrency是 Dataset 实验的并发数。建议从1开始，确认单条链路稳定后，再根据模型服务、worker 和沙盒容量逐步提高。并发过高会同时放大模型限流与沙盒创建压力，导致大量超时。
• --timeout-seconds是每条样本等待 Yuxi 结果的上限。超时发生时 CLI 会报告当前运行状态，但不应把它当作成功——后端在等待超时时返回 HTTP 504，并携带运行中的 Run 状态。

查看结果

实验完成后，在 Langfuse Dataset 的 experiment 中查看每条 item 的最终输出。Yuxi 会在本地运行上下文和 trace 中保存以下标记，便于筛选：

source=agent_evaluation evaluation_dataset_name=<dataset-name> evaluation_dataset_item_id=<item-id> evaluation_experiment_name=<experiment-name>

这些标记在后端路由中由EVALUATION_FIELDS = ("dataset_name", "dataset_item_id", "experiment_name")与EVALUATION_SOURCE = "agent_evaluation"常量定义（见 agent_invocation_eval_router.py），经RunOrigin(source=EVALUATION_SOURCE, ...)与origin_metadata写入运行上下文，并随 trace 上报 Langfuse。

评估时注意两点：

• 先横向比较：优先对比同一 Dataset 下多条 item 的输出差异，再按自己的评估规则打分（人工评审或 Langfuse evaluator）；
• 一次实验只代表当时的状态：输出只反映当时的模型、Agent 配置、工具、知识库和外部服务状态。改变这些条件后，应创建新的 experiment 名称，保持实验可追溯。

排查失败

关于"实验部分成功"，CLI 在实验结束后会比较result.item_results数量与 Dataset item 总数，不一致时抛出Langfuse experiment 部分失败: processed/total 个 item 成功写入的错误（对应单测 test_agent_eval.py 中的test_run_langfuse_agent_experiment_rejects_partial_langfuse_results）。因此命令退出码为 0 不代表实验完整，务必回到 Langfuse 逐条核对。

底层实现原理

后端：同步阻塞式评估路由

评估入口 agent_invocation_eval_router.py 定义了POST /agent-invocation/eval/runs，请求体AgentEvalRunCreate支持：

• query（必填）：评估样例输入；
• agent_slug（必填）：目标智能体 slug；
• thread_id：可选，不传则自动创建临时线程（按uid:agent_slug:request_id哈希生成）；
• evaluation：包含dataset_name、dataset_item_id、experiment_name的上下文对象；
• meta：可选追踪信息，支持request_id（幂等 ID，最多 64 字符）；
• image_content：可选 base64 图片内容，可用于多模态评估；
• model_spec、tool_approval_mode：可选的模型与工具审批模式覆盖；
• include_trajectory_summary：是否返回轻量工具调用轨迹摘要。

路由的关键行为：

1. 通过submit_agent_request提交请求，origin.source固定为agent_evaluation、channel为api，并设置queue_policy="reject"（评估为同步语义，不排队）；
2. 创建名为Agent Evaluation Run的临时 Conversation；
3. 调用await_agent_run_result阻塞等待最终结果；等待超时抛AgentRunWaitTimeout并返回 504，携带运行中的 Run 状态供排查；
4. 若开启include_trajectory_summary，则从运行事件流中统计生成轨迹摘要。

轨迹摘要：评估中的可观测性补充

_build_trajectory_summary读取最多 500 条运行事件（TRAJECTORY_SUMMARY_EVENT_LIMIT），输出包含schema_version、event_count、event_range（首尾事件序号）、tool_call_count、tool_error_count、interrupt_count以及按工具聚合的tools列表（含各工具调用次数与错误次数）。中断状态集合覆盖ask_user_question_required、human_approval_required、interrupted三种情况。若运行关联了langfuse_trace_id，摘要中也会带回该 trace ID，方便从评估结果直接跳到完整 trace。

CLI：Dataset 与 Yuxi 之间的编排者

agent_eval.py 中的run_langfuse_agent_experiment负责整体编排：

1. 校验 remote 已登录、并发与超时参数合法；
2. 构造 experiment 名称（未指定时使用yuxi-agent-eval-<UTC时间戳>）；
3. 调用 Langfuse SDK 的dataset.run_experiment(name, task, max_concurrency, metadata)，为每条 item 执行_run_agent_eval_item；
4. 每个 item 生成eval-<uuid>形式的 request_id，并携带完整的 evaluation 上下文调用run_agent_eval；
5. 等待每个 item 返回status=completed并提取output写回 Langfuse；
6. 打印汇总后调用flush()确保数据落库，最后校验写入数量与总数一致。

对应单测覆盖了：extract_query对四种字段与非法输入的兼容性、experiment 元数据与参数的透传、未登录时报错、以及部分成功时的报错逻辑（见 test_agent_eval.py）。

小结

Yuxi 的智能体评估把 Langfuse Dataset 当作"测试集"，把真实的 AgentRun/worker/工具链路当作"被测系统"，用yuxi agent eval一键串联两端：样本输入从 Dataset 读出，真实运行在 Yuxi 上完成，输出写回 experiment 供打分。由于评估走的是生产级调用链，其结果可以可靠地用于比较不同模型、Agent 配置、工具集与知识库条件下的智能体表现。

核心参考：

• 评估路由：agent_invocation_eval_router.py
• CLI 实验实现：agent_eval.py
• 客户端调用：client.py
• CLI 命令定义：main.py
• 单元测试：test_agent_eval.py
• Langfuse 接入：langfuse-integration.md
• 知识库评估（recall@K 等）：evaluation.md

【免费下载链接】Yuxi可私有部署的多租户知识智能体平台：统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi