---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - langchain
  - langsmith
  - data-governance
  - privacy
topic: LangSmith 查询、过滤、采样、脱敏、导出与用量
sources:
  - https://docs.langchain.com/langsmith/big-query-bulk-export
  - https://docs.langchain.com/langsmith/conditional-tracing
  - https://docs.langchain.com/langsmith/export-traces
  - https://docs.langchain.com/langsmith/filter-traces-in-application
  - https://docs.langchain.com/langsmith/granular-usage
  - https://docs.langchain.com/langsmith/mask-inputs-outputs
  - https://docs.langchain.com/langsmith/otel-gateway-trace-redaction
  - https://docs.langchain.com/langsmith/query-threads
  - https://docs.langchain.com/langsmith/sample-traces
  - https://docs.langchain.com/langsmith/semantic-search
  - https://docs.langchain.com/langsmith/trace-query-syntax
last_verified: 2026-08-11
---

# 查询、过滤、采样、脱敏、导出与用量

> [!summary]
> 数据治理的顺序应是：先决定什么不能离开进程，再决定记录多少，最后决定如何检索和导出。UI 隐藏字段不是脱敏，采样也不能替代敏感数据控制。

## 一、三层控制

| 层 | 目标 | 典型机制 |
|---|---|---|
| 内容控制 | 不上传秘密/PII | hide、anonymizer、input/output processor、OTel redaction |
| 数量控制 | 控制成本与吞吐 | conditional tracing、随机采样、用户/project 限额 |
| 使用控制 | 查询、导出、核算 | filter DSL、thread query、bulk export、usage |

## 二、查询模型

UI 的 filter builder 最适合日常排查；SDK/API 的 filter DSL 适合自动化。可筛：

- run name、run type、status/error。
- trace、run、project、thread 标识。
- start/end time、latency、TTFT。
- tags 和 metadata。
- token、input/output/total cost。
- feedback key、score 和是否存在。

DSL 常见思想：

    and(eq(name, "agent"), gt(latency, 2))
    has(metadata, '{"environment":"prod"}')
    and(eq(run_type, "llm"), gt(total_tokens, 1000))

具体字段和操作符以当前 Trace query syntax 为准；不要把 UI 文案直接拼成 DSL。保存的视图应纳入变更审查，因为字段重命名会让规则静默失配。

## 三、Thread 查询

Thread 查询需要 project/session 与 thread ID 语义一致。可查询：

- thread 的 traces/messages。
- thread 时间范围和聚合统计。
- thread 级 feedback。
- 满足 trace filter 的 thread stats。

多轮评估前先验证：

- 相同用户的不同业务会话没有复用 thread ID。
- 同一会话没有因服务重启产生多个 ID。
- 迟到 trace 能进入正确 thread。
- thread idle window 足以覆盖完整会话。

## 四、Semantic Search

语义搜索用于按含义寻找相似 trace，而不是精确条件过滤。适合：

- 找相似失败、用户意图或输出模式。
- 从生产 trace 建候选数据集。
- 辅助聚类与根因分析。

不适合替代：

- ID、时间、环境、状态等精确筛选。
- 合规发现和删除。
- 可重复的告警条件。

生产检索应先用精确过滤缩小环境/版本/时间，再做语义搜索，减少跨租户或跨版本误匹配。

## 五、条件追踪与采样

条件追踪用于按业务条件启停，例如：

- 只追 prod 的特定功能。
- 对内部健康检查禁用。
- 对已获用户同意的会话启用完整 trace。

随机采样用于按比例保留。采样策略要明确：

- root 级决策，整棵 trace 一致，避免只有孤儿子 run。
- 错误、超时、关键租户可提高采样率。
- 采样率写入 metadata，统计时才能校正。
- 先脱敏再采样；未被抽中的数据也可能在采样决策前经过内存/日志。

LangSmith SDK 的采样和 OTel sampler 处于不同层。混合接入时只能指定一个主决策源，避免双重 10% 变成约 1%。

## 六、Mask 与 Anonymizer

常见模式：

- 全隐藏：inputs/outputs 只上传空或固定占位。
- 正则/函数 anonymizer：替换邮箱、电话、账号、token。
- Presidio 或 Amazon Comprehend：实体识别后替换。
- 自定义 processor：按 schema 删除字段或只保留白名单。

批处理回调必须保持输入 run 与输出 run 的数量、顺序、ID 一一对应，否则会把内容写到错误 run。脱敏函数应：

- 对异常 fail closed，不能因识别器失败而上传原文。
- 保留必要结构，例如角色、长度、工具名，而不是破坏整条消息。
- 有确定性占位符，便于同 trace 内关联，但不能可逆。
- 对 attachments、tool arguments、metadata、错误栈分别覆盖。

## 七、OTel Gateway redaction

OTel Collector 可在出口前通过 transform/processor 删除或替换 span attributes/events。它适合统一处理多语言服务，但要注意：

- LangSmith 特有字段、GenAI semantic conventions 和自定义字段都需列入规则。
- 删除 <code>gen_ai.prompt</code> 不会自动删除其他 message/event 属性。
- Collector 日志、debug exporter 和失败队列也可能泄露原文。
- 规则升级要用固定样本回归，避免字段改名后失效。

## 八、导出

SDK export 适合小批查询和脚本；Bulk Export 适合大规模、定期数据管道。可导出 runs、trace/thread 相关字段，近期更新支持显式选择 feedbacks 列。

生产导出要求：

- 固定时间窗口与游标，支持断点续传和去重。
- 输出落到受控对象存储，启用加密、最小权限和生命周期。
- 记录导出 schema/version。
- 对删除/合规请求建立下游传播机制。
- 大文件优先 zstd；自托管旧路径可能仍默认 gzip。

BigQuery Bulk Export 是仓库化方案，不等于实时告警通道。需单独处理分区、成本、schema 演进、重复 run update 和迟到数据。

## 九、Granular Usage

Granular Usage 用于查看组织范围的可计费用量，可按 workspace、项目、保留层等维度过滤/分组。解释数字时区分：

- trace 数与 run 数。
- base/short-lived 与 extended/long-lived retention。
- Observability、Evaluation、Deployment、Gateway/Fleet 等不同产品单位。
- 当前 workspace 页面和组织账单的范围。

不要把 trace UI 当前查询行数当作计费量；采样、保留升级、反馈/annotation queue 行为和组织限额都会影响最终用量。

## 十、治理基线

- [ ] 数据分类表覆盖 prompt、completion、tool、retrieval、metadata、attachment 和 error。
- [ ] SDK 与 OTel 各自只有一套明确的脱敏责任。
- [ ] 采样在 root 统一决策，错误/高价值路径有保留策略。
- [ ] 导出有加密、审计、生命周期和删除传播。
- [ ] 保存的 filter/rule 有 owner、版本和失配监控。
- [ ] 用量按组织、workspace、project 与 retention 层定期对账。