你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
如何使用提示流 SDK 跟踪应用 | Azure AI Studio
重要
本文中标记了“（预览版）”的项目目前为公共预览版。 此预览版未提供服务级别协议，不建议将其用于生产工作负载。 某些功能可能不受支持或者受限。 有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。
跟踪是强大的工具，可以让开发者深入了解其生成式 AI 应用的执行进程，如代理、AutoGen 和检索增强生成 (RAG) 用例。 它提供了执行流的详细视图，包括应用程序中每个节点的输入和输出。 已证实，在调试复杂的应用或优化性能时，这些重要信息至关重要。
而越来越多的开发者正在使用各种框架，如 Langchain、Semantic Kernel、OpenAI 和各种类型的代理来创建基于 LLM的 应用。 使用提示流 SDK 进行跟踪为基于 LLM 的应用提供了增强的可见性和简化的故障排除，有效地支持开发、迭代和生产监视。 AI Studio 中的跟踪遵循 OpenTelemetry 规范，捕获并可视化任何 AI 应用的内部执行细节，增强整体开发体验。
AI Studio 跟踪在企业级云平台上的权益
此外，我们现在在企业级云平台 AI Studio 上提供永久性本地测试，显著增强了协作、永久性和测试历史管理。
借助跟踪，可以：
- 有基于云的位置来保存和跟踪历史测试。
- 轻松提取和可视化测试结果，比较不同测试用例的输出。
- 重用以前的测试资产以供以后使用，例如，人工反馈、数据策展等。
- 促进未来更好的资源利用率。
- 轻松调试和优化应用。 要开始调试 LLM 应用程序方案，请参阅使用 LLM 应用进行跟踪
- 分析 RAG 应用中的检索和生成进程。
- 观察多代理方案中的多代理交互。 要开始在多代理方案中进行跟踪，请参阅使用 AutoGen 进行跟踪。
记录和查看应用的跟踪
AI Studio 提供了跟踪功能，用于记录和管理 LLM 应用测试和评估，同时通过向下钻取跟踪视图进行调试和观察。
如今，跟踪任何应用功能都是在提示流开放源代码包中实现的，使用户能够跟踪 LLM 调用或函数，以及像 LangChain 和 AutoGen 这样的 LLM 框架，无论使用哪种框架，都遵循 OpenTelemetry 规范。
在应用中启用跟踪
代码优先 - 确保已经注释了代码，以便在提示流中进行跟踪！
- 安装提示流：需要提示流跟踪
- 检测应用程序代码：使用
@trace和start_trace()。 - 在本地测试和查看跟踪
有关提示流中跟踪的更多详细信息，请参阅此提示流文档。
将跟踪记录到 AI Studio
设置跟踪目标
默认情况下，会在本地环境中记录和查看跟踪。 若要将其记录在云中的 AI Studio 中，需要将 trace destination 设置为指定的 AI Studio 项目。
可以参考以下步骤将跟踪目标设置为 AI Studio 项目。
首先，确保已安装并登录 Azure CLI：
az login
接下来，执行以下命令来设置跟踪目标。 将 <your_subscription_id>、<your_resourcegroup_name>和 <your_studio_project_name> 替换为特定的订阅 ID、资源组名称和 AI Studio 项目名称：
pf config set trace.destination=azureml://subscriptions/<your_subscription_id>/resourcegroups/<your_resourcegroup_name>/providers/Microsoft.MachineLearningServices/workspaces/<your_studio_project_name>
注意
美国西部 3 (westus3) 区域不支持跟踪。
集合
集合是一组关联的跟踪。 在 AI Studio 中，这些集合及其内部跟踪在“集合”选项卡下的“跟踪”模块中进行管理和存储。
转到 AI Studio 中的项目。
在左侧窗格中，选择“跟踪”。 可以看到“集合”选项卡。只能在集合列表中看到自己的集合。 在此示例中，尚无任何集合。
集合选项卡显示已创建的所有集合的完整列表。 它显示每个集合的基本元数据，包括其名称、运行位置、上次更新时间和创建时间。
- 运行位置：指示应用程序是在本地还是云中运行。 云集合与在云端创作测试历史的特定提示流以及生成的跟踪相关联。 在本示例下，集合名称与提示流显示名称相同。
- 更新时间：显示最近向集合记录新跟踪的时间。 默认情况下，集合根据其更新时间按降序排序。
- 创建时间：最初创建集合的时间。
通过选择集合的名称，可以访问该集合中所有跟踪的列表。 只有跟踪的子集可以与其他子集共享。 有关详细信息，请参阅共享跟踪。
记录跟踪时，可以选择“指定集合名称”以将其与其他相关跟踪分组。 可以创建多个集合，以便更好地组织跟踪。 如果在记录跟踪时未指定集合名称，则默认为项目文件夹名称或默认集合。
自定义集合
为了更好地组织跟踪，可以在记录跟踪时指定自定义集合名称。
如果要跟踪自己的应用程序，则可以在代码的 start_trace() 函数中设置集合名称：
from promptflow.tracing import start_trace, trace
@trace
def my_function(input: str) -> str:
output = input + "Hello World!"
return output
my_function("This is my function")
start_trace(collection="my_custom_collection")
查看跟踪
首先，必须完成前面的步骤才能在云中查看跟踪：
现在，直接运行 Python 脚本。 成功执行后，输出中会显示一个云跟踪链接。 它应如下所示：
Starting prompt flow service...
...
You can view the traces in cloud from AI Studio: https://ai.azure.com/projecttrace/detail/....
选择 URL 以导航到云端门户上的跟踪详细信息页。 此页面类似于本地跟踪视图。
跟踪详细信息视图提供应用程序内操作的全面结构化概览。
了解跟踪详细信息视图
在跟踪视图的右上角，可以找到：
- 跟踪名称：与根范围名称相同，代表应用程序的输入函数名称。
- 状态：可能是“已完成”或“失败”。
- 总持续时间：测试执行的总持续时间。 将鼠标悬停在上方可以查看开始和结束时间。
- 总令牌：测试的总令牌成本。 将鼠标悬停在上方可以查看提示令牌和已完成的令牌。
- 创建时间：创建跟踪的时间。
在左侧，可以看到分层树结构。 此结构显示函数调用序列。 每个函数调用的元数据都组织成范围。 这些跨度以树状结构链接在一起，说明了执行顺序。
在提示流 SDK中，我们定义了几种范围类型，包括 LLM、函数、嵌入、检索和流。 系统会自动创建包含指定属性和事件中的执行信息的范围。
可以在每个范围中查看：
- 函数名称：默认情况下，这是代码中定义的函数的名称。 但是，它也可以是通过开放遥测定义的自定义范围名称。
- 持续时间：表示函数运行的持续时间。 将鼠标悬停在上方可以查看开始和结束时间。
- LLM 调用的令牌：这是 LLM 调用的令牌成本。 将鼠标悬停在上方可以查看提示令牌和已完成的令牌。
通过选择特定范围，可以在右侧查看其关联的详细信息。 此信息包括输入、输出、原始 JSON、日志和异常，这些信息对于观察和调试应用程序至关重要。
对于 LLM 范围，会提供清晰的对话视图。 这包括系统提示、用户提示和助手响应。 此信息在多代理情况下尤其重要，因为你可以通过这些信息了解 LLM 中间自动呼叫中的对话流程和交互。
可以选择“原始 JSON”选项卡以查看范围的 json 数据。 当涉及到调试和故障排除时，这种格式可能更适合开发人员。
共享跟踪
如果你想与具有项目权限的其他人共享跟踪，则可以选择跟踪详细信息页右上角的“共享”按钮，然后复制页面链接以与其他人共享。
注意
共享跟踪是只读的，只有具有项目权限的人员才能通过链接查看它。