OpenTelemetry GenAI 语义约定
OpenTelemetry GenAI 语义约定定义了一套用于描述 AI 和 LLM 遥测数据的标准架构，由云原生计算基金会 (CNCF) 提供支持。该约定已被众多可观测性平台和云服务采用，包括 Google Cloud、AWS、Azure、Datadog 等。通过原生支持此标准，MLflow 确保您的 AI 可观测性数据不会被锁定在专有格式中，且任何兼容的工具均可生产或消费这些数据。
以 GenAI Semconv 格式导出追踪记录 (Traces)
默认情况下，MLflow 使用其内部的 mlflow.* 属性格式导出追踪记录。如需以 GenAI 语义约定格式 (gen_ai.*) 导出，请设置 MLFLOW_ENABLE_OTEL_GENAI_SEMCONV 环境变量，并将 OTLP 端点配置为导出目标。
import os
# Enable GenAI Semantic Convention format for OTLP export
os.environ["MLFLOW_ENABLE_OTEL_GENAI_SEMCONV"] = "true"
os.environ["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"] = "https://:4317/v1/traces"
启用后，MLflow 会在导出时转换 span 属性。这使得其他兼容 OTel 的后端能够理解追踪数据，并以人类可读的格式进行展示。
下表总结了关键映射：
| MLflow 属性 | GenAI Semconv 属性 | 描述 |
|---|---|---|
mlflow.spanType | gen_ai.operation.name | 操作类型（例如，CHAT_MODEL → chat） |
mlflow.llm.model | gen_ai.request.model | 模型名称 |
mlflow.llm.provider | gen_ai.provider.name | 提供商（例如，openai, anthropic） |
mlflow.chat.tokenUsage | gen_ai.usage.input_tokens / gen_ai.usage.output_tokens | 令牌 (Token) 计数 |
mlflow.spanInputs | gen_ai.input.messages | 输入消息 |
mlflow.spanOutputs | gen_ai.output.messages | 输出消息 |
如需查看完整的映射表，请参阅属性映射参考。
GenAI semconv 导出功能在 MLflow 3.11 及更高版本中可用。设置 MLFLOW_ENABLE_OTEL_GENAI_SEMCONV=true 即可启用。
将 GenAI Semconv 追踪记录摄取到 MLflow
MLflow Server 本身兼容 OTel，并在 /v1/traces 路径下公开了一个 OTLP 端点，该端点会自动识别使用 GenAI 语义约定属性的追踪记录。您可以将符合 GenAI semconv 标准的追踪记录发送给 MLflow，它们将作为一等公民进行展示，并具备正确的 span 类型、令牌计数、模型信息以及结构化的输入/输出。
请参阅将 OpenTelemetry 追踪记录收集到 MLflow 获取设置说明。
支持的框架
以下提供商和框架支持针对 GenAI semconv 导出的消息格式转换：
- OpenAI (聊天补全和响应 API)
- Anthropic
- Google Gemini
- Amazon Bedrock
在摄取端，MLflow 可以识别来自任何兼容工具的 GenAI semconv 追踪记录，包括 Google ADK、LiveKit Agents、Spring AI 等。
使用 GenAI 格式进行双重导出
您可以将 GenAI semconv 导出与双重导出结合使用，从而同时将追踪记录发送到 MLflow 和兼容 OpenTelemetry 的后端。MLflow 在本地以其自有格式存储追踪记录（用于 MLflow UI），同时将 GenAI semconv 版本导出到 OTLP 端点。要启用双重导出，请设置 MLFLOW_TRACE_ENABLE_OTLP_DUAL_EXPORT=true。
import os
# Enable both GenAI semconv format and dual export
os.environ["MLFLOW_ENABLE_OTEL_GENAI_SEMCONV"] = "true"
os.environ["MLFLOW_TRACE_ENABLE_OTLP_DUAL_EXPORT"] = "true"
# Configure the MLflow tracking server URI and experiment ID
os.environ["MLFLOW_TRACKING_URI"] = "https://:5000"
os.environ["MLFLOW_EXPERIMENT_ID"] = "123"
# Configure the other OpenTelemetry-compatible backend OTLP endpoint
os.environ["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"] = (
"http://other-backend-otlp-endpoint:4317/v1/traces"
)