OpenTelemetry GenAI 语义约定：统一模型与 Agent 可观测数据
OpenTelemetry GenAI 语义约定为模型调用、Agent、指标、事件和追踪定义共同字段，帮助不同框架与后端交换可观测数据。
OpenTelemetry Generative AI semantic conventions observability OpenTelemetry generative-ai open-source OpenTelemetry GenAI 语义约定为模型调用、Agent、指标、事件和追踪定义共同字段，帮助不同框架与后端交换可观测数据。
1. 项目是什么
OpenTelemetry Generative AI semantic conventions 是面向生成式 AI 调用和 Agent 工作流的开放语义约定。它不是监控产品，而是规定 span、事件、指标及属性如何命名和表达，让不同语言的埋点、框架与可观测后端对同类操作使用共同结构。[S1][S2]
2. 解决什么问题
模型供应商和 Agent 框架常各自记录模型名、token、延迟、提示、响应和错误，字段不一致会让仪表板、告警和迁移重复建设。共同语义可以让运维团队跨服务关联请求，也让工具开发者不用为每个后端重新定义数据模型。[S2]
3. 核心能力
官方介绍把 GenAI 可观测信号分为 traces、metrics 和 events：追踪描述一次模型交互及参数、响应和错误；指标聚合请求量、时延和 token 使用；事件可承载输入与输出等细节。[S2] 相关约定还持续覆盖 Agent、会话和工具执行。当前主文档已标记内容迁移到独立 GenAI 语义约定仓库。[S1]
4. 典型工作流
平台团队先盘点现有模型调用和 Agent 节点，选定要记录的 operation、model、token、duration、error 与会话关联字段；由 SDK 或自动插桩生成遥测，经过 Collector 做过滤、采样和导出，再在后端建立追踪与成本视图。应用自定义字段应与标准字段分开，避免名称冲突。
5. 适用场景
它适合同时使用多个模型供应商、多个编程语言或多个 Agent 框架的团队，也适合正在建设统一 AI 平台和供应商中立观测层的企业。只有一个小型原型时可先记录少量关键字段；若团队没有告警、评测或调试流程，完整埋点本身不会自动产生治理价值。
6. 部署与接入
语义约定通过应用插桩和 OpenTelemetry 管道落地，不需要单独部署“GenAI 标准服务器”。实施应固定所采用的语义约定版本，记录哪些字段是稳定、开发中或已迁移，并在 SDK 升级时做兼容测试。Collector 与后端要验证属性、事件和采样规则没有丢失关键关联。
7. 主要风险
提示词和模型输出可能包含个人信息、密钥、客户数据或受版权保护内容，不能因为标准支持事件就默认全量记录。高基数字段还会提高存储费用。约定仍在演进，字段迁移可能破坏旧仪表板；token 数也不能直接等同于实际账单，必须结合供应商计费记录核对。
8. 竞争与生态位
OpenTelemetry 定义的是供应商中立的数据语言和传输基础，不替代 LangSmith、Phoenix、云监控或安全审计产品。后者可在标准数据上提供存储、搜索、评测与告警。它的核心价值是降低工具绑定和重复埋点，但具体可视化、质量判断与事件响应仍由实施团队负责。
9. 验收建议
准备成功调用、限流、超时、工具失败和多轮 Agent 五类样本，确认每类数据都能从应用跨 Collector 到后端，且 trace 关联完整。对敏感字段做注入测试，确保过滤后不能在日志和事件中检索到原文。再比较 SDK 升级前后字段集合、仪表板查询和存储量，防止无声变化。
10. 来源与更新时间
本文核对时间为 2026-08-09。规范入口用于确认 GenAI 内容的当前迁移状态；OpenTelemetry 官方文章用于确认语义约定的目标、三类信号和早期插桩方向。由于规范持续演进，生产接入前应再次核对目标版本。[S1][S2]