跳到主要内容
版本:v4.24

智能诊断

1. 功能概述​

智能诊断用于辅助排查 DataPipeline 平台运行过程中出现的组件异常、任务失败和性能波动等问题。用户可以通过自然语言描述故障现象,或直接粘贴错误信息;系统将结合已配置的主机、组件、日志及平台运行信息执行分析,并在同一诊断会话中持续展示诊断过程和结论。

智能诊断适用于以下场景:

  • 同步任务启动失败、运行中断或出现异常报错;
  • 任务运行速度下降、延迟增大或吞吐异常;
  • 平台组件状态异常,需要定位关联主机、容器或日志;
  • 已获得错误信息,但尚不明确故障原因和处理方向;
  • 需要汇总排查过程,形成可继续验证的诊断建议。

智能诊断提供的是辅助分析结果。涉及生产环境配置变更、服务重启、数据修复或高风险命令时,应由具备相应权限的人员复核后执行。

2. 功能入口与页面组成​

进入 系统设置 > 智能诊断。页面包含以下两个页签:

页签说明
智能诊断新建和管理诊断会话,输入待排查问题,查看诊断过程与结论。
配置管理配置诊断使用的大语言模型,以及需要访问的主机和组件信息。页面中的“LLM 配置”和“主机与组件配置”默认收起,可按需展开。

智能诊断页由会话列表和会话区组成:

  • 会话列表:展示历史诊断会话,支持新建、选择、重命名和删除会话;会话较多时可滚动到底部加载更多。
  • 会话区:展示用户问题、诊断过程、工具执行进度和诊断回复,并提供问题输入框。
  • 问题输入框:用于输入本次需要排查的问题。一个会话只用于排查一个问题;排查新的独立问题时,应新建会话。

3. 使用前准备​

首次使用前,管理员需要至少完成以下配置:

  1. 配置并验证一个可用的大语言模型-当前仅支持 DeepSeek。
  2. 按部署形态补充需要诊断的主机和组件信息。
  3. 确认组件日志目录可被诊断服务访问。
  4. 确认大语言模型服务、DataPipeline 服务及目标主机之间网络连通。

若仅粘贴错误信息进行通用分析,可以不依赖完整的主机识别结果;但缺少主机、组件或日志配置时,系统能够获取的现场信息会受到限制,诊断结论也可能不完整。

4. 配置大语言模型​

进入 配置管理,展开 LLM 配置,填写或编辑模型配置。当前模型提供方为 DeepSeek

配置项说明
模型提供方选择实际使用的模型服务提供方。可选范围以当前版本页面为准。
当前版本仅支持 DeepSeek。
模型名称填写服务商提供的模型名称。模型需支持工具调用(Tool Calling)。
API Key模型服务的访问密钥。出于安全考虑,已保存的密钥不会回显;编辑时留空表示保留原密钥。首次配置必须填写。
API 地址填写兼容 OpenAI Chat Completions 协议的服务地址。
温度控制回复随机性。诊断场景建议设置为 0~0.3,以提高结果稳定性,默认值为 0.3。
最大 Token 数单次模型回复的最大输出长度,不代表上下文窗口大小。诊断场景建议使用默认值 4096。
流式输出当前智能诊断仅支持非流式模型回复,应保持关闭。诊断工具的执行进度仍可在页面中持续更新。

配置完成后,单击 测试连接 进行验证。测试窗口会展示 API 地址、模型名称、发送的提示词和模型响应。验证成功后,单击 保存配置 使配置生效。

连接失败时,依次检查:

  1. API 地址是否正确且网络可达;
  2. 模型名称是否与服务商提供的名称一致;
  3. API Key 是否有效、是否具有模型调用权限;
  4. 模型接口是否兼容 OpenAI Chat Completions 协议;
  5. 模型是否支持 Tool Calling。

5. 配置主机与组件​

进入 配置管理,展开 主机与组件配置。主机列表展示主机地址、SSH 端口、SSH 用户、组件和操作,可展开查看组件部署目录与日志目录。未配置主机时,列表显示“暂无主机配置”。

5.1 新增主机​

单击 新增主机,填写主机连接信息。新增主机弹窗包含主机地址、SSH 端口、SSH 用户、认证方式及认证凭据。SSH 端口默认填写为 22;认证方式支持密码或上传私钥文件,具体可选项以当前版本页面为准。

配置时应注意:

  • 主机地址、SSH 端口和 SSH 用户必须与实际部署环境一致;
  • 建议使用仅具备查询权限、不具备修改权限的 SSH 账号,降低诊断过程对主机环境造成变更的风险;
  • 使用密码认证时,应填写有效的 SSH 密码;
  • 使用私钥认证时,应先上传可用的 SSH 私钥文件;
  • 编辑已有主机时,密码留空表示保留原密码;
  • 单击 确定 前确认诊断服务能够连接目标主机;单击 取消 或关闭弹窗不会新增主机。

5.2 配置组件​

在主机列表中单击对应主机的 组件配置,扫描或手动补充该主机上的 DataPipeline 组件。

每个组件主要包含以下信息:

配置项说明
组件类型选择该实例对应的 DataPipeline 或基础设施组件类型。
组件名称用于区分同类型的不同实例;未填写时页面可能显示为“未命名”。
部署目录组件在主机上的实际部署位置。
宿主机日志目录组件日志所在的宿主机绝对路径,可配置多个目录。
是否容器化用于区分容器化与非容器化组件,并影响日志读取方式。

日志目录配置规则:

  • 非容器化部署必须填写宿主机日志目录,并使用绝对路径;
  • 容器化部署只填写已经挂载到宿主机的目录;
  • 容器化组件未配置宿主机日志目录时,系统会尝试读取容器内日志;
  • 保存组件配置会全量覆盖该主机原有的组件配置,当前列表中未保留的组件将被删除,提交前应核对完整性。

6. 发起智能诊断​

6.1 新建会话​

  1. 进入 智能诊断 页签。
  2. 单击 新建诊断会话。
  3. 在输入框中描述需要排查的问题。
  4. 发送问题,等待系统分析。

新会话默认名称为“新诊断会话”。系统生成会话后,可通过会话菜单重命名。会话删除后不可恢复,请谨慎操作。

6.2 编写问题​

建议在一个问题中提供以下信息:

  • 故障发生时间或大致时间范围;
  • 任务名称、任务 ID 或相关组件;
  • 当前现象和期望状态;
  • 完整错误信息或关键日志片段;
  • 问题是否可以稳定复现;
  • 故障前是否执行过升级、配置变更、节点变更或任务重启。

示例:

任务 task_1024 从今天 10:20 开始持续延迟,源端写入量没有明显变化。
请检查任务当前运行位置、相关组件日志和资源状态,分析可能原因并给出后续验证建议。
以下是任务启动失败时的错误信息:
[粘贴完整错误信息]
请说明错误发生在哪个阶段、可能原因,以及建议优先检查的配置。

为避免上下文相互干扰,同一会话应围绕同一个故障持续追问。若需要排查另一个任务或无关问题,请新建会话。

6.3 查看诊断过程​

发送问题后,系统会按需调用诊断工具并显示执行进度。页面中的 诊断过程 用于展示当前已执行或正在执行的分析步骤;工具返回的大段内容会由系统保存并按需读取,避免单次对话被大量日志占满。

诊断过程中请保持页面与服务连接正常。一次提问默认最多可触发 50 次工具调用;达到系统限制或发生连接异常时,诊断可能提前结束,此时可根据已有结果缩小问题范围后重新提问。

6.4 继续追问​

系统会在单个会话内保留诊断上下文。用户可以围绕当前问题继续追问,例如:

  • “请说明最可能的根因及判断依据。”
  • “还需要补充哪些日志才能进一步确认?”
  • “请把建议按风险和执行顺序排列。”
  • “当前结论是否会影响任务数据一致性?”

会话较长时,系统会自动压缩早期上下文并保留近期消息,以控制上下文长度。因此,关键任务标识、时间范围或错误信息发生变化时,建议在追问中再次明确。

7. 诊断结果解读与处置​

阅读诊断结果时,应重点核对以下内容:

内容核对要点
现象概述是否准确描述了实际故障和影响范围。
证据是否引用了对应主机、组件、任务或时间范围的日志和运行信息。
原因判断是已确认根因、较高概率原因,还是待验证假设。
建议动作是否包含验证步骤、风险提示和必要的回退措施。
数据风险是否可能影响全量/增量同步、断点续传、数据一致性或任务恢复。

建议按照“先验证、后变更”的顺序处理。涉及以下操作时,不应仅依据模型回复直接执行:

  • 重启或停止生产组件、同步任务;
  • 修改任务位点、清理 checkpoint 或重新初始化任务;
  • 删除或覆盖日志、数据文件和配置文件;
  • 执行 DDL、DML 或可能影响源端、目的端数据的命令;
  • 修改主机资源、网络、账号权限或安全策略。

系统具有高风险命令拦截机制,但不能代替生产变更审批和人工复核。

8. 不同部署形态下的使用说明​

8.1 单机与集群部署​

智能诊断已在单机和集群环境完成测试。集群环境中,应配置涉及诊断的多台主机及其组件,系统可依据日志判断任务容器的源端和目的端分别分配在哪些主机上。

若集群主机配置不完整,系统可能只能看到部分组件或日志,进而影响跨主机故障定位。

8.2 容器化部署​

容器化部署下,系统可结合容器和组件信息定位运行实例。应确保容器日志可访问,或将日志目录挂载到宿主机并在组件配置中填写对应路径。

8.3 非容器化部署​

非容器化部署已通过功能测试,但存在以下限制:

  • 系统不能自动识别全部组件;
  • 系统不能自动识别 DataPipeline 配置;
  • 只有正确配置组件日志路径后,系统才能读取对应日志;
  • 相比容器化部署,首次配置和后续维护成本更高。

因此,非容器化环境应优先保证主机、组件类型、部署目录和日志目录配置准确。

9. 当前能力边界​

  • 智能诊断更擅长基于错误信息、日志和运行信息进行辅助分析,不能保证每次都直接给出唯一根因。
  • 当前模型对 DataPipeline 节点、链路等产品概念的理解仍可能存在偏差。建议提供准确的任务标识和完整错误信息,并人工核对结论。
  • checkpoint 或同步位点类问题,当前主要依据日志中的错误信息进行判断,无法仅凭现象直接确认位点状态。
  • 当前不支持模型回复逐 Token 流式输出;工具执行进度可持续展示。
  • 上下文仅在当前诊断会话内保存,不同会话之间不共享诊断记忆。
  • 外部技能扩展能力当前未开放给用户使用。
  • 本次测试未开展基准性能测试,暂不应据此承诺固定的诊断响应时间或并发性能。

10. 常见问题​

10.1 页面未显示“智能诊断”菜单​

确认当前版本已启用智能诊断功能,并联系管理员检查功能开关及当前账号权限。账号权限规则待以实际环境配置为准。

10.2 模型连接测试失败​

检查 API 地址、模型名称、API Key、网络连通性、接口协议兼容性及 Tool Calling 支持情况。生产环境不建议开启模型调用的 DEBUG 日志,以免输出不必要的请求信息。

10.3 系统无法找到组件或日志​

检查目标主机是否已配置、SSH 连接是否有效、组件类型是否正确、部署目录和日志目录是否为实际路径。非容器化部署必须显式配置日志目录;容器化部署还需确认目录已正确挂载或容器内日志可访问。

10.4 诊断结论与实际环境不一致​

先核对会话中的任务、时间范围、主机和错误信息是否准确,再补充关键日志继续追问。若当前问题与原会话主题不同,应新建会话,避免旧上下文干扰判断。

10.5 是否可以直接执行诊断建议​

不建议。诊断结果属于辅助建议,生产环境操作应经过人工确认和既有变更流程。涉及数据一致性、位点、任务重建、组件重启或高风险命令时,必须评估影响并准备回退方案。