Phoenix项目中的链路追踪(FAQ)技术指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00743/article/details/148490524

Phoenix项目中的链路追踪(FAQ)技术指南

phoenix AI Observability & Evaluation 项目地址: https://gitcode.com/gh_mirrors/phoenix13/phoenix

前言

在当今复杂的AI应用开发中，链路追踪(Tracing)已成为不可或缺的调试和监控工具。Phoenix项目提供了一套完善的链路追踪解决方案，特别针对LangChain等AI框架进行了深度优化。本文将全面解析Phoenix项目中链路追踪的常见问题和使用技巧。

基础配置篇

本地环境配置

当在本地开发环境中使用Phoenix时，配置过程极为简单：

import phoenix as px
from phoenix.trace import LangChainInstrumentor

# 启动Phoenix可视化界面
px.launch_app()

# 启用LangChain自动追踪
LangChainInstrumentor().instrument()

# 在此之后运行的LangChain应用将自动生成追踪数据

这种配置方式默认使用6006端口，无需任何额外设置即可开始收集追踪数据。

远程服务器配置

在生产环境或远程服务器上部署时，需要通过环境变量指定Phoenix服务的地址：

import os
from phoenix.trace import LangChainInstrumentor

# 设置Phoenix服务地址和端口
os.environ["PHOENIX_HOST"] = "your-server-ip"
os.environ["PHOENIX_PORT"] = "6007"  # 根据实际端口修改

# 或者使用单端点配置方式
os.environ["PHOENIX_COLLECTOR_ENDPOINT"] = "your-server-ip:6007"

# 启用追踪
LangChainInstrumentor().instrument()

高级控制篇

临时暂停追踪

在某些场景下，我们可能需要暂时关闭追踪功能，例如：

文档分块处理过程
性能敏感代码段
批量测试运行

Phoenix提供了优雅的上下文管理器来实现这一需求：

from phoenix.trace import suppress_tracing

# 常规代码，会生成追踪数据
do_something()

with suppress_tracing():
    # 此代码块内的操作不会生成追踪数据
    process_documents()
    
# 离开代码块后，追踪功能自动恢复
continue_tracing()

永久禁用追踪

如果需要完全关闭特定组件的追踪功能，可以调用uninstrument方法：

# 关闭LangChain追踪
LangChainInstrumentor().uninstrument()

# 关闭LlamaIndex追踪
LlamaIndexInstrumentor().uninstrument()

# 关闭OpenAI追踪
OpenAIInstrumentor().uninstrument()

特殊场景处理

OpenAI流式响应中的令牌计数

在使用OpenAI的流式API时，默认不会返回令牌使用情况。通过以下配置可以获取详细的令牌统计：

response = openai.OpenAI().chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "写一首关于AI的诗"}],
    max_tokens=50,
    stream=True,
    stream_options={"include_usage": True},  # 关键配置项
)

注意：此功能需要openai库版本1.26或更高。

自定义LangChain组件的追踪

当开发自定义LangChain组件时，需要确保正确继承基类才能使追踪生效。以下是一个自定义检索器的示例：

from langchain_core.retrievers import BaseRetriever, Document

class CustomRetriever(BaseRetriever):
    """自定义检索器实现"""
    
    k: int = 3  # 返回结果数量
    
    def _get_relevant_documents(self, query: str, **kwargs) -> List[Document]:
        # 实现自定义检索逻辑
        return [Document(page_content=f"结果{i}") for i in range(self.k)]

关键点：