Phoenix 自动插桩（Auto-Instrumentation）Python 实战指南：零代码改动为 LLM 应用生成追踪 Span

可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载导读本文以 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(groupopeninference_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_providertracer_provider)这段代码解释了自动发现的本质只要你通过pip install openinference-instrumentation-{name}安装了对应的插桩包Phoenix 就能在register(auto_instrumentTrue)时自动发现并启用它无需在代码里显式 import 任何 instrumentor。二、支持的框架一览Python 生态下Phoenix 自动插桩覆盖两类目标类别支持范围安装方式LLM SDKOpenAI、Anthropic、Bedrock、Mistral、Vertex AI、Groq、Ollamapip install openinference-instrumentation-{name}框架LangChain、LlamaIndex、DSPy、CrewAI、Instructor、Haystackpip install openinference-instrumentation-{name}命名规律统一包名均为openinference-instrumentation-名称例如 OpenAI 对应openinference-instrumentation-openai、LangChain 对应openinference-instrumentation-langchain、LlamaIndex 对应openinference-instrumentation-llama-index参考 setup-python.md 中的安装清单。每个插桩器生成不同 Span KindLLM、CHAIN、RETRIEVER、TOOL 等的完整属性结构可查阅 references 目录下的span-*.md文件。三、快速开始两条命令 一行注册第一步安装核心包与目标插桩器pip install arize-phoenix-otel pip install openinference-instrumentation-openai # 按需添加其他插桩器第二步注册并自动插桩from phoenix.otel import register register(project_namemy-app, auto_instrumentTrue) # 自动发现并启用所有已安装的插桩器第三步正常使用客户端即可无需任何埋点from phoenix.otel import register from openai import OpenAI register(project_namemy-app, auto_instrumentTrue) client OpenAI() response client.chat.completions.create( modelgpt-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关键参数如下参数类型默认值说明endpointstr环境变量推断Collector 端点未传时读取PHOENIX_COLLECTOR_ENDPOINT再回退到OTEL_EXPORTER_OTLP_ENDPOINT最终默认为http://localhost:6006project_namestr环境变量推断Span 归属的项目名未传时读取PHOENIX_PROJECT别名PHOENIX_PROJECT_NAME最后回退到defaultbatchboolFalse源码签名为True时使用BatchSpanProcessor为False时使用SimpleSpanProcessor生产环境建议显式传batchTrue并在启动时打印的配置详情中确认 Span Processor 类型set_global_tracer_providerboolTrue是否将该 TracerProvider 设为 OpenTelemetry 全局默认设为False可避免影响应用内已有的全局配置headersdict环境变量推断发送给 Collector 的请求头未传时读取PHOENIX_CLIENT_HEADERS或OTEL_EXPORTER_OTLP_HEADERSprotocolhttp/protobuf|grpc自动推断传输协议会根据 endpoint 的 URL 形态自动判断也可显式指定verboseboolTrue是否向 stdout 打印追踪配置详情auto_instrumentboolFalse为True时自动插桩所有已安装的 OpenInference 库api_keystr环境变量推断Phoenix Cloud 认证用未传时读取PHOENIX_API_KEY内部会拼装为authorization: Bearer api_key请求头从源码看两个容易被忽略的细节项目名始终写入资源register会强制把project_name合并进Resource的project.name属性见 otel.py。即使调用方传入自定义resourceproject.name也会被合并进去不会覆盖用户的其它资源属性。协议推断逻辑endpoint 路径以/v1/traces结尾时走 HTTPprotobuf无路径且端口等于PHOENIX_GRPC_PORT默认 4317时走 gRPC见_maybe_http_endpoint/_maybe_grpc_endpoint。HTTP 模式下register会自动补全/v1/traces后缀并保留已有路径前缀因此部署在反向代理子路径下的 Phoenix 也能正常工作——例如endpointhttp://host/prefix会实际发送到http://host/prefix/v1/traces。生产推荐配置示例完整示例见 otel.py 的 docstringfrom phoenix.otel import register tracer_provider register( project_namemy-app, batchTrue, # 批量上报生产推荐 auto_instrumentTrue, # 自动插桩 api_keyyour-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改为手动实例化指定 instrumentorfrom phoenix.otel import register from openinference.instrumentation.openai import OpenAIInstrumentor tracer_provider register(project_namemy-app) # 不传 auto_instrument OpenAIInstrumentor().instrument(tracer_providertracer_provider)两种方式的取舍auto_instrumentTrue适合装了就用的快速上手新装的插桩包在下一次启动时自动生效显式instrument()适合对依赖集合有严格管控的生产环境插桩对象一目了然也便于按需传参。六、OTel GenAI 原生插桩不装 OpenInference 插桩器也能追踪Phoenix 对 OpenTelemetry GenAI 语义约定gen_ai.*属性提供了原生兼容层当 Phoenix 通过 OTLP 接收到 Span 时会自动把gen_ai.*属性转换为 OpenInference 语义。这意味着任何能产出gen_ai.*属性的OTel 原生 AI 插桩库都可以直接使用无需安装 OpenInference instrumentorPhoenix 即可正确展示 LLM Span Kind、模型名、Token 计数与消息内容。转换规则要点优先级如果 Span 上已带有 OpenInference 属性例如来自双写插桩器这些已有值优先于转换生成的值消息部分的结构化转换消息内容按结构转换而非字符串拼接。gen_ai消息中的文本text、图片image、Blob、推理reasoning等部分各自成为llm.{input,output}_messages.{i}.message.contents.{j}下的一个条目并以message_content.typetext、image、reasoning等标记类型——因此模型的推理内容会以reasoning部分独立保留而不会被折叠进回答文本。完整的 content part 结构见 span-llm.md#messages。使用方式客户端无需任何改动照常向 Phoenix 发送 OTLP 即可from phoenix.otel import register # 适用于任何产出 gen_ai.* 属性的 OTel 原生 AI 插桩器 register(project_namemy-app)以 Anthropic 为例使用 OTel GenAI 官方插桩包来自opentelemetry-python-genai项目pip install opentelemetry-instrumentation-anthropicfrom phoenix.otel import register from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor import anthropic register(project_namemy-app) # 插桩 Anthropic AnthropicInstrumentor().instrument() # 正常使用 Anthropic 客户端Span 自动创建 client anthropic.Anthropic() response client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens1024, messages[ {role: user, content: Hello, Claude!} ] )目前opentelemetry-python-genai提供的插桩包包括opentelemetry-instrumentation-anthropic与opentelemetry-instrumentation-openai等。选择哪条技术路线取决于你更愿意依赖 OpenInference 生态属性更完整、覆盖框架更广还是 OTel 官方生态gen_ai.*原生标准。七、环境变量与配置优先级自动插桩的运行时配置既可以走代码参数也可以走环境变量详见 settings.py环境变量作用备注PHOENIX_COLLECTOR_ENDPOINTCollector 端点优先于OTEL_EXPORTER_OTLP_ENDPOINTPHOENIX_PROJECT项目名规范变量优先于别名PHOENIX_PROJECT_NAME两者同时设置且不同值时以PHOENIX_PROJECT为准并打印一次性告警PHOENIX_API_KEYPhoenix Cloud API Key自动转为authorization: Bearer key头PHOENIX_CLIENT_HEADERS自定义客户端请求头W3C Baggage 格式需 URL 编码PHOENIX_GRPC_PORTgRPC 端口默认 4317PHOENIX_DISCOVER_CONFIG置为false/0/no/off时禁用.env.phoenix发现仅读取进程环境.env.phoenix凭据文件发现settings.py当某个配置既未以参数传入、也未在进程环境中设置时register()会从当前工作目录向上逐级查找最近的.env.phoenix文件dotenv 格式仅读取PHOENIX_前缀键# .env.phoenix PHOENIX_COLLECTOR_ENDPOINThttp://localhost:6006 PHOENIX_API_KEYyour-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 Spantracer.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.valuePhoenix 评估器依赖这两个属性完整用法见手动插桩文档。推荐组合自动插桩负责框架层全覆盖手动插桩补全业务编排层二者叠加即可得到完整的调用链。九、验证与排错验证步骤启动 Phoenix自托管默认可通过终端pxi或 Docker 方式启动参考 docs/phoenix/get-started.mdx打开 UIhttp://localhost:6006进入my-app项目register启动时打印的 Phoenix Project 即项目名运行你的应用检查 Span 是否出现使用BatchSpanProcessor时会有批量延迟。常见问题现象排查方向完全没有 Span核对PHOENIX_COLLECTOR_ENDPOINT是否指向正确的 Phoenix 服务Cloud 场景确认已设PHOENIX_API_KEY确认已安装对应插桩包register在未发现任何 instrumentor 时会打印 warning属性缺失对照 Span Kind 文件检查所需属性名如 span-llm.md模型名、Token、Cost、消息结构与 span-chain.md插桩未生效确认register(auto_instrumentTrue)在创建 SDK 客户端之前执行选择性插桩模式下确认instrument(tracer_provider...)传入了同一个 provider十、进一步阅读Python 追踪安装与配置含 .env.phoenix 细节手动插桩装饰器 / Context Manager / set_input / set_outputLLM Span 属性 Schemamessages、tokens、cost自动插桩原理源码_auto_instrument_installed_openinference_libraries环境变量与.env.phoenix解析实现Phoenix 快速上手get-started赞分享可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载相关推荐Cursor试用限制破解终极指南机器码重置工具一招刷新设备指纹Cursor试用限制破解终极指南机器码重置工具一招刷新设备指纹 Cursor试用限制这道坎几乎每个重度用户都踩过正写着代码屏幕突然弹出一句 Too ma可观测性AI 评测LLMOpsAI 应用人工智能Opik Python SDK Span 对象详解从手动插桩到分布式追踪的完整实践指南Opik Python SDK Span 对象详解从手动插桩到分布式追踪的完整实践指南 导读 opik.Span 是 Opik Python SDK 中描述人工智能LLMOps模型评测可观测性AI AgentAI 应用后端前端Phoenix AGENT Span 完整指南OpenInference 自主推理追踪语义与实战Phoenix AGENT Span 完整指南OpenInference 自主推理追踪语义与实战 AGENT span 是 OpenInference 语义约可观测性AI 评测LLMOpsAI 应用人工智能上一篇FunASR多语言支持中英文混合识别的最佳实践下一篇Awesome Design Patterns 容器健康管理自愈与重启策略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考