MaxKB 常见问题排查：现象、原因与解决办法
MaxKB 是一款开源项目：飞致云开源的企业知识库问答系统。
下面按「现象 → 可能原因 → 处理办法」整理常见问题。
排查表
| 现象 | 处理办法 |
|---|---|
| 智能体陷入循环 | 设置最大步数和超时，关键步骤改为固定工作流。 |
| 调用外部系统失败 | 增加重试和失败通知，记录请求参数便于排查。 |
| 输出格式不稳定 | 要求结构化输出并做格式校验，不合格时重试。 |
| 费用超出预期 | 给每次运行设上限，监控调用次数，先用小模型处理简单步骤。 |
| 误发消息给客户 | 对外发送前加人工审批节点，测试环境与正式环境分开。 |
通用排查顺序
- 确认账号、额度和网络状态正常。
- 用一份简单材料复现问题，排除材料本身的干扰。
- 检查设置是否被改动（模型、语言、格式等）
- 查看官方状态页或更新日志。
- 仍无法解决时整理复现步骤联系官方支持。
用标准任务做对照测试
线索整理流程
输入：每天从表单收到的客户咨询。
搭建一个流程：新表单提交后，AI 判断咨询类型（报价 / 售后 / 合作 / 其他），提取联系人和需求摘要写入表格，报价类自动通知销售群。分类不确定时标记为「待人工」。
交付前确认：不确定的情况进入人工。
延伸练习
定时提醒与汇总
准备材料：团队群聊或任务看板。
每天下午 6 点汇总今日新增和逾期任务，按负责人分组发送提醒，周五额外输出一周完成情况。
验收标准：提醒内容与看板一致。
多步骤调研任务
适用情况：手头有一个需要多来源信息的问题时。
围绕【主题】做调研：先列出调研计划，再分别检索，最后输出带来源的报告。每个结论注明来源链接，来源之间矛盾时并列呈现。
检查点：矛盾信息被并列呈现。
知识库问答机器人
适用情况：手头有一批产品文档和 FAQ 时。
用这些文档搭建问答机器人：回答只基于文档，找不到答案时回复「这个问题我需要转给同事」，并记录未解决问题供每周补充文档。
验收标准：答不出时不编造。
常见问题：调用外部系统失败
增加重试和失败通知，记录请求参数便于排查。
常见问题：输出格式不稳定
要求结构化输出并做格式校验，不合格时重试。
常见问题：智能体陷入循环
设置最大步数和超时，关键步骤改为固定工作流。
概念补充：工具调用
模型调用外部 API 或函数完成动作的能力。
概念补充：可观测性
记录每一步输入输出与耗时，便于排查和评估。
适合人群：HR 与招聘
HR 与招聘可以用 MaxKB 处理岗位描述撰写、面试题与评估表等工作。需要注意：简历筛选不得以性别、年龄等因素做歧视性判断，候选人信息需妥善保管。
适合人群：销售
销售可以用 MaxKB 处理客户背景调研、跟进邮件与话术等工作。需要注意：客户数据按公司规定处理，报价和承诺以合同为准。
使用提醒
本文基于 MaxKB 公开的定位与通用用法编写，具体功能、套餐与可用地区以官方页面为准，产品更新后界面和名称可能变化。
涉及个人信息、商业机密或受监管数据时，先确认 MaxKB 的数据处理条款，再决定能否使用。