From 394d08db6884a4e786fb4e4654ee20cfcf730976 Mon Sep 17 00:00:00 2001 From: bot_dev1 Date: Wed, 5 Aug 2026 04:23:56 +0800 Subject: [PATCH] =?UTF-8?q?feat(#91):=20[M5]=20=E7=94=A8=E6=88=B7=E6=89=8B?= =?UTF-8?q?=E5=86=8C/=E9=83=A8=E7=BD=B2=E6=89=8B=E5=86=8C=E7=BC=96?= =?UTF-8?q?=E5=86=99=EF=BC=88=E4=B8=9A=E5=8A=A1=E7=94=A8=E6=88=B7=E4=B8=89?= =?UTF-8?q?=E7=B1=BB=E5=9C=BA=E6=99=AF+Helm=E9=83=A8=E7=BD=B2/=E5=90=8E?= =?UTF-8?q?=E7=AB=AF=E5=88=87=E6=8D=A2/=E5=B7=A1=E6=A3=80/=E7=81=B0?= =?UTF-8?q?=E5=BA=A6=E5=9B=9E=E6=BB=9A+=E4=B8=80=E8=87=B4=E6=80=A7?= =?UTF-8?q?=E6=A0=B8=E5=AF=B9=E8=84=9A=E6=9C=AC=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/README.md | 2 + docs/_check_user_deploy_manual.py | 105 ++++++++++++++++++ docs/用户手册.md | 117 ++++++++++++++++++++ docs/部署手册.md | 178 ++++++++++++++++++++++++++++++ 4 files changed, 402 insertions(+) create mode 100644 docs/_check_user_deploy_manual.py create mode 100644 docs/用户手册.md create mode 100644 docs/部署手册.md diff --git a/docs/README.md b/docs/README.md index 1693136..407e46f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,6 +6,8 @@ | 文档 | 说明 | 版本 | |------|------|------| +| [用户手册.md](./用户手册.md) | **最终业务用户手册**（监控/优化/LLM 助手三类场景，面向工艺工程师/值班长/管理者） | v1.0 | +| [部署手册.md](./部署手册.md) | **运维/交付部署手册**（Helm 一键部署、后端切换、健康巡检、灰度回滚） | v1.0 | | [产品设计文档_iAOP.md](./产品设计文档_iAOP.md) | **PRD 主文件**（开发依据） | v1.2 | | [产品设计文档_iAOP_对外评审.docx](./产品设计文档_iAOP_对外评审.docx) | 对外评审版（Word，含内嵌架构/流程/ER 图） | v1.2 | | [产品设计评审_iAOP.pptx](./产品设计评审_iAOP.pptx) | 内部评审/汇报版幻灯片 | v1.2 | diff --git a/docs/_check_user_deploy_manual.py b/docs/_check_user_deploy_manual.py new file mode 100644 index 0000000..7fb4e9d --- /dev/null +++ b/docs/_check_user_deploy_manual.py @@ -0,0 +1,105 @@ +# -*- coding: utf-8 -*- +"""用户手册 / 部署手册（issue #91）文档一致性检查。 + +检查项： +1. 两份手册必备章节齐全； +2. 关键红线 / 验收关键词存在（PRD §5.6 / §7.7 / §9 NFR）； +3. 跨文档引用与配套资产路径存在； +4. 角色画像 / 场景流关键词存在（PRD §2 角色画像）。 + +用法：python _check_user_deploy_manual.py +""" +import os +import sys + +HERE = os.path.dirname(os.path.abspath(__file__)) +USER_DOC = os.path.join(HERE, "用户手册.md") +DEPLOY_DOC = os.path.join(HERE, "部署手册.md") + +USER_SECTIONS = [ + "## 1. 平台简介", + "## 2. 角色与权限（RBAC）", + "## 3. 登录", + "## 4. 场景 A：实时监控与告警处置", + "## 5. 场景 B：工艺优化", + "## 6. 场景 C：LLM 自然语言助手", + "## 7. 交接班报告", + "## 8. 常见问题（FAQ）", +] + +DEPLOY_SECTIONS = [ + "## 1. 部署目标与边界", + "## 2. 环境要求（前置条件）", + "## 3. 一键部署（Quick Start）", + "## 4. 配置点速查（values.yaml）", + "## 5. 健康巡检（可用性 ≥ 99.8%）", + "## 6. 灰度发布与回滚", + "## 7. 升级流程", + "## 8. 故障排查（SOP）", +] + +USER_KEYWORDS = ["可溯源", "敏感度", "DLP", "交接班", "驾驶舱"] +DEPLOY_KEYWORDS = [ + "inference.backend", # 后端可切换配置点 + "nvidia-5090", + "ascend-910b", + "99.8%", # 可用性验收口径 + "helm install", + "helm rollback", +] + +# 必须存在的配套资产路径（相对仓库根） +ASSET_PATHS = [ + "deploy/k8s/helm/iaop/README.md", + "deploy/k8s/helm/iaop/values.yaml", + "deploy/k8s/healthz/probe_availability.py", +] + + +def main() -> int: + failures = [] + repo_root = os.path.dirname(HERE) + + if not os.path.isfile(USER_DOC): + failures.append("用户手册不存在：用户手册.md") + if not os.path.isfile(DEPLOY_DOC): + failures.append("部署手册不存在：部署手册.md") + + user_text = open(USER_DOC, "r", encoding="utf-8").read() if os.path.isfile(USER_DOC) else "" + deploy_text = open(DEPLOY_DOC, "r", encoding="utf-8").read() if os.path.isfile(DEPLOY_DOC) else "" + + for sec in USER_SECTIONS: + if sec not in user_text: + failures.append(f"用户手册缺少章节：{sec}") + + for sec in DEPLOY_SECTIONS: + if sec not in deploy_text: + failures.append(f"部署手册缺少章节：{sec}") + + for kw in USER_KEYWORDS: + if kw not in user_text: + failures.append(f"用户手册缺少关键词：{kw}") + + for kw in DEPLOY_KEYWORDS: + if kw not in deploy_text: + failures.append(f"部署手册缺少关键词：{kw}") + + # 部署手册必须正确引用用户手册（跨文档链接） + if "用户手册.md" not in deploy_text: + failures.append("部署手册缺少对『用户手册』的引用链接") + + for rel in ASSET_PATHS: + if not os.path.isfile(os.path.join(repo_root, *rel.split("/"))): + failures.append(f"配套资产缺失：{rel}") + + if failures: + print("FAIL") + for f in failures: + print(" -", f) + return 1 + print("OK: 用户手册/部署手册 章节齐全、关键词与配套资产校验通过") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/docs/用户手册.md b/docs/用户手册.md new file mode 100644 index 0000000..645fe33 --- /dev/null +++ b/docs/用户手册.md @@ -0,0 +1,117 @@ +# iAOP 用户手册（User Guide） + +> 对应 issue #91「[M5] 用户手册/部署手册编写」，父 Issue #15（EPIC 跟踪），里程碑 iAOP v1.0 · Template-Ti 一期。 +> 本手册面向 **最终业务用户**（工艺工程师 / 值班长 / 生产管理者），即 PRD §2 角色画像中的张工、李工、王主任。 +> 部署 / 运维操作请见《[部署手册](./部署手册.md)》。 + +## 1. 平台简介 + +iAOP（云美工业 AI 优化平台）= **可配置、可复制的工业 AI 优化内核** + **按行业沉淀的行业模板**。 + +- **内核（iAOP-Core）**：采集 → 模型推理 → LLM 解释 → 驾驶舱呈现，一次建设、多行业复用； +- **行业模板**：氯化车间/海绵钛（Template-Ti）、吸附树脂（Template-Resin）等，决定 ~90% 落地工作量。 + +你日常接触的是**配置化驾驶舱**（Web / 移动端）与 **LLM 自然语言助手**。本手册教你如何用它们完成监控、优化、辅助三类场景。 + +## 2. 角色与权限（RBAC） + +| 角色 | 主要入口 | 权限 | +| --- | --- | --- | +| 工艺工程师 / 值班长（张工、李工） | 驾驶舱、LLM 助手 | 查看实时数据 / 告警 / 趋势；发起查询；接收优化建议并 review | +| 生产管理者（王主任） | 驾驶舱大屏、移动端助手 | 查看 KPI / 趋势 / 报表；接收交接班报告 | + +> 配置台（模板配置台 Template Console）三级权限 Viewer / Editor / Publisher 面向**实施/行业工程师**，普通业务用户无需使用，详见《模板开发手册》。 + +## 3. 登录 + +1. 浏览器打开驾驶舱地址（由实施提供，形如 `http://iaop.example.com`）； +2. 输入管理员分配的账号密码登录； +3. 登录后默认进入「实时监控」驾驶舱。 + +> 移动端：扫描实施提供的二维码，使用同一账号登录（只读模式，支持查看告警 / 报表 / 推送）。 + +## 4. 场景 A：实时监控与告警处置 + +**目标**：及时发现工艺异常并了解原因。 + +1. 进入驾驶舱「实时监控」页： + - **四状态工艺流程视图**：直观展示氯化/还原等工序当前状态（绿/黄/红）； + - **实时趋势**：关键点位（如 `CLF-01.TEMP`）实时曲线； + - **KPI 卡片**：核心指标（如 `Ti_purity` 海绵钛纯度）； + - **告警面板**：当前未确认告警列表。 +2. 当出现红色告警（如炉层温度异常）： + - 点击告警条目 → 系统展示 LLM 生成的**报警解释**（原因 + 处置建议，附引用依据，可溯源）； + - 值班长确认后，按建议处置或转交相关人员； + - 处置完成后在告警面板标注「已确认 / 已处置」。 + +> 不使用 iAOP 时：靠人工盯趋势、微信群喊人，平均 20–40 分钟才发现，且无根因解释。iAOP 将发现到解释压缩到分钟级。 + +## 5. 场景 B：工艺优化（配方 / 参数建议） + +**目标**：给定质量目标，让模型给出参数建议，review 后下发。 + +1. 进入「优化建议」页（一期质量预测 + 炉层杂质预警上线后，二期配方优化 / 跨工序寻优逐步开放）； +2. 输入或确认本批次质量目标（如目标纯度、约束条件）； +3. 系统给出**可溯源优化建议**： + - 建议参数（决策变量取值）； + - 目标函数值与约束满足情况； + - 跨工序权重与依据（引用上游 TiCl₄ 指标 → 下游海绵钛寻优）； +4. 工艺工程师（李工）**review 建议**，确认后下发 DCS； +5. 实际质量反馈回流，持续训练模型。 + +> 建议为「辅助决策」，高利害输出低于信度阈值时系统会提示「需人工确认」。 + +## 6. 场景 C：LLM 自然语言助手 + +**目标**：用自然语言提问，获得带引用的答案 / 报表。 + +支持四类能力： + +| 能力 | 示例提问 | 说明 | +| --- | --- | --- | +| NL 工艺查询 | 「最近一周 CLF-01 温度超标几次？」 | NL→SQL/API，返回数据 + 来源 | +| 报警解释 | （点击告警自动触发） | 原因 + 处置建议 + 引用 | +| 交接班报告 | （班次结束自动生成） | 汇总关键事件/能耗/待办，≤ 2 分钟 | +| 配方 RAG 问答 | 「国标对 XX 指标的要求？」 | 命中领域知识库，强制引用溯源 | + +**安全说明**：平台内置**敏感度分级路由**（准确率 ≥ 96.5%）+ **DLP 防泄漏**（拦截率 100%）：敏感/核心问题在本地 70B 模型闭环，脱敏/通用问题走云端，结果均附引用来源，可追溯。 + +## 7. 交接班报告 + +每班次结束时，系统自动生成交接班报告（汇总关键事件、能耗、待办），并推送给下一班。 + +- 查看入口：驾驶舱「交接班」页 / 移动端推送； +- 报告可导出（PDF）； +- 历史报告在「报告归档」中可检索。 + +> 不使用 iAOP 时：手写记录本 + 口头交代，遗漏率约 15%，夜班回溯困难。 + +## 8. 常见问题（FAQ） + +**Q1：建议 / 解释能否给出依据？** +A：所有 LLM 输出强制引用溯源（返回命中文档片段 + 来源），可点击查看原文。 + +**Q2：数据准吗？多久更新？** +A：采集 P99 ≤ 1.8s，驾驶舱数据准实时刷新；批量写入 5k 点 / 100ms。 + +**Q3：看不到某个功能？** +A：功能按行业模板与里程碑分批开放（一期：监控+预警+LLM；二期：优化寻优）。确认你的模板版本与权限。 + +**Q4：发现数据异常 / 误报怎么办？** +A：在告警面板标注「误报」并留言，系统回流用于模型迭代；紧急情况联系运维（见《部署手册》§8）。 + +## 9. 移动端使用 + +- **只读模式**：查看驾驶舱、接收告警 / 报告推送； +- 登录账号与 Web 一致； +- 支持 ≥ 200 并发只读用户（PRD §9 NFR）。 + +## 10. 帮助与反馈 + +- 使用问题：联系工艺主管或实施工程师； +- 功能建议：在配置台「反馈」入口提交（如已开放）； +- 故障：参考《部署手册》§8 故障排查 SOP，或联系运维 bot_dev。 + +--- + +**维护**：本文档随行业模板与功能开放节奏更新。当前对应 Template-Ti 一期（氯化车间/海绵钛）。 diff --git a/docs/部署手册.md b/docs/部署手册.md new file mode 100644 index 0000000..93368f7 --- /dev/null +++ b/docs/部署手册.md @@ -0,0 +1,178 @@ +# iAOP 部署手册（Deployment Guide） + +> 对应 issue #91「[M5] 用户手册/部署手册编写」，父 Issue #15（EPIC 跟踪），里程碑 iAOP v1.0 · Template-Ti 一期。 +> 配套 PRD §5.6「⑥ 部署底座」与 `deploy/k8s/helm/iaop/`。本手册面向 **运维/交付工程师（bot_dev、现场运维）**。 +> 业务最终用户的日常使用请见《[用户手册](./用户手册.md)》。 + +## 1. 部署目标与边界 + +iAOP 采用「内核 + 行业模板」分层架构，部署目标： + +- **内核（iAOP-Core）**：6 大模块（采集总线 / 模型框架 / LLM 网关 / 配置化驾驶舱 / 部署底座 / 模板配置台）一次部署，多行业复用； +- **行业模板（iAOP-Template）**：作为「模板资产包」随内核发布，切换行业仅改配置不改码。 + +**验收口径（PRD §5.6 / §10）**：内核 + 模板一键 Helm 部署；昇腾后端切换仅需适配层，不改业务代码；可用性 ≥ 99.8%。 + +**本手册覆盖范围**：生产 / 验收环境部署、推理后端切换、健康巡检、灰度与回滚。 +**不覆盖**：商务定价、第三方 License 采购、单厂实施方案（由交付阶段单独产出）。 + +## 2. 环境要求（前置条件） + +### 2.1 软件依赖 + +| 组件 | 版本 | 说明 | +| --- | --- | --- | +| Kubernetes | ≥ 1.26 | 生产集群（建议 3 控制面 + N 工作节点） | +| Helm | ≥ 3.12 | 一键部署工具 | +| kubectl | 与集群匹配 | 集群操作 | +| ArgoCD（可选） | ≥ 2.7 | GitOps 灰度发布 | +| Python | ≥ 3.10 | 探针 / 离线校验脚本运行时 | +| 容器运行时 | containerd ≥ 1.7 | 集群默认即可 | + +### 2.2 推理后端硬件（二选一，PRD §5.6） + +| 后端 (`inference.backend`) | 设备 (`inference.device`) | 运行时 | 驱动要求 | +| --- | --- | --- | --- | +| `gpu` | `nvidia-5090` | vllm / triton | NVIDIA Driver + nvidia-container-toolkit | +| `npu` | `ascend-910b` / `ascend-310p` | mindie / onnx-ascend | CANN 工具链（见 `inference.cannVersion`） | + +> 切换后端 = 改 `values.yaml` 的 `inference.backend` / `inference.device`，业务代码零改动（差异收敛在 `core/inference-backend/` 适配层）。 + +### 2.3 资源配额基线（默认 values，可调） + +| 资源 | requests | limits | +| --- | --- | --- | +| CPU | 2 core | 8 core | +| 内存 | 8 Gi | 32 Gi | +| 模型权重存储 | 100 Gi（PVC） | — | + +> 生产环境建议启用 HPA（`autoscaling.enabled: true`，min 2 / max 8，CPU 70%）。 + +## 3. 一键部署（Quick Start） + +### 3.1 部署内核 + 模板（默认 GPU 后端） + +```bash +# 1) 命名空间（一次性） +kubectl create namespace iaop + +# 2) Helm 一键部署（Chart 在仓库 deploy/k8s/helm/iaop/） +helm install iaop deploy/k8s/helm/iaop \ + -n iaop \ + --set inference.backend=gpu \ + --set inference.device=nvidia-5090 + +# 3) 验证 +kubectl -n iaop rollout status deployment/iaop-inference +kubectl -n iaop get svc iaop-inference # ClusterIP :8000 +``` + +部署成功标志：Deployment 就绪、`/health` 返回 200（见 §5 健康巡检）。 + +### 3.2 切换为华为昇腾 NPU 后端 + +```bash +helm upgrade iaop deploy/k8s/helm/iaop -n iaop \ + --set inference.backend=npu \ + --set inference.device=ascend-910b \ + --set inference.cannVersion=8.0 +``` + +切换行为（模板自动处理，无需手工干预）： + +- `backend-configmap.yaml` 渲染对应后端适配层配置（npu 追加 `cann_version`）； +- `deployment.yaml` 的 nodeSelector 自动切到 `ascend.com/npu=true`（GPU 为 `nvidia.com/gpu=true`）； +- Pod 标签标注 `iaop.ai/inference-backend`，便于灰度与监控分流。 + +### 3.3 开启域名入口（可选） + +```bash +helm upgrade iaop deploy/k8s/helm/iaop -n iaop \ + --set ingress.enabled=true \ + --set ingress.host=iaop.example.com \ + --set ingress.className=nginx +``` + +## 4. 配置点速查（values.yaml） + +完整配置见 `deploy/k8s/helm/iaop/values.yaml`，常用项： + +| 配置点 | values 路径 | 默认 | 说明 | +| --- | --- | --- | --- | +| 推理后端 | `inference.backend` | `gpu` | `gpu` / `npu` | +| 模型名 | `inference.model` | `iaop-ti-cl4-v1` | 随模板切换 | +| 副本数 | `replicaCount` | `2` | 生产 ≥ 2 | +| 滚动策略 | `rollingUpdate` | `maxUnavailable:0, maxSurge:1` | 灰度发布策略 | +| HPA | `autoscaling.enabled` | `false` | 生产建议 `true` | +| 资源配额 | `resources.requests/limits` | 见 §2.3 | CPU/内存 | +| 存储 | `storage.size` | `100Gi` | 模型权重持久卷 | +| 域名 | `ingress.host` | — | 可选 | + +**多环境分离**：用 `values.dev.yaml` / `values.prod.yaml` 覆盖，例如： + +```bash +helm upgrade iaop deploy/k8s/helm/iaop -n iaop \ + -f deploy/k8s/helm/iaop/values.prod.yaml +``` + +## 5. 健康巡检（可用性 ≥ 99.8%） + +部署底座提供可用性探针（EPIC #8 子任务 #61）： + +```bash +# 轮询 60 轮（每 1s），目标可用率 99.8% +python deploy/k8s/healthz/probe_availability.py \ + --endpoints http://:8000 \ + --rounds 60 --interval 1 --target 0.998 +``` + +- 退出码 `0` = 达标（PASS）；`1` = 低于目标（FAIL）； +- 建议以 K8s CronJob 定时执行，FAIL 时触发告警（接 Prometheus / 企业微信）。 + +## 6. 灰度发布与回滚 + +### 6.1 ArgoCD 灰度（推荐） + +Chart 已内置滚动策略（`maxUnavailable: 0, maxSurge: 1`），配合 ArgoCD 可实现 GitOps 灰度： + +```bash +# 1) Chart 纳入 Git 仓库，ArgoCD Application 指向该仓库 +# 2) 升级 = 改 values 并提交，ArgoCD 自动同步 + 滚动 +``` + +### 6.2 Helm 回滚 + +```bash +helm history iaop -n iaop # 查看修订历史 +helm rollback iaop -n iaop # 回滚到上一版本 +``` + +> 模板资产包发布同样走「校验 → 灰度 → 回滚点」流程（PRD §5.7 模板配置台），配置台支持版本 diff 与一键回滚。 + +## 7. 升级流程 + +1. **预演**：在 dev 命名空间用 `values.dev.yaml` 部署，跑通探针与冒烟用例； +2. **生产灰度**：`helm upgrade`，观察 `rollout status` 与探针可用率； +3. **质保观察**：上线后进入 1 个月质保观察期（PRD §7.7），监控 NFR 指标（可用性 ≥ 99.8% / P99 ≤ 1.8s）。 + +## 8. 故障排查（SOP） + +| 现象 | 排查步骤 | +| --- | --- | +| Deployment 不就绪 | `kubectl describe pod` 看 nodeSelector / 镜像 / 资源；GPU/NPU 驱动是否就绪 | +| `/health` 不通 | `kubectl logs`；确认推理后端适配层加载（`core/inference-backend/`） | +| 可用率 < 99.8% | 看探针 FAIL 轮次分布；HPA 是否触发；节点资源是否打满 | +| 推理慢 | 确认 `inference.runtime` 与硬件匹配；检查 `maxTokens/temperature` | + +## 9. 交付物清单（对应 PRD §7.7） + +部署阶段交付： + +- [ ] 内核 + 模板 Helm 一键部署通过（GPU / NPU 各验一次）； +- [ ] 可用性探针连续达标（≥ 99.8%）； +- [ ] 灰度 + 回滚演练通过； +- [ ] 故障排查 SOP（本文 §8）就绪。 + +--- + +**维护**：本文档随部署底座（`deploy/`）演进，版本与 Chart `appVersion` 对齐。模板资产打包发布见 `templates/<行业>/version.yaml`。 -- 2.54.0