生成式 AI 事件的语义约定

状态: 开发中

GenAI 仪器化可以捕获用户发送给模型和模型返回的响应，作为 事件。

注意：事件处于开发中，尚未在某些语言中提供。请查看 规范合规性矩阵 以了解相应语言的实现状态。

事件: event.gen_ai.client.inference.operation.details

状态:

事件名称必须是 gen_ai.client.inference.operation.details。

描述 GenAI 完成请求的详细信息，包括聊天记录和参数。

此事件是可选的，可用于独立于跟踪来存储输入和输出详细信息。

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
gen_ai.operation.name		必需	字符串	正在执行的操作的名称。[1]	chat；generate_content；text_completion
error.type		如果操作以错误结束，则条件必需	字符串	描述操作结束时发生的错误类型。[2]	timeout；java.net.UnknownHostException；server_certificate_invalid；500
gen_ai.conversation.id		如果可用，则条件必需	字符串	对话（会话、线程）的唯一标识符，用于存储和关联对话内的消息。[3]	conv_5j66UpCpwteGg4YSxUnt7lPY
gen_ai.output.type		有条件地必需 [4]	字符串	客户端请求的内容类型。[5]	text；json；image
gen_ai.request.choice.count		如果在请求中可用且不等于 1，则条件必需	int	目标候选补全数量。	3
gen_ai.request.model		有条件必需 如果可用。	字符串	请求的 GenAI 模型名称。[6]	gpt-4
gen_ai.request.seed		如果适用且请求包含种子，则条件必需	int	具有相同种子值的请求更有可能返回相同的结果。	100
server.port		如果设置了 server.address，则条件必需。	int	GenAI 服务器端口。[7]	80; 8080; 443
gen_ai.request.frequency_penalty		推荐	double	GenAI 请求的频率惩罚设置。	0.1
gen_ai.request.max_tokens		推荐	int	模型为请求生成的最大令牌数。	100
gen_ai.request.presence_penalty		推荐	double	GenAI 请求的存在惩罚设置。	0.1
gen_ai.request.stop_sequences		推荐	string[]	模型将用于停止生成更多令牌的序列列表。	["forest", "lived"]
gen_ai.request.temperature		推荐	double	GenAI 请求的温度设置。	0.0
gen_ai.request.top_p		推荐	double	GenAI 请求的 top_p 采样设置。	1.0
gen_ai.response.finish_reasons		推荐	string[]	模型停止生成令牌的原因数组，对应于收到的每个生成。	["stop"]；["stop", "length"]
gen_ai.response.id		推荐	字符串	补全的唯一标识符。	chatcmpl-123
gen_ai.response.model		推荐	字符串	生成响应的模型名称。[8]	gpt-4-0613
gen_ai.usage.input_tokens		推荐	int	GenAI 输入（提示）使用的令牌数。	100
gen_ai.usage.output_tokens		推荐	int	GenAI 响应（补全）使用的令牌数。	180
server.address		推荐	字符串	GenAI 服务器地址。[9]	example.com；10.1.2.80；/tmp/my.sock
gen_ai.input.messages		选择加入	any	作为输入提供给模型的聊天记录。[10]	[   {     “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		选择加入	any	模型返回的消息，每条消息代表一个特定的模型响应（选择、候选）。[11]	[   {     “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		选择加入	any	与聊天记录分开提供给 GenAI 代理或模型的系统消息或指令。[12]	[   {     “type”: “text”,     “content”: “You are an Agent that greet users, always use greetings tool to respond”   } ]; [   {     “type”: “text”,     “content”: “You are a language translator."   },   {     “type”: “text”,     “content”: “Your mission is to translate text in English to French."   } ]
gen_ai.tool.definitions		选择加入	any	可用于 GenAI 代理或模型的源系统工具定义列表。[13]	[   {     “type”: “function”,     “name”: “get_current_weather”,     “description”: “Get the current weather in a given location”,     “parameters”: {       “type”: “object”,       “properties”: {         “location”: {           “type”: “string”,           “description”: “The city and state, e.g. San Francisco, CA”         },         “unit”: {           “type”: “string”,           “enum”: [             “celsius”,             “fahrenheit”           ]         }       },       “required”: [         “location”,         “unit”       ]     }   } ]

[1] gen_ai.operation.name: 如果预定义值之一适用，但特定系统使用不同名称，则建议在特定 GenAI 系统的语义约定中记录它，并在仪器中使用系统特定的名称。如果未记录不同名称，仪器库应使用适用的预定义值。

[2] error.type：error.type 应匹配生成式 AI 提供程序或客户端库返回的错误代码、发生的异常的标准名称或另一个低基数错误标识符。Instrumentations 应记录其报告的错误列表。

[3] gen_ai.conversation.id：如果仪器化能够轻松获取给定操作的对话 ID，则应填充该 ID，例如

• 当被仪器化的客户端框架管理对话历史时（请参阅 LlamaIndex chat store）

• 当仪器化维护后端会话的 GenAI 客户端库时（请参阅 AWS Bedrock agent sessions，OpenAI Assistant threads）

管理对话历史的应用程序开发人员可以添加对话 ID 到 GenAI 和其他跨度或日志，使用仪器库提供的自定义跨度或日志记录处理器或钩子。

[4] gen_ai.output.type：当适用且请求包含输出格式时。

[5] gen_ai.output.type：当客户端请求特定类型的输出时，应使用此属性。模型可以返回零个或多个此类型的输出。此属性指定输出的模态，而不是实际的输出格式。例如，如果请求了图像，则实际输出可能是指向图像文件的 URL。将来可以在 gen_ai.output.{type}.* 属性中记录其他输出格式详细信息。

[6] gen_ai.request.model：请求的 GenAI 模型名称。如果模型由供应商提供，则该值必须是请求模型的确切名称。如果模型是经过微调的自定义模型，则该值应比经过微调的基础模型具有更具体的名称。

[7] server.port: 当从客户端观察到并且通过中间件通信时，server.port 应代表任何中间件（例如代理）之后的服务器端口，如果可用。

[8] gen_ai.response.model：如果可用。提供响应的 GenAI 模型名称。如果模型由供应商提供，则该值必须是实际使用的模型的确切名称。如果模型是经过微调的自定义模型，则该值应比经过微调的基础模型具有更具体的名称。

[9] server.address： 当从客户端观察并与中间件通信时，server.address 应表示任何中间件（例如代理）之后的服务器地址，如果可用。

[10] gen_ai.input.messages：仪器化必须遵循 输入消息 JSON schema。当属性记录在事件上时，它必须以结构化形式记录。当记录在 spans 上时，如果不支持结构化格式，则可以将其记录为 JSON 字符串，否则应将其记录为结构化形式。

消息必须按发送给模型的顺序提供。仪器可以提供一种方法供用户过滤或截断输入消息。

有关更多详细信息，请参阅 在属性上记录内容 部分。

[11] gen_ai.output.messages：仪器化必须遵循 输出消息 JSON schema

每条消息代表模型生成的单个输出选择/候选。每条消息恰好对应一个生成（选择/候选），反之亦然 - 一个选择不能跨越多条消息，或者一条消息不能包含来自多个选择的部分。

当属性记录在事件上时，它必须以结构化形式记录。当记录在跨度上时，如果不支持结构化格式，它可以被记录为 JSON 字符串，否则应以结构化形式记录。

仪器可以提供一种方法供用户过滤或截断输出消息。

有关更多详细信息，请参阅 在属性上记录内容 部分。

[12] gen_ai.system_instructions：当相应的提供商或 API 允许单独提供系统指令或消息与聊天历史记录分开时，应使用此属性。

作为聊天记录一部分的指令应记录在 gen_ai.input.messages 属性中，而不是此处。

仪器必须遵循 System instructions JSON schema。

当记录在跨度上时，如果不支持结构化格式，它可以被记录为 JSON 字符串，否则应以结构化形式记录。

仪器可以提供一种方法供用户过滤或截断系统指令。

有关更多详细信息，请参阅 在属性上记录内容 部分。

[13] gen_ai.tool.definitions：此属性的值匹配源系统工具定义格式。

预计它是一个对象数组，其中每个对象代表一个工具定义。如果仪器可用序列化字符串，仪器应尽最大努力将其反序列化为数组。当记录在跨度上时，如果不支持结构化格式，它可以被记录为 JSON 字符串，否则应以结构化形式记录。

由于此属性可能很大，因此不建议默认填充它。仪器可以提供一种启用填充此属性的方法。

error.type 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。

值	描述	Stability
_OTHER	当检测不到自定义值时使用的回退错误值。

gen_ai.operation.name 具有以下知名值列表。如果其中之一适用，则必须使用相应的值；否则，可以使用自定义值。

值	描述	Stability
chat	聊天完成操作，例如 OpenAI Chat API
create_agent	创建 GenAI 代理
embeddings	嵌入操作，例如 OpenAI 创建嵌入 API
execute_tool	执行工具
generate_content	多模态内容生成操作，例如 Gemini 生成内容
invoke_agent	调用 GenAI 代理
text_completion	文本补全操作，例如 OpenAI Completions API (Legacy)

gen_ai.output.type 具有以下知名值列表。如果其中之一适用，则必须使用相应的值；否则，可以使用自定义值。

值	描述	Stability
image	Image
json	具有已知或未知架构的 JSON 对象
speech	Speech
text	纯文本

事件: event.gen_ai.evaluation.result

状态:

事件名称必须是 gen_ai.evaluation.result。

此事件捕获评估 GenAI 输出的质量、准确性或其他特征的结果。当可能时，此事件应作为正在评估的 GenAI 操作 span 的父级，或在 span ID 不可用时设置 gen_ai.response.id。

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
gen_ai.evaluation.name		必需	字符串	用于 GenAI 响应的评估指标的名称。	Relevance; IntentResolution
error.type		如果操作以错误结束，则条件必需	字符串	描述操作最终结束的一类错误。[1]	timeout；java.net.UnknownHostException；server_certificate_invalid；500
gen_ai.evaluation.score.label		如果适用，则为“有条件必需”。	字符串	评估结果的人类可读标签。[2]	relevant; not_relevant; correct; incorrect; pass; fail
gen_ai.evaluation.score.value		如果适用，则为“有条件必需”。	double	评估器返回的评估分数。	4.0
gen_ai.evaluation.explanation		推荐	字符串	评估器为分配的分数提供的自由格式解释。	响应在事实方面是准确的，但缺乏足够的细节来完全回答问题。
gen_ai.response.id		如果可用，则为“推荐”。	字符串	完成的唯一标识符。[3]	chatcmpl-123

[1] error.type： error.type 应匹配生成式 AI 评估提供商或客户端库返回的错误代码、发生的异常的规范名称或其他低基数错误标识符。仪器化应记录其报告的错误列表。

[2] gen_ai.evaluation.score.label：此属性提供了评估器生成的评估分数的易于理解的解释。例如，在某个评估系统中，分数 1 可能意味着“相关”，而在另一个评估系统中可能意味着“不相关”，具体取决于评分范围和评估器。标签的基数应较低。可能的值取决于使用的评估指标和评估器；实现应记录可能的值。

[3] gen_ai.response.id：分配给正在评估的特定完成的唯一标识符。此属性有助于在 span ID 不可用时将评估事件与相应的操作关联起来。

error.type 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。

值	描述	Stability
_OTHER	当检测不到自定义值时使用的回退错误值。