跳到主要内容

关键背景 — GenAI 的「搬家」与弃用墓碑

这章解释一个读者一打开仓库就会困惑的事实:为什么 docs/gen-ai/ 几乎是空的、model/gen-ai/ 只剩 deprecated/? 看懂这点,你才知道该去哪读真东西、本仓的定义还作不作数。

4.1 事实:GenAI 已经搬出本仓​

本仓 open-telemetry/semantic-conventions 是 OTel 的总语义约定仓。在本 commit(b51e2a6),GenAI 这块已经迁移到独立仓 open-telemetry/semantic-conventions-genai。

证据有三层:

  1. 文档全成占位页:docs/gen-ai/ 下 11 个 .md 每个只有 11 行,正文是「Moved: ... 已移到 GenAI 仓」(docs/gen-ai/README.md:1-11,其余如 gen-ai-spans.md 同形)。
  2. 模型只剩 deprecated/:model/gen-ai/ 下只有 deprecated/ 子目录,没有活跃定义(model/gen-ai/deprecated/ 四个 YAML)。
  3. 每个组都带「moved」note:几乎所有 group 和 attribute 都有 deprecated.reason: uncategorized + note「Moved to the OpenTelemetry GenAI semantic conventions repository」(如 model/gen-ai/deprecated/spans-deprecated.yaml:5-8)。

[!IMPORTANT] 我没有本地克隆 semantic-conventions-genai 新仓,因此本系列前几章讲的「GenAI 领域模型」全部来自本仓留下的 deprecated YAML——它就是搬家前最后一刻的完整定义。字段语义在两仓间应当一致(搬家通常是平移),但最新演进要以新仓为准。本文档对新仓内容不做任何具体断言。

4.2 为什么不直接删?——「墓碑」的工程意义​

如果 GenAI 搬走了,为什么不把这些 YAML 删干净?因为删除会破坏向后兼容:已经有 instrumentation 在发 gen_ai.* 字段、有后端在读它们。直接删,Rego 兼容性闸门(第 3 章)会拒,下游也会断。

于是用了**「墓碑」模式**:定义全留着,但全标 deprecated,达到三个效果:

  • 历史可查:老字段的名字、类型、语义依然在仓里有据可查。
  • 停止演进:deprecated 标记 + 文档占位页,告诉所有人「别在这继续改了,去新仓」。
  • 指明去向:统一的 note 把读者导向新仓。

4.3 墓碑是怎么编码的:两个标记​

每个搬走的字段身上挂着两个机制配合的标记(以下行号针对 registry-deprecated.yaml 里的 gen_ai.request.model)。

① deprecated 块——人和文档看的「退休告示」:

# model/gen-ai/deprecated/registry-deprecated.yaml (gen_ai.request.model 的 deprecated 块)
deprecated:
  reason: uncategorized
  note: >
    Moved to the [OpenTelemetry GenAI semantic conventions repository](...).

② dependency_resolution.exclude——给 Weaver 看的「别再被引用」:

# 同一字段的 annotations 块
annotations:
  dependency_resolution:
    exclude: true

exclude: true 让 Weaver 在解析依赖时跳过这些字段——它们不再参与别处的 ref 解析,等于在工具链层面把它们「摘出」活跃图谱,只留作历史记录。几乎每个搬走的字段都同时带这两个标记。

4.4 弃用的几种语义:moved vs renamed vs obsoleted​

deprecated.reason 不止一种,表达不同的「退休方式」:

reason含义例子
uncategorized + moved/replaced note搬走了或有替代,去新仓找绝大多数 gen_ai.*(spans-deprecated.yaml:5-8);也包括 gen_ai.system(见下)
renamed + renamed_to改了名,有明确新名(本仓内的结构化改名)gen_ai.system 的枚举成员 vertex_ai → gcp.vertex_ai(registry-deprecated.yaml 该成员的 deprecated 块)
obsoleted直接废弃,无替代gen_ai.prompt / gen_ai.completion:「Removed, no replacement」

一个值得细看的样本是 gen_ai.system(旧的 provider 字段,registry-deprecated.yaml:65-273):

  • 它的字段级 deprecated.reason 其实是 uncategorized,只用一段 prose note 说「Replaced by gen_ai.provider.name」(registry-deprecated.yaml:170-174)——字段本身没有结构化的 renamed+renamed_to。替代关系是真的,但在模型里是「prose 说明」而非结构化分类。
  • 真正的结构化 renamed/renamed_to 只出现在它的枚举成员上,如 vertex_ai → gcp.vertex_ai、gemini → gcp.gemini、az.ai.inference → azure.ai.inference。

这说明:renamed_to 这种结构化改名在本仓里主要发生在枚举成员级;字段级的「被替代」多数走 uncategorized + note。第 3 章的 deprecation.rego 正是逐条校验这些成员级 renamed_to 都指向真实存在的新家。

4.5 边界与局限(诚实交代)​

  • 本仓的 GenAI 定义是「冻结快照」,非最新真相。 要追最新字段,去 semantic-conventions-genai。本文档前几章是基于本仓 deprecated YAML 的忠实重建。
  • 稳定性普遍是 development。 几乎所有 GenAI 字段 stability: development(实验性),意味着即便在新仓也可能继续变动——不要当成已冻结的稳定契约依赖。
  • 本仓不含 Weaver 源码。 代码生成与策略评估的真正引擎在外部 otel/weaver 仓,本仓只固定其版本并调用(dependencies.Dockerfile:6)。Weaver 内部如何渲染模板、如何跑 Rego,超出本仓可读范围。
  • reason: uncategorized 用得很泛。 几乎所有「moved/replaced」都用 uncategorized——它更像「有 note 说明、但不属于 renamed/obsoleted 这些结构化类别」的兜底,而非精确的语义分类。

4.6 横向对比(本 shelf 视角)​

GenAI 语义约定在 ai-protocol-reference 里扮演的是**「跨工具的字段契约层」**,和别的协议子库取舍不同:

  • 它只规定数据长什么样,不规定怎么传输——这点和 MCP(规定客户端/服务器如何通信)互补:本仓里 MCP span 复用 gen_ai.tool.name 当 target、并和 execute_tool span 去重(见第 2 章 2.7),正是两套约定在字段层对齐的体现。
  • 它把评估(eval)也标准化(gen_ai.evaluation.*,见 2.6),呼应本 shelf 的 evals-observability area——多数协议只管「调用」,它连「质量打分」都纳入同一套遥测词汇。

4.7 代码地图​

主题文件符号/位置
文档占位页(搬家公告)docs/gen-ai/README.md全文 11 行
「moved」note 模式model/gen-ai/deprecated/registry-deprecated.yaml各字段 deprecated.note
Weaver 摘除标记model/gen-ai/deprecated/registry-deprecated.yamlannotations.dependency_resolution.exclude
字段「被替代」样本(reason: uncategorized)model/gen-ai/deprecated/registry-deprecated.yamlgen_ai.system(prose:→gen_ai.provider.name)
枚举成员级改名(renamed_to)model/gen-ai/deprecated/registry-deprecated.yamlgen_ai.system members(vertex_ai→gcp.vertex_ai)
obsoleted(无替代)model/gen-ai/deprecated/registry-deprecated.yamlgen_ai.prompt, gen_ai.completion
改名校验策略policies/deprecation.regorenamed_to 规则族