作业10：企业 AI 平台使用手册

作业目标：把已沉淀的部署与排错文档，升级为一本面向企业的《企业 AI 平台使用手册》。

读者：业务同事（第二～四、六章）、开发对接（第五章）、全员红线（第七章）、运维内部（第八章）。

环境实录：192.168.110.207（Dify 1.16.1 + Xinference + Langfuse + Grafana）+ 116.62.10.183（vLLM qwen3.6-27b）。

HTML：docs/html_cursor/作业10_企业AI平台使用手册_cursor.html

细节排障仍以专题为准，本手册给标准用法与红线。入口索引：内部智能体搭建_文档索引首页_cursor.html。

目录

1. 第一章 平台概述与架构
2. 第二章 快速上手（5 分钟创建你的第一个 AI 助手）
3. 第三章 知识库管理（上传、更新、权限）
4. 第四章 Prompt 编写规范
5. 第五章 API 接入指南
6. 第六章 常见问题 FAQ
7. 第七章 安全与合规红线
8. 第八章 运维排错手册（内部）

第一章 平台概述与架构

1.1 平台解决什么

本平台是企业内部智能体底座，不是公网 ChatGPT 替代品。当前已落地的能力：

控制台：http://192.168.110.207 观测：Langfuse http://192.168.110.207:3000 SLA 大盘：http://192.168.110.207:3001/d/ai-platform-sla（账号向运维领取）

1.2 逻辑架构

业务同事 / 业务系统
        │  浏览器对话，或 API
        ▼
┌─────────────────────────────────────┐
│  Dify 1.16（207）                    │
│  工作室：Agent / Workflow / 知识库    │
│  新 Agent 真正配置在「快照 + 草稿」   │
└──────────────┬──────────────────────┘
               │
     ┌─────────┼──────────┐
     ▼         ▼          ▼
  Qwen3.6-27B  bge-m3    bge-reranker
  vLLM :8000   Xinference :9997
  （GPU 116）   （207 CPU）
     │
     ▼
  Weaviate 向量库（207，经 socat 中继 :8088）
     │
     ▼
  Langfuse :3000  Trace / Token
  Prometheus :9092 + Grafana :3001  SLA

1.3 角色与权限（使用侧）

1.4 关键口诀（全员先记住）

1. 工作室里没有的开关，去工作区「设置 → 模型供应商」，或请运维用 dify_api.py。
2. 改完新 Agent 快照后不要点「发布」，会把 max_tokens 写回空（专题十一）。
3. 知识库页的检索设置 ≠ 对话真正用的设置，新 Agent 还要改快照里的 knowledge（专题十三）。

第二章 快速上手（5 分钟创建你的第一个 AI 助手）

目标：建一个能回答本部门制度的对话助手。完整选项见 专题十五。

2.1 登录

打开 http://192.168.110.207，使用管理员下发的邮箱账号。没有账号走工单，不要共用别人的登录态。

2.2 五分钟路径

先问一句验收：「管理人员需要钉钉打卡吗？」 有引用、能指向打卡/考勤相关段落，即算成功。

2.3 做不到时别硬点

第三章 知识库管理（上传、更新、权限）

3.1 原则

知识库是「可引用的企业内部事实」，不是网盘。只上传现行有效的制度、流程、FAQ。过期文件必须下线或归档，否则助手会答旧规。

本环境示例库：

3.2 上传

1. Dify → 知识库 → 进入目标库 → 添加文件。
2. 优先 PDF / 干净的 Word / Markdown。扫描件先 OCR。
3. 一份制度一个文件，文件名带文号或生效日期，例如 考勤管理办法-2024.pdf。
4. 上传后看状态变成 available。长期 indexing / failed 不要让业务先用（专题六 Weaviate、专题十四）。

分段建议：制度类按条款切，避免一整章揉成一段。命中测试要用业务原话，不要用自己编的摘要句。

3.3 更新

新 Agent 对话走快照。知识库页改了 Top-K / Rerank，还要同步快照，否则命中测试准、对话仍旧。

3.4 权限

红线： 薪酬密表、身份证扫描件、未脱敏客户清单，禁止入库。需要时走专库 + 更小授权范围，并在第七章登记。

3.5 命中测试（上传后必做）

知识库页 → 命中测试，用三句：

1. 文档里的原词（如条款号）。
2. 业务口语（如「怎么请假」）。
3. 曾经答偏的难题（如「法定假日加班费怎么算」）。

第 1 句 0 条 → 入库失败。第 3 句排序离谱 → 开 Rerank（专题十三）。

第四章 Prompt 编写规范

4.1 最短可用模版（知识库问答）

你是企业内部制度助手，只根据已检索到的知识库片段回答。
要求：
1. 先给结论，再列依据（文号/条款号，若片段中有）。
2. 片段没有写的内容，明确说「知识库未收录」，不要编造。
3. 涉及金额、比例、时限，必须原样引用数字。
4. 用户要你绕过制度或提供个人隐私，拒绝并提示走线下流程。

4.2 编写原则

客服分流（作业 2）应写清：请假制度走知识库；报修走工单工具；投诉转人工；其它走兜底话术。

运维助手应写清：只报告探测结果，不擅自 docker rm、不输出密钥。

4.3 改 Prompt 的流程

1. 准备 5 句验收问法（含边界题：「帮我改工资」应拒绝）。
2. 只改指令，其它参数不动。
3. 新开对话再测，旧会话可能带着失败状态。
4. 对比 Langfuse 里本轮是否检索到了预期 chunk。
5. 新 Agent：不要点发布保存指令（用工作室保存/API 写快照，见专题十五）。

第五章 API 接入指南

5.1 先分清两条路

不要把 app_id 当成 agent_id。新 Agent 对话 404「Conversation Not Exists」多半是路径抄错（专题十五）。

5.2 业务系统对接清单（向平台申请）

1. 应用名称、环境（现网仅 207）。
2. 调用方系统名、负责人、预估 QPS。
3. 是否需要知识库引用字段。
4. 超时：建议客户端 ≥ 60s，流式优先。
5. 密钥只放服务器环境变量，禁止写进前端。

公开 Chat 形态示例（旧应用 API Key，占位符）：

curl -N "http://192.168.110.207/v1/chat-messages" \
  -H "Authorization: Bearer <APP_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {},
    "query": "怎么请假",
    "response_mode": "streaming",
    "user": "biz-system-001"
  }'

user 填业务侧稳定用户 ID，便于审计，不要全员同一个 abc。

5.3 控制台自动化（内部脚本）

仓库 dify_api.py 已处理登录、CSRF、密码编码。作业与专题脚本一律：

/usr/bin/python3 /opt/workbuddy/scripts_cursor/<文档名>/xxx.py

不要在业务服务里复制一份管理员密码。需要无头对话，由运维签发应用 API Key，而不是控制台账号。

5.4 限流与成本

作业 4 已有会话 Token 上限与日预算思路。接入方应：

• 单次 query 控制长度；
• 禁止用 API 做压测打满 GPU；
• 批量任务走离峰或独立队列。

第六章 常见问题 FAQ

Q1 为什么有的问题答得很准，换个说法就不会了？ 检索靠向量 +（可选）关键词 + Rerank。口语和条款用词差太远会召不回。先在知识库做命中测试；需要口语覆盖就补充 FAQ 文档，而不是加长 Prompt。

Q2 一直转圈、气泡是空的？ 先新开对话。仍空：Max Tokens 过小（专题十二）、vLLM 排队（专题十四）、或旧会话已 error。不要连点发送。

Q3 知识库明明有文档，助手说不知道？ Agent 可能没绑库，或快照检索与知识库页不一致，或索引不是 available。走第三章命中测试。

Q4 配置页一打开就红条，但聊天还行？ 多半是 OpenAPI 工具 ID 被当成内置插件（专题十六）。聊天可继续，把截图给运维。

Q5 能不能让它上网搜 / 执行服务器命令？ 默认不能。Shell 与任意 HTTP 工具必须单独开通并走第七章评审。

Q6 回答里的数字和制度对不上？ 以知识库原文为准。把问句 + 截图提给知识库管理员做命中测试；不要在 Prompt 里手写「加班费 300%」这种易过期的硬编码。

Q7 我想用自己的 API Key 接公网模型？ 本工作区默认走内网 Qwen。外发模型涉及数据出境，必须走第七章合规，禁止私自改供应商凭据。

Q8 Langfuse 里看不到我的对话？ 新 Agent 工作室没有「监测」菜单，需运维按《Langfuse 连接 Dify》用 API 打开 Tracing。

第七章 安全与合规红线

以下为强制，违反即停用助手并追溯账号。

7.1 数据红线

7.2 密钥与账号

• 控制台密码、Xinference Key、vLLM Bearer、Langfuse PK/SK、应用 API Key 不进代码仓库公开分支、不进 PPT、不进群公告。
• 离职当天关闭账号；共用账号视为违规。
• 前端页面不得内置 API Key。

7.3 工具与外联

7.4 生成内容责任

助手输出不替代盖章制度与法务意见。涉及处分、合同、薪酬以书面制度与人为准。对外转发助手答案须人工确认。

第八章 运维排错手册（内部）

本章给平台运维。业务投诉标准流程见 企业 AI 助手排错 SOP。

先分层、再改一处。禁止一投诉就重启全家桶。

8.1 接到投诉先问三句

1. 哪个应用 / 哪个智能体？
2. 原话怎么问的？有截图吗？
3. 偶发还是全员、全天？

8.2 症状路由

8.3 一分钟分层

命中测试有结果？
  ├─ 否 → 入库 / Weaviate / bge-m3
  └─ 是 → 对话仍差？
         ├─ 快照知识库 / Top-K / Rerank 与库页是否一致
         └─ 是检索排序问题还是 Prompt / 幻觉
GPU 全员慢？ → nvidia-smi / vLLM waiting（作业 5）
单人空泡？ → max_tokens、新开会话
OOM？ → 作业 7 自愈；勿在高峰反复 docker restart

8.4 平台组件速查（207）

脚本一律在 /opt/workbuddy，Python /usr/bin/python3。配置只改 _config.py。

8.5 相关文档（不要改 docs/workbuddy/ 原文）

手册修订