使用 Logfire 验证 LangChain 到 Pydantic AI 的迁移：观测驱动的等价性检验实践指南-平芜编程栈

使用 Logfire 验证 LangChain 到 Pydantic AI 的迁移：观测驱动的等价性检验实践指南

【免费下载链接】pydantic-aiHow Python does AI. Agents, realtime voice, image generation, embeddings. Every model, every interface, typed end to end.项目地址: https://gitcode.com/GitHub_Trending/py/pydantic-ai

在把 LangChain / LangGraph 应用迁移到 Pydantic AI 的过程中，仅仅"跑通了"并不意味着"行为等价"。本指南以仓库内migrating-langchain-to-pydantic-ai技能的观测验证参考文档 LOGFIRE-VERIFICATION.md 为主体，系统讲解如何用 Logfire 把迁移后的 Pydantic AI 应用"实际做了什么"暴露出来，作为诊断与佐证证据；读完你将掌握：如何与用户协商可观测性方案、如何刻意插桩、如何对比源与目标运行、如何在流式边界观测、如何保护敏感内容、如何在不导出的情况下测试，以及追踪数据"不能证明什么"。

定位声明：Logfire 的追踪数据是诊断和佐证证据，而非两个框架语义完全相同的证明。等价性最终必须由可执行的契约测试来确立，追踪数据负责解释轨迹、暴露差异。

为什么迁移验证需要观测手段

LangChain 与 Pydantic AI 的 API 形状相似，但底层语义不同：消息历史合并方式不同、重试与工具调用生命周期不同、结构化输出传输方式不同、流式终止语义不同（详见 CONCEPT-MAPPING.md 与 SEMANTIC-GAPS.md）。仅凭"happy path 跑通了""导入成功""类名相同""trace 形状相似"都无法构成等价性证据。

Logfire 的价值在于：它能展示一次真实运行中模型请求、工具调用、重试、错误、token 用量与耗时的完整轨迹，让迁移者看清"源系统走了哪条路、目标系统走了哪条路"。仓库主文档 docs/logfire.md 也强调：LLM 应用"慢、不可靠、昂贵且不确定"，需要新的工具来理解模型性能与应用行为——这正是迁移验证中观测手段的用武之地。

第一步：与用户协商观测方案

当源系统已经有可观测性时，在改动它之前先把决策摆到用户面前。推荐 Logfire 作为 Pydantic AI 的第一方观测体验，但推荐不等于获得替换既有系统的授权。三种可选方案及适用场景如下：

选择	适用时机	成本或遗留问题
保留现有系统	连续性优先，且迁移范围是窄的 agent 运行时	必须证明嵌套的 Pydantic AI 模型/工具生命周期仍然可见；外层框架 span 不足以证明这一点
临时并行接入 Logfire	脱敏影子对比或迁移调试需要双通道遥测	存在双份导出、隐私、采样、成本与 trace 关联问题；必须设置移除条件
切换到 Logfire	用户想要原生 Pydantic AI 插桩，并接受一次可观测性迁移	需要迁移或退役仪表盘、告警、评估、trace 摄取、保留/隐私控制、凭据与运维文档

向用户说明：你推荐哪个选项、为什么适合这个应用、运维人员将看到什么变化、以及哪些仍未被验证。如果可观测性本就不在迁移范围内，请保留现状并给出建议，而不是擅自扩大迁移面。这一原则与 SKILL.md 中"不静默替换 LangSmith/Langfuse 等既有观测系统"的约束一致：Logfire 是 Pydantic AI 的第一方集成，但替换整套观测体系（仪表盘、告警、评估、保留与导出管线）是一个独立的运维迁移，必须获得用户同意。

刻意插桩：在启动阶段一次性配置

基本配置

Logfire 应在应用启动时、构造或运行任何 agent 之前完成配置，且 Pydantic AI 插桩只安装一次：

import logfire logfire.configure() logfire.instrument_pydantic_ai( include_content=False, include_binary_content=False, )

logfire.configure()配置 SDK，默认从当前目录的.logfire目录读取写入 token（见 docs/logfire.md 的完整安装与认证流程：logfire auth、logfire projects new）。
logfire.instrument_pydantic_ai(...)一次性启用 Pydantic AI 插桩；默认插桩会暴露 agent 运行、模型请求、工具调用、重试、错误、token 用量与耗时。

命名与作用域

为可复用的 agent 命名，使其运行可区分。命名会让 agent 的 run span 在 Logfire 中带上可读标签；当多个 agent 运行于同一应用时，这直接决定 trace 的可分辨性。
当应用有更窄的 trace 或隐私边界时，只插桩特定 agent，而不是全部 agent。
在传入插桩设置前，先检查已安装的logfire与pydantic_ai版本：遥测数据格式版本与 Pydantic AI 包版本是独立演进的，不同版本的事件角色与属性可能不同。仓库中InstrumentationSettings.version默认值为 5（见 instrumented.py），版本 2/3/4 是已弃用的兼容格式，版本 6 是 opt-in 的新消息角色格式；插桩版本与 logfire 包的兼容性需要以实际安装版本为准。

补充应用边界 span

在 Pydantic AI 不拥有的边界上补充小 span，例如检索、持久化、队列、审批记录、公共流式输出与外部写入。复用应用的请求、线程、租户与幂等关联标识作为安全属性——不要把密钥放进属性。

清点源系统的回调与指标

在替换前，清点源模型/工具回调生命周期与应用指标。需要注意：在 LangGraph 外层节点上保留 LangSmith、Langfuse 或其他回调，并不会自动插桩嵌套的 Pydantic AI 调用。要么通过测试过的适配器保留既有模型/工具的观测，要么明确做出可观测性变更；无论哪种方式，都要验证成功、token、完成与错误路径，以及父级关联。

不要每 token 一个 span

优先使用有界的一组 span 与指标：首个事件、终止事件、事件计数、队列延迟、取消与失败。从源码看，record_metrics 只记录三个直方图（token 用量、成本、首块耗时），span 结构也是每个模型请求/工具调用一层，而非按 token 展开。

对比源与目标运行

在影子（shadow）或回放（replay）对比时，按以下步骤执行：

同一输入、同一边界：将相同的脱敏输入、依赖、模型设置与确定性 fixture，通过相同的应用边界分别喂给源与目标。
同一 OTel 后端：尽可能将两条 trace 发送到同一 OpenTelemetry 后端。LangChain 与 LangGraph 可将 LangSmith 的 OTel trace 导出到 Logfire，只需在导入这些框架前设置LANGSMITH_OTEL_ENABLED=true与LANGSMITH_TRACING=true；只有当你有意只走 OTel 通道、不再保留 LangSmith 导出时，才设置LANGSMITH_OTEL_ONLY=true。保持源与目标的 trace 命名空间彼此独立。
规范化为事实再比较：不要直接 diff 原始 span。比较模型请求数、工具调用及其因果关系、安全参数与结果、重试、错误、用量、延迟、允许情况下的模型可见消息，以及应用边界事件。当工具顺序是契约时，使用应用序列 ID 或可执行断言，而非原始 span 到达顺序。
调查每个无法解释的差异：看起来相似的 trace 不是等价性证据。
把已验证的声明链接到确立它的可执行测试，并用 trace 解释其轨迹。

注意：不要对带副作用的 agent 做双跑，除非工具处于 dry-run、沙箱化或被持久化幂等键保护。观察到一次写入并不能证明"恰好一次"语义。

在双边界观测流式

流式延迟必须分开测量：

插桩的模型调用边界：Pydantic AI 可记录从发出流式请求到包装响应浮现第一个块的时间。这包含传输与客户端 SDK 行为，不是provider 内部耗时。从源码看，InstrumentedModel.request_stream 在包装模型打开流之前用time.perf_counter()打点，流关闭时通过response_stream.time_to_first_chunk(request_start)计算 TTFT；该值同时写入 span 属性gen_ai.client.operation.time_to_first_chunk并记录到直方图（见 _instrumentation.py 与 docs/logfire.md 中的指标表）。
应用边界：测量 API、SSE 或 WebSocket 消费者收到第一个公共事件与终止事件的时间。

模型首块时间不能证明客户端首事件时间——服务可能在模型开始流式输出后仍缓冲整个 agent 运行。必须用真实客户端测试公共流式契约：

精确的事件 schema 与顺序；
增量交付而非运行后缓冲；
源暴露的工具、重试、部分输出、最终结果与终止错误事件；
关联标识与用量放置；
断连与取消传播；
背压与有界缓冲；
承诺时的重连/恢复行为；
消费者提前退出后的清理与迟到的生产者错误。

根据契约选择流式 API

Pydantic AI 的流式 API 语义不同，必须按所需生命周期选择（见 abstract.py 中的run_stream、run_stream_events、iter与event_stream_handler定义）：

run_stream()可能在第一个匹配的最终输出处停止——流式过程中共同发出的工具与重试可能产生与完整run()不同的终止结果；
当契约要求完整的工具执行或更底层的事件控制时，使用run(event_stream_handler=...)、run_stream_events()或iter()；
处理原始事件时，既要组装初始 part 事件，也要组装后续增量。

Logfire trace 可以揭示最终的运行轨迹，但只有真实客户端测试能证明交付行为。

保护敏感内容

Pydantic AI 插桩默认包含提示词、补全、工具参数与工具结果，这些数据可能包含个人、专有、凭据或租户信息。

优先使用InstrumentationSettings(include_content=False)：当原始内容不必要或不安全时，结构化遥测仍然有用。从源码看，include_content=False会排除提示词、补全、工具调用参数与响应，以及任何其他消息内容（见 docs/logfire.md 的"Excluding prompts and completions"一节）。
不要假设通用 scrub 能保证 LLM 内容安全：Logfire 有意不对自由格式的 LLM 消息属性应用通用正则 scrubbing，因为那既嘈杂又不完整。应在启用内容捕获前定义组织特定的控制与保留规则。
避免默认开启完整 HTTPX header/body 捕获：那只是临时诊断升级，可能暴露 provider 授权信息与原始载荷。logfire.instrument_httpx(capture_all=True)会同时捕获请求与响应的 header 和 body（见 docs/logfire.md）；此外 Bedrock 等非 HTTPX 传输（使用 boto3）需要单独处理。
对影子输入与对比属性消毒：保持认证身份与密钥远离模型可见内容与 trace 属性。

最后，明确陈述隐私选择及其后果：内容被禁用时，trace 无法佐证提示词、参数或输出的等价性——这类声明必须留给契约测试。

不导出遥测的测试

使用 Logfire 的内存测试导出器或 Pytestcapfirefixture 来断言一小撮稳定的 span 与属性，不把遥测发送到远程项目。仓库测试 tests/test_logfire.py 就是这一实践的完整范例：

通过logfire.testing.CaptureLogfire获取capfirefixture，用capfire.exporter.exported_spans_as_dict()读取导出的 span，并组装成 trace 树（LogfireSummary）；
断言重要的应用 span 与 agent 运行关联，且失败/取消可观测；
测试对插桩版本（True/False/v2/v3）参数化，验证不同配置下的 span 结构。

要点：

避免把完整原始 trace 快照作为唯一断言：遥测 schema 会变化，原始 trace 包含偶然性数据。
对短生命周期命令、worker 或测试，在关闭时 flush 遥测，而非每次请求 flush。
采样可能丢 span：SDK 尾采样是进程本地的，可能割裂分布式 trace；当整个分布式 trace 必须共享同一决策时，使用 collector 侧尾采样。绝不要把被采样的生产 trace 当作穷尽的等价性证据。
插桩测试路径上参与的每个服务，并验证 trace 上下文在 HTTP、队列、worker 与分离任务之间的传播。应用创建的 background task 可能比它的请求 span 活得更久或丢失父级；保留安全的业务关联 ID，且不要把断裂的 trace 树当作"工作未发生"的证明。同理，取消可能留下不完整的遥测，因此资源与副作用断言仍然是权威的。

知道 trace 不能证明什么

Logfire 能帮助证明：一次被执行的运行使用了预期的模型、工具、重试路径、观察到的 token 用量与耗时。它本身无法证明：

来自非确定性模型的确定性输出等价性；
公共流式交付、背压、重连或取消；
checkpoint、fork、回放或进程重启语义；
授权或租户隔离；
恰好一次的外部副作用；
未被插桩或被采样移除的行为。

对这些声明，应使用：确定性表征测试、provider 集成测试、真实客户端、持久化/重启探针、数据库与副作用断言，以及安全测试（完整的验证方法体系见 VERIFICATION-AND-CUTOVER.md，其中包含测试金字塔、运维语义验证与安全的切换清单）。把缺失的遥测报告为"证据缺失"，而不是"测试通过"。

落地建议：把观测纳入迁移工作流

先确定可观测性归属：保留、临时并行还是切换，与用户达成一致后再动插桩代码。
启动时一次配置：logfire.configure()+logfire.instrument_pydantic_ai()，为 agent 命名，必要时仅插桩特定 agent，并显式做出内容捕获的隐私决策。
影子对比时规范化：设置LANGSMITH_OTEL_ENABLED=true与LANGSMITH_TRACING=true让源 trace 进入同一后端，比较事实而非原始 span。
流式契约用真实客户端验证：模型 TTFT 与应用首事件延迟分开测，用run(event_stream_handler=...)/run_stream_events()/iter()满足完整事件契约。
生产前用 capfire 做无导出测试，断言稳定 span 子集；采样后的生产 trace 只作参考。
最终以契约测试为准：trace 负责解释轨迹、暴露差异、佐证运行路径；等价性的裁决权始终在可执行的测试与边界断言手中（对照 VERIFICATION-AND-CUTOVER.md 的完成清单逐项核对，包括"Logfire 隐私设置经过深思熟虑、trace 能关联应用/agent/模型/工具/子 agent 边界、且不被当作唯一的等价性证明"）。