Phoenix 中的 OpenInference Span 属性规范：必选与强烈推荐属性完整指南

Phoenix 中的 OpenInference Span 属性规范必选与强烈推荐属性完整指南【免费下载链接】phoenixAI Observability Evaluation项目地址: https://gitcode.com/gh_mirrors/phoenix13/phoenixOpenInference 是一套基于 OpenTelemetry 的 AI/LLM 应用语义约定Phoenix 用它来采集、存储与分析 AI 应用的链路Trace数据。本指南以 Phoenix 仓库中的语义约定参考文档为主线系统讲解所有 OpenInference Span 都必须携带的唯一必选属性openinference.span.kind、九种合法 Span Kind 的含义与适用场景以及强烈推荐在所有 Span 上记录的input.value/output.value输入输出属性及其在评估、调试与分析中的价值。读完后你将能够为手写或自动插桩的 Span 正确地附加语义属性使数据可直接用于 Phoenix 的评估器、链路过滤与微调数据集导出。必选属性每个 Span 都必须有且仅有一个openinference.span.kindOpenInference 规范要求每一个 Span 都必须携带且仅携带一个必选属性openinference.span.kind用于标明该 Span 封装的工作类型。最小合法示例{ openinference.span.kind: LLM }这一要求同样体现在 Phoenix 的源码实现中。在 Span 数据模型 里SpanKind是一个独立的枚举类型Phoenix 在解码 OTLP Span 时正是通过该属性来还原 Span 类型在 OTLP 解码入口 中decode_otlp_span调用get_attribute_value(attributes, OPENINFERENCE_SPAN_KIND)从展平后的属性中读取该值并转换为SpanKind枚举在 OTLP 编码出口 中encode_span_to_otlp会在属性缺失时自动补写openinference.span.kind span.span_kind.value确保导出的数据始终满足每 Span 必有一个 kind的不变量。因此无论是通过自动插桩、手动插桩还是直接构造 Spanopeninference.span.kind都是数据进入 Phoenix 后被正确分类、建树与聚合的前提。九种合法的 Span Kind 及其适用场景OpenInference 共定义了9 种合法valid的 Span Kind覆盖了 LLM 应用中的典型操作单元Span Kind用途常见使用场景LLM语言模型推理OpenAI、Anthropic、本地模型调用EMBEDDING向量生成文本转向量CHAIN应用流程编排LangChain 链、自定义工作流RETRIEVER文档/上下文检索向量数据库查询、语义搜索RERANKER结果重排序对检索结果重新排序TOOL外部工具调用API 调用、函数执行AGENT自主推理ReAct 智能体、规划循环GUARDRAIL安全/策略检查内容审核、PII 检测EVALUATOR质量评估答案相关性、忠实度评分Phoenix 源码中的SpanKind枚举在此基础上还包含了PROMPT与UNKNOWN两个额外取值见 schemas.py其中UNKNOWN用于兜底_missing_方法在遇到无法识别的字符串时返回UNKNOWN而非抛错从而保证异常或不完整的数据不会导致链路解析中断。也就是说写入手工 Span 时应优先使用上述 9 种规范取值遇到非规范值时会以UNKNOWN兼容处理。不同 Span Kind 还对应各自的专属属性集例如LLMSpan 需要llm.model_name、llm.token_count.prompt/completion/total、llm.input_messages.{i}.*等详见 LLM Span 属性参考。这些 kind 专属属性与通用属性配合共同构成一个可查询、可评估的完整 Span。强烈推荐属性input.value与output.value除必选属性外OpenInference 还定义了**强烈推荐highly recommended**在所有 Span 上记录的输入输出属性属性类型描述input.valueString操作的输入提示词、查询、文档output.valueString操作的输出响应、结果、答案示例{ openinference.span.kind: LLM, input.value: What is the capital of France?, output.value: The capital of France is Paris. }在 Phoenix 的 OTLP 解码流程 中还有一个值得注意的细节如果input.value不是字符串类型例如传入的是结构化对象Phoenix 会自动将其json.dumps序列化并同步把input.mime_type置为application/json。这保证了输入输出值无论原始形态如何都能以稳定可解析的形式存入链路数据。为什么要记录输入输出评估Evaluationsfaithfulness忠实度、relevance相关性、hallucination detection幻觉检测等大量评估器必须同时拿到输入与输出才能评判质量。没有input.value/output.value的 Span 无法参与这类评估。信息流理解Information flow看到每一步的输入输出就能直观追踪数据在应用中的变换路径例如用户问题 → 检索结果 → 模型回答。调试Debugging出问题时真实的输入输出能大幅缩短根因定位时间避免靠猜测复现问题。分析Analytics支持对相似输入或输出进行模式分析例如聚合同类用户问题、统计同类错误回答。Phoenix 对输入输出的行为输入/输出会在 Span 详情中显著展示方便人工查看评估器可以自动访问这些值无需额外传参支持按输入或输出内容搜索、过滤链路可将输入输出导出用于构建微调fine-tuning数据集。补充推荐让 Span 更具上下文在记录input.value/output.value的同时建议搭配input.mime_type/output.mime_type标注数据类型如text/plain、application/json并可叠加session.id、user.id做会话与用户维度的归因以及metadataJSON 序列化字符串携带环境、模型版本等自定义信息。这些通用属性适用于任意 Span Kind具体字段与示例见 通用属性参考。完整示例{ openinference.span.kind: CHAIN, input.value: What is the weather?, input.mime_type: text/plain, output.value: I dont have access to weather data., output.mime_type: text/plain, session.id: session_abc123, user.id: user_xyz789, metadata: {\environment\: \production\, \model_version\: \v2.1\} }属性如何存储点号展平约定OpenInference 将嵌套数据结构展平为点号dot-notation属性键这与 OpenTelemetry 的键值模型兼容也便于在 Phoenix 的spans.attributesJSONB 列中直接查询。展平规则为对象 → 点号路径{llm: {model_name: gpt-4}}展平为{llm.model_name: gpt-4}数组 → 从 0 开始的索引{llm: {input_messages: [{role: user, content: Hi}]}}展平为{llm.input_messages.0.message.role: user, llm.input_messages.0.message.content: Hi}消息约定消息类属性必须保留.message.段如llm.input_messages.{index}.message.{field}。上述展平/反展平逻辑在 Phoenix 的 属性处理模块 中实现flatten()将嵌套字典递归拍平为(key, value)键值对流unflatten()则反向还原为嵌套结构。其中还有一个重要的仅结构数组参与索引规则——只有后跟映射字典的数字键才会被解释为数组下标如documents.0.content而tags.0这类标量结尾的数字键会保留为字典字符串键以确保语义正确的往返转换见 attributes.py。一个完整的实战示例将上述约定组合起来一个典型的 LLM 调用 Span 展平后如下存储于 Phoenix 的spans.attributesJSONB{ openinference.span.kind: LLM, llm.model_name: claude-3-5-sonnet-20241022, llm.invocation_parameters: {\temperature\: 0.7, \max_tokens\: 1024}, input.value: What is the capital of France?, output.value: The capital of France is Paris., llm.input_messages.0.message.role: system, llm.input_messages.0.message.content: You are a helpful assistant., llm.input_messages.1.message.role: user, llm.input_messages.1.message.content: What is the capital of France?, llm.output_messages.0.message.role: assistant, llm.output_messages.0.message.content: The capital of France is Paris., llm.token_count.prompt: 25, llm.token_count.completion: 8, llm.token_count.total: 33 }更多展平前后的对照示例可参考 展平约定文档Trace 与 Span 的层级、父子关系与生命周期概念见 Overview 文档。最佳实践清单每个 Span 必填openinference.span.kind取值限定为 9 种规范值之一优先记录input.value与output.value这是评估器可用性的硬前提也是调试与分析的基础善用mime_type标注输入输出类型非字符串输入由 Phoenix 自动 JSON 序列化按需叠加通用属性session.id、user.id、metadata提供会话、用户与业务上下文遵循展平约定手写属性时直接使用点号路径数组从 0 开始编号消息属性保留.message.段kind 专属属性按类型补齐例如 LLM Span 补llm.model_name与 token 计数让链路数据的分析价值最大化。【免费下载链接】phoenixAI Observability Evaluation项目地址: https://gitcode.com/gh_mirrors/phoenix13/phoenix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考