跳到主要内容

批量导出追踪数据

计划限制适用

请注意，数据导出功能仅支持 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",
    "filter": "and(eq(run_type, \"llm\"), eq(name, \"ChatOpenAI\"), eq(input_key, \"messages.content\"), like(input_value, \"%messages.content%\"))"
  }'
注意

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 端点将验证目的地和凭据是否有效，以及存储桶是否存在写入权限。

如果您收到错误并希望调试此错误，您可以使用 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 存储凭据或存储桶无效。当提供的访问密钥和私密密钥组合没有访问指定存储桶或执行所需操作的必要权限时，会发生此错误。
存储桶无效指定的 Blob 存储桶无效。当存储桶不存在或没有足够的权限对存储桶执行写入操作时，会抛出此错误。
您提供的密钥 ID 不存在提供的 Blob 存储凭据无效。当用于身份验证的访问密钥 ID 不是有效密钥时，会发生此错误。
无效端点提供的 endpoint_url 无效。当指定的端点是无效端点时，会引发此错误。仅支持 S3 兼容的端点，例如 GCS 的 https://storage.googleapis.com，MinIO 的 https://play.min.io 等。如果使用 AWS，则应省略 endpoint_url。

此页面有帮助吗？


您可以在 GitHub 上提供详细反馈 在 GitHub.