PydanticAI项目中的Logfire监控与调试指南

PydanticAI项目中的Logfire监控与调试指南

pydantic-ai Agent Framework / shim to use Pydantic with LLMs 项目地址: https://gitcode.com/gh_mirrors/py/pydantic-ai

引言：LLM应用开发的挑战

在现代应用开发中，集成大型语言模型(LLM)已成为趋势，但开发者面临着几个关键挑战：

1. 性能问题：LLM响应速度慢
2. 可靠性问题：模型输出不稳定
3. 成本问题：API调用费用高昂
4. 调试困难：缺乏类似传统数据库的EXPLAIN工具

PydanticAI项目为解决这些问题提供了Logfire监控工具，本文将详细介绍其使用方法。

Logfire核心功能概述

Logfire是Pydantic团队开发的观测平台，基于OpenTelemetry构建，具有以下特点：

• 全栈监控：覆盖Gen AI、传统预测AI、HTTP流量、数据库查询等
• 商业支持：提供托管服务，含永久免费层
• 低侵入性：安装简单，不使用时几乎无开销

快速入门指南

安装与配置

1. 安装依赖包：

pip install "pydantic-ai[logfire]"

2. 认证本地环境：

python -m logfire auth

3. 创建新项目或使用现有项目：

python -m logfire projects new

基础使用示例

import logfire
from pydantic_ai import Agent

# 初始化配置
logfire.configure()
logfire.instrument_pydantic_ai()

# 创建并运行Agent
agent = Agent('openai:gpt-4o', instructions='简洁回答')
result = agent.run_sync('"hello world"的起源是什么？')
print(result.output)

执行后可在Logfire面板查看详细的调用追踪信息。

高级监控功能

HTTP请求监控

要查看原始API请求/响应（包括prompt和完整响应）：

logfire.instrument_httpx(capture_all=True)

性能监控

Logfire提供SQL查询界面，可分析：

• 调用延迟分布
• 错误率统计
• 成本消耗趋势

调试可视化

对于复杂的工作流（如聊天应用），Logfire提供：

• 调用链路可视化
• 各步骤耗时分析
• 中间状态检查

OpenTelemetry集成

Logfire基于OpenTelemetry标准，支持多种后端：

使用替代OTel后端示例

import os
os.environ['OTEL_EXPORTER_OTLP_ENDPOINT'] = 'http://localhost:4318'
logfire.configure(send_to_logfire=False)

纯OpenTelemetry方案

无需Logfire SDK，直接使用OTel：

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

provider = TracerProvider()
processor = BatchSpanProcessor(OTLPSpanExporter())
provider.add_span_processor(processor)

from pydantic_ai.agent import Agent
Agent.instrument_all()

高级配置选项

数据格式控制

# 将消息作为独立日志事件而非span属性
logfire.instrument_pydantic_ai(event_mode='logs')

自定义Provider

from opentelemetry.sdk._events import EventLoggerProvider
from opentelemetry.sdk.trace import TracerProvider

settings = InstrumentationSettings(
    tracer_provider=TracerProvider(),
    event_logger_provider=EventLoggerProvider()
)
Agent.instrument_all(settings)

二进制内容排除

settings = InstrumentationSettings(include_binary_content=False)
Agent('gpt-4o', instrument=settings)

最佳实践建议

1. 生产环境：启用HTTP监控以记录完整请求
2. 调试阶段：使用event_mode='logs'获取更详细的消息记录
3. 性能敏感场景：考虑排除二进制内容减少开销
4. 长期运行服务：定期检查性能指标和错误率

通过合理配置Logfire，开发者可以显著提升LLM应用的可靠性和可维护性，有效控制成本并快速定位问题。

pydantic-ai Agent Framework / shim to use Pydantic with LLMs 项目地址: https://gitcode.com/gh_mirrors/py/pydantic-ai