Skip to main content

Documentation Index

Fetch the complete documentation index at: https://langchain-zh.cn/llms.txt

Use this file to discover all available pages before exploring further.

计划限制适用请注意，数据导出功能仅适用于 LangSmith Plus 或企业版。
LangSmith 的批量数据导出功能允许您将特定项目和日期范围内的追踪数据导出到 S3 兼容的存储桶，格式为 Parquet，字段与 运行数据格式 相匹配。这对于在 BigQuery、Snowflake、Redshift 或 Jupyter Notebooks 等工具中进行离线分析非常有用。 本页涵盖以下内容：
  • 创建导出目标
  • 创建和配置导出作业，包括计划导出和字段过滤
  • 监控导出进度
开始前须知： 导出时间可能因数据量而异，并且 LangSmith 限制了可以并发运行的导出数量。批量导出有 72 小时的运行超时限制——详情请参阅 自动重试行为。一旦启动，LangSmith 会自动处理导出流程的编排和 弹性。

​
1. 创建目标

目标告诉 LangSmith 将导出的数据写入何处。发出此请求前，您需要准备：
  • 您的 LangSmith API 密钥 和 工作区 ID。
  • 一个 S3 或 S3 兼容的存储桶，并已授予 LangSmith 写入权限（请参阅 所需权限）。
  • 存储桶名称、前缀，以及 AWS 区域（对于 AWS S3）或端点 URL（对于 GCS、MinIO 或其他 S3 兼容提供商）。
  • 存储桶的访问密钥和秘密密钥。
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"
    }
  }'
凭证以加密形式安全存储。API 将在保存前验证目标和凭证的有效性。如果请求失败，请参考 调试目标错误。 保存响应中的 id；创建导出作业时将需要它。 有关权限设置、特定提供商配置（AWS S3、GCS、MinIO）和凭证选项，请参阅 管理批量导出目标。

​
2. 创建导出作业

导出作业针对特定的项目和日期范围。您需要：
  • 来自 上一步 的目标 id。
  • 项目 ID (session_id)——从 追踪项目 列表 中的单个项目视图中复制。
  • UTC ISO 8601 格式的 start_time 和 end_time。
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-03T00:00:00Z",
    "format_version": "v2_beta"
  }'
start_time 是包含的，end_time 是排除的。导出将包括所有满足 run.start_time >= start_time 且 run.start_time < end_time 的运行。 保存响应中的 id 以监控导出进度。 您可以选择添加 filter 表达式来缩小导出的运行集。有关语法，请参考我们的 过滤查询语言 和 示例。不设置 filter 字段将导出所有运行。

​
计划定期导出

需要 LangSmith Helm 版本 >= 0.10.42（应用版本 >= 0.10.109）
计划导出会定期收集运行并导出到配置的目标。 要创建计划导出，请包含 interval_hours 并省略 end_time： 
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",
    "interval_hours": 1,
    "format_version": "v2_beta"
  }'
  • interval_hours 必须在 1 到 168（1 周）之间（含）。
  • 对于计划导出，必须省略 end_time；对于一次性导出，它仍然是必需的。
  • 每个派生的导出覆盖 start_time 到 start_time + interval_hours，然后为每个后续运行前进 interval_hours。由于 end_time 是排除的，连续的导出不会重叠。
  • 派生的导出在 end_time + 10 分钟 运行，以考虑在最近过去提交的带有 end_time 的运行。
  • 派生的导出具有填充的 source_bulk_export_id 属性。如果需要，必须单独取消它们——取消源导出 不会 取消已派生的导出。
  • 要停止计划导出，请 取消它。
示例 如果创建了一个计划批量导出，其 start_time=2025-07-16T00:00:00Z 且 interval_hours=6：
导出开始时间结束时间运行时间
12025-07-16T00:00:00Z2025-07-16T06:00:00Z2025-07-16T06:10:00Z
22025-07-16T06:00:00Z2025-07-16T12:00:00Z2025-07-16T12:10:00Z
32025-07-16T12:00:00Z2025-07-16T18:00:00Z2025-07-16T18:10:00Z

​
限制导出字段

需要 LangSmith Helm 版本 >= 0.12.11（应用版本 >= 0.12.42）。在一次性导出和计划导出中均受支持。
您可以通过使用 export_fields 参数限制包含哪些字段来提高导出速度并减小文件大小。省略时，将包含所有字段。 
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-03T00:00:00Z",
    "export_fields": ["id", "name", "run_type", "start_time", "end_time", "status", "total_tokens", "total_cost"],
    "format_version": "v2_beta"
  }'
排除 inputs 和 outputs 可以显著提高导出性能并减小文件大小，特别是对于大型运行。仅在分析需要时才包含这些字段。

​
可导出的字段

默认情况下，批量导出为每个运行包含以下字段： 标识符与层次结构：
字段描述
id运行 ID
tenant_id工作区/租户 ID
session_id项目/会话 ID
trace_id追踪 ID
parent_run_id父运行 ID
parent_run_ids所有父运行 ID 的列表
reference_example_id如果属于数据集，则引用示例
基本元数据：
字段描述
name运行名称
run_type运行类型（例如，“chain”、“llm”、“tool”）
start_time开始时间戳（UTC）
end_time结束时间戳（UTC）
status运行状态（例如，“success”、“error”）
is_root是否为根级运行
dotted_order层次排序字符串
trace_tier追踪层级/保留级别
运行数据：
字段描述
inputs运行输入（JSON）
outputs运行输出（JSON）
error如果失败，错误消息
extra额外元数据（JSON）
events运行事件（JSON）
标签与反馈：
字段描述
tags标签列表
feedback_stats反馈统计（JSON）
令牌使用与成本：
字段描述
total_tokens总令牌数
prompt_tokens提示令牌数
completion_tokens完成令牌数
total_cost总成本
prompt_cost提示成本
completion_cost完成成本
first_token_time首次令牌时间

​
分区方案

数据使用以下 Hive 分区结构导出到您的存储桶： 
<bucket>/<prefix>/export_id=<export_id>/tenant_id=<tenant_id>/session_id=<session_id>/runs/year=<year>/month=<month>/day=<day>

​
3. 监控您的导出

使用来自 上一步 的 id 轮询导出状态： 
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'
响应中的 status 字段将是以下之一：CREATED、RUNNING、COMPLETED、FAILED、CANCELLED 或 TIMEDOUT。导出时间可能因数据量而异。一旦状态变为 COMPLETED，Parquet 文件即可在您的存储桶中使用。 有关如何列出运行、停止导出和诊断故障，请参阅 监控和故障排除批量导出。
Edit this page on GitHub or file an issue.
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.