批量导出追踪数据

受计划限制请注意，数据导出功能仅支持 LangSmith Plus 或 Enterprise 层级。

LangSmith 的批量数据导出功能允许您将追踪数据导出到外部目的地。如果您希望在 BigQuery、Snowflake、RedShift、Jupyter Notebooks 等工具中离线分析数据，这将非常有用。导出可以针对特定的 LangSmith 项目和日期范围启动。一旦批量导出启动，我们的系统将处理导出过程的编排和弹性。请注意，导出数据可能需要一些时间，具体取决于数据的大小。我们还限制了同时运行的导出数量。批量导出的运行时限为 24 小时。

目的地

目前我们支持导出到您提供的 S3 存储桶或兼容 S3 API 的存储桶。数据将以 Parquet 列式格式导出。这种格式将使您能够轻松地将数据导入其他系统。数据导出将包含与运行数据格式相同的数据字段。

导出数据

目的地 - 提供 S3 存储桶

要导出 LangSmith 数据，您需要提供一个 S3 存储桶作为数据导出目的地。导出需要以下信息：

存储桶名称：数据将导出到的 S3 存储桶的名称。
前缀：数据将导出到的存储桶中的根前缀。
S3 区域：存储桶的区域 - AWS S3 存储桶需要此信息。
端点 URL：S3 存储桶的端点 URL - 兼容 S3 API 的存储桶需要此信息。
访问密钥：S3 存储桶的访问密钥。
秘密密钥：S3 存储桶的秘密密钥。

我们支持任何 S3 兼容的存储桶，对于非 AWS 存储桶（如 GCS 或 MinIO），您需要提供端点 URL。

准备目的地

对于自托管和欧盟区域部署在下面的请求中，对于自托管安装或欧盟区域的组织，请相应地更新 LangSmith URL。对于欧盟区域，使用 eu.api.smith.langchain.com。

所需权限backend 和 queue 服务都需要对目标存储桶的写入权限：

backend 服务在创建导出目的地时会尝试向目标存储桶写入一个测试文件。如果它有权限，它将删除该测试文件（删除权限是可选的）。
queue 服务负责批量导出执行并将文件上传到存储桶。

以下示例演示如何使用 cURL 创建目的地。将占位符值替换为您的实际配置详细信息。请注意，凭据将以加密形式安全地存储在我们的系统中。

curl --request POST \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "destination_type": "s3",
    "display_name": "My S3 Destination",
    "config": {
      "bucket_name": "your-s3-bucket-name",
      "prefix": "root_folder_prefix",
      "region": "your aws s3 region",
      "endpoint_url": "your endpoint url for s3 compatible buckets"
    },
    "credentials": {
      "access_key_id": "YOUR_S3_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_S3_SECRET_ACCESS_KEY"
    }
  }'

使用返回的 id 在后续的批量导出操作中引用此目的地。 如果您在创建目的地时收到错误，请参阅调试目的地错误以获取如何调试此错误的详细信息。

凭证配置

需要 LangSmith Helm 版本 >= 0.10.34（应用程序版本 >= 0.10.91）

除了静态 access_key_id 和 secret_access_key 之外，我们还支持以下其他凭证格式

要使用包含 AWS 会话令牌的临时凭证，在创建批量导出目的地时额外提供 credentials.session_token 键。
（仅限自托管）：要使用基于环境的凭证，例如 AWS IAM Service Accounts 的角色 (IRSA)，在创建批量导出目的地时从请求中省略 credentials 键。在这种情况下，将按照库定义的顺序检查标准 Boto3 凭证位置。

AWS S3 存储桶

对于 AWS S3，您可以省略 endpoint_url 并提供与您的存储桶区域匹配的区域。

curl --request POST \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "destination_type": "s3",
    "display_name": "My AWS S3 Destination",
    "config": {
      "bucket_name": "my_bucket",
      "prefix": "data_exports",
      "region": "us-east-1"
    },
    "credentials": {
      "access_key_id": "YOUR_S3_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_S3_SECRET_ACCESS_KEY"
    }
  }'

Google GCS XML S3 兼容存储桶

使用 Google 的 GCS 存储桶时，您需要使用 XML S3 兼容 API，并提供 endpoint_url，通常是 https://storage.googleapis.com。以下是使用兼容 S3 的 GCS XML API 时 API 请求的示例

curl --request POST \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "destination_type": "s3",
    "display_name": "My GCS Destination",
    "config": {
      "bucket_name": "my_bucket",
      "prefix": "data_exports",
      "endpoint_url": "https://storage.googleapis.com"
    },
    "credentials": {
      "access_key_id": "YOUR_S3_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_S3_SECRET_ACCESS_KEY"
    }
  }'

有关更多信息，请参阅 Google 文档

创建导出任务

要导出数据，您需要创建一个导出任务。此任务将指定目的地、项目、日期范围和要导出的数据的筛选表达式。筛选表达式用于缩小导出的运行集，是可选的。不设置筛选字段将导出所有运行。请参阅我们的筛选查询语言和示例以确定您的导出正确的筛选表达式。您可以使用以下 cURL 命令创建任务：

curl --request POST \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "bulk_export_destination_id": "your_destination_id",
    "session_id": "project_uuid",
    "start_time": "2024-01-01T00:00:00Z",
    "end_time": "2024-01-02T23:59:59Z",
    "filter": "and(eq(run_type, \"llm\"), eq(name, \"ChatOpenAI\"), eq(input_key, \"messages.content\"), like(input_value, \"%messages.content%\"))"
  }'

session_id 也称为追踪项目 ID，可以通过在追踪项目列表中点击项目来从单个项目视图中复制。

使用返回的 id 在后续的批量导出操作中引用此导出。

计划导出

需要 LangSmith Helm 版本 >= 0.10.42（应用程序版本 >= 0.10.109）

计划导出定期收集运行并导出到配置的目的地。要创建计划导出，请包含 interval_hours 并删除 end_time

curl --request POST \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "bulk_export_destination_id": "your_destination_id",
    "session_id": "project_uuid",
    "start_time": "2024-01-01T00:00:00Z",
    "filter": "and(eq(run_type, \"llm\"), eq(name, \"ChatOpenAI\"), eq(input_key, \"messages.content\"), like(input_value, \"%messages.content%\"))",
    "interval_hours": 1
  }'

详情

interval_hours 必须在 1 小时到 168 小时（1 周）之间（含）。
对于衍生的导出，第一个导出时间范围是 start_time=(scheduled_export_start_time), end_time=(start_time + interval_hours)。然后是 start_time=(previous_export_end_time), end_time=(this_export_start_time + interval_hours)，以此类推。
计划导出必须省略 end_time。非计划导出仍然需要 end_time。
计划导出可以通过取消导出来停止。
- 由计划导出衍生的导出具有填充的 source_bulk_export_id 属性。
- 如果需要，这些衍生的批量导出必须与源计划批量导出分开取消 - 取消源批量导出不会取消衍生的批量导出。
衍生的导出在 end_time + 10 分钟 后运行，以考虑最近提交的 end_time 的任何运行。

示例如果创建了一个计划批量导出，其中 start_time=2025-07-16T00:00:00Z 和 interval_hours=6：

导出	开始时间	结束时间	运行时间
1	2025-07-16T00:00:00Z	2025-07-16T06:00:00Z	2025-07-16T06:10:00Z
2	2025-07-16T06:00:00Z	2025-07-16T12:00:00Z	2025-07-16T12:10:00Z
3	2025-07-16T12:00:00Z	2025-07-16T18:00:00Z	2025-07-16T18:10:00Z

监控导出任务

监控导出状态

要监控导出任务的状态，请使用以下 cURL 命令

curl --request GET \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/{export_id}' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID'

将 {export_id} 替换为您要监控的导出 ID。此命令检索指定导出任务的当前状态。

列出导出的运行

导出通常分为多个运行，这些运行对应于要导出的特定日期分区。要列出与特定导出相关的所有运行，请使用以下 cURL 命令

curl --request GET \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/{export_id}/runs' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID'

此命令获取与指定导出相关的所有运行，提供运行 ID、状态、创建时间、导出行数等详细信息。

列出所有导出

要检索所有导出任务的列表，请使用以下 cURL 命令

curl --request GET \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID'

此命令返回所有导出任务的列表，以及它们的当前状态和创建时间戳。

停止导出

要停止现有导出，请使用以下 cURL 命令

curl --request PATCH \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/{export_id}' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "status": "Cancelled"
}'

将 {export_id} 替换为您希望取消的导出 ID。请注意，一旦任务被取消，就无法重新启动，您需要创建一个新的导出任务。

分区方案

数据将以以下 Hive 分区格式导出到您的存储桶中

<bucket>/<prefix>/export_id=<export_id>/tenant_id=<tenant_id>/session_id=<session_id>/runs/year=<year>/month=<month>/day=<day>

将数据导入其他系统

大多数分析系统通常都支持从 S3 和 Parquet 格式导入数据。请参阅下面的文档链接

BigQuery

要将数据导入 BigQuery，请参阅从 Parquet 加载数据和 Hive 分区加载。

Snowflake

您可以通过遵循从云加载文档将数据从 S3 加载到 Snowflake 中。

RedShift

您可以通过遵循 AWS COPY 命令文档将数据从 S3 或 Parquet 复制到 Amazon Redshift 中。

Clickhouse

您可以在 Clickhouse 中直接查询 S3 / Parquet 格式的数据。例如，如果使用 GCS，您可以按如下方式查询数据

SELECT count(distinct id) FROM s3('https://storage.googleapis.com/<bucket>/<prefix>/export_id=<export_id>/**',
 'access_key_id', 'access_secret', 'Parquet')

有关更多信息，请参阅 Clickhouse S3 集成文档。

DuckDB

您可以使用 DuckDB 在内存中通过 SQL 查询 S3 中的数据。请参阅 S3 导入文档。

错误处理

调试目的地错误

目的地 API 端点将验证目的地和凭据是否有效，以及存储桶是否存在写入权限。如果您收到错误，并希望调试此错误，您可以使用 AWS CLI 测试与存储桶的连接。您应该能够使用与上面提供给目的地 API 的相同数据，通过 CLI 写入文件。 AWS S3:

aws configure

# set the same access key credentials and region as you used for the destination
> AWS Access Key ID: <access_key_id>
> AWS Secret Access Key: <secret_access_key>
> Default region name [us-east-1]: <region>

# List buckets
aws s3 ls /

# test write permissions
touch ./test.txt
aws s3 cp ./test.txt s3://<bucket-name>/tmp/test.txt

GCS 兼容存储桶： 您需要使用 --endpoint-url 选项提供 endpoint_url。对于 GCS，endpoint_url 通常是 https://storage.googleapis.com：

aws configure

# set the same access key credentials and region as you used for the destination
> AWS Access Key ID: <access_key_id>
> AWS Secret Access Key: <secret_access_key>
> Default region name [us-east-1]: <region>

# List buckets
aws s3 --endpoint-url=<endpoint_url> ls /

# test write permissions
touch ./test.txt
aws s3 --endpoint-url=<endpoint_url> cp ./test.txt s3://<bucket-name>/tmp/test.txt

监控运行

您可以使用 List Runs API 监控您的运行。如果这是一个已知错误，它将添加到运行的 errors 字段中。

常见错误

以下是一些常见错误

错误	描述
访问被拒绝	Blob 存储凭据或存储桶无效。当提供的访问密钥和秘密密钥组合没有访问指定存储桶或执行所需操作的必要权限时，会发生此错误。
存储桶无效	指定的 blob 存储桶无效。当存储桶不存在或没有足够的权限对存储桶执行写入操作时，会抛出此错误。
您提供的密钥 ID 不存在	提供的 blob 存储凭据无效。当用于身份验证的访问密钥 ID 不是有效密钥时，会发生此错误。
无效的端点	提供的 endpoint_url 无效。当指定的端点是无效端点时，会引发此错误。仅支持 S3 兼容的端点，例如 GCS 的 `https://storage.googleapis.com`，minio 的 `https://play.min.io` 等。如果使用 AWS，您应该省略 endpoint_url。

在 GitHub 上编辑此页面源文件。

以编程方式连接这些文档到 Claude、VSCode 等，通过 MCP 获取实时答案。

追踪设置

配置和故障排除

查看和管理追踪

自动化

反馈与评估

监控与告警

数据类型参考

目的地

导出数据

目的地 - 提供 S3 存储桶

准备目的地

凭证配置

AWS S3 存储桶

Google GCS XML S3 兼容存储桶

创建导出任务

计划导出

监控导出任务

监控导出状态

列出导出的运行

列出所有导出

停止导出

分区方案

将数据导入其他系统

BigQuery

Snowflake

RedShift

Clickhouse

DuckDB

错误处理

调试目的地错误

监控运行

常见错误

追踪设置

配置和故障排除

查看和管理追踪

自动化

反馈与评估

监控与告警

数据类型参考

​目的地

​导出数据

​目的地 - 提供 S3 存储桶

​准备目的地

​凭证配置

​AWS S3 存储桶

​Google GCS XML S3 兼容存储桶

​创建导出任务

​计划导出

​监控导出任务

​监控导出状态

​列出导出的运行

​列出所有导出

​停止导出

​分区方案

​将数据导入其他系统

​BigQuery

​Snowflake

​RedShift

​Clickhouse

​DuckDB

​错误处理

​调试目的地错误

​监控运行

​常见错误

目的地

导出数据

目的地 - 提供 S3 存储桶

准备目的地

凭证配置

AWS S3 存储桶

Google GCS XML S3 兼容存储桶

创建导出任务

计划导出

监控导出任务

监控导出状态

列出导出的运行

列出所有导出

停止导出

分区方案

将数据导入其他系统

BigQuery

Snowflake

RedShift

Clickhouse

DuckDB

错误处理

调试目的地错误

监控运行

常见错误