调试和监控
使用 LLM 的应用程序面临一些众所周知的挑战：LLM **速度慢**、**不可靠** 且 **昂贵**。
这些应用程序还面临一些大多数开发人员不太常遇到的挑战：LLM **不稳定** 且 **不确定**。提示中的细微变化可能会完全改变模型的性能，而且没有可以运行的 EXPLAIN 查询来了解原因。
警告
从软件工程师的角度来看，你可以将 LLM 视为你听过的最糟糕的数据库，而且更糟糕。
如果 LLM 不是那么有用，我们永远不会碰它们。
为了使用 LLM 构建成功的应用程序，我们需要新的工具来了解模型性能以及依赖于它们的应用程序的行为。
仅仅让你了解你的模型表现如何的 LLM 可观察性工具是无用的：向 LLM 发出 API 调用很容易，但将其构建到应用程序中却很难。
Pydantic Logfire
Pydantic Logfire 是一个由创建和维护 Pydantic 和 PydanticAI 的团队开发的可观察性平台。Logfire 旨在让您了解您的整个应用程序：Gen AI、经典预测 AI、HTTP 流量、数据库查询以及现代应用程序所需的一切。
Pydantic Logfire 是一款商业产品
Logfire 是一个商业支持的托管平台，具有非常慷慨且永久的 免费层级。您可以在几分钟内注册并开始使用 Logfire。
PydanticAI 内置（但可选）支持 Logfire。这意味着如果安装并配置了 logfire 包，并且启用了代理检测，则有关代理运行的详细信息将发送到 Logfire。否则，实际上没有开销，也不会发送任何内容。
这是一个示例，显示在 Logfire 中运行 天气代理 的详细信息
使用 Logfire
要使用 logfire，您需要一个 logfire 帐户，并安装 logfire
pip install "pydantic-ai[logfire]"
uv add "pydantic-ai[logfire]"
然后使用 logfire 验证您的本地环境
logfire auth
uv run logfire auth
并配置一个项目以将数据发送到
logfire projects new
uv run logfire projects new
（或使用 logfire projects use 使用现有项目）
然后将 logfire 添加到您的代码中
import logfire
logfire.configure()
并在您的代理中启用检测
from pydantic_ai import Agent
agent = Agent('openai:gpt-4o', instrument=True)
# or instrument all agents to avoid needing to add `instrument=True` to each agent:
Agent.instrument_all()
logfire 文档 提供了有关如何使用 logfire 的更多详细信息，包括如何检测其他库，如 Pydantic、HTTPX 和 FastAPI。
由于 Logfire 构建于 OpenTelemetry 之上，因此您可以使用 Logfire Python SDK 将数据发送到任何 OpenTelemetry 收集器。
设置好 logfire 后，它可以通过两种主要方式帮助您了解您的应用程序
- 调试 — 使用实时视图查看您的应用程序中实时发生的情况。
- 监控 — 使用 SQL 和仪表板来观察应用程序的行为，Logfire 实际上是一个 SQL 数据库，用于存储有关应用程序运行方式的信息。
调试
为了演示 Logfire 如何让您可视化 PydanticAI 运行的流程，这是在运行 聊天应用示例 时从 Logfire 获取的视图
监控性能
我们还可以使用 Logfire 中的 SQL 查询数据来监控应用程序的性能。这是一个使用 Logfire 监控 Logfire 内部 PydanticAI 运行的真实示例
监控 HTTPX 请求
为了监控模型发出的 HTTPX 请求，您可以使用 logfire 的 HTTPX 集成。
检测非常简单，只需将以下三行添加到您的应用程序中
import logfire
logfire.configure()
logfire.instrument_httpx(capture_all=True) # (1)!
- 有关更多
httpx检测详细信息，请参阅 logfire 文档。
特别是，这可以帮助您跟踪特定的请求、响应和标头
import logfire
from pydantic_ai import Agent
logfire.configure()
logfire.instrument_httpx(capture_all=True) # (1)!
agent = Agent('openai:gpt-4o', instrument=True)
result = agent.run_sync('What is the capital of France?')
print(result.data)
# > The capital of France is Paris.
- 捕获所有标头、请求正文和响应正文。
提示
如果您在模型中使用自定义 httpx 客户端以深入了解您的自定义请求，则 httpx 检测可能特别有用。
使用 OpenTelemetry
PydanticAI 的检测使用 OpenTelemetry，Logfire 基于此构建。您可以完全免费地使用 Logfire SDK，并按照 备用后端 指南将数据发送到任何 OpenTelemetry 收集器，例如自托管的 Jaeger 实例。或者您可以完全跳过 Logfire 并直接使用 OpenTelemetry Python SDK。
数据格式
PydanticAI 遵循 OpenTelemetry 生成式 AI 系统语义约定，但有一个注意事项。语义约定指定消息应作为请求 span 的子项的单独事件（日志）捕获。默认情况下，PydanticAI 而是将这些事件收集到 JSON 数组中，该数组设置为请求 span 上的名为 events 的单个大型属性。要更改此设置，请使用 InstrumentationSettings(event_mode='logs')。
from pydantic_ai import Agent
from pydantic_ai.agent import InstrumentationSettings
instrumentation_settings = InstrumentationSettings(event_mode='logs')
agent = Agent('openai:gpt-4o', instrument=instrumentation_settings)
# or instrument all agents:
Agent.instrument_all(instrumentation_settings)
目前，这在 Logfire UI 中看起来不会那么好，但我们正在努力改进。
如果您有非常长的对话，则 events span 属性可能会被截断。使用 event_mode='logs' 将有助于避免此问题。
请注意，OpenTelemetry 语义约定仍处于实验阶段，并且可能会发生变化。
设置 OpenTelemetry SDK 提供程序
默认情况下，使用全局 TracerProvider 和 EventLoggerProvider。这些由 logfire.configure() 自动设置。它们也可以由 OpenTelemetry Python SDK 中的 set_tracer_provider 和 set_event_logger_provider 函数设置。您可以使用 InstrumentationSettings 设置自定义提供程序。
from opentelemetry.sdk._events import EventLoggerProvider
from opentelemetry.sdk.trace import TracerProvider
from pydantic_ai.agent import InstrumentationSettings
instrumentation_settings = InstrumentationSettings(
tracer_provider=TracerProvider(),
event_logger_provider=EventLoggerProvider(),
)
检测特定 Model
from pydantic_ai import Agent
from pydantic_ai.models.instrumented import InstrumentationSettings, InstrumentedModel
settings = InstrumentationSettings()
model = InstrumentedModel('gpt-4o', settings)
agent = Agent(model)