追踪跨度规范

实验性功能

这是一个实验性功能，可能会随时更改。了解更多更多。

本文档概述了Prompt flow spans的设计，详细说明了跟踪的信息及其结构。

介绍

你可能知道，span是跟踪系统的基本单位，代表在Prompt flow系统中捕获执行信息的单元。Span以父子关系嵌套在一起，并通过链接关系配对，为开发者和用户提供应用程序执行过程的全面视图。

通过遵守这些规范，我们确保跟踪系统的透明度和一致性。

用户界面解释捕获的跨度并以用户友好的方式呈现它们。理解跨度中定义的字段和合同对于有效利用Prompt flow或集成其组件至关重要。

OpenTelemetry Span 基础

一个典型的 span 对象包含以下信息：

字段	描述
name	跨度的名称
parent_id	父级跨度ID（根跨度为空）
上下文	Span Context
start_time	时间段的开始时间
end_time	时间段的结束时间
状态	Span Status
属性	Attributes
事件	Span Events
链接	Span Links

提示流中的Span

在Prompt flow中，我们定义了几种跨度类型，系统会自动在指定的属性和事件中创建包含执行信息的跨度。

这些span类型共享共同的属性和事件，我们称之为标准属性和事件。在深入探讨每种span类型的具体细节之前，让我们先探索这些共同的元素。

常见属性和事件

属性

Prompt flow 中的每个 span 都附带了一组标准属性，这些属性提供了关于 span 上下文和目的的基本信息。下表概述了这些属性：

属性	类型	描述	示例	需求级别
框架	字符串	此属性指定记录跟踪的框架。对于我们的项目，此值始终设置为promptflow。	promptflow	必需
node_name	string	表示流程节点的名称。	chat	条件性 必需 如果流程是有向无环图（DAG）流程。
span_type	string	指定span的类型，例如LLM或Flow。详情请参见this。	LLM	Required
line_run_id	string	在Prompt flow中执行运行的唯一标识符。	d23159d5-cae0-4de6-a175-295c715ce251	Required
function	string	与跨度关联的函数。	search	推荐
session_id	string	聊天会话的唯一标识符。	4ea1a462-7617-439f-a40c-12a8b93f51fb	Opt-In
referenced.line_run_id	string	表示作为评估运行来源的线路运行ID。	f747f7b8-983c-4bf2-95db-0ec3e33d4fd1	有条件 必需 仅在评估运行中使用 - 运行于 评估流程。
batch_run_id	string	批处理模式下的批处理运行ID。	61daff70-80d5-4e79-a50b-11b38bb3d344	条件性 必需 仅在批处理运行中使用。
referenced.batch_run_id	string	记录评估流程运行的批次运行ID。	851b32cb-545c-421d-8e51-0a3ea66f0075	有条件 必需 仅在评估运行中使用。
line_number	int	批处理运行中的行号，从0开始。	1	Conditionally Required 仅在批处理运行中使用。
__computed__.cumulative_token_count.prompt	int	提示的子节点的累计令牌计数。[1]	200	Recommended
__computed__.cumulative_token_count.completion	int	完成响应的子节点的累计令牌计数。[1]	80	Recommended
__computed__.cumulative_token_count.total	int	提示和完成的总累积令牌计数。[1]	120	推荐

[1]: 累计令牌计数会沿着跨度层次结构向上传播，确保每个跨度反映其范围内所有LLM执行的总令牌计数。

事件

在Prompt flow中，由Prompt flow框架发出的事件遵循以下格式

• 事件必须具有属性

• 事件属性必须包含一个名为payload的键，它指的是事件中携带的数据。

• 事件属性 payload 必须是一个表示对象的 JSON 字符串。

事件	负载描述	负载示例	需求级别
promptflow.function.inputs	函数调用的输入	{"chat_history":[],"question":"What is ChatGPT?"}	Required
promptflow.function.output	函数调用的输出	{"answer":"ChatGPT is a conversational AI model developed by OpenAI."}	Required

跨度类型规范

在Prompt flow系统中，我们定义了几种不同的span类型，以适应各种执行单元。每种span类型都旨在捕获特定的执行信息，补充标准属性和事件。目前，我们的系统包括以下span类型：LLM、Function、LangChain、Flow、Embedding和Retrieval。

除了标准属性和事件外，每种跨度类型都拥有指定的字段，用于存储与其在系统中的角色相关的独特信息。这些专门的属性和事件确保所有相关数据都被细致地追踪并可用于分析。

大型语言模型

LLM（大型语言模型）跨度捕获了从调用大型语言模型中获取的详细执行信息。

属性	类型	描述	示例	需求级别
span_type	string	标识该span为LLM类型。	LLM	Required
llm.usage.total_tokens	int	使用的总令牌数，包括提示和响应。	180	Required
llm.usage.prompt_tokens	int	LLM提示中使用的令牌数量。	100	Required
llm.usage.completion_tokens	int	LLM响应中使用的令牌数量（完成）。	80	Required
llm.response.model	string	指定生成响应的LLM。	gpt-4	Required

事件	负载描述	负载示例	需求级别
promptflow.llm.generated_message	捕获来自LLM调用的输出消息。	{"content":"ChatGPT is a conversational AI model developed by OpenAI.","role":"assistant","function_call":null,"tool_calls":null}	Required

注意：OpenTelemetry 目前定义了几个与LLM相关的跨度属性和事件作为语义约定。我们计划在未来与这些约定保持一致。更多信息，请访问 Semantic Conventions for GenAI operations。

函数

函数 span 是 Prompt flow 中的一个多功能默认 span，旨在捕获广泛的通用函数执行信息。

属性	类型	描述	示例	需求级别
span_type	string	标识该span为函数类型。	Function	Required

事件	负载描述	负载示例	需求级别
promptflow.prompt.template	详细说明提示模板和变量信息。	{"prompt.template":"# system:\nYou are a helpful assistant.\n\n# user:\n{{question}}","prompt.variables":"{\n "question": "What is ChatGPT?"\n}"}	Conditionally Required 如果函数包含提示模板格式化。[1]

[1]: 模板格式化是一个通过解析提示模板生成提示信息的过程，这个过程可能发生在调用LLM的函数内部。

流程

Flow span 封装了 Prompt flow 中流程的执行细节。

属性	类型	描述	示例	需求级别
span_type	string	将span指定为Flow类型。	Flow	Required

嵌入

嵌入跨度专门用于记录Prompt flow中嵌入调用的详细信息。

属性	类型	描述	示例	需求级别
span_type	string	表示该span为Embedding类型。	Embedding	Required
llm.usage.total_tokens	int	使用的总令牌数，提示和响应令牌的总和。	180	Required
llm.usage.prompt_tokens	int	用于嵌入调用的提示中的令牌数量。	100	Required
llm.usage.completion_tokens	int	嵌入调用响应中使用的令牌数量。	80	Required
llm.response.model	string	标识用于生成嵌入的LLM模型。	text-embedding-ada-002	Required

事件	负载描述	负载示例	需求级别
promptflow.embedding.embeddings	详细说明由调用生成的嵌入。	[{"embedding.vector":"","embedding.text":"当 管道 作业 在 Azure 机器学习 中 重用 先前 作业的 结果 时 会发生什么？"}]	必需

检索

检索跨度类型专门设计用于封装Prompt flow中检索任务的执行细节。

属性	类型	描述	示例	需求级别
span_type	string	将跨度标记为检索类型。	Retrieval	Required

事件	负载描述	负载示例	需求级别
promptflow.retrieval.query	捕获检索查询的文本。	"When does a pipeline job reuse a previous job's results in Azure Machine Learning?"	Required
promptflow.retrieval.documents	详细列出与查询相关的检索文档列表。	[{"document.id":"https://componentsdk.azurewebsites.net/howto/caching-reuse.html","document.score":2.677619457244873,"document.content":"# Component concepts &..."},{"document.id":"https://learn.microsoft.com/en-us/azure/machine-learning/v1/reference-pipeline-yaml","document.score":2.563112735748291,"document.content":"etc. |\r\n| runconfig | T..."}]	Required