OTel GenAI 语义约定是什么
OpenTelemetry 的生成式 AI 语义约定是一套统一的埋点属性命名规范，用 gen_ai.* 前缀描述系统、模型、请求参数与用量。遵循它的价值在于跨服务聚合：你的应用、网关与上游服务用同一套属性名，观测平台才能把一次调用串起来，做统一看板与告警。自创属性名虽然当下方便，但会把数据锁在单个服务里。
基本信息
| 适用平台 | 使用 OpenTelemetry 采集遥测的 LLM 应用与服务 |
|---|---|
| 核心前缀 | gen_ai.*：系统与模型标识、请求参数、用量统计 |
| 属性原则 | 命名遵循约定；自定义信息放在扩展属性中，不污染标准字段 |
| 隐私要求 | 敏感内容不写入 span 属性；用量与成本分开统计 |
典型使用场景
- 统一看板：按模型与调用方聚合请求量、错误率与延迟
- 成本核算：从用量属性汇总 token 消耗，与账单对账
- 问题排查：通过追踪把应用、网关与模型调用串成一条链
- 多服务协同：多个团队共用一套属性，避免口径分裂
- 容量规划：按模型维度的调用分布判断需要多少配额
常用属性示例
常用属性示例
# span: gen_ai.request
# gen_ai.system = <provider> # 提供方标识
# gen_ai.request.model = <model-id> # 请求的模型
# gen_ai.request.temperature = 0.2
# gen_ai.request.max_tokens = 1024
# gen_ai.usage.input_tokens = 812 # 输入用量
# gen_ai.usage.output_tokens = 233 # 输出用量
# 注意：属性名以官方约定为准，版本间可能有调整，落地前对照当前文档确认为什么统一命名重要
| 做法 | 短期效果 | 长期代价 |
|---|---|---|
| 遵循 gen_ai 约定 | 接入成本略高，需对照文档 | 跨服务可聚合，看板与告警可复用 |
| 自创属性名 | 当下方便 | 数据锁在单服务，口径无法合并 |
| 把提示全文写进属性 | 排查时信息最全 | 隐私风险与存储成本显著上升 |
| 只记用量不记模型 | 指标简单 | 无法按模型归因成本与质量 |
用量属性是成本归因的基础：把输入与输出分开记录，才能算出真实花费，也才能在提示改版时解释成本变化来自哪一段。
不要把完整的提示与模型输出写进 span 属性。遥测数据往往流向第三方观测平台，保留周期长、访问面宽，等同于把用户内容复制一份到另一个系统。