SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场genai-conformance

genai-conformance

测试与质量

查看项目

更新于 10-16 15:55

技能介绍

用途

GenAI Conformance 是 OpenInference 仓库内置的一致性测试框架，用于验证 OpenInference instrumentor 能否正确地将原生属性转换为 OTel GenAI 语义约定。它使用确定性的模拟提供商 API 来触发 instrumentor，并将 OTLP trace 导出到 weaver registry live-check，从而生成一份控制台摘要，显示注册表属性已见/缺失/建议级别的计数。

主要能力

  • 对 OpenInference instrumentor 在确定性模拟提供商 API 下进行测试。
  • 导出 OTLP trace 至 weaver registry live-check，并打印注册表属性摘要。
  • 验证 _genai_conversion.py 中的双重写入逻辑，即把 OpenInference 原生属性（llm.*、input.*、output.*、openinference.*）转换为 OTel GenAI 语义约定（gen_ai.*）。
  • 支持按提供商脚本（Anthropic、OpenAI、Google GenAI）分别运行。

目录结构

scripts/conformance/
├── run.py                 # orchestrator (PEP 723, stdlib only)
├── mock_server.py         # Flask mock with all providers' endpoints
├── anthropic_conformance.py      # PEP 723 + editable [tool.uv.sources]
├── openai_conformance.py         # PEP 723 + editable [tool.uv.sources]
├── google_genai_conformance.py   # PEP 723 + editable [tool.uv.sources]
├── README.md
└── results/                      # gitignored Weaver output

每个提供商脚本以 PEP 723 内联元数据声明依赖，并通过 [tool.uv.sources.<pkg>] 块固定本地 OpenInference 包。run.py 通过 uv run 调用一切。文件名避免使用裸提供商名（openai.py、anthropic.py），以免在 sys.path[0] 上覆盖 SDK 包。

run.py 中的 PROVIDER_SCRIPTS 元组同时用于预热和执行。新增提供商时，需追加到 PROVIDER_SCRIPTS，并添加对应的 <provider>_conformance.py 以及任何新的 mock 端点。

使用方式

运行命令：

uv run python/openinference-instrumentation/scripts/conformance/run.py

首次运行会下载固定版本的 weaver v0.22.1 和 semantic-conventions v1.40.0 到 ~/.cache/oi-conformance/；后续运行较快。uv 会根据 PEP 723 元数据哈希缓存每个提供商脚本的环境。

摘要解读

  • 已见注册表属性：运行中发出的 gen_ai.*（以及少量 service.* / telemetry.sdk.*）属性及其样本计数。
  • 已见非注册表属性：OpenInference 原生词汇表。按设计会显示为 Weaver missing_attribute 违规——它们不在（也不应在）OTel 注册表中。
  • 缺失注册表属性（gen_ai.*）：运行未发出的注册表属性。需分类为：
    1. 真实双重写入缺口（可在转换中修复）
    2. 测试场景缺口（可在 <provider>_conformance.py 中修复）
    3. Mock 数据缺口（可在 mock_server.py 中修复）
    4. 提供商不支持（记录并跳过）
    5. 应用级/无法自动发出（超出范围）
    6. 仅指标（如 gen_ai.token.type）
  • 建议级别：违规计数主要是 OI 原生词汇的 missing_attribute（预期内）；改进计数是开发阶段 gen_ai.* 属性的 not_stable 警告（同样预期内）。

迭代以最大化覆盖率

  • 类别 1（双重写入缺口）：检查 results/live_check.json，决定在 _genai_conversion.py 的何处扩展，并始终在 test_genai.py 中为新路径添加单元测试，然后重新运行验证。
  • 类别 2（测试场景缺口）：使用 OITracer(trace.get_tracer(__name__), TraceConfig(enable_genai_semconv=True)) 手动发出非 LLM span（TOOL、RETRIEVER、EMBEDDING、AGENT）。
  • 类别 3（Mock 数据缺口）：在 mock_server.py 顶部的 mock 响应字典中添加字段。

升级 semconv 版本

run.py 中固定了 SEMCONV_VERSION（当前 v1.41.1）和 WEAVER_VERSION（当前 v0.23.0）。升级清单包括：检查新版 Weaver 发布、更新常量、运行一次以下载新注册表、从缓存刷新 vendored JSON schema、运行单元测试、检查 semconv 变更日志中的特定风险（新必填字段、新 Role/FinishReason 枚举值、新增/移除的 gen_ai.* 属性）、刷新内联版本引用，最后端到端重新运行一致性测试。

注意事项

  • PEP 723 内联表行长度：使用多段形式以避免 ruff E501。
  • 一致性目录被排除在包级检查之外：pyproject.toml 将 scripts/* 排除于 mypy 和 pytest 的 norecursedirs。
  • Weaver 不活动超时为 90 秒；run.py 通过 --prewarm 提前退出预热每个提供商环境。
  • 所有提供商共享一个 mock 服务器：一个 Flask 应用处理 /v1/messages（Anthropic）、/v1/chat/completions + /v1/embeddings + /v1/responses（OpenAI）、以及 /v1beta/models/<path:model>（Google）。
  • 可编辑安装是强制性的：PyPI 版本不会包含进行中的双重写入变更。
  • 系统消息保留在 gen_ai.input.messages 中，不发出 gen_ai.system_instructions。
  • tool_call（单数）finish_reason：转换将 tool_calls（OpenAI 复数）和 function_call（旧版）都规范化为 tool_call。
  • 不要混淆违规与形状错误：真正的形状错误需解析 results/live_check.json 并查找 id != missing_attribute 的 advice。

限制

资料中未提供该工具的具体收费、价格、平台支持范围、性能指标或效果数据。