页面用法
- 新建排查:描述问题(必填)。输入框上方可选择问题方向(模型、索引、图谱、问答、平台与依赖、权限与配额)和问题发生时间(默认最近 24 小时),输入框里可选诊断使用的模型(默认组织的对话模型)。具体文档、知识库或对话写在问题里。
- 追问:在同一排查中继续补充信息。诊断助手定位对象有歧义时会列出候选,选择后再继续。
- 回答:先看原因和该做什么。查不到、查询失败或无权限的数据会单独标出,不作为正常结果。
- 排查历史:页面左侧列出当前管理员的排查记录,标题是该排查里最早的一条提问,可删除。
模型测试
页面右上角的「模型测试」:从已配置的模型里选一个,名称后会标出类型(对话、补全、嵌入、Jev)。使用场景随类型变化:对话和补全模型可选对话、知识库问答、后台任务;嵌入模型只有向量索引。测试的是选中的模型按该场景能不能调通。返回是否可用、失败原因和处理建议。需要临时调高日志级别时,到可观测性页面操作。
按轮次 ID 取证
已有一个回合 ID、想绕过诊断助手直接看执行证据时,平台管理员可以调只读接口:
GET /api/v2/admin/diagnostics/turns/{turn_id}/evidence
认证与页面一致:平台管理员的会话 Cookie 或 OAuth Bearer;API Key 不能调用(接口要求用户授权,API Key 请求返回 403)。回合不存在返回 404。
返回分两块:diagnosis 是规则判定的结论(rule、owner、cause、action,中英文各一份);evidence 是支撑证据,含回合状态与时间线、终结失败明细(failure)、该回合逐次模型调用(model_calls)、工具调用统计与失败步骤(tools.trace、first_failed_tool)、子回合(sub_turns)、证据读取计数、回答形态特征(answer_shape)和拼好的日志采集命令(log_command)。
隐私边界与诊断助手一致:不返回用户提问、回答正文、工具入参/出参、工具摘要原文(只返回字符数)和提示词;错误文本已脱敏截断。evidence.missing 里列出的字段表示没有记录到(如旧版本产生的回合、由其他进程终结的回合),是未知而不是正常,回答时应如实说明。
该接口只覆盖执行失败与降级(报错、中断、限流、超窗降级等);回答质量问题(答错、答得不全)不属于它的判定范围,请走差评反馈流程。
查看每轮发给模型的提示词
平台管理员自己在对话里提问时,运行时始终会记下该回合每一轮发给模型的请求:模型、指令、模型可见的工具定义,以及经过历史处理后的消息(含工具调用与结果、证据兜底那一轮)。公开访问点上的访客回合以 Agent 所有者的身份运行,不因所有者是平台管理员、也不因针对该用户的录制规则而记录;管理员自己的预览会话仍按管理员回合记录。组织录制规则按机器人所属组织匹配,因此会覆盖该组织 Agent 的访客回合。要排查某个用户或某个组织的问题,管理员还可以在观测页(Diagnostics 视图)的「提示词录制」里为其开一条录制规则,时长 1 / 3 / 7 天,到期自动失效;同一对象重复添加会替换名称和到期时间,也可以提前删除。命中的回合出现在同一张卡片的「最近记录」里,点开同一抽屉查看每轮提示词。回合结束后,回答下方操作栏也会出现调试图标;与上一轮相同的历史消息默认折叠,每轮可复制为 JSON。
GET /api/v2/agent/chats/{chat_id}/turns/{turn_id}/prompts
GET /api/v2/admin/diagnostics/prompt-trace/rules
POST /api/v2/admin/diagnostics/prompt-trace/rules {kind: "user"|"org", id, days: 1|3|7}
DELETE /api/v2/admin/diagnostics/prompt-trace/rules/{kind}/{id}
GET /api/v2/admin/diagnostics/prompt-trace/turns?limit=50
GET /api/v2/admin/diagnostics/prompt-trace/turns/{turn_id}
只有平台管理员能读这些接口。会话内的读取仍要求对该对话有正常的读取权限;/admin/diagnostics/ 下的列表与详情则面向全部录制记录,不要求该回合对话的读权限。都需要会话 Cookie 或 OAuth Bearer,API Key 请求返回 403。回合不存在、无权读取或没有记录时返回 404。
与上面的取证接口不同,这里返回的是提示词和消息原文,只用于管理员调试,不要转发到 Issue、PR 或聊天里。图片等二进制内容只保留类型和字节数;单个回合的记录超过 8 MiB 后停止记录,返回里的 truncated 为 true。记录保存在 agent_turn_prompt_trace 表,每次写入时顺带删除 7 天前的行。数据边界:在 SaaS 部署上开启录制后,被录制用户的提示词和检索到的文档摘录会写入该表并保留至多 7 天,仅平台管理员可见;只为具体排查开启,结束后删除规则,内容不得复制到 Issue、PR 或聊天里。添加、删除录制规则和查看提示词都会写审计日志,审计条目不含提示词内容。
采集服务器日志:diagnose.sh
诊断需要容器日志时(应用内读不到),在服务器上执行部署目录下的 scripts/diagnose.sh,输出已脱敏的压缩包。
Docker Compose(在部署目录执行):
scripts/diagnose.sh --since 2026-10-18T08:00:00+08:00 --until 2026-10-18T09:00:00+08:00 \
--service api,indexing-worker --id <document_id> --grep "finalize skipped|re-enqueued|dead-lettered"
Kubernetes:
scripts/diagnose.sh --context <集群> --namespace <命名空间> --since 2h \
--service api --id <turn_id> --grep "Agent Runtime V3 turn failed|turn_lease_lost"
共同参数:
| 参数 | 说明 | 默认 |
|---|---|---|
--since <时间> |
起始时间,RFC3339 或相对时长(30m、2h、1d) | 1h |
--until <时间> |
结束时间 | 当前 |
--service <列表> |
服务/组件名,逗号分隔 | 全部应用服务 |
--id <ID> |
只保留含该 ID 的日志行及完整 traceback 段;可重复 | 无 |
--grep <正则> |
关键词过滤(扩展正则) | 无 |
--tail <行数> |
未指定 --since 时的兜底行数 |
200(K8s 300) |
--timeout <秒> |
单条外部命令超时 | 30 |
--output <目录> |
输出目录 | ./apemind-diagnostics-<时间戳> |
K8s 版另有必填 --context、--namespace,可选 --release。
脚本只读:不进容器执行命令、不连数据库、不读 Secret 或 .env 的值;写入前脱敏(连接串密码、常见密钥键名、Authorization 头),逐项记录成败(见输出中的 summary.txt)。发送到组织外部前,请人工检查生成的压缩包。
外置依赖检查清单
应用只能检查自己的连接。外置依赖的服务端问题请客户 DBA 或云控制台提供:
- PostgreSQL(业务库、图库):版本、最大/当前连接数、慢查询、磁盘使用、复制状态(如有)。
- Elasticsearch:集群健康、未分配分片、磁盘水位、JVM 内存。
- Redis:版本、内存使用与上限、淘汰策略、连接数。
- 对象存储:可用性、桶配额、近期错误。
- 向量库:版本、集合状态、磁盘与内存。
移交支持团队
以下情况诊断助手会建议移交,并输出可直接发送的问题描述:判断为产品缺陷、工具都查过仍无法定位、需要研发修改代码。移交时请附带:
- 诊断助手输出的问题描述(现象、时间、对象 ID、平台版本、已检查项与结论)。
- 按建议命令采集的
diagnose.sh压缩包(人工检查后)。 - 外置依赖检查清单的结果(如适用)。
数据外发说明
诊断助手读取的内容仅限元数据、状态、统计和脱敏后的错误摘要(截断并去除连接串、密钥、路径)。不读取文档正文、用户提问或回答原文、chunk、实体名、提示词、key 值。
诊断使用的模型如果是外部服务,上述脱敏后的元数据与错误摘要会发送给该模型服务。对数据外发敏感的场景,请为诊断选择内部部署的模型(新建排查时可指定)。
边界
- 诊断助手只读:不执行任何修复,修复动作只给建议并指向对应页面,由管理员操作。
- 诊断 Bot、诊断工具、诊断 Skill 不出现在任何用户入口、MCP 管理页面或 Skill 库。
- 非平台管理员无法使用页面、接口和诊断 MCP 端点。