LLM Trace字段定义说明-阿里云帮助中心

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

Span一级字段定义参考OpenTelemetry开源标准，阿里云可观测链路 OpenTelemetry 版底层存储的Trace一级字段详细说明，请参见调用链分析参数说明。

说明

LLM相关的SpanKind是一个Attribute，不同于OpenTelemetry中Trace定义的Span kind。

公共部分

Attributes

AttributeKey	描述	类型	示例值	需求等级
`gen_ai.session.id`	会话ID	String	`ddde34343-f93a-4477-33333-sdfsdaf`	有条件时必须
`gen_ai.user.id`	应用的C端用户标识	String	`u-lK8JddD`	有条件时必须
`gen_ai.span.kind`	操作类型	String	参考LLM Span Kind	必须
`gen_ai.framework`	使用的框架类型	String	`langchain`;`llama_index`	有条件时必须

Resources

ResourceKey	描述	类型	示例值	需求等级
`service.name`	应用名称	String	`test-easy-rag`	必须

Chain

Chain是一种将LLM和其他多个组件连接在一起的工具，以实现复杂的任务，可能包含Retrieval、Embedding、LLM调用、还可以嵌套Chain等。

Attributes

AttributeKey	描述	类型	示例值	需求等级
`gen_ai.span.kind`	操作类型，大模型spanKind专用枚举，Chain中取值必须为 `CHAIN`。	String	`CHAIN`	必须
`gen_ai.operation.name`	操作二级类型	String	`WORKFLOW`; `TASK`	有条件时必须
`input.value`	输入内容	String	`Who Are You!`	推荐
`output.value`	返回内容	String	`I am ChatBot`	推荐
`gen_ai.user.time_to_first_token`	首包延迟，一次提问的整体响应首包耗时，从服务端获取的用户请求到首包返回的时间，单位纳秒。	Integer	1000000	推荐

Retriever

Retriever一般表示访问向量存储或者数据库获取数据，一般用于补充上下文内容，以提升LLM的响应准确性以及效率。

Attributes

AttributeKey	描述	类型	示例值	需求等级
`gen_ai.span.kind`	操作类型，大模型spanKind专用枚举，Retriever中取值必须为 `RETRIEVER`。	String	`RETRIEVER`	必须
`retrieval.query`	检索内容短句	String	`what is the topic in xxx?`	推荐
`retrieval.document`	召回的文档列表	JSON数组	`[{"document":{"content":"This is a sample document content.","metadata":{"source":"https://aliyun.com/xxx/wiki","title":"How LLM Works"},"score":0.7680862242896571,"id":"7af0e529-2531-42d9-bf3a-d5074a73c184"}}]`	必须

Reranker

Reranker针对输入的多个文档，结合提问内容判断相关性进行排序处理，可能返回TopK的文档作为LLM。

Attributes

AttributeKey	描述	类型	示例值	需求等级
`gen_ai.span.kind`	操作类型，大模型spanKind专用枚举，Reranker中取值必须为 `RERANKER`。	String	`RERANKER`	必须
`reranker.query`	Reranker请求的入参	String	`How to format timestamp?`	可选
`reranker.model_name`	Reranker所用的模型名	String	`cross-encoder/ms-marco-MiniLM-L-12-v2`	可选
`reranker.top_k`	Reranker后的排名	Integer	`3`	可选
`reranker.input_document`	输出文档相关的元数据。重排序输入文档、JSON数组结构、metadata为文档的基本信息，包含路径，文件名以及来源等。	String	-	必须
`reranker.output_document`	输出文档相关的元数据。重排序输出文档、JSON数组结构、metadata为文档的基本信息，包含路径，文件名以及来源等。	String	-	必须

LLM

LLM标识对大模型的调用，例如基于SDK或OpenAPI请求不同的大模型进行推理或者文本生成等场景。

Attributes

AttributeKey	描述	类型	示例值	需求等级
`gen_ai.span.kind`	操作类型，大模型spanKind专用枚举，LLM中取值必须为 `LLM`。	String	`LLM`	必须
`gen_ai.operation.name`	操作二级类型	String	`chat`; `completion`	可选
`gen_ai.prompt_template.template`	提示词模板	String	`Weather forecast for {city} on {date}`	可选
`gen_ai.prompt_template.variables`	提示词模板的具体值	String	`{ context: "<context from retrieval>", subject: "math" }`	可选
`gen_ai.prompt_template.version`	提示模板的版本号	String	`1.0`	可选
`gen_ai.system`	大模型的提供商	String	`openai`	必须
`gen_ai.request.parameters`	LLM调用的入参	String	`{"temperature": 0.7}`	可选
`gen_ai.model_name`	模型名称	String	`gpt-4`	可选
`gen_ai.conversation.id`	会话的唯一ID，当埋点可以比较方便地获取会话的ID时应该采集。	String	`conv_5j66UpCpwteGg4YSxUnt7lPY`	有条件时必须
`gen_ai.output.type`	LLM请求中指定的输出类型，当可以获取并且请求指定了类型（如指定了output format）时应该采集。	String	`text`;`json`;`image`;`audio`	有条件时必须
`gen_ai.request.choice.count`	LLM请求中希望获得的候选生成数量	Int	`3`	有条件且不为1时必须
`gen_ai.request.model`	LLM请求中指定的模型名	String	`gpt-4`	必须
`gen_ai.request.seed`	LLM请求中指定的seed	String	`gpt-4`	有条件时必须
`gen_ai.request.frequency_penalty`	LLM请求中设定的频率惩罚	Float	`0.1`	推荐
`gen_ai.request.max_tokens`	LLM请求中指定的最大token数	Integer	`100`	推荐
`gen_ai.request.presence_penalty`	LLM请求中设定的存在性惩罚	Float	`0.1`	推荐
`gen_ai.request.temperature`	LLM请求中指定的温度	Float	`0.1`	推荐
`gen_ai.request.top_p`	LLM请求中指定的topP	Float	`1.0`	推荐
`gen_ai.request.top_k`	LLM请求中指定的topK	Float	`1.0`	推荐
`gen_ai.request.is_stream`	是否为流式响应，如果不存在，则代表取值为false。	Boolean	`false`	推荐
`gen_ai.request.stop_sequences`	LLM的终止序列	String[]	`["stop"]`	推荐
`gen_ai.request.tool_calls`	Tools调用的内容	String	`[{"tool_call.function.name": "get_current_weather"}]`	推荐
`gen_ai.response.id`	LLM生成的唯一ID	String	`gpt-4-0613`	推荐
`gen_ai.response.model`	LLM生成所使用的模型名	String	`gpt-4-0613`	推荐
`gen_ai.response.finish_reason`	LLM终止生成的原因	String[]	`["stop"]`	推荐
`gen_ai.response.time_to_first_token`	流式响应场景下的大模型自身的首包响应耗时。代表一次提问的整体响应首包耗时，从服务端获取的用户请求到首包返回的时间，单位纳秒。	Integer	`1000000`	推荐
`gen_ai.response.reasoning_time`	推理模型的推理时间，代表响应reasoning过程的持续时长，单位毫秒。	Integer	`1248`	推荐
`gen_ai.usage.input_tokens`	输入使用的token数	Integer	`100`	推荐
`gen_ai.usage.output_tokens`	输出使用的token数	Integer	`200`	推荐
`gen_ai.usage.total_tokens`	使用的总token数	Integer	`300`	推荐
`gen_ai.input.messages_ref`	模型输入内容链接	String	`s3://acme.prod.support_bot.chats.2025/conv_1234/run_42.json`	推荐
`gen_ai.output.messages_ref`	模型输出内容链接	String	`s3://acme.prod.support_bot.chats.2025/conv_1234/run_42.json`	推荐
`gen_ai.system.instructions_ref`	system提示词的内容链接。用于单独记录system提示词（/system指令）内容的外部链接。如果system提示词（/system指令）内容可以单独获取，则应该用该字段记录；如果system提示词（/system指令）内容是模型调用的一部分，应该记录在`gen_ai.input.messages_ref`属性对应的链接中。	String	`s3://acme.prod.support_bot.chats.2025/conv_1234/invocation_42.json`	如果能获取时推荐
`gen_ai.input.messages`	模型输入内容，消息必须按照发送给模型或智能体的顺序提供。默认情况下，不应采集该信息，除非使用者主动打开开关。	String	`[{"role": "user", "parts": [{"type": "text", "content": "Weather in Paris?"}]}, {"role": "assistant", "parts": [{"type": "tool_call", "id": "call_VSPygqKTWdrhaFErNvMV18Yl", "name":"get_weather", "arguments":{"location":"Paris"}}]}, {"role": "tool", "parts": [{"type": "tool_call_response", "id":" call_VSPygqKTWdrhaFErNvMV18Yl", "result":"rainy, 57°F"}]}]`	可选
`gen_ai.output.messages`	模型输出内容，消息必须按照发送给模型或智能体的顺序提供。默认情况下，不应采集该信息，除非使用者主动打开开关。	String	`[{"role":"assistant","parts":[{"type":"text","content":"The weather in Paris is currently rainy with a temperature of 57°F."}],"finish_reason":"stop"}]`	可选
`gen_ai.system.instructions`	system提示词的内容。用于单独记录system提示词（/system指令）内容，格式为一个JSON字符串。如果system提示词（/system指令）内容可以单独获取，则应该用该字段记录；如果system提示词（/system指令）内容是模型调用的一部分，应该记录在`gen_ai.input.messages`属性中。默认情况下，不应采集该信息，除非使用者主动打开开关。	String	`{"role": "system", "message": {"type": "text", "content": "You are a helpful assistant"}}`	可选
`gen_ai.response.reasoning_content`	推理模型的推理内容。代表响应reasoning过程的内容，默认长度限制为1024字符，超出的部分应截断。	String	`Okay, let's tackle this question about xxx.`	可选

Embedding

Embedding标识一次嵌入处理，例如针对文本嵌入大模型的操作，后续可以根据相似度查询优化问题。

Attributes

AttributeKey	描述	类型	示例值	需求等级
`gen_ai.span.kind`	操作类型，大模型spanKind专用枚举，Embedding中取值必须为 `EMBEDDING`。	String	`EMBEDDING`	必须
`gen_ai.usage.input_tokens`	输入文本的token消耗	Integer	`10`	可选
`gen_ai.usage.total_tokens`	Embedding的token总消耗	Integer	`10`	可选
`embedding.model_name`	Embedding的模型名称	String	`text-embedding-v1`	可选
`embedding.embedding_output`	嵌入结果	String	-	可选

Tool

Tool标识对外部工具的调用，例如可能调用计算器或者请求天气API获取最新的天气情况。

Attributes

AttributeKey	描述	类型	示例值	需求等级
`gen_ai.span.kind`	操作类型，大模型spanKind专用枚举，Tool中取值必须为 `TOOL`。	String	`TOOL`	必须
`tool.name`	工具名称	String	`WeatherAPI`	必须
`tool.description`	工具描述	String	`An API to get weather data.`	必须
`tool.parameters`	工具入参	String	`{'a': 'int' }`	必须

Agent

Agent表示智能体场景，一种更复杂的Chain，需要基于大模型的推理结果决策执行下一步，例如可能涉及到LLM以及Tool的多次调用，一步步决策得出最终答案。

Attributes

AttributeKey	描述	类型	示例值	需求等级
`gen_ai.span.kind`	操作类型，大模型spanKind专用枚举，Agent中取值必须为 `AGENT`。	String	`AGENT`	必须
`input.value`	输入参数，记录原始输入。	String	`请帮我规划xxxx`	必须
`input.mime_type`	输入MimeType	String	`text/plain`; `application/json`	可选
`output.value`	返回结果，返回最终输出。	String	`规划结束，请查看结果xxx`	必须
`output.mime_type`	输出MimeType	String	`text/plain`; `application/json`	可选
`gen_ai.response.time_to_first_token`	Agent的首包响应耗时。代表一次提问的整体响应首包耗时，从服务端获取的用户请求到首包返回的时间，单位纳秒。	Integer	`1000000`	推荐

Task

Task标识一次内部自定义方法，例如可能调用本地的某个Function等应用自定义的逻辑。

Attributes

AttributeKey	描述	类型	示例值	需求等级
`gen_ai.span.kind`	操作类型，大模型spanKind专用枚举，Task中取值必须为 `TASK`。	String	`TASK`	必须
`input.value`	输入参数	String	自定义JSON格式	可选
`input.mime_type`	输入MimeType	String	`text/plain`; `application/json`	可选
`output.mime_type`	输出MimeType	String	`text/plain`; `application/json`	可选