企业官网建设流程全解析

• 可观测性
• AI 评测
• LLMOps
• AI 应用
• 人工智能

导读：本文以 Phoenix 的 Python 自动插桩能力为主线，讲解如何在不修改业务代码的前提下，通过运行时补丁（runtime patching）为 OpenAI、Anthropic、LangChain、LlamaIndex 等主流 LLM SDK 与框架自动生成追踪 Span。读完本文，你将掌握phoenix.otel.register的完整配置（含选择性插桩与 OTel GenAI 原生插桩两种模式）、gen_ai.*语义约定的自动转换机制，以及自动插桩的边界与手动插桩的补充方案，让 Phoenix UI 自动呈现模型名、输入输出、Token 用量与耗时等关键信息。

一、自动插桩的工作原理

自动插桩（auto-instrumentation）的核心思想是：对已安装的受支持库在运行时打补丁（patch），从而自动创建 Span。它适用于 LangChain、LlamaIndex、OpenAI SDK 等官方支持框架；对于自定义业务逻辑，则需要配合手动插桩来补全。

从源码结构看，Phoenix 的自动插桩是围绕OpenInference 插桩器入口点（entry point）机制实现的。在 otel.py 中，_auto_instrument_installed_openinference_libraries会读取openinference_instrumentor组的所有 entry points，逐个实例化并调用其instrument(tracer_provider=...)：

def _auto_instrument_installed_openinference_libraries(tracer_provider: TracerProvider) -> None: openinference_entry_points = entry_points(group="openinference_instrumentor") if not openinference_entry_points: warnings.warn( "No OpenInference instrumentors found. " "Maybe you need to update your OpenInference version? " "Skipping auto-instrumentation." ) return for entry_point in openinference_entry_points: instrumentor_cls = entry_point.load() instrumentor = instrumentor_cls() instrumentor.instrument(tracer_provider=tracer_provider)

这段代码解释了"自动发现"的本质：只要你通过pip install openinference-instrumentation-{name}安装了对应的插桩包，Phoenix 就能在register(auto_instrument=True)时自动发现并启用它，无需在代码里显式 import 任何 instrumentor。

二、支持的框架一览

Python 生态下，Phoenix 自动插桩覆盖两类目标：

命名规律统一：包名均为openinference-instrumentation-<名称>，例如 OpenAI 对应openinference-instrumentation-openai、LangChain 对应openinference-instrumentation-langchain、LlamaIndex 对应openinference-instrumentation-llama-index（参考 setup-python.md 中的安装清单）。每个插桩器生成不同 Span Kind（LLM、CHAIN、RETRIEVER、TOOL 等）的完整属性结构，可查阅 references 目录下的span-*.md文件。

三、快速开始：两条命令 + 一行注册

第一步，安装核心包与目标插桩器：

pip install arize-phoenix-otel pip install openinference-instrumentation-openai # 按需添加其他插桩器

第二步，注册并自动插桩：

from phoenix.otel import register register(project_name="my-app", auto_instrument=True) # 自动发现并启用所有已安装的插桩器

第三步，正常使用客户端即可（无需任何埋点）：

from phoenix.otel import register from openai import OpenAI register(project_name="my-app", auto_instrument=True) client = OpenAI() response = client.chat.completions.create( model="gpt-4", messages=[{"role": "user", "content": "Hello!"}] )

运行后，Span 会出现在 Phoenix UI 的my-app项目中，模型名、输入/输出、Token 用量、耗时等属性均由插桩器自动采集。各 Span Kind 的完整属性 Schema 见 span-llm.md、span-chain.md 等文件。

四、register()参数详解：从源码理解默认行为

register是arize-phoenix-otel的入口函数，其完整签名定义于 otel.py，关键参数如下：

从源码看两个容易被忽略的细节：

1. 项目名始终写入资源：register会强制把project_name合并进Resource的project.name属性（见 otel.py）。即使调用方传入自定义resource，project.name也会被合并进去，不会覆盖用户的其它资源属性。
2. 协议推断逻辑：endpoint 路径以/v1/traces结尾时走 HTTP+protobuf；无路径且端口等于PHOENIX_GRPC_PORT（默认 4317）时走 gRPC（见_maybe_http_endpoint/_maybe_grpc_endpoint）。HTTP 模式下register会自动补全/v1/traces后缀并保留已有路径前缀，因此部署在反向代理子路径下的 Phoenix 也能正常工作——例如endpoint="http://host/prefix"会实际发送到http://host/prefix/v1/traces。

生产推荐配置示例（完整示例见 otel.py 的 docstring）：

from phoenix.otel import register tracer_provider = register( project_name="my-app", batch=True, # 批量上报，生产推荐 auto_instrument=True, # 自动插桩 api_key="your-api-key", # 或改用 PHOENIX_API_KEY 环境变量 )

BatchSpanProcessor的批量行为还可通过标准 OTLP 环境变量调优（otel.py 的 docstring 列出）：OTEL_BSP_SCHEDULE_DELAY（调度间隔）、OTEL_BSP_MAX_QUEUE_SIZE（队列上限）、OTEL_BSP_MAX_EXPORT_BATCH_SIZE（单批最大条数）、OTEL_BSP_EXPORT_TIMEOUT（导出超时）。

五、选择性插桩：显式控制插桩目标

如果希望精确控制启用哪些插桩器（例如避免自动发现引入意料之外的插桩），可以关闭auto_instrument，改为手动实例化指定 instrumentor：

from phoenix.otel import register from openinference.instrumentation.openai import OpenAIInstrumentor tracer_provider = register(project_name="my-app") # 不传 auto_instrument OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)

两种方式的取舍：

• auto_instrument=True：适合"装了就用"的快速上手，新装的插桩包在下一次启动时自动生效；
• 显式instrument()：适合对依赖集合有严格管控的生产环境，插桩对象一目了然，也便于按需传参。

六、OTel GenAI 原生插桩：不装 OpenInference 插桩器也能追踪

Phoenix 对 OpenTelemetry GenAI 语义约定（gen_ai.*属性）提供了原生兼容层：当 Phoenix 通过 OTLP 接收到 Span 时，会自动把gen_ai.*属性转换为 OpenInference 语义。这意味着，任何能产出gen_ai.*属性的OTel 原生 AI 插桩库都可以直接使用，无需安装 OpenInference instrumentor，Phoenix 即可正确展示 LLM Span Kind、模型名、Token 计数与消息内容。

转换规则要点：

• 优先级：如果 Span 上已带有 OpenInference 属性（例如来自双写插桩器），这些已有值优先于转换生成的值；
• 消息部分的结构化转换：消息内容按结构转换而非字符串拼接。gen_ai消息中的文本（text）、图片（image）、Blob、推理（reasoning）等部分，各自成为llm.{input,output}_messages.{i}.message.contents.{j}下的一个条目，并以message_content.type（text、image、reasoning等）标记类型——因此模型的推理内容会以reasoning部分独立保留，而不会被折叠进回答文本。完整的 content part 结构见 span-llm.md#messages。

使用方式：客户端无需任何改动，照常向 Phoenix 发送 OTLP 即可：

from phoenix.otel import register # 适用于任何产出 gen_ai.* 属性的 OTel 原生 AI 插桩器 register(project_name="my-app")

以 Anthropic 为例，使用 OTel GenAI 官方插桩包（来自opentelemetry-python-genai项目）：

pip install opentelemetry-instrumentation-anthropic

from phoenix.otel import register from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor import anthropic register(project_name="my-app") # 插桩 Anthropic AnthropicInstrumentor().instrument() # 正常使用 Anthropic 客户端，Span 自动创建 client = anthropic.Anthropic() response = client.messages.create( model="claude-3-5-sonnet-20241022", max_tokens=1024, messages=[ {"role": "user", "content": "Hello, Claude!"} ] )

目前opentelemetry-python-genai提供的插桩包包括opentelemetry-instrumentation-anthropic与opentelemetry-instrumentation-openai等。选择哪条技术路线，取决于你更愿意依赖 OpenInference 生态（属性更完整、覆盖框架更广）还是 OTel 官方生态（gen_ai.*原生标准）。

七、环境变量与配置优先级

自动插桩的运行时配置既可以走代码参数，也可以走环境变量（详见 settings.py）：

.env.phoenix凭据文件发现（settings.py）：当某个配置既未以参数传入、也未在进程环境中设置时，register()会从当前工作目录向上逐级查找最近的.env.phoenix文件（dotenv 格式，仅读取PHOENIX_前缀键）：

# .env.phoenix PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006 PHOENIX_API_KEY=your-api-key

优先级恒定：显式参数 > 进程环境变量 >.env.phoenix文件，文件永远不会覆盖已设置的值。发现结果按工作目录缓存于进程生命周期内；对长驻进程（如 Jupyter Notebook），创建或修改文件后可调用phoenix.otel.settings.clear_env_file_cache()清除缓存（settings.py）。此外，解析器会检查文件是否为当前用户拥有的常规文件，并在权限过宽（如 0666）时给出警告，避免凭据泄露风险。

八、自动插桩的边界与手动补充

自动插桩不会捕获以下内容：

• 自定义业务逻辑（custom business logic）
• 内部函数调用（internal function calls）

以如下工作流为例，自动插桩只会覆盖其中对 LLM 客户端的调用：

def my_custom_workflow(query: str) -> str: preprocessed = preprocess(query) # 不会被追踪 response = client.chat.completions.create(...) # 自动插桩（被追踪） postprocessed = postprocess(response) # 不会被追踪 return postprocessed

解决方案：叠加手动插桩，把整个工作流包装为 CHAIN Span：

@tracer.chain def my_custom_workflow(query: str) -> str: preprocessed = preprocess(query) response = client.chat.completions.create(...) postprocessed = postprocess(response) return postprocessed

手动插桩提供的 Span Kind 装饰器还包括@tracer.retriever、@tracer.tool、@tracer.agent、@tracer.llm、@tracer.embedding等，装饰器会自动捕获函数入参与返回值作为input.value/output.value（Phoenix 评估器依赖这两个属性），完整用法见手动插桩文档。推荐组合：自动插桩负责框架层全覆盖，手动插桩补全业务编排层，二者叠加即可得到完整的调用链。

九、验证与排错

验证步骤：

1. 启动 Phoenix（自托管默认可通过终端pxi或 Docker 方式启动，参考 docs/phoenix/get-started.mdx），打开 UIhttp://localhost:6006；
2. 进入my-app项目（register启动时打印的 "Phoenix Project" 即项目名）；
3. 运行你的应用；
4. 检查 Span 是否出现（使用BatchSpanProcessor时会有批量延迟）。

常见问题：

十、进一步阅读

• Python 追踪安装与配置（含 .env.phoenix 细节）
• 手动插桩（装饰器 / Context Manager / set_input / set_output）
• LLM Span 属性 Schema（messages、tokens、cost）
• 自动插桩原理源码：_auto_instrument_installed_openinference_libraries
• 环境变量与.env.phoenix解析实现
• Phoenix 快速上手（get-started）

• 可观测性
• AI 评测
• LLMOps
• AI 应用
• 人工智能