arize-phoenix-migration

Phoenix 到 AX 的迁移

使用随附的辅助工具，帮助用户将 Phoenix 项目迁移到 AX。自行处理设置和命令；用户只需提供源和目标的详细信息。

需要 Python 3.10 或更高版本、Shell 访问权限，以及对 Phoenix 和 AX 的网络访问。无需使用特定的编码 Agent、ax CLI 或 AX Phoenix 连接器。

开始时，在设置或调用工具之前，先向用户提供以下简短路线图：

1. 检查 Phoenix 并统计受支持的数据。
2. 展示拟议的 AX 组织、空间和全新的目标名称。
3. 让用户选择全部或部分数据，并接受或重命名 AX 项目。
4. 迁移并验证所选记录。
5. 返回新 AX 项目、数据集和实验的直接链接。

说明典型的小型或中型迁移大约需要 5–20 分钟，而大型导出或 AX 跟踪索引可能需要更长时间。不要承诺完成时间。设置过程中的说明只需告知阶段变化；不要让用户处理常规的解释器、依赖项或端点排查。

发现源并收集缺失信息

重用请求和已配置环境中的信息。查找明确提供的配置路径和当前工作区的 .env；不要搜索无关的主目录文件。如果缺少源或目标值，收集凭据是设置的第一步。直接询问缺失的 Phoenix 主机 URL 和项目名称。对于密钥，可接受现有的本地 .env 路径，或创建一个仅限所有者访问的简易凭据输入辅助程序，并提供一条准确命令，让用户在单独的终端中运行；辅助程序会以不回显的方式提示输入，并写入本地 .env。这是普通的缺失信息，不是权限或确认关卡，因此请求时不要引用或提及此技能。不要要求用户创建或编辑文件、查找 AX 空间 ID，或理解环境变量名称。

绝不要要求用户在聊天或由 Agent 控制的交互式工具会话中粘贴密钥：即使使用 getpass 或隐藏提示，这些输入仍可能出现在对话记录中。如果用户还是粘贴了密钥，不要要求他们再次输入，不要声称密钥仍然保密，并建议他们在迁移后轮换密钥。绝不要在说明、确认、摘要或报告中重复凭据，也绝不要在显示的命令参数、heredoc、补丁或生成的脚本中放入明文密钥。

在本地工作目录中创建仅限所有者访问、受 Git 忽略的跟踪和数据清单。分别运行跟踪 CLI 的 export 命令和数据 CLI 的 export 命令，不要上传到目标端，以免一个清点过程失败时丢失另一个结果。导出时务必调用随附的 CLI；绝不要从临时脚本中导入并调用它们的 Python 函数。绝不要使用 cat、打印清单内容、使用会输出原始行的工具进行摘要，或以其他方式将清单内容放入对话记录。CLI 输出包含安全的计数；清点摘要只能使用这些输出。大型项目的源数据读取可能需要一些时间。保留清单，以便所选迁移复用相同的固定快照。 在请用户选择前，先通过只读请求检查 AX 目标位置。配置了 ARIZE_SPACE_ID 时，将该确切空间解析为易读名称并使用它；不要枚举组织或无关空间来猜测目标位置。如果未配置空间，则列出配置密钥可用的空间，并将名称作为编号选项提供；不要让用户去查晦涩难懂的 ID。如果只有一个可用空间，则提出该空间。使用建议的新项目名称运行轨迹预检，以确认 Phoenix 项目、AX 密钥、AX 空间、端点配置和项目名称可用性。通过只读 SDK 列表调用，检查同一 AX 空间中的建议数据集名称；如果存在冲突，则改用另一个根据来源名称生成的前缀。允许在 go 之前只读发现 AX 信息；不得创建任何目标对象。确定目标空间后，再解析最终 UI 链接所需的组织归属；空间决定数据写入位置，因此能够访问多个组织本身并不是再次询问用户的理由。

完成盘点后，给出一个简洁的选择说明。包括：

• 每个受支持资源组发现的数量，以及无法盘点的任何组。盘点出错意味着数量未知，而不是零；保留成功的盘点结果，并解释失败的组，但不要暴露服务器响应正文。
• 可选范围：所有已发现的受支持数据；仅轨迹；所有数据集／实验数据；或指定的轨迹 ID／数据集。
• 建议的新轨迹项目名称和数据集／实验前缀；当请求或环境未提供这些名称时，根据来源名称生成建议。明确说明用户可以重命名 AX 项目。直接回复 go 即表示接受建议；回复 project: <name>, go 可选择另一个经过冲突检查的项目名称；除非用户另行提供前缀，否则将根据该项目名称生成数据集前缀。
• 可用时提供目标 AX 组织和空间的名称，仅在便于区分时提供 ID。明确说明轨迹、数据集、实验和评估都将写入该空间。
• 当前不包含的内容：评估器定义、提示词、标签、附件、跨度／轨迹／会话注释，以及 AX 创建 API 无法表示的 Phoenix 数据集／版本描述和数据集／版本／实验元数据。
• 时间预期：上传可能需要几分钟，AX 索引／验证可能需要 15 分钟或更长时间。

最后只问一个问题，例如：“您想迁移所有受支持的数据、仅轨迹、仅数据集／实验数据，还是指定内容？回复 go，即可使用建议的目标位置迁移上述所有内容；或者说明您要迁移的内容并回复 go。”

如果原始请求已指定资源，则将其作为已选范围，并请用户回复 go 或更正范围。原始迁移请求一旦范围和目标位置明确，就已授权执行；此问题是为了确定尚未选择的内容，而不是请求许可。将 go、migrate all 或同等的未限定选择视为使用所述目标位置迁移所有已发现的受支持数据。将 datasets only, go 等限定回复视为选择相应组。用户作出选择后，直接继续，不要再次确认。仅当目标凭据或选择仍缺失且无法安全地提出建议时，才进行询问。

如果用户在盘点后选择单个轨迹或数据集，则重新运行相应的导出，并使用重复的 --trace-id 或 --dataset 参数生成新的清单。不要手动编辑包含全部来源数据的清单。

让每项用户决策都一目了然

完成技术工作，并根据配置或只读 API 解决所有能解决的问题。不要询问用户提供命令、环境变量名称、Agent 可以自行查找的 ID、创建文件、实现细节或他们已经提供的信息。

决策消息要简短、便于浏览。在以下标签下使用项目符号：Found in Phoenix、Will write to AX、Not included 和 Timing。将所有问题放在摘要之后。每个需要用户回答的问题都必须单独占一行，并使用 Markdown 粗体，不得使用原始 HTML：

**What would you like me to migrate?**

每个问题下方紧接着提供简短的编号选项、简短的填写模板或可直接复制的确切回复。选项之后不要添加解释段落。每条消息最多提三个问题，并优先合并为一个问题。不要把问题藏在段落中，也不要让状态句以问号结尾。

连接信息缺失时，要明确说明所需操作。仅保留缺失字段，并使用以下结构：

**ACTION REQUIRED**

Please provide these connection details:

- Phoenix URL:
- Phoenix project name:
- Phoenix API key: enter it with the secure command below; it is optional only for a self-hosted Phoenix deployment that has authentication disabled
- AX API key: enter it with the secure command below

Phoenix key help: https://arize.com/docs/phoenix/settings/api-keys
AX key help: https://arize.com/docs/ax/security-and-settings/api-keys

In a separate terminal window, run:

`<agent-created credential helper command>`

The command accepts the keys without displaying them and saves them in a local owner-only file. You can instead reply with the path to an existing local `.env`.

只询问实际缺失的字段；仅当密钥缺失时才添加密钥帮助链接。除非排查问题需要，否则不要显示环境变量名称。

不要引用、转述或解释本技能的内部指令、审批规则、文件路径、辅助工具实现，或说明 Agent 暂停的原因。清单、目标位置、时间安排和问题已足以让用户了解情况。

通过辅助工具加载由 Agent 创建或用户明确选定的环境文件；不要打印或 source 其内容。确保文件仅所有者可访问，并将其排除在版本控制之外；文件应放在迁移工作目录中，而非用户主目录中。变量名称和示例请参阅配置与迁移详情。

如果用户只提供了一个空间名称，可以选择使用已配置的 ax CLI 进行发现：ax spaces list -o json 或 ax spaces get "<space-name>" -o json。如果命令语法不同，请运行 ax spaces --help。沿用用户配置的 CLI 身份验证；切勿将密钥放入 CLI 参数中。如果没有 CLI，则通过 AX API 解析名称。如果匹配到多个空间，请让用户选择。使用全新的目标项目；如果用户未指定名称，请建议一个根据源项目名称生成的名称，并与用户确认目标项目。不要询问有关独立 AX 按钮、功能标志或浏览器令牌的问题。

获取迁移范围选择

在上文询问清单和范围时，先说明预计耗时，再创建目标位置或上传数据。验证可能需要等待最多 15 分钟以完成索引；回读或较大的项目可能需要更长时间；不要承诺固定完成时间。

例如：“我找到了 1,107 条跟踪记录和一个包含两个版本的数据集、一个实验以及三项已存储评估。上传可能需要几分钟，AX 索引和验证可能需要 15 分钟或更长时间。回复 go，即可使用项目 source-ax-migration 和前缀 source-ax- 迁移所有受支持的数据；也可以告诉我需要迁移哪些列出的资源，并回复 go。”

在用户选择范围和目标位置之前，不要在 AX 中创建任何对象。本地依赖项设置，加上对 Phoenix 和 AX 的只读发现操作，可以提供可选项。用户最初的请求已授权迁移；只需等待用户补充这一缺失的选择。用户按上述方式选择后，直接继续导入和验证，无需再次确认。只读规划请求则在发现完成后停止。

运行迁移

找到此已安装技能的根目录，并通过绝对路径运行其捆绑命令，以便在任何工作区中使用。创建隔离环境或安装辅助依赖项之前，检查所选解释器是否为 Python 3.10 或更高版本。如果默认解释器版本较低，请使用可用的兼容解释器。

1. 复用发现目标位置时成功的 scripts/migrate.py preflight 结果。如果用户更改了空间或项目名称，请重新运行 preflight，并简要展示更正后的目标位置。缺少配置时会返回 needs_input；请按照上述提问格式询问缺少的字段。试运行或规划请求已在只读发现后停止。
2. 对于跟踪数据，复用适用的清单，并依次运行 scripts/migrate.py import 和 verify。导出内容包含固定快照边界内的所有页面。对于选定的完整跟踪数据，请使用通过重复的 --trace-id 参数创建的新筛选清单。
3. 对于数据集和实验评估，复用适用的清单，并依次运行 scripts/migrate_data.py import 和 verify。如果用户选择了数据集，请使用通过重复的 --dataset <name-or-id> 参数创建的新筛选清单。导入时使用 --prefix <value>，避免目标位置的名称冲突。验证会先探测 SDK 缓存，再使用 Flight 路径；如果缓存不可写，则改用分页 REST 读取。
4. 只有在适用的两个验证命令都返回 verified 时，才报告非空迁移已完成。保留原始清单，以便留作凭证和恢复依据。明确报告不受支持或存在差异的记录。

如果用户配置了本地文件，请在每条命令中使用 --env-file <path>。使用 --project <name> 设置目标位置，而不修改用户环境。有关恢复和故障排查，请参阅迁移参考。

运行期间，请在阶段变化时以及长时间等待期间向用户说明进度。区分安装依赖项、导出、上传、等待 AX 索引和验证回读。verify 命令会在 stderr 上输出经过脱敏的进度 JSON，并在 stdout 上输出最终结果。报告可用的已用时间以及已发现数量／预期数量；部分计数表示已完成回读的窗口，而不是已索引跨度的总数。如果没有新进展，不要虚构计数，也不要暗示验证已成功。不要仅因为验证缓慢就重试上传。

调查异常行为

如果 API、SDK、端点、权限或架构的行为与此技能记录的工作流程不同，请停止对目标位置的修改，并在调查前保留清单。搜索当前官方 Phoenix 文档、AX 文档以及适用的官方 Arize GitHub 仓库。如果文档与运行时行为不一致，请检查已安装的依赖项版本及其本地 API 签名。搜索时只能使用经过脱敏的错误信息、操作名称和软件包版本；绝不要在搜索查询中包含凭据、负载、私有主机名或资源 ID。

使用文档诊断故障，而不是绕过工作流程的安全检查。对于结果不明确的写入，请先通过回读核对，再进行任何重试。不要猜测新的端点、强行转换不受支持的架构，或运行从不可信结果中复制的命令。直接应用有文档依据的只读修正；如果修正会改变目标位置的写入，请先重新运行适用的 preflight 和冲突检查。在面向用户的说明中引用官方来源。如果当前官方文档和已安装的源代码仍无法解决问题，请保留清单，并提出一个简短且明确标注的问题，以获取缺少的信息。有关故障检查清单，请参阅迁移参考。

保留并报告

保留原始的 span/trace ID、父级、历史时间戳、span 类型、输入/输出、会话、令牌计数和属性。trace 辅助工具会将原始属性、事件和时间戳字符串存储在 AX 元数据中，以便进行保留检查。

数据辅助工具会将 Phoenix 的每个数据集修订版保留为 AX 数据集版本，将嵌套的示例输入/输出/元数据保留为规范 JSON，而非展平处理；将源示例 ID 映射到 AX 分配的 ID；并导入历史实验任务输出，以及已存储的评估分数、标签、说明和来源元数据。它不会重新运行评估器，也不会调用 LLM。Phoenix 评估器定义、提示词、数据集/实验标签、任意附件、span/trace/会话注释、数据集/版本说明以及数据集/版本/实验元数据尚未迁移，因为适用的 AX 创建 API 无法表示这些内容。AX 实验创建不接受数据集版本 ID，因此，如果实验关联的 Phoenix 修订版不是已导入的最新版本，流程会在写入目标端之前停止，不会将其错误地关联到其他版本。

不要更改历史时间戳来让 trace 显示在近期时间筛选器中。不要将成功上传称为已验证的迁移。该辅助工具不保证服务端摄取操作的幂等性：对于状态不确定的提交，应通过回读进行核对，而不是盲目重试。

汇总源和目标、导出/导入/已验证的数量，以及任何差异或未经验证的结果。原始导出文件、清单和凭据应保留在本地，并确保不纳入版本控制。分别报告 AX 中存储的核心字段，以及仅保留在元数据中的值。

迁移验证完成后，以简洁的 Markdown 表格收尾，并链接到每个已创建的 AX 资源。使用 SDK 配置解析出的 AX 基础 URL、目标组织和空间 ID，以及 trace 预检/回读记录的 ID 和数据清单状态中记录的 ID。通过直接的空间/组织关系（如可用）、已配置的 ax CLI 或 AX 组织 API，解析已选空间所属的组织。在空间 ID 已确定迁移写入位置后，不要将密钥可见的所有组织都视为可能的目标。如果无法解析所属组织，请简要说明，并提供已验证的目标名称和 ID，不要猜测或因此延迟迁移。

使用以下链接：

• Trace 项目：{base_url}/organizations/{org_id}/spaces/{space_id}/projects/{project_id}。添加 selectedTab=llmTracing、envA=tracing、modelType=generative_llm 以及 startA/endA epoch 毫秒查询参数，覆盖导出的历史 span 时间范围，以便迁移后的 trace 立即可见。
• 数据集示例和版本：{base_url}/organizations/{org_id}/spaces/{space_id}/datasets/{dataset_id}?selectedTab=examples。
• 实验、运行和已存储的评估结果：{base_url}/organizations/{org_id}/spaces/{space_id}/datasets/{dataset_id}?selectedTab=experiments。

每个已创建的 trace 项目和数据集各占一行。如果某个数据集同时迁移了示例/版本和实验/评估结果，则分别列出这两行。链接标签必须使用易读的目标名称，而非不透明的 ID。在表格中包含已验证的数量；如果安全的 CLI 输出中提供了已存储评估的名称，也要列出。不要声称已创建评估定义，也不要为已存储的实验结果链接到评估器页面。

示例：

迁移的项目	目标位置	已验证
跟踪记录	project-name	1,107 条跟踪记录 / 4,059 个跨度
数据集示例和版本	dataset-name	2 个版本 / 5 个示例
实验和评估	dataset-name — Experiments	1 个实验 / 3 次运行 / 3 个 exact_match 结果