[Beta] 批量导出追踪数据

计划限制适用

请注意，数据导出功能目前处于测试阶段，仅支持 LangSmith Plus 或企业版。

LangSmith 的批量数据导出功能允许您将追踪数据导出到外部目标。如果您希望在 BigQuery、Snowflake、RedShift、Jupyter Notebook 等工具中离线分析这些数据，该功能将非常有用。

可以启动导出任务，以针对特定的 LangSmith 项目和日期范围。一旦启动批量导出任务，我们的系统将负责导出过程的编排与容错处理。 请注意，导出您的数据所需时间取决于数据量大小。此外，我们对您同时运行的导出任务数量也有限制。 批量导出任务还设有 24 小时的运行超时限制。

目的地

目前我们支持将数据导出至您提供的 Amazon 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。

以下示例演示了如何使用 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 在后续的批量导出操作中引用此目标。

如果在创建目标时收到错误，请参阅 调试目标错误 以了解如何调试此问题的详细信息。

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"
  }'

笔记

session_id 也称为追踪项目 ID，您可通过在“追踪项目”列表中点击相应项目，然后在单独的项目视图中复制该 ID。

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

监控导出任务

监控导出状态

要监控导出作业的状态，请使用以下 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。此命令用于检索指定导出任务的当前状态。

列出导出的运行记录

导出通常被划分为多个运行（runs），每个运行对应一个特定的日期分区以进行导出。 要列出与特定导出关联的所有运行，请使用以下 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 分区加载。

雪花云

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

RedShift

您可以通过遵循AWS COPY 指令，将数据从 S3 / Parquet 复制到 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

兼容 Google Cloud Storage 的存储桶：

您需要提供 endpoint_url。--endpoint-url option.
对于 Google Cloud Storage（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

监控运行

您可以使用列出运行记录 API来监控您的运行记录。如果这是一个已知错误，该错误将被添加到运行记录的errors字段中。

常见错误

以下是一些常见错误：

错误	描述
Access denied	The blob store credentials or bucket are not valid. This error occurs when the provided access key and secret key combination doesn't have the necessary permissions to access the specified bucket or perform the required operations.
Bucket is not valid	The specified blob store bucket is not valid. This error is thrown when the bucket doesn't exist or there is not enough access to perform writes on the bucket.
Key ID you provided does not exist	The blob store credentials provided are not valid. This error occurs when the access key ID used for authentication is not a valid key.
Invalid endpoint	The endpoint_url provided is invalid. This error is raised when the specified endpoint is an invalid endpoint. Only S3 compatible endpoints are supported, for example https://storage.googleapis.com for GCS, https://play.min.io for minio, etc. If using AWS, you should omit the endpoint_url.