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

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 构造、实验运行到结果排查的完整闭环并理解其底层调用链与实现细节。本文不涉及知识库的recallK与答案指标评估那部分见 知识库评估。评估智能体解决什么问题智能体与普通问答接口的区别在于它会编排多步推理、调用工具、读写文件、操作沙盒最终输出可能依赖大量中间状态。仅靠单条对话的成功与否难以衡量一个智能体在研究、编程、文件处理或多步骤任务上的真实表现。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因此评估结果能反映生产级行为而非模拟结果。环境准备运行智能体评估需要满足以下前提Yuxi 已配置 Langfuse tracing。API 与 worker 的运行环境需要包含三组变量LANGFUSE_PUBLIC_KEYyour-public-key LANGFUSE_SECRET_KEYyour-secret-key LANGFUSE_BASE_URLhttps://cloud.langfuse.comLANGFUSE_BASE_URL用于自托管或指定区域留空时使用 Langfuse SDK 默认地址需要显式关闭时可设置LANGFUSE_ENABLEDfalse不填写时默认开启但只有公钥、密钥齐备且已安装 SDK 时才会真正启用 tracing。修改环境变量后需重新创建 API 和 worker 容器docker compose up -d --force-recreate api worker更多细节见 Langfuse 集成。本机 CLI 能读取同一 Langfuse 项目变量。CLI 进程会直接读取LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY与LANGFUSE_BASE_URL来连接 Dataset 并创建 experiment——注意这与 API/worker 的 tracing 配置相互独立两侧都要配置。已安装yuxi-cli并登录目标实例yuxi remote add local http://localhost:5173 yuxi login --browserCI 或没有浏览器时可以使用 API Key 登录yuxi login --api-key $YUXI_API_KEY目标智能体已存在且当前登录用户有权访问。命令中使用 Agent slug 定位智能体例如default-chatbotCLI 从本地ConfigStore读取 remote 与 API Key未登录时会直接报错remote 尚未登录。准备 Dataset在 Langfuse 中创建 Dataset为每个 item 的input字段提供任务文本{input:请整理这份资料并列出三个需要核实的事实。}CLI 的任务文本提取逻辑见 agent_eval.py 的extract_query依次兼容四种字段input、query、question、promptitem 直接传字符串也可以。其余字段会被判定为无法提取并报错。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中参数如下参数默认值说明--dataset-name必填Langfuse Dataset 名称--agent-slug必填Yuxi 目标智能体的 slug--experiment-name自动生成未指定时生成yuxi-agent-eval-UTC时间戳--remote当前 remote目标实例 remote 名称--max-concurrency1Dataset 实验的并发数必须大于等于 1--timeout-seconds900每条样本等待 Yuxi 结果的上限秒必须大于 0执行流程CLI 对 Dataset 中的每条 item 依次执行从 Dataset 读取任务文本通过extract_query从input/query/question/prompt中提取调用 Yuxi 的POST /api/agent-invocation/eval/runs客户端实现见 client.py 的run_agent_eval请求体包含query、agent_slug、evaluation、meta、image_content、model_spec等字段由 Yuxi 创建临时 Conversation 和 AgentRun通过 worker 执行真实智能体等待 Run 进入终态把最终输出写回 Langfuse experiment item。实验的metadata会记录sourceagent_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 中保存以下标记便于筛选sourceagent_evaluation evaluation_dataset_namedataset-name evaluation_dataset_item_iditem-id evaluation_experiment_nameexperiment-name这些标记在后端路由中由EVALUATION_FIELDS (dataset_name, dataset_item_id, experiment_name)与EVALUATION_SOURCE agent_evaluation常量定义见 agent_invocation_eval_router.py经RunOrigin(sourceEVALUATION_SOURCE, ...)与origin_metadata写入运行上下文并随 trace 上报 Langfuse。评估时注意两点先横向比较优先对比同一 Dataset 下多条 item 的输出差异再按自己的评估规则打分人工评审或 Langfuse evaluator一次实验只代表当时的状态输出只反映当时的模型、Agent 配置、工具、知识库和外部服务状态。改变这些条件后应创建新的 experiment 名称保持实验可追溯。排查失败现象排查方向没有 experiment检查 CLI 的 Langfuse 公钥、密钥、地址和 Dataset 名称experiment 有 item 但 Yuxi 失败检查 CLI 登录的 API Key、Agent slug并用docker compose logs api worker查看当前槽位日志Trace 缺失检查 API/worker 是否读取到 Langfuse 配置Yuxi 业务结果仍以 PostgreSQL 的 Run 和消息为准大量超时降低--max-concurrency检查模型响应时间、worker 健康状态和沙盒创建耗时实验部分成功不要只看命令退出前的汇总回到 Langfuse 检查每条 item 是否都有结果关于实验部分成功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必填目标智能体 slugthread_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是否返回轻量工具调用轨迹摘要。路由的关键行为通过submit_agent_request提交请求origin.source固定为agent_evaluation、channel为api并设置queue_policyreject评估为同步语义不排队创建名为Agent Evaluation Run的临时 Conversation调用await_agent_run_result阻塞等待最终结果等待超时抛AgentRunWaitTimeout并返回 504携带运行中的 Run 状态供排查若开启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。CLIDataset 与 Yuxi 之间的编排者agent_eval.py 中的run_langfuse_agent_experiment负责整体编排校验 remote 已登录、并发与超时参数合法构造 experiment 名称未指定时使用yuxi-agent-eval-UTC时间戳调用 Langfuse SDK 的dataset.run_experiment(name, task, max_concurrency, metadata)为每条 item 执行_run_agent_eval_item每个 item 生成eval-uuid形式的 request_id并携带完整的 evaluation 上下文调用run_agent_eval等待每个 item 返回statuscompleted并提取output写回 Langfuse打印汇总后调用flush()确保数据落库最后校验写入数量与总数一致。对应单测覆盖了extract_query对四种字段与非法输入的兼容性、experiment 元数据与参数的透传、未登录时报错、以及部分成功时的报错逻辑见 test_agent_eval.py。小结Yuxi 的智能体评估把 Langfuse Dataset 当作测试集把真实的 AgentRun/worker/工具链路当作被测系统用yuxi agent eval一键串联两端样本输入从 Dataset 读出真实运行在 Yuxi 上完成输出写回 experiment 供打分。由于评估走的是生产级调用链其结果可以可靠地用于比较不同模型、Agent 配置、工具集与知识库条件下的智能体表现。核心参考评估路由agent_invocation_eval_router.pyCLI 实验实现agent_eval.py客户端调用client.pyCLI 命令定义main.py单元测试test_agent_eval.pyLangfuse 接入langfuse-integration.md知识库评估recallK 等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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考