migrate-to-langfuse

迁移到 Langfuse

你正在进行一次性的平台切换，迁移到 Langfuse。先访谈，再规划，只有确认后才能执行。切勿凭记忆实施——执行时请获取下方列出的最新 Langfuse 文档。

1. 访谈（始终先进行，之后才能编写任何代码）

只询问无法检测到的信息。先检查代码仓库：依赖项和导入通常可以揭示来源平台（langsmith、arize、phoenix、braintrust、openinference、旧版 langfuse 固定版本）。

1. 来源——使用的是哪个平台和版本？是云端还是自托管？有哪些访问权限：API 密钥、数据库连接，还是只有应用代码仓库？
2. 目标——使用哪个区域的 Langfuse Cloud，还是自托管？只通过是否存在来验证凭据（例如 [ -n "$LANGFUSE_SECRET_KEY" ]）；切勿在聊天中索要密钥，也绝不能以任何方式访问 .env 内容或密钥值——不要运行会回显这些值的 shell 命令，不要使用文件工具读取 .env，也不要搜索这些值。只检测设置了哪些变量名，不做其他操作。
3. 范围——包括以下哪些内容：实时追踪切换、历史追踪（包括其评分、评分配置和自定义模型定义）、数据集、提示词、评估器/LLM 裁判、实验代码。对于历史数据：迁移全部数据，还是从某个截止日期开始？询问来源账户中还存在什么其他内容（仪表板、警报、标注队列、已保存视图等）。代码仓库无法揭示服务端资产。上述支持列表之外的内容不在此技能的覆盖范围内：请在范围表中注明，以便用户计划手动重建，而不是在切换后才发现遗漏。
4. 模式——仅规划（编写运行手册），还是执行？

如果请求与代码仓库不符（请求中提到的平台代理并未出现，或要求升级未安装的 SDK），请停止并先与用户协调——切勿将请求擅自解释为另一种迁移，然后开始执行。

请展示最终计划（范围表和操作顺序），并在修改任何文件前取得用户确认。无论请求听起来多么迫切，都不能视为已授权在计划确认前移除或替换现有平台的检测代码。

2. 应用的默认规则

• 先切换实时追踪。 历史数据迁移是可选的，并会在 Langfuse 中按新数据摄入计费——迁移历史数据前请说明这一点。如果来源平台已经发出 OTel/OpenInference spans，应在现有检测代码上添加 Langfuse，作为第二个导出器，而不是重新埋点；只有在下方的并行运行窗口结束后，才移除旧目标。
• 复制数据集和提示词。重建评估器和裁判。 重写实验代码，并针对迁移后的数据集重新运行；切勿导入旧实验的评分。
• 先用样本测试，再进行完整迁移。 先迁移约 10 条追踪，关联目标追踪，然后等待用户确认数据看起来正确，再迁移全部数据。
• 展示进度（页数/数量），方便用户了解长时间运行任务的进展，并确保可以断点续跑：在状态文件中跟踪已发送的来源 ID 并跳过它们；重新发送相同 ID 会创建重复的观测记录（参见 references/reingest-history.md）。
• 并行运行窗口。 保留旧导出器，直到用户确认目标数据无误；之后再通过一个单独且明确的步骤将其移除。这不仅约束计划，也约束实施：完成修改后，旧平台的导出器/检测代码必须仍然存在且处于启用状态。展示差异前，请重新检查没有删除或重定向任何平台导入、注册调用、导出器端点或导出器环境变量。并行导出应实现为一个检测流程使用两个导出器（同一 tracer provider 上的两个 span processor）——绝不能对应用进行两次检测。目标端出现重复生成和重复计算费用，说明存在第二条采集路径。

3. 按场景处理

获取并遵循以下内容；不要复述其内容：

场景	权威来源
已发布迁移指南的供应商（LangSmith、Arize AX、Phoenix、Braintrust、Helicone、Promptfoo 等）	https://langfuse.com/resources/engineering/migrate-from-<vendor>.md — 查看 https://langfuse.com/llms.txt 以获取当前列表
未发布迁移指南的供应商，或任何供应商的历史数据	references/reingest-history.md，以及供应商自己的导出 API 文档

绝不能凭经验重新导入历史追踪数据：在编写或运行任何重新导入代码之前，必须完整阅读 references/reingest-history.md，即使已有供应商指南也是如此。供应商指南涵盖数据提取；该参考文档规定重新导入的要求——确定性 ID、原始 OTLP 负载、原始时间戳、切换时间边界，以及导入历史数据会按新数据摄取计费的警告。

如果发现来源是另一个 Langfuse 部署（旧版本、不同项目、区域或主机），请停止——这不属于供应商切换。请引导用户查看主 langfuse 技能（其中的 SDK 升级和 v4 迁移参考），以及项目间迁移指南。

对于实时埋点切换，请使用 https://langfuse.com/llms.txt 中与用户框架或 SDK 匹配的集成指南。如果要在 Langfuse 端进行深入操作（创建提示词、使用数据集 API、编写实验代码），且已安装主 langfuse 技能，则交由该技能处理。

4. 验证并收尾

• 在完整运行之前，先由用户在目标端 UI 中确认抽样检查结果。
• 请用户确认实时切换样本之前，先通过 Langfuse API 或 CLI 自行审核：每个请求对应一个追踪；根 Span 以 Agent/应用命名（追踪也以根 Span 命名）；包含所有 Span 类型（generation 和 tool/chain Span）；每次 LLM 调用恰好记录一次；已填充 token 用量和费用。之后才能向用户发送追踪链接。
• 按迁移的数据类型核对数量（源端与目标端）；报告中须包含失败项的汇总表。
• 实时流量已进入目标端；只有在用户选择的并行运行期结束后，才移除旧的导出器。
• 收尾摘要须涵盖访谈中的范围表每一行，包括标记为跳过或未涵盖的行——不得悄然遗漏任何内容。