使用 Ragas workflow_eval 模板评估复杂 LLM 工作流邮件分类与路由实战指南【免费下载链接】ragasSupercharge Your LLM Application Evaluations 项目地址: https://gitcode.com/gh_mirrors/ra/ragas本文基于 Ragas CLI 的workflow_eval快速开始模板讲解如何对“分类 → 信息抽取 → 回复生成”这类多步骤 LLM 工作流进行端到端评估。读者将掌握从项目脚手架创建、依赖安装、数据集与离散指标DiscreteMetric定义到实验运行与结果解读的完整闭环并理解其底层源码实现可直接迁移到自己的业务流程评估中。模板定位评估什么workflow_eval是 Ragas CLI 内置的快速开始模板之一其官方描述为“使用邮件分类与路由场景评估复杂 LLM 工作流”见 CLI 模板注册表。与单轮 RAG 问答评估不同它面向的是内部由多个 LLM 调用与确定性逻辑串联而成的业务流水线——即使每个环节单独看起来都正确组合起来的端到端行为仍然可能出错因此需要以“整条流水线”为单位进行验收。该模板评估的目标是一个客户支持邮件处理工作流工作流形态多步骤邮件处理分类 → 抽取 → 回复对应workflow.py中的ConfigurableSupportTriageAgent.process_email()分类类别Bug Report缺陷报告、Feature Request功能需求、Billing账单问题三类测试用例一批带预期类别与期望抽取字段的客户邮件核心指标一个自定义离散指标DiscreteMetric以pass/fail方式校验工作流输出是否满足逐条编写的pass_criteria。从零开始创建项目并运行评估workflow_eval模板与其余 8 个模板一样通过ragas quickstart命令分发其实现位于 src/ragas/cli.py该命令本质上是从模板源目录ragas_examples/workflow_eval克隆出一个完整可运行的项目模板源码即仓库中的 examples/ragas_examples/workflow_eval/。第一步创建项目ragas quickstart workflow_eval cd workflow_eval不传模板名时ragas quickstart会列出全部可用模板quickstart还支持-o/--output-dir指定输出目录默认当前目录例如ragas quickstart workflow_eval -o ./my-project参见 Ragas CLI 总览。项目创建后目录内会生成 README、pyproject.toml 及示例代码等脚手架文件。第二步安装依赖uv sync模板通过pyproject.toml声明ragas、openai等依赖uv sync会依据锁文件一键创建虚拟环境并安装全部依赖。若本机尚未安装uv也可以改用pip install ragas后直接运行ragas包内已包含 CLI 入口。第三步配置 API Keyexport OPENAI_API_KEYyour-openai-key该 Key 被三处消费工作流内部的分类/抽取/回复调用使用gpt-3.5-turbo、评估阶段的裁判 LLMgpt-4o见evals.py中的llm_factory(gpt-4o, clientopenai_client)以及OpenAI客户端的初始化。第四步运行评估uv run python evals.py运行结束后终端会打印Experiment_result:及每条样本的评估明细。整个运行链路为load_dataset()构建数据集 →run_experiment.arun(dataset)逐条执行工作流并用离散指标打分 → 将结果含原始行、response、score、score_reason写入实验存储。项目结构解析模板生成的工程布局如下workflow_eval/ ├── README.md # 项目文档 ├── pyproject.toml # 项目配置与依赖声明 ├── workflow.py # 工作流实现业务方代码 ├── evals.py # 评估工作流Ragas 侧代码 ├── __init__.py # Python 包标记 └── evals/ ├── datasets/ # 测试数据集运行时生成/保存 ├── experiments/ # 评估结果 └── logs/ # 执行日志其中workflow.py与evals.py是核心文件职责严格分离前者是被测对象后者是评估编排。运行时还会产生额外产物——evals.py中以local/csv后端保存的test_dataset以及workflow.py中工作流 agent 按logdirlogs写出的 JSON 运行轨迹详见下文“可观测性”小节。被测工作流实现workflow.pyworkflow.py是一个结构完整、可直接运行的客户支持分流 Agent核心类为ConfigurableSupportTriageAgent对外暴露default_workflow_client()工厂函数from workflow import default_workflow_client workflow default_workflow_client() result workflow.process_email(I found a bug in version 2.1.4...) # 返回: category, extracted_info, response_templateprocess_email()内部严格按三个阶段串行执行对应源码 workflow.py分类Step 1classify_email()调用gpt-3.5-turbotemperature0要求只输出Billing/Bug Report/Feature Request三个类别之一调用失败时回退为Bug Report并记录错误 trace。抽取Step 2extract_info()根据类别调用当前配置的抽取器。模板默认使用DeterministicExtractor——纯正则/规则实现例如用version\s*[:\-]?\s*([0-9]\.[0-9](?:\.[0-9])?)提取版本号、invoice\s*[#:\-]?\s*([A-Z0-9\-_])提取发票号并内置了紧急度关键词表urgent/high/medium/low与产品区域表dashboard/api/mobile/reports/billing 等。也可通过default_workflow_client(extractor_typellm)切换为LLMExtractor用gpt-3.5-turbo以 JSON 格式输出同样的字段。回复Step 3generate_response()将“类别 抽取字段”拼成上下文让 LLM 生成礼貌、专业、引用了抽取信息的回复模板temperature0.3失败时回退到固定话术。该设计刻意体现了“确定性逻辑 LLM 调用”混合工作流的典型特征分类与回复依赖 LLM字段抽取则可选正则或 LLM 两种实现这为后续做“抽取器对比实验”留出了天然的评估空间。可观测性Trace 与日志导出ConfigurableSupportTriageAgent内部维护self.traces事件列表TraceEvent记录llm_call、llm_response、extraction、error等事件类型及所属组件每次process_email()结束后通过export_traces_to_log()将run_id、时间戳、原始邮件、结果与全部 trace 以 JSON 形式落盘到logs/run_run_id_*.json。这意味着即便工作流本身判断失误评估者仍可拿到每一步的中间证据是定位端到端失败根因的关键抓手。评估脚本核心evals.py数据集构建行数据 pass_criteriaload_dataset()内置了 10 条真实风格的中英文混合测试邮件每条样本是一个“输入 验收标准”对def load_dataset(): dataset_dict [ { email: Hi, Im getting error code XYZ-123 when using version 2.1.4..., pass_criteria: category Bug Report; product_version 2.1.4; error_code XYZ-123, }, # More test cases... ]数据集通过Dataset类构建指定nametest_dataset、backendlocal/csv、root_dir.逐条append()后save()持久化。pass_criteria是这套模板的精髓——它把“类别是否正确 关键字段是否抽全 回复是否引用关键信息”压缩成了一段半结构化验收文本交由裁判 LLM 做最终判定。离散指标DiscreteMetricmy_metric DiscreteMetric( nameresponse_quality, promptEvaluate the response based on the pass criteria: {pass_criteria}. Does the response meet the criteria? Return pass or fail.\nResponse: {response}, allowed_values[pass, fail], )DiscreteMetric位于 src/ragas/metrics/discrete.py继承自SimpleLLMMetric与DiscreteValidator专用于输出预定义类别值的评估场景。其关键实现点allowed_values默认即[pass, fail]可扩展为任意离散类别如excellent/good/poor__post_init__中通过create_auto_response_model自动构建一个带reason判定理由与value判定结果的结构化响应模型底层使用 instructor 库强制 LLM 输出符合该模型的 JSONscore()返回的对象同时携带.value与.reason两个字段评估结果天然可解释。实验编排experimentexperiment() async def run_experiment(row): response workflow_client.process_email(row[email]) score my_metric.score( llmllm, responseresponse.get(response_template, ), pass_criteriarow[pass_criteria], ) experiment_view { **row, response: response.get(response_template, ), score: score.value, score_reason: score.reason, } return experiment_viewexperiment装饰器实现在 src/ragas/experiment.py把普通异步函数包装为ExperimentWrapper使其获得.arun(dataset)批量执行能力。注意这里的评估对象是response_template而非最终分类——因为pass_criteria中同时约束了“category 正确 字段被抽取 回复引用关键信息”而工作流生成回复时已将分类结果与抽取字段注入上下文所以对回复模板的离散判定实际上等效于对整条流水线做端到端验收。深入原理llm_factory 与裁判 LLMevals.py通过llm_factory(gpt-4o, clientopenai_client)创建裁判 LLM。llm_factory定义于 src/ragas/llms/base.py签名要点如下参数默认值说明model必填模型名如gpt-4o、claude-3-sonnet、gemini-2.0-flashprovideropenaiLLM 提供商如openai/anthropic/google等clientNone已初始化的客户端实例OpenAI 场景必传adapterauto结构化输出适配器auto自动探测instructor为默认litellm支持 100 提供商cacheNone可传DiskCacheBackend()缓存 LLM 响应重复评估可显著提速并省钱modeNoneinstructor 结构化输出模式默认Mode.JSON不支持response_format的后端可用Mode.MD_JSON其返回对象统一提供generate()与agenerate()方法接受 Pydantic 模型以约束输出结构——这正是DiscreteMetric能拿到稳定value/reasonJSON 的底层保障。测试用例设计三类场景全覆盖模板内置的 10 条用例刻意覆盖了正常、边界与鲁棒性场景场景预期类别关键验收点报错码 版本号Bug Reportproduct_version 2.1.4; error_code XYZ-123发票争议金额Billinginvoice_number INV-2024-001; amount 299.99需求 产品区域 紧急度Feature Requestrequested_feature dark mode; product_area dashboard; urgency_level high/medium只有错误码、无版本号Bug Reportproduct_version null要求优雅处理缺失版本紧急 PDF 导出需求Feature Requesturgency_level urgent/high要求回复体现紧急度语气随意的定制需求Feature Requesturgency_level low/medium要求回复匹配轻松语气模糊版本描述latestBug Reportproduct_version latest/null要求识别 API 上下文Beta 版本崩溃Bug Reportproduct_version 2.5.1-beta; error_code FATAL_ERROR_001非标准发票格式Billinginvoice_number BILL2024-March-001; amount 1299要求容忍非标准格式结构化短文本Feature needed:...Feature Request要求能解析结构化输入从源码结构看这些用例针对三类最常见的失败模式设计抽取器对非标准格式的鲁棒性正则未命中返回None、缺失字段时的优雅降级generate_response与回退话术、语气/紧急度等软性属性的对齐依赖裁判 LLM 对pass_criteria的语义理解。新增用例只需追加一条{email: ..., pass_criteria: ...}字典即可。自定义与扩展替换为自己的工作流评估代码与被测工作流完全解耦替换成本极低from your_workflow import YourWorkflow workflow YourWorkflow() experiment() async def run_experiment(row): result await workflow.process(row[input]) # 将 result 映射为可被离散指标评分的字段例如: # score my_metric.score(llmllm, responseresult[output], pass_criteriarow[pass_criteria])只需满足两个约定一是工作流入口接收数据行、返回可评分的输出字段二是为每个输入行配套编写对应的pass_criteria。若工作流是异步实现直接await workflow.process(...)即可experiment原生支持异步函数。进一步可探索的方向切换抽取器做对比实验default_workflow_client(extractor_typellm)可对比“正则抽取 vs LLM 抽取”对端到端通过率的影响这正是workflow.py预留set_extractor()运行时切换能力的意义更换裁判模型修改llm_factory的模型名或provider即可评估同一工作流在不同裁判 LLM 下的稳定性扩展离散类别将allowed_values改为[pass, partial, fail]等更细粒度等级并相应调整prompt中的判定指令使用 CLI 直跑在已生成项目的基础上也可参考 Ragas CLI 总览 使用ragas evals evals.py --dataset ... --metrics ...从命令行触发评估适合接入 CI 场景。下一步Agent Evaluation评估求解数学问题的 AI AgentLlamaIndex Agent Evaluation用工具调用类指标评估 LlamaIndex Agent。若你的业务同样存在“多个 LLM 步骤串联、需要整体验收”的场景如工单分流、意图路由、客服自动应答workflow_eval模板的“输入 pass_criteria 离散判定”三件套可以直接作为你评估体系的起点。【免费下载链接】ragasSupercharge Your LLM Application Evaluations 项目地址: https://gitcode.com/gh_mirrors/ra/ragas创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考