exploring-llm-clusters

Name: exploring-llm-clusters
Author: posthog

github.com/posthog数据与数据库76410 次安装今天更新

代码仓库

关于 exploring-llm-clusters

用于探索 LLM 轨迹、生成记录和评估结果聚类的 PostHog 技能。它帮助可观测性用户比较使用模式与指标，并深入检查有代表性的轨迹。

主要功能

01列出聚类任务与运行记录
02检查轨迹、生成和评估聚类
03计算成本、延迟、令牌和错误指标
04查看代表性轨迹
05比较不同运行的聚类

适用场景

01概览 LLM 流量模式
02找出成本或延迟较高的聚类
03调查错误集中的聚类
04比较不同时段的聚类模式

MCP 相关

使用 PostHog MCP 工具列出聚类任务、通过 SQL 查询聚类事件，并检查 LLM 轨迹。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/posthog/skills --skill exploring-llm-clusters

安装后在 Claude Code 中输入/exploring-llm-clusters确认已加载。

附带文件scripts/print_clusters.py

详细介绍

探索 LLM 聚类

在调查 AI 可观测性聚类时使用此技能 — 了解 AI/LLM 流量中存在的模式、比较聚类行为，并深入查看单个聚类。

工具

工具	用途
`posthog:llma-clustering-job-list`	列出团队的聚类作业配置
`posthog:llma-clustering-job-get`	按 ID 获取指定的聚类作业
`posthog:execute-sql`	查询聚类运行事件并计算指标
`posthog:query-llm-traces-list`	查找属于某个聚类的追踪
`posthog:query-llm-trace`	详细检查指定追踪

聚类的工作原理

PostHog 根据嵌入相似度对 LLM 追踪、单次生成或评估事件进行聚类。 Temporal 工作流会定期或按需运行，并生成存储为 $ai_trace_clusters（追踪级）、$ai_generation_clusters（生成级）或 $ai_evaluation_clusters（评估级）的聚类事件。

每个聚类事件包含：

$ai_clustering_run_id — 唯一的运行标识符（格式：<team_id>_<level>_<YYYYMMDD>_<HHMMSS>[_<job_id>]）
$ai_clustering_level — "trace"、"generation" 或 "evaluation"
$ai_window_start / $ai_window_end — 已分析数据的时间窗口
$ai_total_items_analyzed — 已处理的追踪、生成或评估数量
$ai_clusters — 聚类对象的 JSON 数组
$ai_clustering_params — 使用的算法参数

运行开始时，分析窗口即关闭；运行完成后，聚类事件才会生成。因此，聚类事件自身的 timestamp 始终晚于 $ai_window_end，时间差从几秒到几小时不等。窗口仅用于限定已分析的追踪、生成和评估。要查找聚类事件本身，请使用 $ai_clustering_run_id，并设置常规的近期时间范围。

聚类对象结构（位于 `$ai_clusters` 中）

{
  "cluster_id": 0,
  "size": 42,
  "title": "User authentication flows",
  "description": "Traces involving login, signup, and token refresh operations",
  "traces": {
    "<trace_or_generation_id>": {
      "distance_to_centroid": 0.123,
      "rank": 0,
      "x": -2.34,
      "y": 1.56,
      "timestamp": "2026-03-28T10:00:00Z",
      "trace_id": "abc-123",
      "generation_id": "gen-456"
    }
  },
  "centroid_x": -2.1,
  "centroid_y": 1.4
}

cluster_id: -1 是噪声／离群点聚类（不适合归入任何聚类的项目）
traces 中的项目以追踪 ID（追踪级）、生成事件 UUID（生成级）或评估事件 UUID（评估级）为键
rank 按与质心的距离排列项目（0 = 最近）
x、y 是用于可视化的二维坐标（经 UMAP/PCA/t-SNE 降维）

聚类作业

每个团队最多可有 10 个聚类作业。作业定义：

name — 易于理解的标签
analysis_level — "trace"、"generation" 或 "evaluation"
event_filters — 用于限定纳入项目的属性筛选条件
enabled — 是否按计划运行作业

创建同一分析级别的自定义作业时，会自动创建并禁用名为 "Default - traces"、"Default - generations" 和 "Default - evaluations" 的默认作业。

工作流：探索聚类

步骤 1 — 列出近期聚类运行

posthog:execute-sql
SELECT
    toString(properties.$ai_clustering_run_id) AS run_id,
    toString(properties.$ai_clustering_level) AS level,
    toString(properties.$ai_clustering_job_id) AS job_id,
    toString(properties.$ai_clustering_job_name) AS job_name,
    toString(properties.$ai_window_start) AS window_start,
    toString(properties.$ai_window_end) AS window_end,
    toFloat64OrNull(toString(properties.$ai_total_items_analyzed)) AS total_items,
    timestamp
FROM events
WHERE event IN ('$ai_trace_clusters', '$ai_generation_clusters', '$ai_evaluation_clusters')
    AND timestamp >= now() - INTERVAL 14 DAY
ORDER BY timestamp DESC
LIMIT 10

步骤 2 — 获取指定运行的聚类

posthog:execute-sql
SELECT
    toString(properties.$ai_clustering_run_id) AS run_id,
    toString(properties.$ai_clustering_level) AS level,
    toString(properties.$ai_clustering_job_id) AS job_id,
    toString(properties.$ai_clustering_job_name) AS job_name,
    toString(properties.$ai_window_start) AS window_start,
    toString(properties.$ai_window_end) AS window_end,
    toFloat64OrNull(toString(properties.$ai_total_items_analyzed)) AS total_items,
    properties.$ai_clusters AS clusters,
    properties.$ai_clustering_params AS params,
    timestamp
FROM events
WHERE event IN ('$ai_trace_clusters', '$ai_generation_clusters', '$ai_evaluation_clusters')
    AND timestamp >= now() - INTERVAL 14 DAY
    AND toString(properties.$ai_clustering_run_id) = '<run_id>'
ORDER BY timestamp DESC
LIMIT 1

回溯时间范围需足够宽，以涵盖步骤 1 中报告的该运行 timestamp。查询中绝不能使用 $ai_window_start / $ai_window_end 作为范围。聚类事件会在窗口关闭后生成，因此这些范围会返回零行。

clusters 字段是一个 JSON 数组。解析后即可查看聚类标题、数量、描述、可选的 metrics，以及每个聚类的 traces 映射。

重要： clusters JSON 可能非常大（包含数千个带坐标的追踪、生成或评估 ID）。当结果过大而无法内联显示时，会自动保存到文件。使用 scripts/ 中的 print_clusters.py 获取易读的摘要。

步骤 3 — 计算簇的指标

对于跟踪级簇，计算成本／延迟／令牌指标：

posthog:execute-sql
SELECT
    properties.$ai_trace_id as trace_id,
    sum(toFloat(properties.$ai_total_cost_usd)) as total_cost,
    max(toFloat(properties.$ai_latency)) as latency,
    sum(toInt(properties.$ai_input_tokens)) as input_tokens,
    sum(toInt(properties.$ai_output_tokens)) as output_tokens,
    countIf(properties.$ai_is_error = 'true') as error_count
FROM events
WHERE event IN ('$ai_generation', '$ai_embedding', '$ai_span')
    AND timestamp >= parseDateTimeBestEffort('<window_start>')
    AND timestamp <= parseDateTimeBestEffort('<window_end>')
    AND properties.$ai_trace_id IN ('<trace_id_1>', '<trace_id_2>', ...)
GROUP BY trace_id

对于生成级簇，按事件 UUID 匹配：

posthog:execute-sql
SELECT
    toString(uuid) as generation_id,
    toFloat(properties.$ai_total_cost_usd) as cost,
    toFloat(properties.$ai_latency) as latency,
    toInt(properties.$ai_input_tokens) as input_tokens,
    toInt(properties.$ai_output_tokens) as output_tokens,
    if(properties.$ai_is_error = 'true', 1, 0) as is_error
FROM events
WHERE event = '$ai_generation'
    AND timestamp >= parseDateTimeBestEffort('<window_start>')
    AND timestamp <= parseDateTimeBestEffort('<window_end>')
    AND uuid IN ('<gen_uuid_1>', '<gen_uuid_2>', ...)

对于评估级簇，先检查 $ai_clusters 中每个簇的 metrics 字段（例如通过率、N/A 比率、主要评估器名称和平均评审成本）。需要单条评估记录时，按事件 UUID 匹配：

posthog:execute-sql
SELECT
    toString(uuid) AS evaluation_id,
    toString(properties.$ai_trace_id) AS trace_id,
    toString(properties.$ai_target_event_id) AS generation_id,
    toString(properties.$ai_evaluation_name) AS evaluation_name,
    toString(properties.$ai_evaluation_result) AS evaluation_result,
    toString(properties.$ai_evaluation_reasoning) AS evaluation_reasoning,
    toFloatOrNull(toString(properties.$ai_total_cost_usd)) AS judge_cost,
    timestamp
FROM events
WHERE event = '$ai_evaluation'
    AND timestamp >= parseDateTimeBestEffort('<window_start>')
    AND timestamp <= parseDateTimeBestEffort('<window_end>')
    AND uuid IN ('<eval_uuid_1>', '<eval_uuid_2>', ...)

步骤 4 — 深入查看具体跟踪

找到值得关注的簇后，使用跟踪工具检查单条跟踪：

posthog:query-llm-trace
{
  "traceId": "<trace_id_from_cluster>",
  "dateRange": {"date_from": "<window_start>", "date_to": "<window_end>"}
}

需要消息内容时

使用 events 获取簇事件、ID、成本／延迟／令牌指标和评估记录。需要用户消息或完整模型输入／输出时，不要查询 events.properties.$ai_input、$ai_output 或 $ai_output_choices — 这些体积较大的字段位于 posthog.ai_events 中。

对于少量代表性示例，优先使用 query-llm-trace；它会为你读取 posthog.ai_events 并返回完整的事件树。对于批量提取，先从簇中获取跟踪 ID，然后以 trace_id 为锚点查询 posthog.ai_events：

posthog:execute-sql
SELECT
    trace_id,
    timestamp,
    span_id,
    event,
    model,
    input,
    output_choices
FROM posthog.ai_events
WHERE trace_id IN ('<trace_id_1>', '<trace_id_2>', ...)
ORDER BY trace_id, timestamp

posthog.ai_events 的保留期限比 events 短；较旧的簇可能仍有元数据和指标，但不再包含消息内容。如需完整的 $ai_* 事件架构，请加载 exploring-llm-traces 技能。

调查模式

“我们有哪些类型的大模型用量？”

列出近期的聚类运行（步骤 1）
加载最新运行的簇（步骤 2）
查看簇标题和描述——每个簇都代表一种不同的用量模式
比较簇的大小，了解流量分布

“哪个簇成本最高／最慢？”

加载某次运行中的簇（步骤 2）
提取每个簇的跟踪 ID
按簇计算指标（步骤 3）
汇总每个簇的 avg(cost)、avg(latency)、sum(cost)
比较各簇

“这个簇里有什么？”

加载该簇的跟踪（来自 traces 字段）
按 rank 排序（最接近质心的跟踪最具代表性）
使用 query-llm-trace 检查排名前 3-5 的跟踪，了解其模式
查看簇的 title 和 description，了解 AI 生成的摘要

“是否存在错误较多的簇？”

使用 error_count 计算指标（步骤 3）
计算每个簇的错误率：items_with_errors / total_items
重点关注错误率较高的簇
深入查看出错的跟踪，找出根本原因

“不同运行中的簇有何差异？”

列出多次运行（步骤 1）
加载每次运行中的簇
比较簇标题——不同运行中相似的标题表明模式稳定
跟踪簇大小变化，以发现流量模式的变化

构建 UI 链接

簇概览：https://app.posthog.com/ai-observability/clusters
具体运行：https://app.posthog.com/ai-observability/clusters/<url_encoded_run_id>
簇详情：https://app.posthog.com/ai-observability/clusters/<url_encoded_run_id>/<cluster_id>

始终提供这些链接，方便用户在 PostHog UI 中直观验证。

提示

执行 SQL 查询时始终设置时间范围——没有时间边界的集群事件查询速度很慢
按集群事件的发出时间限定搜索范围，而不是按其分析的时间窗口限定——某次运行的 $ai_window_end 早于事件自身的 timestamp
先列出运行以了解整体情况，再深入查看特定集群
集群标题和描述由 AI 生成，是摘要——请通过检查追踪记录进行核实
噪声集群（cluster_id: -1）包含未匹配任何模式的离群点
使用 llma-clustering-job-list 了解当前启用的聚类配置
集群中的追踪 ID 可直接用于 query-llm-trace，以进行深入检查
消息内容位于 posthog.ai_events，而不是 events.properties；除非需要自定义批量 SQL，否则请使用 query-llm-trace
对于大型集群，请检查排名靠前的追踪记录（最接近质心），以获取代表性示例

支持 Markdown

登录后评论

基本信息

作者: posthog
仓库: posthog/skills
分类: 数据与数据库
安装次数: 410
GitHub Stars: 76

报告问题