跟踪 Span 规范#

实验性功能

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

本文档概述了 Prompt flow span 的设计，详细说明了跟踪哪些信息以及如何组织这些信息。

介绍#

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

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

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

OpenTelemetry Span 基础知识#

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

字段	描述
name	Span 名称
parent_id	父 span ID（根 span 为空）
context	Span 上下文
start_time	Span 的开始时间
end_time	Span 的结束时间
状态	Span 状态
属性	属性
事件	Span 事件
链接	Span 链接

Prompt flow 中的 Span#

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

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

通用属性和事件#

属性#

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

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

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

事件#

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

事件必须具有属性
事件属性必须包含一个名为 payload 的键，它指的是事件中携带的数据。
事件属性 payload 必须是表示对象的 JSON 字符串。

事件	Payload 描述	Payload 示例	要求级别
promptflow.function.inputs	函数调用的输入	`{"chat_history":[],"question":"什么是 ChatGPT?"}`	`必填`
promptflow.function.output	函数调用的输出	`{"answer":"ChatGPT 是 OpenAI 开发的一个对话式 AI 模型。"}`	`必填`

Span 类型规范#

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

除了标准属性和事件之外，每种 span 类型都具有指定的字段，用于存储与其在系统中的角色相关的独特信息。这些专用属性和事件确保所有相关数据都经过仔细跟踪并可用于分析。

LLM#

LLM（大型语言模型）span 捕获对大型语言模型调用的详细执行信息。

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

事件	Payload 描述	Payload 示例	要求级别
promptflow.llm.generated_message	捕获 LLM 调用的输出消息。	`{"content":"ChatGPT 是 OpenAI 开发的一个对话式 AI 模型。","role":"assistant","function_call":null,"tool_calls":null}`	`必填`

注意：OpenTelemetry 目前将几个与 LLM 相关的 span 属性和事件定义为语义约定。我们计划未来与这些约定保持一致。有关详细信息，请访问 GenAI 操作的语义约定。

函数#

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

属性	类型	描述	示例	要求级别
span_type	字符串	将 span 标识为函数类型。	功能	`必填`

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

[1]：模板格式化是将提示模板解析为提示消息的过程，此过程可以在调用 LLM 的函数中发生。

流#

流 span 封装了 Prompt flow 中流的执行详细信息。

属性	类型	描述	示例	要求级别
span_type	字符串	将 span 指定为流类型。	流	`必填`

嵌入#

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

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

事件	Payload 描述	Payload 示例	要求级别
promptflow.embedding.embeddings	详细说明调用生成的嵌入。	`[{"embedding.vector":"","embedding.text":"Azure 机器学习中，管道作业何时重用以前作业的结果？"}]`	`必填`

检索#

检索 span 类型专门设计用于封装 Prompt flow 中检索任务的执行详细信息。

属性	类型	描述	示例	要求级别
span_type	字符串	将 span 标记为检索类型。	检索	`必填`

事件	Payload 描述	Payload 示例	要求级别
promptflow.retrieval.query	捕获检索查询的文本。	`"Azure 机器学习中，管道作业何时重用以前作业的结果？"`	`必填`
promptflow.retrieval.documents	详细说明与查询相关的检索文档列表。	`[{"document.id":"https://componentsdk.azurewebsites.net/howto/caching-reuse.html","document.score":2.677619457244873,"document.content":"# 组件概念 &..."},{"document.id":"https://learn.microsoft.com/en-us/azure/machine-learning/v1/reference-pipeline-yaml","document.score":2.563112735748291,"document.content":"等。 \|\r\n\| runconfig \| T..."}]`	`必填`