> ## 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.
# 通过 Insights Agent 发现错误和使用模式
Insights Agent 会自动分析您的追踪数据，以检测使用模式、常见代理行为和故障模式——无需您手动审查成千上万条追踪记录。
Insights 采用分层分类法来理解您的数据，并突出显示可操作的趋势。
Insights 功能适用于 LangSmith Plus 和企业版[套餐](https://www.langchain.com/pricing)。
## 前提条件
* 在您的工作空间中为 Insights 设置好[模型配置](/langsmith/model-configurations)。
* 在 LangSmith 中创建规则的权限（生成新的 Insights 报告所需）。
* 在 LangSmith 中查看追踪项目的权限（查看现有 Insights 报告所需）。
## 生成您的第一份 Insights 报告
1. 在左侧菜单中导航至 **追踪项目**，并选择一个追踪项目。
2. 点击右上角的 **+新建**，然后选择 **新建 Insights 报告**，以基于该项目生成新的洞察。
3. 为您的任务输入一个名称。
4. 如果尚未配置，请在您的工作空间设置中为 Insights [配置一个模型](/langsmith/model-configurations)。
5. 回答引导性问题，将您的 Insights 报告聚焦于您想了解的代理相关信息，然后点击 **运行任务**。
切换到手动模式以[手动配置任务](#configure-a-job)。
这将启动一个后台 Insights 报告任务。报告可能需要长达 30 分钟才能完成。
您可以使用 Python SDK 对存储在 LangSmith 之外的数据生成 Insights 报告。这允许您分析来自生产系统、日志或其他来源的聊天历史记录。
当您调用 `generate_insights()` 时，SDK 将：
1. 将您的聊天历史记录作为追踪数据上传到新的 LangSmith 项目
2. 基于这些上传的追踪数据生成一份 Insights 报告
3. 返回一个指向 LangSmith 用户界面中结果的链接
```python Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import os
from langsmith import Client
client = Client()
chat_histories = [
[
{"role": "user", "content": "how are you"},
{"role": "assistant", "content": "good!"},
],
[
{"role": "user", "content": "do you like art"},
{"role": "assistant", "content": "only Tarkovsky"},
],
]
report = client.generate_insights(
chat_histories=chat_histories,
name="Customer Support Topics - March 2024",
instructions="What are the main topics and questions users are asking about?",
openai_api_key=os.environ["OPENAI_API_KEY"], # 如果已设置为工作空间密钥，则为可选
)
# client.poll_insights(report=report)
```
使用 OpenAI 模型分析 1,000 条对话线程通常花费 \$1.00-\$2.00，使用当前的 Anthropic 模型通常花费 \$3.00-\$4.00。成本随采样的线程数量和每个线程的大小而增加。
## 理解结果
任务完成后，您可以导航到 **Insights** 选项卡，在那里您将看到一个 Insights 报告表格。每个报告都包含基于追踪项目中特定样本追踪数据生成的洞察。
点击进入您的任务，可以看到按一组自动生成的类别组织的追踪数据。
您可以深入查看类别和子类别，以查看底层的追踪数据、反馈和运行统计信息。
### 执行摘要
在每个报告的顶部，您会找到一个执行摘要，其中列出了在您的追踪数据中发现的最重要模式。这包括：
* 关键发现，并附有显示每个模式出现频率的百分比。
* 可点击的引用（例如，#1, #2, #3），指向代理识别为与您的问题特别相关的追踪数据。
### 顶级类别
您的追踪数据会自动分组到代表数据中最广泛模式的顶级类别中。
分布条显示了每个模式出现的频率，便于发现比预期发生更多或更少的行为。
每个类别都有一个简短的描述，并显示其所包含追踪数据的聚合指标，包括：
* 典型的追踪统计信息（如错误率、延迟、成本）
* 来自评估者的反馈分数
* 作为任务一部分提取的[属性](#attributes)
### 子类别
点击任何类别会显示其细分为子类别，这使您能更细致地理解该类追踪数据中的交互模式。
在 [Chat Langchain](https://chat.langchain.com) 示例中，**数据与检索** 下有如 **向量存储** 和 **数据摄取** 这样的子类别。
### 单个追踪数据
您可以点击查看分配给每个类别或子类别的追踪数据，进入追踪数据表格。从那里，您可以点击任何追踪数据以查看完整的对话详情。
## 配置任务
您可以使用自动生成的流程或通过手动配置来创建 Insights 报告。
### 自动生成配置
1. 打开 **新建 Insights** 并确保 **自动** 切换开关处于活动状态。
2. 回答关于您代理的目的、您想了解的内容以及追踪数据结构化的自然语言问题。Insights 会将您的答案转换为一个草稿配置（任务名称、摘要提示、属性和采样默认值）。
3. 选择一个提供商，然后点击 **生成配置** 进行预览，或点击 **运行任务** 立即启动。
**提供有用的上下文**
为了获得最佳结果，请为每个提示写一两句话，为代理提供所需的上下文——您想了解什么、哪些信号或字段最重要，以及任何您已经知道无用的信息。您对代理的功能及其追踪数据结构的描述越清晰，Insights Agent 就越能以一种具体、可操作且符合您数据推理逻辑的方式对示例进行分组。
**描述您的追踪数据**
解释您的数据是如何组织的——这些是单次运行还是多轮对话？哪些输入和输出包含关键信息？这有助于 Insights Agent 生成专注于重要内容的摘要提示和属性。如果需要，您也可以直接指定[摘要提示](#summary-prompt)部分中的变量。
### 选择模型
Insights 使用两种模型：
* **思考模型**：执行聚类步骤（能力更强，成本更高）。
* **摘要模型**：生成每个追踪数据的摘要（速度更快，成本更低）。
这两种模型都是从您在工作空间中配置的提供商中选择的。当您的[模型配置](/langsmith/model-configurations)中已为 Insights 启用了特定模型时，您可以单独选择它们。如果未配置单个模型，您可以选择一个提供商（OpenAI 或 Anthropic），Insights 将使用该提供商的默认模型。
为了获得最佳结果，请为两个角色使用来自同一提供商的模型。
### 手动配置
手动配置为您提供更多控制权——例如，预定义您希望数据分组到的类别，或针对匹配特定反馈分数和筛选条件的追踪数据。
#### 选择追踪数据
* **样本大小**：要分析的最大追踪数据数量。目前上限为 1,000 条
* **时间范围**：从此时间范围内采样追踪数据
* **筛选器**：额外的追踪数据筛选器。调整筛选器时，您将看到有多少追踪数据符合您的条件
#### 类别
默认情况下，顶级类别是从底层追踪数据自底向上自动生成的。
在某些情况下，您事先知道感兴趣的特定类别，并希望任务将追踪数据分到这些预定义的类别中。
配置的 **类别** 部分允许您通过枚举您希望使用的顶级类别的名称和描述来实现这一点。
子类别仍然由算法在预定义的顶级类别内自动生成。
当任务完成时，发现的顶级类别会自动保存回配置中——但前提是配置之前没有定义任何类别。这意味着后续的定时运行将重用这些类别以保持一致性。
#### 摘要提示
任务的第一步是为每条追踪数据创建一个简短的摘要——正是这些摘要随后被分类。
在摘要中提取正确的信息对于获得有用的类别至关重要。
用于生成这些摘要的提示是可以编辑的。
编辑提示时需要考虑的两点是：
* 摘要指令：任何不在追踪摘要中的信息都不会影响生成的类别，因此请确保提供清晰的指令，说明从每条追踪数据中提取哪些重要信息。
* 追踪内容：使用 mustache 格式来指定将每条追踪数据的哪些部分传递给摘要器。包含大量输入和输出的大型追踪数据可能成本高昂且噪声大。将提示减少到仅包含追踪数据中最相关的部分可以改善您的结果。
您必须使用以下至少一个模板变量来指定将每条追踪数据的哪些部分发送给摘要器：
| 变量 | 描述 | 示例 |
| --------------------- | ---------------------------------------------- | ------------------------------ |
| `run.inputs` | 最近一次根运行的输入 | `{{run.inputs}}` |
| `run.outputs` | 最近一次根运行的输出 | `{{run.outputs}}` |
| `run.error` | 错误字符串（如果运行失败） | `{{run.error}}` |
| `run.feedback` | 所有反馈分数的 JSON 数据块 | `{{run.feedback}}` |
| `run.feedback.` | 按键指定的特定反馈分数 | `{{run.feedback.correctness}}` |
| `all_thread_messages` | 线程的完整消息历史记录（仅适用于具有[线程](/langsmith/threads)的项目） | `{{all_thread_messages}}` |
您可以使用点号访问嵌套字段。例如，`{{run.inputs.foo.bar}}` 仅包含最后一次运行输入中 `foo` 内的 `bar` 字段。
对于具有[线程](/langsmith/threads)的项目，Insights 会分析完整的对话。每个线程中只有最近的根运行用于 `run.*` 变量。使用 `all_thread_messages` 来访问完整的对话历史记录。
#### 属性
除了摘要之外，您还可以定义要从每条追踪数据中提取的额外字符串、数值和布尔属性。
这些属性将影响分类步骤——具有相似属性值的追踪数据往往会被归类在一起。
您还可以查看每个类别中这些属性的聚合值。
例如，您可能希望从每条追踪数据中提取属性 `user_satisfied: boolean`，以引导算法将正面和负面用户体验区分开来的类别，并查看每个类别的平均用户满意度。
#### 筛选属性
您可以在布尔属性上使用 `filter_by` 参数，在生成洞察之前预先筛选追踪数据。启用后，只有属性评估为 `true` 的追踪数据才会包含在分析中。
当您希望将 Insights 报告聚焦于特定的追踪数据子集时，这非常有用——例如，仅分析错误、仅检查英语对话，或仅包含符合特定质量标准的追踪数据。
**工作原理：**
* 为 Insights Agent 创建配置时，在任何布尔属性中添加 `"filter_by": true`。
* LLM 在摘要生成过程中根据属性描述评估每条追踪数据。
* 属性为 `false` 或缺失的追踪数据在生成洞察之前被排除。
## 定时运行 Insights 报告
安排 Insights 报告按重复计划自动运行。在创建或编辑配置时，使用 **计划** 部分选择：
* **每日**：每天 UTC 时间 8:00 运行。
* **每周一**：每周一 UTC 时间 8:00 运行。
* **自定义**：输入您自己的 cron 表达式（UTC 时间）。
每个定时运行都会使用您保存的配置生成一份新报告。时间范围是动态计算的——例如，“最近 24 小时”总是在执行时分析最新的 24 小时窗口。
## 保存您的配置
您可以选择使用“另存为”按钮保存配置以供将来重用。
如果您想比较不同时间的 Insights 报告以识别用户和代理行为的变化，这尤其有用。
在创建新的 Insights 报告时，可以在窗格左上角的下拉菜单中选择先前保存的配置。
***
[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/i18n\zh-CN\langsmith\insights.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.