迁移到 BYOC

将用户、数据集、提示词、实验、Fleet 资源和其他数据从现有 LangSmith 实例复制到 BYOC 数据平面。

LangSmith 数据迁移工具 会将数据从现有的 LangSmith Cloud 组织或自托管实例复制到 BYOC 数据平面。该工具是复制数据（而非将数据搬移过去），因此源实例保持不变，并在迁移期间保持可用。

在数据平面处于活动状态且可访问后运行迁移。追踪数据不会被迁移，因此请将手动步骤与该工具一并规划。

支持的资源

该工具在源实例和目标数据平面之间迁移以下资源：

资源	详细信息
用户和角色	自定义角色、组织成员和工作区成员资格。
数据集	数据集及其示例和文件附件。
实验	实验、实验运行和反馈，随其数据集一起迁移。
标注队列	队列配置和设置。迁移后的队列为空。
自动化规则	项目自动化规则，映射到目标项目。
提示词	带完整提交历史的提示词。
图表	监控图表和仪表盘。
自定义模型定价	工作区自定义的模型价格条目。
Fleet	智能体、共享技能、MCP 服务器、集成、身份认证服务商、调度、触发器、Webhook、用量限制、沙箱策略和工作区密钥。
Context Hub	Context Hub 智能体和技能，包括文件、仓库元数据、提交历史和提交标签。

每种资源类型都有自己的命令、标志和注意事项。有关命令参考，请参阅工具 README。

NOTE

属于 BYOC 尚不支持的功能的资源，例如 Engine，无法迁移。请参阅可用功能。

使用该工具进行迁移

Install the tool

使用 uv、uvx 或 pip 安装最新版本。有关当前的安装命令，请参阅安装。

验证安装：

langsmith-migrator --help

Create the destination workspaces

工作区 ID 因实例而异，因此请先在数据平面中创建目标工作区。请参阅 BYOC 入门文档的 Create workspaces 部分。

迁移命令按工作区对运行。请为每一对重复运行这些命令。

Create the destination tracing projects

该工具不会创建追踪项目。在迁移自动化规则或图表之前，请在目标工作区中创建所需的项目，否则那些映射将没有目标。

Configure the connection details

设置源和目标的凭据及终端节点：

export LANGSMITH_OLD_API_KEY="<source_instance_key>"
export LANGSMITH_NEW_API_KEY="<data_plane_key>"
export LANGSMITH_OLD_BASE_URL="<source_instance_api_url>"
export LANGSMITH_NEW_BASE_URL="https://<data_plane_host>"
export LANGSMITH_VERIFY_SSL=true

NOTE

OLD 指你当前的 LangSmith 部署，NEW 指目标 BYOC 数据平面：

• LANGSMITH_OLD_API_KEY：来自你当前部署的 API 密钥，具有读取你要迁移的所有资源的权限。对于 smith.langchain.com 上的 LangSmith Cloud，请在 Settings > API Keys 下创建它。对于其他 Cloud 区域或自托管实例，请使用该部署的 UI。
• LANGSMITH_NEW_API_KEY：在 aws.smith.langchain.com 的 Settings > API Keys 下创建的 API 密钥。将其限定到目标 BYOC 数据平面中的某个工作区。请参阅创建 API 密钥。
• LANGSMITH_OLD_BASE_URL：你当前部署的 API URL。对于 GCP US 中的 LangSmith Cloud，使用 https://api.smith.langchain.com。对于其他 Cloud 区域，使用其区域 API URL。对于自托管 LangSmith，使用你实例的 API URL。
• LANGSMITH_NEW_BASE_URL：目标 BYOC 数据平面的 API URL，包含 https://。在 Settings > Data Planes 下找到它。请参阅 BYOC 入门指南。

WARNING

目标密钥必须限定到目标数据平面中的某个工作区。组织范围的密钥不起作用。

若要迁移带有所有者的 Fleet 智能体，请使用个人访问令牌（lsv2_pt_*）作为目标密钥。工作区 API 密钥不携带用户身份，因此用它们创建的智能体没有所有者。

Test both connections

langsmith-migrator test

Run the migration

使用交互式向导逐步处理每种资源类型：

langsmith-migrator migrate-all

若要一次迁移一种资源类型，请改为运行其命令，例如 datasets、prompts 或 fleet。添加 --dry-run 可在不写入的情况下预览某个步骤，添加 -v 可输出详细信息。使用 langsmith-migrator resume 重试上次会话中待处理或失败的项目。

有关各命令的标志、工作区映射和项目映射，请参阅工具 README。

完成 Fleet 手动步骤

Fleet 资源通过 fleet 命令迁移，但有些值无法跨实例。在迁移后于目标工作区中完成以下操作：

• 重新输入密钥值：Fleet API 不会返回密钥值。该工具会将工作区密钥和身份认证服务商客户端密钥创建为空占位符。
• 重新认证 OAuth 连接：每个用户的智能体连接，例如 Gmail、Slack 和 GitHub，都与单个用户令牌绑定。每个用户都必须重新连接。
• 重新共享智能体：每个用户的访问列表只保留目标上存在的用户 ID。该工具会报告它移除了哪些用户。
• 检查智能体模型：当目标目录不提供源模型时，该工具会替换某个模型。它会记录每一次替换。
• 配置基础设施级设置：OAuth 服务商、GitHub App 和 Slack 应用在部署配置中设置，而不是通过 API 设置。请联系 LangChain 团队在你的数据平面中配置它们。

Fleet 迁移器绝不会覆盖目标上已存在的资源，因此重新运行 fleet 是安全的。

迁移该工具不迁移的数据

追踪

该工具不迁移追踪。若要在旧实例生命周期之后保留历史追踪，请将它们批量导出到兼容 S3 的存储桶。

若要迁移追踪应用，请创建限定到数据平面中某个工作区的 API 密钥，然后重新指向该应用：

• 切换：将 LANGSMITH_ENDPOINT 设置为数据平面终端节点，将 LANGSMITH_API_KEY 设置为新密钥。请参阅追踪到数据平面。
• 双重追踪：在过渡期间同时写入旧实例和数据平面。请参阅追踪到多个终端节点。

已部署的智能体

将运行在现有实例上的智能体重新部署到数据平面中的某个工作区。使用 LangSmith UI 或 API。你可能还需要在数据平面集群中重新创建服务账户、镜像拉取密钥和其他资源。

对于智能体数据库和缓存，请选择以下之一：

• 在数据平面中创建新实例，并将重新部署的智能体指向它们。可以从空开始，或从旧实例的备份恢复。
• 将重新部署的智能体指向你现有的数据库实例，并从数据平面集群通过 PrivateLink 或 VPC 对等连接访问它们。

有关更多信息，请参阅 LangSmith 部署。

洞察报告

洞察报告不会跨实例迁移。若要保留某个报告，请在 LangSmith UI 中打开其详细信息并选择 Download。

另请参阅

• BYOC 入门指南
• BYOC 用法
• 批量导出追踪数据

---