Arize Phoenix 集成 Smolagents 实现智能体追踪与评估
Arize Phoenix 推出针对 Hugging Face Smolagents 框架的集成方案,提供可视化的智能体执行追踪与自动化评估能力。该工具通过记录输入、处理步骤及最终输出,帮助开发者诊断智能体行为并量化其性能表现。
报道正文
本文目录14 个章节
使用 Arize Phoenix 追踪与评估你的 Agent
发布于 2025 年 2 月 28 日 在 GitHub 上更新 点赞 43
Sri Chavali schavalii arize-ai John Gilhuly jgilhuly16 arize-ai Aymeric Roucher m-ric
假设你已经构建好了自己的 Agent。它接收输入和工具,处理这些信息,并生成响应。也许它正在做出决策、检索信息、自主执行任务,或者三者兼而有之。但现在面临一个关键问题——它的表现如何?更重要的是,你如何得知?
构建 Agent 是一回事;理解其行为则是另一回事。这就是追踪(Tracing)和评估(Evaluation)发挥作用的地方。追踪让你能够逐步看清 Agent 的具体操作——它接收了哪些输入,如何处理信息,以及如何得出最终输出。你可以将其想象为对 Agent 决策过程进行“X 光透视”。与此同时,评估帮助你衡量性能,确保你的 Agent 不仅功能可用,而且真正有效。它是否给出了正确的答案?每一步的发现相关性如何?Agent 的响应质量如何?是否符合你的目标?
Arize Phoenix 提供了一个集中式平台,让你能够实时追踪、评估和调试 Agent 的决策——所有功能集成于一处。我们将深入探讨如何通过实施这些功能来完善和优化你的 Agent。因为构建只是开始——真正的智能源于对底层运作机制的清晰洞察。
为此,让我们先确保有一个配置好的 Agent!你可以按照以下步骤进行操作,也可以使用你自己的 Agent。
创建一个 Agent
步骤 1:安装所需的库
pip install -q smolagents步骤 2:导入所有核心组件
现在,让我们引入将要使用的类和工具:
from smolagents import (
CodeAgent,
DuckDuckGoSearchTool,
VisitWebpageTool,
HfApiModel,
)步骤 3:设置基础模型
我们将创建一个由 Hugging Face Hub Serverless API 驱动的模型实例:
hf_model = HfApiModel()步骤 4:创建调用工具的 Agent
agent = CodeAgent(
tools=[DuckDuckGoSearchTool(), VisitWebpageTool()],
model=hf_model,
add_base_tools=True
)步骤 5:运行 Agent
现在到了见证奇迹的时刻——让我们看看 agent 的实际表现。我们向 agent 提出的问题是: “获取 Google 从 2020 年到 2024 年的股价,并据此创建一个折线图?”
agent.run("fetch the share price of google from 2020 to 2024, and create a line graph from it?")你的 agent 将会执行以下操作:
- 使用
DuckDuckGoSearchTool搜索 Google 的历史股价。 - 可能使用
VisitWebpageTool访问网页以查找相关数据。 - 尝试收集信息,并生成或描述如何创建该折线图。
追踪你的 Agent
当你的 agent 开始运行后,下一个挑战是理解其内部工作流。追踪(Tracing)功能有助于你记录 agent 执行的每一步——从调用工具、处理输入到生成响应——从而让你能够调试问题、优化性能并确保其行为符合预期。
为了启用追踪,我们将使用 Arize Phoenix 进行可视化,并结合 OpenTelemetry + OpenInference 进行插桩(instrumentation)。
安装 smolagents 的遥测模块:
pip install -q 'smolagents[telemetry]'你可以通过多种方式运行 Phoenix。以下命令将在你的本地机器上启动一个 Phoenix 实例:
python -m phoenix.server.main serve关于 Phoenix 的其他托管选项,你可以 创建一个免费的在线 Phoenix 实例,在本地自托管应用程序,或者 将应用程序托管在 Hugging Face Spaces 上。
启动后,我们需要注册一个 tracer provider,并将其指向我们的 Phoenix 实例。
from phoenix.otel import register
from openinference.instrumentation.smolagents import SmolagentsInstrumentor
tracer_provider = register(project_name="my-smolagents-app")
SmolagentsInstrumentor().instrument(tracer_provider=tracer_provider) 现在,任何对 smolagents 的调用都将通过我们的 Phoenix 实例发送。
既然追踪已启用,让我们用一个简单的查询来测试它:
agent.run("What time is it in Tokyo right now?")一旦 OpenInference 与 SmolAgents 配置完成,每次 agent 调用都将在 Phoenix 中自动被追踪。

评估你的 Agent
当你的 agent 部署完成并处于监控状态后,下一步就是评估其性能。评估(evals)有助于确定你的 agent 在检索、处理和呈现信息方面的表现如何。
你可以运行多种类型的评估,例如响应相关性、事实准确性、延迟等。如需深入了解不同的评估技术,请查阅 Phoenix 文档。
在本示例中,我们将重点评估我们的 agent 所使用的 DuckDuckGo 搜索工具。我们将使用大语言模型(LLM)作为评判者——具体来说是 OpenAI 的 GPT-4o——来衡量其搜索结果的相关性。
步骤 1:安装 OpenAI
首先,安装必要的包:
pip install -q openai我们将使用 GPT-4o 来评估搜索工具的响应是否相关。 这种方法被称为 LLM-as-a-judge(LLM 作为评判者),它利用语言模型对响应进行分类和评分。
步骤 2:获取工具执行 Span
为了评估 DuckDuckGo 的信息检索效果,我们首先需要提取调用该工具时的执行追踪数据。
from phoenix.trace.dsl import SpanQuery
import phoenix as px
import json
query = SpanQuery().where(
"name == 'DuckDuckGoSearchTool'",
).select(
input="input.value",
reference="output.value",
)
tool_spans = px.Client().query_spans(query, project_name="my-smolagents-app")
tool_spans["input"] = tool_spans["input"].apply(lambda x: json.loads(x).get("kwargs", {}).get("query", ""))
tool_spans.head()步骤 3:导入 Prompt 模板
接下来,我们加载 RAG Relevancy Prompt Template(RAG 相关性提示词模板),它将帮助 LLM 判断搜索结果是否相关。
from phoenix.evals import (
RAG_RELEVANCY_PROMPT_RAILS_MAP,
RAG_RELEVANCY_PROMPT_TEMPLATE,
OpenAIModel,
llm_classify
)
import nest_asyncio
nest_asyncio.apply()
print(RAG_RELEVANCY_PROMPT_TEMPLATE)步骤 4:运行评估
现在,我们使用 GPT-4o 作为评判者来运行评估:
from phoenix.evals import (
llm_classify,
OpenAIModel,
RAG_RELEVANCY_PROMPT_TEMPLATE,
)
eval_model = OpenAIModel(model="gpt-4o")
eval_results = llm_classify(
dataframe=tool_spans,
model=eval_model,
template=RAG_RELEVANCY_PROMPT_TEMPLATE,
rails=["relevant", "unrelated"],
concurrency=10,
provide_explanation=True,
)
eval_results["score"] = eval_results["explanation"].apply(lambda x: 1 if "relevant" in x else 0)What’s happening here?
- We use GPT-4o to analyze the search query (input) and search result (output).
- The LLM classifies whether the result is relevant or unrelated based on the prompt.
- We assign a binary score (1 = relevant, 0 = unrelated) for further analysis.
To see your results:
eval_results.head()Step 5: Send Evaluation Results to Phoenix
from phoenix.trace import SpanEvaluations
px.Client().log_evaluations(SpanEvaluations(eval_name="DuckDuckGoSearchTool Relevancy", dataframe=eval_results))With this setup, we can now systematically evaluate the effectiveness of the DuckDuckGo search tool within our agent. Using LLM-as-a-judge, we can ensure our agent retrieves accurate and relevant information, leading to better performance. Any evaluation is easy to set up using this tutorial—just swap out the RAG_RELEVANCY_PROMPT_TEMPLATE for a different prompt template that fits your needs. Phoenix provides a variety of pre-written and pre-tested evaluation templates, covering areas like faithfulness, response coherence, factual accuracy, and more. Check out the Phoenix docs to explore the full list and find the best fit for your agent!
| Evaluation Template | Applicable Agent Type |
|---|---|
| Hallucination Detection | RAG agents General chatbots Knowledge-based assistants |
| Q&A on Retrieved Data | RAG agents Research Assistants Document Search Tools |
| RAG Relevance | RAG agents Search-based AI assistants |
| Summarization | Summarization tools Document digesters Meeting note generators |
| Code Generation | Code assistants AI programming bots |
| Toxicity Detection | Moderation bots Content filtering AI |
| AI vs Human (Ground Truth) | Evaluation & benchmarking tools AI-generated content validators |
| Reference (Citation) Link | Research assistants Citation tools Academic writing aids |
| SQL Generation Evaluation | Database query agents SQL automation tools |
| Agent Function Calling Evaluation | Multi-step reasoning agents API-calling AI Task automation bots |