Skip to main content

[Beta] 批量导出跟踪数据

计划限制适用

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

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。

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

监控导出作业​

监控导出状态​

要监控导出任务的状态，请使用以下 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 中。

红移​

您可以通过遵循 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​

您可以使用 SQL 在内存中通过 DuckDB 查询来自 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 字段中。

常见错误​

以下是一些常见错误：

错误描述
Access deniedThe 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 validThe 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 existThe blob store credentials provided are not valid. This error occurs when the access key ID used for authentication is not a valid key.
Invalid endpointThe 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.

此页面有帮助吗？


您可以留下详细的反馈 在 GitHub 上。