DeepEval 怎么评估 MCP 应用的单轮与多轮工具使用场景-育师

DeepEval 怎么评估 MCP 应用的单轮与多轮工具使用场景

【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval

如果你的应用基于 MCP（Model Context Protocol）工作——一个 Host 通过 Client 连接 MCP Server、调用其中的 tools / resources / prompts——你想知道它是否选对了工具、传对了参数、并最终完成了任务，就可以用deepeval的 MCP 指标来评估。做法分三步：在应用运行时跟踪所有 MCP 交互，在应用执行之后据此创建测试用例，然后用 LLM 评判指标跑evaluate()。单轮场景用LLMTestCase+MCPUseMetric；多轮会话场景用ConversationalTestCase+MultiTurnMCPUseMetric/MCPTaskCompletionMetric。

本文以 Python SDK 为主路径（文档中的示例即 Python），TypeScript 分支在各节末尾给出。

准备条件

按 MCP Evaluation Quickstart/getting-started-mcp.mdx) 的要求，你需要安装deepeval、一个 MCP 客户端，以及你的 Host 实际调用的 LLM SDK。Quickstart 的示例应用通过 streamable HTTP 连接服务器，并调用 Anthropic：

pip install -U deepeval mcp anthropic

TypeScript 环境：

npm install --save-dev deepeval npm install @modelcontextprotocol/sdk @anthropic-ai/sdk

其余前置条件：

评判模型：MCP 指标都是 LLM-as-a-judge，默认使用 OpenAI，需在 CLI 中提供OPENAI_API_KEY。也可以换成任何deepeval支持的模型（如deepeval set-ollama、deepeval set-gemini，或传入自定义DeepEvalBaseLLM实例），配置方式见 configure-llm-judge。
Confident AI API key（推荐）：用于在 Confident AI 平台查看和分享测试报告，在 CLI 中设置CONFIDENT_API_KEY（文档示例值为"confident_us..."，替换成你注册得到的实际 key）。
一个可访问的 MCP 服务器，Host 应用已经能连上它并list_tools()。

单轮与多轮怎么选

两种路径跟踪的是同一类运行时交互（tools_called、resources_called、prompts_called），区别在数据落到哪里：

单轮	多轮
测试用例	`LLMTestCase`（一个`input`/`actual_output`）	`ConversationalTestCase`（多个`Turn`）
MCP 调用记录位置	用例顶层的`mcp_tools_called`等字段	每个`Turn`内部（不是顶层）
指标	`MCPUseMetric`	`MultiTurnMCPUseMetric`、`MCPTaskCompletionMetric`

MCPUseMetric的 FAQ/metrics-mcp-use.mdx) 明确了这一选择标准：单个input/actual_output用MCPUseMetric，跨会话的工具使用用MultiTurnMCPUseMetric。

单轮评估：跟踪交互并构建 LLMTestCase

创建 MCPServer 对象

连接你的 MCP 服务器，把list_tools()的结果作为available_tools存入MCPServer，评估时指标需要用它知道"有哪些原语可用"：

# main.py from contextlib import AsyncExitStack from mcp import ClientSession from mcp.client.streamable_http import streamablehttp_client from deepeval.test_case import MCPServer url = "https://example.com/mcp" # 替换为你自己的 MCP 服务器地址（streamable-http 传输） mcp_servers = [] async def connect(): stack = AsyncExitStack() read, write, _ = await stack.enter_async_context(streamablehttp_client(url)) session = await stack.enter_async_context(ClientSession(read, write)) await session.initialize() tool_list = await session.list_tools() mcp_servers.append(MCPServer( server_name=url, transport="streamable-http", available_tools=tool_list.tools, )) return session, tool_list

TypeScript 分支：new MCPServer({ serverName: url, transport: "streamable-http", availableTools: toolList.tools })。

跟踪工具调用

Host 每次通过 LLM 决定调用工具并执行后，把这次调用记成MCPToolCall。下面是文档示例的调用链：把可用工具转成 Anthropic 的 tools 格式，调messages.create，对返回中的每个tool_use块执行session.call_tool并记录（模型名claude-3-5-sonnet-20241022来自文档示例）：

from anthropic import Anthropic from deepeval.test_case import MCPToolCall tools_called = [] client = Anthropic() async def process_query(session, tool_list, query): available_tools = [ {"name": t.name, "description": t.description, "input_schema": t.inputSchema} for t in tool_list.tools ] response = client.messages.create( model="claude-3-5-sonnet-20241022", max_tokens=1000, messages=[{"role": "user", "content": query}], tools=available_tools, ) response_text = [] for content in response.content: if content.type == "text": response_text.append(content.text) elif content.type == "tool_use": result = await session.call_tool(content.name, content.input) tools_called.append(MCPToolCall( name=content.name, args=content.input, result=result, )) return "\n".join(response_text)

如果你还使用了 MCP 的 resources 或 prompts，同样要跟踪resources_called/prompts_called（MCPUseMetric 文档/metrics-mcp-use.mdx) 说明：只要用到就必须提供，否则指标无法完整评估）。

构建测试用例并运行评估

测试用例必须在应用执行完之后创建。MCPUseMetric的必填字段是input、actual_output、mcp_servers，再加上实际调用过的原语：

from deepeval.test_case import LLMTestCase from deepeval.metrics import MCPUseMetric from deepeval import evaluate test_case = LLMTestCase( input=query, actual_output=response, mcp_servers=mcp_servers, mcp_tools_called=tools_called, ) metric = MCPUseMetric() evaluate([test_case], [metric])

仓库中有一个可直接运行的完整单轮示例：mcp_eval_single_turn.py（streamable HTTP + Anthropic，交互式chat_loop，退出时打印构建好的LLMTestCase）。Quickstart 的建议是让你的main()返回跟踪到的 servers 和 interactions，方便在不同测试文件中复用。

验证结果

evaluate()会把所有指标跑在所有测试用例上，每个指标输出0-1的分数，threshold默认0.5。
也可以单独跑一次用于调试：

metric.measure(test_case) print(metric.score, metric.reason)

注意：单独measure()没有evaluate()/deepeval test run的测试报告、缓存与并发优化，只适合调试或自建评估管线。

设置过CONFIDENT_API_KEY后，test run 会自动出现在 Confident AI；没有登录时，也可以从本地缓存上传：deepeval view（TypeScript 为npx deepeval view）。

多轮评估：把 MCP 交互挂到 Turn 上

多轮的关键区别：mcp_tools_called、mcp_resources_called、mcp_prompts_called要加在每个 assistantTurn对象内部，而不是ConversationalTestCase的顶层（Multi-Turn MCP-Use FAQ/metrics-multi-turn-mcp-use.mdx) 专门强调了这一点）。

跟踪阶段与单轮类似，但每发生一次工具调用，就往turns里追加一个带mcp_tools_called的 assistantTurn：

from deepeval.test_case import MCPToolCall, Turn, ConversationalTestCase turns = [] # 用户每发一条 query turns.append(Turn(role="user", content=query)) # 每次 assistant 调用工具后 result = await session.call_tool(tool_name, tool_args) tool_called = MCPToolCall(name=tool_name, args=tool_args, result=result) turns.append( Turn( role="assistant", content=f"Tool call: {tool_name} with args {tool_args}", mcp_tools_called=[tool_called], ) )

assistant 的文本回复也各追加一个Turn(role="assistant", content=...)（见 mcp_eval_multi_turn.py，该示例通过 stdio 传输连接本地.py/.js服务器脚本，适合你自写 MCP server 的场景）。会话结束后再创建用例——同样必须在应用执行完之后：

convo_test_case = ConversationalTestCase( turns=turns, mcp_servers=mcp_servers, )

定义指标并运行

多轮 MCP 评估支持两个指标，Quickstart/getting-started-mcp.mdx) 建议一起用：

from deepeval.metrics import MultiTurnMCPUseMetric, MCPTaskCompletionMetric from deepeval import evaluate mcp_use_metric = MultiTurnMCPUseMetric() mcp_task_completion = MCPTaskCompletionMetric() evaluate([convo_test_case], [mcp_use_metric, mcp_task_completion])

两者分工不同（MCP Task Completion FAQ/metrics-mcp-task-completion.mdx)）：MCPTaskCompletionMetric评的是结果（任务是否完成），MultiTurnMCPUseMetric评的是过程（原语与参数选择）——工具用得再对也可能没完成目标，所以是互补关系。验证方式与单轮相同：分数0-1、threshold默认0.5，可单独metric.measure(convo_test_case)后打印metric.score与metric.reason，或通过 Confident AI /deepeval view查看完整报告。

读懂分数与排查低分

分数含义以各指标文档的公式为准：

MCPUseMetric：MCP Use Score = AlignmentScore(Primitives Used, Primitives Available)，由评判模型根据"调用了哪些原语及其参数相对于用户输入是否恰当"打分。如果一次原语都没调用，指标会评判"调用任何一个可用原语是否会更好"，即评判"完全不用 MCP"这个决定本身。
MultiTurnMCPUseMetric：AlignmentScore / 总 MCP 交互次数。分母是所有交互，所以每次多出来的调用都被同一标准衡量——多余或低质量的调用会拉低平均分。
MCPTaskCompletionMetric：各交互中完成任务数 / 总交互数。它把 turns 拆成一个个 unit interaction 逐个用 LLM 判断，且是 self-explaining 指标，会输出reason。

排查时文档给出的路径：

单轮分数低：AlignmentScore低意味着选了不合适的原语或参数不对。打开verbose_mode=True（默认False，会把计算中间步骤打印到控制台）或直接读metric.reason，评判模型会给出更优选择的理由。
多轮分数低：某一个坏调用拉低平均分时，同样开verbose_mode查看每次交互的推理，定位是哪一轮的问题；MCPTaskCompletionMetric保持include_reason=True（默认值）可以看到具体哪个交互被判为未完成。
想更严格时调整threshold（可设成None进入 score-only 模式），或设strict_mode=True强制二元打分（1 为完美，否则 0，并覆盖 threshold 为 1）。

关于单轮打分过程有一处文档表述差异：Quickstart/getting-started-mcp.mdx) 描述MCPUseMetric先评 primitive usage、再评 argument correctness、取两者最小值作为最终分数；而 metrics-mcp-use/metrics-mcp-use.mdx) 页给出的公式是单一的AlignmentScore。以指标文档的公式为准，Quickstart 的表述可理解为该对齐打分内部同时考察了原语选择与参数正确性。

限制与下一步

本文主路径是 streamable HTTP 传输 + Anthropic Host（Quickstart 的设定）；stdio 传输、其他 LLM SDK 的接入方式见两个完整示例文件。
MCP 指标评判默认依赖 OpenAI，换用自定义模型时文档提示：无法保证评估行为完全符合预期，因为评估需要较强的指令遵循与 JSON 输出能力。
文档给出的后续动作：按用例收紧threshold；没有数据集时先用 golden synthesizer 生成输入存为 goldens；如果自建了 MCP server，可以在工具定义上配置 tracing，对每次工具调用做 span 级评估。

【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考