跳到主要内容

[Beta] 批量导出追踪数据

注意

请注意，数据导出功能目前为 Beta 测试版，仅支持 LangSmith Plus 或 Enterprise 级别。

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

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

目标位置​

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

导出数据​

目标位置 - 提供 S3 存储桶​

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

导出需要以下信息

  • 存储桶名称：数据将导出到的 S3 存储桶的名称。
  • 前缀：数据将导出到的存储桶内的根前缀。
  • S3 区域：存储桶的区域 - 这是 AWS S3 存储桶所必需的。
  • Endpoint URL：S3 存储桶的 endpoint URL - 这是 S3 API 兼容的存储桶所必需的。
  • 访问密钥：S3 存储桶的访问密钥。
  • Secret Key：S3 存储桶的 secret key。

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

准备目标位置​

以下示例演示了如何使用 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 中。

RedShift​

您可以通过遵循 AWS COPY 指令，将数据从 S3 / Parquet COPY 到 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 endpoint 将验证目标位置和凭据是否有效，以及存储桶是否具有写入访问权限。

如果您收到错误，并且想要调试此错误，您可以使用 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

监控运行​

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

常见错误​

以下是一些常见错误

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

此页内容对您有帮助吗？


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