06｜语义约定：让所有人对同一个字段说同一种语言

数据格式一致，不代表数据含义一致。一个团队写 model，另一个写 llm_name，第三个写 provider_model，后端很难统一查询。OpenTelemetry Semantic Conventions 用公共名称、类型和含义解决这个问题。

规范统一什么

语义约定会规定 Span 名称、Attribute 名称与类型、Metric 单位和合法取值。例如 HTTP、数据库、消息系统和 GenAI 都有各自的字段约定。

使用标准字段的好处是：不同服务和语言可以被同一种查询理解，仪表盘与告警也更容易复用。

一个简单案例

三个 Agent 分别接入不同模型供应商。如果都使用统一的模型、操作、Token 和响应状态字段，就可以直接比较各供应商的延迟、成本和失败率，而不用先写三套字段映射。

业务特有字段仍然可以补充，例如 agent.task.type 和 agent.plan.version。原则是：标准字段表达通用语义，自定义字段表达团队独有语义。

现实挑战：规范仍在演进

GenAI 和 Agent 语义约定仍可能处于 Development 状态。字段改名或含义变化后，如果生产环境同时存在多个版本，查询可能漏掉一部分数据。

现象—假设—证据—判断

现象：升级埋点库后，模型调用仪表盘突然减少。假设包括调用量下降、数据未导出、字段名变化。证据显示 Trace 数量正常，新旧版本使用了不同属性名。判断：语义约定迁移没有兼容查询，而不是模型调用减少。

应记录埋点库版本和 Schema URL，升级前检查稳定性级别，必要时短期双写或在 Collector 中转换，但要设定移除旧字段的时间。

工具返回结构也需要契约

OTel 统一遥测语义，却不会自动保证业务工具返回值稳定。工具还需要 JSON Schema、版本号、必填字段和错误模型。Harness 在把结果交给模型前，应先做结构校验。

小结

语义约定降低跨团队和跨供应商的数据翻译成本。采用规范时要同时关注字段含义、稳定性和版本迁移；标准之外的业务字段，也应由团队维护清晰契约。