跳到主要内容
版本：dev

HertzBeat AI 调查指南

HertzBeat 2.0 alpha 的 AI 工作区使用有边界的只读工具，帮助运维人员调查已有证据。本文覆盖当前 Agent Gateway 和 /ai 工作区，不承诺自动创建监控、修改告警规则、批量管理或任意命令执行。

配置模型提供方​

完成安装并登录后，再打开 AI 工作区。有权限的管理员可以打开模型提供方对话框，新增配置，填写 API 基础地址、模型标识和 API Key，保存后激活。预设项用于方便配置，不代表所有模型都已通过兼容性或输出质量认证。

已激活的数据库配置优先于服务端回退配置。没有激活的数据库配置时，Gateway 使用已设置的 hertzbeat.agent.provider。下面是显式自定义提供方模板，应替换地址和模型，并私下提供密钥：

hertzbeat:
  agent:
    provider:
      type: openai-compatible
      code: custom
      base-url: https://provider.example/v1
      model: your-model-id
      api-key: ${HERTZBEAT_AGENT_PROVIDER_API_KEY:}

这些是当前 Gateway 配置；旧的 spring.ai.openai 聊天配置不能替代 Gateway 提供方选择。不要在配置示例、截图或问题报告中发布密钥。

保存成功不证明远端 API Key、配额、模型或网络已经可用。先发起一个小范围只读调查，并检查真实结果。修改会为后续请求重新加载；如果重新加载失败，之前可用的提供方可能仍然生效，因此重试前应查看实际配置和错误。

明确调查范围​

从服务或监控、命名空间／环境和时间窗口开始。适合的输入示例：

检查 staging 环境中 checkout 服务最近的错误链路。
汇总这条触发中告警的证据，并指出还缺哪些测量值。
比较这个监控的当前指标与选定历史时间窗。
查找这条链路关联的日志，并说明实际查询范围。

这些是输入示例，不是虚构的返回结果，也不保证相应数据存在。应核对实际工具观察、返回范围、时间戳和来源。缺少数据、查询被拒绝、存储不可用和成功的空查询具有不同含义。部分链路、采样 RED 聚合或有上限的查询不能证明数据完整或因果根因。

工具边界限制受支持的操作和查询范围。日志或返回文档中的指令是证据内容，不是修改配置的授权。需要有意调整配置时，应使用正常的监控、告警和设置页面。

运行状态、停止与回放​

工作区展示真实运行状态和可用的工具观察。停止操作取消当前请求；取消状态与超时、其他失败不同。重试发起新尝试，不会把之前的失败改写成成功。取消一个运行不应终止另一个运行的提供方请求。

会话记录和终态按保留期及大小限制持久化，供之后回放。运行时默认保留会话记录 30 天；过大的结构化工具快照可能被明确省略，回放不是无限制的原始响应档案。刷新或重新打开会话后，应保留已存证据及其失败／取消状态。

当前可由运维配置的运行限制包括：

hertzbeat:
  agent:
    runtime:
      model-request-timeout: 360s
      tool-timeout: 180s
      transcript-retention: 30d
      retry:
        max-model-retries: 2

以上是源码默认值，不是本地协议验收使用的短超时、零重试配置。应根据提供方和工作负载有意调整限制。

系统对可识别的敏感模式执行输出脱敏，包括流式输出、错误字段和持久化回放。敏感输出可能缓冲到能够按完整消息安全脱敏之后再展示。这不保证识别任意敏感数据。应避免提交密钥，分享前检查观察结果，并保护会话记录及提供方配置的访问权限。

排错​

现象检查项
未配置提供方激活有效的已保存提供方，或设置 Gateway 回退配置。
鉴权或模型错误根据真实错误检查 API 地址、确切模型标识、凭据和提供方配额；不要根据 API Key 前缀推断有效性。
查询为空核对服务／监控、环境、时间窗，以及对应信号是否已经到达。
查询被拒绝检查受支持的工具范围和权限，不要用任意 SQL 或命令绕过边界。
超时或取消检查终态后，重试一个小请求。恢复尝试与失败运行是两份独立证据。
回放省略工具快照查看明确的大小或可用性原因，不要把省略理解为成功的空查询。
/ai 无法直接刷新核对安装的前后端制品是否匹配，并查看服务端日志。当前安装包直接提供该文档路由；其他路由与 API 仍保留各自的访问规则。

报告问题时，应提供版本／制品、运行状态、提供方类型、脱敏错误和查询范围。排除 API Key、Authorization 请求头和私有遥测。

Alpha 验收边界​

本地验收使用真实 HertzBeat 数据和明确标注的受控协议提供方，覆盖成功读取、无数据、拒绝、超时、取消、并发运行隔离、即时恢复、脱敏和持久化回放。这验证应用策略和传输行为，不测量外部模型质量，也不保证所有提供方或生产规模可靠性。

旧聊天／SOP API 是另一套接口表面。它的会话历史修正不会扩大 Gateway 的只读授权。AI 解释仍需与返回证据核对，不能自动成为操作基础设施的许可。