LLM Trace字段定义说明_可观测链路 OpenTelemetry 版(OpenTelemetry)-阿里云帮助中心

LLM Trace字段是阿里云参考OpenTelemetry标准以及大语言模型应用领域概念制定的，通过对Attributes、Resource、Event扩展用于描述LLM应用调用链数据的语义，能够反映LLM的输入输出请求、令牌消耗等关键操作。它们为Completion、Chat、RAG、Agent、Tool等场景提供了丰富的、语境相关的语义数据，以便于数据跟踪和上报。此语义字段将随着社区的发展而不断更新和优化。

Span Field

Span一级字段定义及可观测链路 OpenTelemetry 版底层存储的Trace一级字段详细说明，请参见调用链分析参数说明。

Attributes

下文定义的字段为LLM Trace场景的保留字段。SDK需要参考如下Key-Value字段规范，将相关数据作为Attributes附加到Span中，然后上报Span数据到服务端。

Common Attributes

说明

不区分操作类型，一次大模型QA涉及的链路里可以透传或者附属于多个Span的字段。

Attribute	类型	描述	是否必选	示例
`gen_ai.session.id`	String	会话ID	否	`"ddde34343-f93a-4477-33333-sdfsdaf"`
`gen_ai.user.id`	String	应用的C端用户标识	否	`"u-lK8JddD" or "张三@爱茉莉.com"`
`gen_ai.span.kind`	String	操作类型详细信息，请参见下方Span Kind	是	`"CHAIN"`
`gen_ai.framework`	String	使用的框架类型	否	`"langchain" or "llama_index" ..`

Span Kind

在大模型的实际交互场景中，往往会涉及多个操作步骤。基于LLM应用范式以及应用研发框架，目前定义了如下操作类型，这些操作类型支持扩展，不同的操作类型对应的Attributes字段会存在差异。

CHAIN：一种将LLM和其他多个组件连接在一起以实现复杂任务的工具，可能包含Retrieval、Embedding、LLM调用，还可以嵌套Chain等。
EMBEDDING：嵌入处理，例如针对文本嵌入大模型的操作，可以根据相似度查询并优化问题。
RETRIEVER：一般表示访问向量存储或者数据库获取数据，一般用于补充上下文内容，以提升LLM的响应准确性以及效率。
RERANKER：针对输入的多个文档，结合提问内容判断相关性进行排序处理，可能返回TopK的文档作为LLM。
LLM：标识对大模型的调用，例如基于SDK或OpenAPI请求不同的大模型进行推理或者文本生成等。
TOOL：标识对外部工具的调用，例如可能调用计算器或者请求天气API获取最新的天气情况。
AGENT：智能体场景，一种复杂的CHAIN，需要基于大模型的推理结果决策执行下一步，例如可能涉及到LLM以及Tool的多次调用，一步步决策得出最终答案。
TASK：标识内部自定义方法，例如可能调用本地的某个Function应用自定义的逻辑。

重要

LLM相关的Span Kind不同于OpenTelemetry中Trace定义的Span kind。

CHAIN

Attribute	类型	描述	是否必选	示例
`gen_ai.span.kind`	String	操作类型	是	`"CHAIN"`
`gen_ai.span.sub_kind`	String	操作二级类型	否	`"WORKFLOW" or "TASK"`
`input.value`	String	输入内容	是	`"Who Are You!"`
`output.value`	String	返回内容	是	`"I am ChatBot"`

EMBEDDING

Attribute	类型	描述	是否必选	示例
`gen_ai.span.kind`	String	操作类型	是	`"EMBEDDING"`
`embedding.model_name`	String	内嵌的模型名称	否	`"text-embedding-v1"`
`gen_ai.usage.prompt_tokens`	Integer	内嵌的Token消耗	否	10
`gen_ai.usage.total_tokens`	Integer	内嵌的Token总消耗	否	10
`embedding.embeddings.0.embedding.text`	String	内嵌的文本	否	`"hello world"`
`embedding.embeddings.0.embedding.vector`	Array	由一系列浮点数组成的嵌入向量	否	`[0.123, 0.456, ...]`
`embedding.embeddings.0.embedding.vector_size`	Integer	向量长度	否	`1536`

RETRIEVER

Attribute	类型	描述	是否必选	示例
`gen_ai.span.kind`	String	操作类型	是	`"RETRIEVER"`
`retrieval.documents.0.document.id`	String	文档的唯一标识符	是	`"2aeab544-f93a-4477-b51d-bec27351325b"`
`retrieval.documents.0.document.score`	Float	文档相关性的得分	是	`0.98`
`retrieval.documents.0.document.content`	String	检索到的文档的内容	是	`"This is a sample document content."`
`retrieval.documents.0.document.metadata`	String	与文档相关的元数据	否	{"file_path": "/dev/EasyRAG/data/laws/laws.txt", "file_name": "/dev/EasyRAG/data/laws/laws.txt", "file_type": "text/plain", "file_size": 15618, "creation_date": "2024-03-20", "last_modified_date": "2024-03-20", "last_accessed_date": null}

RERANKER

Attribute	类型	描述	是否必选	示例
`gen_ai.span.kind`	String	操作类型	是	`"RERANKER"`
`reranker.query`	String	重排器的查询参数	否	`"How to format timestamp?"`
`reranker.model_name`	String	重排器的模型名称	否	`"cross-encoder/ms-marco-MiniLM-L-12-v2"`
`reranker.top_k`	Integer	重排器的TopK参数	否	`3`
`reranker.input_documents.0.document.id`	String	文档的唯一标识符	是	`"2aeab544-f93a-4477-b51d-bec27351325b"`
`reranker.input_documents.0.document.score`	Float	文档相关性的得分	是	`0.98`
`reranker.input_documents.0.document.content`	String	检索到的文档的内容	是	`"This is a sample document content."`
`reranker.input_documents.0.document.metadata`	String	与文档相关的元数据	否	{"file_path": "/dev/EasyRAG/data/laws/laws.txt", "file_name": "/dev/EasyRAG/data/laws/laws.txt", "file_type": "text/plain", "file_size": 15618, "creation_date": "2024-03-20", "last_modified_date": "2024-03-20","last_accessed_date": null}
`reranker.output_documents.0.document.id`	String	文档的唯一标识符	是	`"2aeab544-f93a-4477-b51d-bec27351325b"`
`reranker.output_documents.0.document.score`	Float	文档相关性的得分	是	`0.98`
`reranker.output_documents.0.document.content`	String	检索到的文档的内容	是	`"This is a sample document content."`
`reranker.output_documents.0.document.metadata`	String	与文档相关的元数据	否	{"file_path": "/dev/EasyRAG/data/laws/laws.txt", "file_name": "/dev/EasyRAG/data/laws/laws.txt", "file_type": "text/plain", "file_size": 15618, "creation_date": "2024-03-20", "last_modified_date": "2024-03-20","last_accessed_date": null}

LLM

Attribute	类型	描述	是否必选	示例
`gen_ai.span.kind`	String	操作类型	是	`"LLM"`
`gen_ai.span.sub_kind`	String	操作二级类型	否	`"CHAT" or "COMPLETION"`
`gen_ai.prompt_template.template`	String	用于生成Prompts的模板，它以Python的f-string形式存在	否	`"Weather forecast for {city} on {date}"`
`gen_ai.prompt_template.variables`	String	一组以JSON格式表示的键值对，这些键值对被用于填充一个先前定义的Prompt模板	否	`{ context: "<context from retrieval>", subject: "math" }`
`gen_ai.prompt_template.version`	String	提示模板的版本号	否	`"1.0"`
`gen_ai.system`	String	大模型的提供商	是	`"OPENAI"`
`gen_ai.request.parameters`	String	调用LLM或API时使用的参数	是	`{"temperature": 0.7}"`
`gen_ai.model_name`	String	LLM的名称	是	`"gpt-4"`
`gen_ai.request.model`	String	请求所指向的LLM的名称	是	`"gpt-4"`
`gen_ai.request.max_tokens`	Integer	LLM为一个请求生成的最大令牌数	否	`100`
`gen_ai.request.temperature`	Float	LLM请求的温度设置	否	`0.1`
`gen_ai.request.top_p`	Float	LLM请求的top_p采样设置	否	`1`
`gen_ai.request.is_stream`	Boolean	LLM是否以stream的形式响应	否	`false`
`gen_ai.request.stop_sequences`	Array	LLM用作停止序列的字符串数组	否	`"stop"`
`gen_ai.request.tool_calls`	Array	LLM生成的工具调用（例如函数调用）列表	否	`[{"tool_call.function.name": "get_current_weather"}]`
`gen_ai.response.model`	String	生成响应的LLM的名称	否	`"gpt-4-0613"`
`gen_ai.response.finish_reason`	String	模型停止生成令牌的原因，对应于收到的每一次生成	否	`"stop"`
`gen_ai.prompts.0.content`	String	提示内容	是	`"中国的首都是哪个城市?"`
`gen_ai.prompts.0.message.role`	String	消息中实体的角色（例如用户、系统）	是	`"user" or "system"`
`gen_ai.prompts.0.message.content`	String	聊天中消息的内容	是	`"What's the weather today?"`
`input.value`	String	API请求传参内容，一般为JSON格式	是	`"Who Are You!"`
`gen_ai.completions.0.content`	String	补全场景：从LLM收到的完整响应	是	`"中国的首都是北京"`
`gen_ai.completions.0.message.role`	String	Chat场景：消息中实体的角色（例如助手）	是	`"assistant"`
`gen_ai.completions.0.message.content`	String	Chat场景：聊天中消息的内容	是	`"聊天内容1"`
`gen_ai.completions.0.message.tool_calls`	Array	Chat场景：LLM生成的工具调用（例如函数调用）列表	否	`[{"tool_call.function.name": "get_current_weather"}]`
`output.value`	String	API返回的完整内容，一般为JSON格式，可以提取关键字段，例如token_usage等	是	`"I am ChatBot"`
`gen_ai.usage.prompt_tokens`	Integer	Prompt中的令牌数量	是	`100`
`gen_ai.usage.completion_tokens`	Integer	Completion中的令牌数量	是	`200`
`gen_ai.usage.total_tokens`	Integer	总令牌数量，包括Prompt和Completion	是	`300`

TOOL

Attribute	类型	描述	是否必选	示例
`gen_ai.span.kind`	String	操作类型	是	`"TOOL"`
`tool.name`	String	工具名称	是	`"WeatherAPI"`
`tool.description`	String	工具描述	是	`"An API to get weather data."`
`tool.parameters`	String	工具参数	是	`"{'a': 'int' }"`

AGENT

Attribute	类型	描述	是否必选	示例
`gen_ai.span.kind`	String	操作类型	是	`"AGENT"`
`input.value`	String	输入内容	是	`"请帮我规划xxxx!"`
`input.mime_type`	String	输入MIME TYPE	否	`"text/plain" or "application/json"`
`output.value`	String	返回结果	是	`"规划结束，请查看结果xxx"`
`output.mime_type`	String	返回MIME Type	否	`"text/plain" or "application/json"`

TASK

Attribute	类型	描述	是否必选	示例
`gen_ai.span.kind`	String	操作类型	是	`"TASK"`
`input.value`	String	输入参数	否	`"输入参数，自定义JSON格式"`
`input.mime_type`	String	输入MIME TYPE	否	`"text/plain" or "application/json"`
`output.value`	String	返回结果	否	`"输出结果，自定义JSON格式"`
`output.mime_type`	String	返回MIME Type	否	`"text/plain" or "application/json"`