企业 AI 助手排错 SOP（培训与赋能）
面向：运维 / 平台支持（业务找你说「搜不到」「答非所问」「很慢」时用）。
环境：
192.168.110.207（Dify + 知识库 + Xinference + Langfuse）+116.62.10.183（vLLM Qwen3.6-27B）。原则：先分层、再改一处。不要业务一投诉就重启全家桶。
运行环境：业务脚本均在 207 固定目录
/opt/workbuddy执行，Python 为/usr/bin/python3。 Windows 开发机仅保留_probe_*调试脚本；同步命令：python scripts_cursor/完整代码约定/00_部署_workbuddy到207.py。
0. 接到投诉，先问三句话
| 问业务 | 为什么 |
|---|---|
| 哪条应用 / 哪个智能体？ | 新 Agent 读的是快照配置，和知识库页显示可能不一致。 |
| 原话怎么问的？有截图吗？ | 后面要靠同一句做「命中测试」和 Langfuse Trace 对照。 |
| 是偶发还是全员、全天？ | 偶发多半是实例挂了；全员变慢多半是 vLLM 排队或 GPU 打满。 |
然后按症状进下面三节，一次只查一条线。
症状 → 文档路由（培训速查）
| 业务原话 | SOP 章节 | 深入查阅 |
|---|---|---|
| 搜不到/制度里没有 | §1 | 专题三、专题十三、专题十四步骤 3 |
| 答非所问/胡说 | §2 | 专题十三 Rerank、专题十五 提示词 |
| 很慢/卡住/一直思考 | §3 | 专题十二 空泡、专题十四 全篇 |
| 配置页红条 500 | — | 专题十六 |
| 模型列表空 | — | 专题十、专题五 |
1. 业务说「搜不到 / 查不到 / 制度里没有」
先声明： 多数是检索层问题，不是大模型「不会答」。运维优先查下面 三个配置，都 OK 再让业务换问法或提工单给算法同事。
配置 ①：文档是否真的入库（索引是否 available）
| 查什么 | 怎么查 | 不正常长什么样 |
|---|---|---|
| 知识库索引状态 | Dify → 知识库 → 目标库 → 看状态列 | indexing / failed / 长期不变成 available |
| 分段是否进向量库 | 同一页 → 命中测试，用业务原话搜 | 0 条结果，或只有无关标题 |
| Weaviate 是否偶发挂 | 207 上 curl http://192.168.110.207:8088/v1/meta（走中继） | 非 200、时好时坏 → 见专题六 |
结论： 命中测试都 0 条 → 入库/索引/向量库问题，别去改 Prompt。
配置 ②：混合检索（语义 + 关键词）是否按场景开对
本环境默认多是 语义检索（semantic_search + bge-m3）。业务问的是制度编号、条款号、专有名词时，若 关键词权重为 0，容易出现「人眼觉得文档里有，向量搜不到」。
| 查什么 | 在哪里 | 建议 |
|---|---|---|
| 检索方式 | 知识库 → 检索设置 | 制度/条款类：可试 混合检索 或提高 keyword 权重 |
| Top-K | 知识库 + Agent 快照两处 | 只改知识库页不够；新 Agent 读快照（专题十三） |
| Rerank | 同上两处 | 开了 Rerank 后排序变准，但 不会 变魔术召回不存在的段 |
结论： 命中测试用同一问句能搜到 chunk，但 Agent 里搜不到 → 查 Agent 是否绑库、快照 retrieval 是否和知识库一致。
配置 ③：Embedding / 分词链路是否正常（「分词器」在这套里指什么）
在 Dify + Xinference 架构里，运维口头的「分词器」通常对应两件事：
| 层级 | 查什么 | 怎么查 |
|---|---|---|
| Embedding 实例 | bge-m3 是否在跑 | 207：curl -H "Authorization: Bearer <xf-Key>" http://127.0.0.1:9997/v1/models，要有 bge-m3 且 model_type=embedding |
| 关键词检索 | 混合检索时中文分词是否生效 | 命中测试：用文档里确切出现的一串字（如「11.1.6」「300%」）搜；纯语义搜不到、混合能搜到 → 关键词/分词侧要开 |
| 容器重启后实例丢失 | Xinference 起来 ≠ 模型在跑 | 重启后需重新 login + launch bge-m3（及 rerank），否则知识库会从 Agent 列表消失（专题三） |
结论： bge-m3 不在列表 → 先 launch，再测命中；不要先怀疑 Qwen。
「搜不到」运维小结（1 分钟版）
命中测试有结果？
├─ 否 → ① 入库/available ③ bge-m3/weaviate
└─ 是 → Agent 对话仍没有？
├─ 是 → ② 混合检索/Top-K/快照与知识库不一致
└─ 否 → 转第 2 节「答非所问」2. 业务说「答非所问 / 胡说 / 没引用制度」
先分层： 是 没召回对（检索错），还是 召回了但模型没用对（Prompt / 生成错）。 Langfuse 看 Trace，但必须和 Dify 命中测试一起看——当前链路里 Generation 的 Input 往往只有用户原话，看不到逐条 chunk（连接专题已写明）。
第一步：Dify 命中测试（定召回）
- 知识库 → 命中测试，粘贴业务原话。
- 看 前 3 条 片段是否包含能答题的条款（不是只有章节标题）。
| 命中测试 | 含义 |
|---|---|
| 第 1 条就不相关 | 召回问题 → 回到第 1 节三配置；可开/调 Rerank（专题十三） |
| 第 1 条相关，但 Agent 答偏 | 生成 / Prompt 问题 → 继续 Langfuse |
第二步：Langfuse 定 Prompt 还是生成
打开：http://192.168.110.207:3000 → 找到对应 Trace（按时间或问句筛）。
| 看什么 | 召回问题 | Prompt / 生成问题 |
|---|---|---|
| Trace 是否存在 | 无 Trace → 观测没接上（专题 Langfuse 连接） | 有 Trace 继续 |
| 总耗时分布 | 检索/Rerank 阶段极长 | 第二次 Generation 极长 → thinking 吃满 token（专题十二/十四） |
| Generation Output | 答案空、泛、不引用数字 | 答案引用了错条款 → 看是否 Top-K 太大或 Prompt 未约束「仅依据检索」 |
| Input 只有用户一句 | 正常限制；不能单靠 Langfuse 判断召回了哪些 chunk | 必须回命中测试 |
运维口径（可直接念给业务）：
- 「命中测试第一条不对」→ 我们调检索和排序（Rerank、Top-K、混合检索）。
- 「命中测试第一条对，但回答不对」→ 我们查 Agent 提示词、max_tokens、模型是否排队（第 3 节）。
- 「Langfuse 里这轮 Trace 都没有」→ 我们查 Tracing 配置和 worker 日志，不是业务问法问题。
答非所问 · 推荐脚本
# 207 上：复现业务问句的命中测试（完整程序见 scripts_cursor）
/usr/bin/python3 /opt/workbuddy/scripts_cursor/Dify_专题十三_知识库Rerank重排序/专题十三_08_命中测试_修改后.py
# Langfuse：最近 Trace
curl -s -u 'pk-lf-...:sk-lf-...' 'http://127.0.0.1:3000/api/public/traces?limit=5'3. 业务说「很慢 / 卡住 / 一直思考」
先分清： 还在跑、已经失败、还是成功但慢（专题十四）。界面停在 knowledge_base_search 不等于 还在检索——可能是 vLLM 在排队或 thinking 吃 token。
3.1 30 秒分层（207 + 116）
| 层 | 命令 / 位置 | 正常 | 异常 |
|---|---|---|---|
| 检索 | 命中测试计时 | 通常数秒内 | 十几秒+ → CPU Rerank 或 bge-m3 压力（专题十四） |
| vLLM 存活 | 207：curl -s http://116.62.10.183:8000/v1/models | 含 qwen3.6-27b | 超时 / 空 → 专题五 |
| GPU | 116：nvidia-smi | 有余量、无 OOM | 显存顶满、多进程抢卡 |
3.2 看 vLLM「排队」——运维必会三指标
本环境 vLLM 启动参数含 --max-num-seqs 8：同一时刻大约 8 路并发生成，第 9 路开始排队，全员变慢但命中测试仍快。
| 指标 | 怎么看 | 说明 |
|---|---|---|
| ① 并发上限 | 查启动脚本 / 容器 vllm_qwen_run.sh 里 --max-num-seqs | 默认 8；业务人数上去后这是第一瓶颈 |
| ② 正在跑 / 在等 | 116：`docker logs <vllm容器> 2>&1 \ | tail -100` |
| ③ Prometheus（若已开） | 116：`curl -s http://116.62.10.183:8000/metrics \ | grep vllm_num_requests` |
# 116 GPU 机 — 排队与显存一眼扫
nvidia-smi
curl -s http://116.62.10.183:8000/metrics 2>/dev/null | grep -E 'vllm_num_requests_(running|waiting)|vllm_gpu'
docker logs $(docker ps -q -f name=vllm | head -1) 2>&1 | tail -50| 现象 | 判断 | 运维动作（先汇报再动刀） |
|---|---|---|
waiting 长期 > 0 | vLLM 排队 | 限并发、错峰；长期要加卡或降 max-model-len / 换小模型 |
| 显存 90%+ 且 OOM 日志 | KV 不够 | 勿盲目调 gpu-memory-utilization；见专题九共享 GPU 保护 |
| 仅单人慢、GPU 空闲 | 多半 token / thinking | 查 Agent max_tokens、专题十二/十四 |
变慢 · 运维小结
全员慢 + 命中测试快 → 几乎总是 vLLM 排队 / GPU（第 3.2 节）
单人慢 + 答案很长 → max_tokens / thinking（专题十二）
重启后集体挂 → Xinference 实例丢（bge-m3 / rerank 要 relaunch）4. 升级与文档索引（培训用）
| 类型 | 入口文档 | 说明 |
|---|---|---|
| 首次部署 | Dify_Qwen安装配置手册 | 步骤 1～16 主线 |
| 总纲路由 | 内部智能体配置文档专题汇总 | 三步主线+卡点 |
| 新 Agent | Dify_专题十五 | 创建到验收 |
| 可观测 | Langfuse_部署 + Langfuse_连接Dify | Trace |
| 集成环境 | 集成环境部署_Prometheus_Grafana_SLA | Prometheus :9092 / Grafana :3001 / Exporter :8781 |
| 作业验收 | 作业1～作业11 | 实验课 |
| 企业手册 | 作业10_企业AI平台使用手册 | 业务上手 + 合规 + 运维第八章 |
| 白皮书 | 作业11_企业AI平台白皮书 | CTO/入职/作品集 |
| 症状 | 优先打开 |
|---|---|
| 搜不到 / 选不到库 | 专题三、专题十三、专题六 |
| 答非所问 | 专题十三命中测试 + Langfuse 连接专题 |
| 空泡 / token 8192 | 专题十一、十二 |
| 全员变慢 | 专题十四（本文第 3 节的上游） |
| 完整代码怎么跑 | 完整代码约定_cursor.md |
给业务的统一回复模板：
我们已用您这句原话做了知识库命中测试和 Langfuse 链路核对。若是检索排序问题会在 X 小时内调 Top-K/Rerank；若是模型并发排队会在 GPU 侧限流或扩容；若是单条失败会请您新开对话再试，不要用已报错的旧会话。
*文档版本：与 Cursor 专题库同步；实战参数以 /opt/workbuddy/scripts_cursor/Dify_Qwen安装配置手册/_config.py 为准。*