> ## Documentation Index > Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt > Use this file to discover all available pages before exploring further. # 使用 Insights Agent 发现错误与使用模式 Insights Agent 会自动分析您的追踪数据，以检测使用模式、常见代理行为和故障模式——无需您手动审查成千上万的追踪记录。 Insights 使用层级分类来理解您的数据并突出可操作的趋势。 Insights 适用于 LangSmith Plus 和 Enterprise [计划](https://www.langchain.com/pricing)。 ## 前提条件 * 已在您的工作区中为 Insights 设置好[模型配置](/langsmith/model-configurations)。 * 拥有在 LangSmith 中创建规则的权限（生成新的 Insights 报告所需）。 * 拥有查看 LangSmith 追踪项目的权限（查看现有 Insights 报告所需）。 ## 生成您的第一份 Insights 报告 1. 在左侧菜单中导航到 **Tracing Projects**（追踪项目），并选择一个追踪项目。 2. 点击右上角的 **+New**（新建），然后选择 **New Insights Report**（新建 Insights 报告），以针对该项目生成新的洞察。 3. 为您的任务输入一个名称。 4. 如果您尚未设置，请在工作区设置中为 Insights [配置一个模型](/langsmith/model-configurations)。 5. 回答引导性问题，将您的 Insights 报告聚焦于您想了解的关于代理的信息，然后点击 **Run job**（运行任务）。 切换到手动模式以[手动配置任务](#configure-a-job)。 这将启动一个后台 Insights 报告任务。报告可能需要长达 30 分钟才能完成。 您可以使用 Python SDK 对存储在 LangSmith 之外的数据生成 Insights 报告。这使您能够分析来自生产系统、日志或其他来源的聊天记录。 当您调用 `generate_insights()` 时，SDK 将会： 1. 将您的聊天记录作为追踪上传到一个新的 LangSmith 项目 2. 针对这些上传的追踪生成一份 Insights 报告 3. 返回一个指向 LangSmith UI 中结果的链接 ```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"], # optional if already set as workspace secret ) # 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) 示例中，**Data & Retrieval**（数据与检索）下有 **Vector Stores**（向量存储）和 **Data Ingestion**（数据摄取）等子类别。 ### 单个追踪 您可以通过点击查看追踪表来查看分配给每个类别或子类别的追踪。从那里，您可以点击任何追踪以查看完整的对话详情。 ## 配置任务 您可以使用自动生成的流程或手动配置来创建 Insights 报告。 ### 自动生成配置 1. 打开 **New Insights**（新建洞察），并确保 **Auto**（自动）开关处于激活状态。 2. 回答关于代理目的、您想了解的内容以及追踪结构的自然语言问题。Insights 会将您的答案转换为配置草稿（任务名称、摘要提示、属性和采样默认值）。 3. 选择一个提供商，然后点击 **Generate config**（生成配置）进行预览，或点击 **Run job**（运行任务）立即启动。 **提供有用的上下文** 为获得最佳效果，请为每个提示写一两句话，为代理提供所需的上下文——您试图了解什么，哪些信号或字段最重要，以及您已知的任何无用信息。您对代理功能及其追踪结构的描述越清晰，Insights Agent 就越能以具体、可操作且符合您数据推理方式的方式对示例进行分组。 **描述您的追踪** 解释您的数据是如何组织的——这些是单次运行还是多轮对话？哪些输入和输出包含关键信息？这有助于 Insights Agent 生成专注于重要内容的摘要提示和属性。如果需要，您也可以直接指定[摘要提示](#summary-prompt)部分中的变量。 ### 选择模型 Insights 使用两个模型： * **思考模型**：执行聚类步骤（能力更强，成本更高）。 * **摘要模型**：生成每个追踪的摘要（速度更快，成本更低）。 两个模型都从您在工作区中配置的提供商中选择。当在您的[模型配置](/langsmith/model-configurations)中为 Insights 启用了特定模型时，您可以单独选择它们。如果未配置单个模型，您可以选择一个提供商（OpenAI 或 Anthropic），Insights 将使用该提供商的默认模型。 为获得最佳效果，请为两个角色使用来自同一提供商的模型。 ### 手动配置 手动配置为您提供更多控制权——例如，预定义您希望数据分组到的类别，或针对匹配特定反馈分数和过滤器的追踪。 #### 选择追踪 * **样本大小**：要分析的最大追踪数量。目前上限为 1,000 * **时间范围**：从该时间范围采样追踪 * **过滤器**：额外的追踪过滤器。当您调整过滤器时，您将看到有多少追踪符合您的条件 #### 类别 默认情况下，顶级类别是从底层追踪自下而上自动生成的。 在某些情况下，您预先知道感兴趣的特定类别，并希望任务将追踪分组到这些预定义的类别中。 配置的 **Categories**（类别）部分允许您通过列举所需的顶级类别名称和描述来实现这一点。 子类别仍然由算法在预定义的顶级类别内自动生成。 当任务完成时，发现的顶级类别会自动保存回配置——但前提是配置之前没有定义任何类别。这意味着后续的计划运行将重用这些类别以保持一致性。 #### 摘要提示 任务的第一步是为每个追踪创建一个简短的摘要——然后对这些摘要进行分类。 在摘要中提取正确的信息对于获得有用的类别至关重要。 用于生成这些摘要的提示可以编辑。 编辑提示时需要考虑两件事： * 摘要说明：任何不在追踪摘要中的信息都不会影响生成的类别，因此请确保提供清晰的说明，说明应从每个追踪中提取哪些重要信息。 * 追踪内容：使用 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 报告以按固定周期自动运行。创建或编辑配置时，使用 **Schedule**（计划）部分进行选择： * **Daily**（每天）：每天在 UTC 8:00 运行。 * **Weekly on Monday**（每周一）：每周一在 UTC 8:00 运行。 * **Custom**（自定义）：输入您自己的 cron 表达式（UTC 时间）。 每次计划运行都会使用您保存的配置生成一份新报告。时间范围是动态计算的——例如，“过去 24 小时”始终分析执行时最近的 24 小时窗口。 ## 保存您的配置 您可以选择使用“另存为”按钮保存配置以供将来重复使用。 如果您希望比较随时间变化的 Insights 报告以识别用户和代理行为的变化，这尤其有用。 在创建新的 Insights 报告时，从窗格左上角的下拉菜单中选择先前保存的配置。 ***
[将这些文档连接](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。 [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/langsmith/insights.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。