[测试版]批量导出跟踪数据

计划限制适用

请注意，数据导出功能处于测试阶段，仅支持 LangSmith Plus 或 Enterprise 层。

LangSmith 的批量数据导出功能允许您将跟踪导出到外部目标。如果要分析在 BigQuery、Snowflake、RedShift、Jupyter Notebooks 等工具中离线数据。

可以启动导出以定位特定的 LangSmith 项目和日期范围。启动批量导出后，我们的系统将处理导出过程的编排和弹性。请注意，导出数据可能需要一些时间，具体取决于数据的大小。我们对您可以同时运行的导出数量也有限制。批量导出的运行时超时为 24 小时。

目的地

目前，我们支持导出到您提供的 S3 存储桶或 S3 API 兼容存储桶。数据将以 Parquet 列式格式导出。这种格式将允许您轻松地将数据导入其他系统。数据导出将包含与 Run data format 等效的数据字段。

导出数据

目标 - 提供 S3 存储桶

要导出 LangSmith 数据，您需要提供数据将导出到的 S3 存储桶。

导出需要以下信息：

存储桶名称：数据将导出到的 S3 存储桶的名称。
Prefix（前缀）：数据将导出到的存储桶中的根前缀。
S3 区域：存储桶的区域 - AWS S3 存储桶需要此区域。
终端节点 URL：S3 存储桶的终端节点 URL - 与 S3 API 兼容的存储桶需要此 URL。
Access Key：S3 存储桶的访问密钥。
Secret Key（密钥）：S3 存储桶的 Secret Key。

我们支持任何与 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在后续的批量导出作中引用此目标。

如果您在创建目标时收到错误，请参阅 debug destination errors 以了解有关如何调试此错误的详细信息。

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，可以通过单击 Tracing Projects 列表中的项目从单个项目视图中复制该 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。此命令检索指定导出作业的当前状态。

列出导出的运行

导出通常分为多个运行，这些运行对应于要导出的特定日期分区。要列出与特定导出关联的所有运行，请使用以下 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。请注意，作业一旦被取消就无法重新启动。您需要改为创建新的 Export Job。

分区方案

数据将以以下 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 中。

红移

您可以按照 AWS COPY 说明将数据从 S3 / Parquet 复制到 RedShift。

点击屋

您可以在 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 端点将验证目标和凭证是否有效，以及写入访问权限是否有效的 Bucket 存在。

如果您收到错误，并且想要调试此错误，则可以使用 AWS CLI 测试与存储桶的连接。您应该能够使用相同的 CLI 编写文件您提供给上述 Destinations API 的数据。

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 监控您的运行。如果这是一个已知错误，则会将其添加到errorsrun 的字段。

常见错误

以下是一些常见错误：

错误	描述
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.