홈 탐색 도움말
가입하기 로그인
zhouyang.xie
/
guanlan-src
1
0
포크 0
파일 이슈 0 풀 리퀘스트 0 위키
트리: 0597a6db58
브랜치 태그
guanlan-src
/
docs
/
说明书_观澜如东样板v2_v0.2.md

说明书_观澜如东样板v2_v0.2.md 13 KB
히스토리 Raw

观澜 · 如东样板 v2 — 离线应用 使用说明书 v0.2 (2026-09-08)

v0.2 变更: 支持 国产化 Linux (银河麒麟 V10 / 统信 UOS 20, x86_64 与 aarch64) · Ollama 离线安装 · Python 多版本机器可指定, 无 3.11+ 时用包内便携运行时 · 修 xzy 测试报告 5 条 (tzdata / 数据路径 / 主轴承跳转 / 报警台数口径 / 报告章节跳转) · 中文表达按 OEM 术语基准替换。

1. 这是什么

一套纯离线的风电场数据分析应用 (如东海上风电场, 西门子 SWT-4.0-130, 38 台): 把运行数据、状态监测、报警、工单、油样落到每台机组的正确部件上, 给出带证据、带边界、带责任人的检修结论; 判断在代码里, 本机模型只负责问答、解释与引用, 不发明结论。软件不含任何联网功能。

包内七个模块 (统一入口 http://127.0.0.1:28084/): | 路径 | 模块 | 用途 | |---|---|---| | / | 中文门户 | 总览 / 系统架构 / 方法 / 经验发现 / 案例 / 文档 (含治理清单) | | /detail/ | 综合详细分析工作台 | 系统矩阵、检修助手、问答区、汇报纸 (含结构化事实契约) | | /cms/ | CMS 振动诊断 | 六层振动模型逐台判读 | | /sim/ /sim/sys/ | 仿真与回放 · 四系统合页 | 液压等系统仿真台 (案例判据标定用) | | /viewer/ | 三维拆装工作台 | 部件层级三维 | | /release/r1 /release/r2 | Release 层 (只读) | 契约生 Verdict / 老结论分层 | | /healthz /api/version | 自检 | 模块状态、指纹 |

2. 系统要求

项 最低 推荐
系统 Windows 10 64 位 · 银河麒麟 V10 · 统信 UOS 20 · Ubuntu 20.04+ · CentOS 8+ Windows 11 / 麒麟 V10 SP3
架构 x86_64 x86_64 或 aarch64 (两套离线轮子都在包内)
Python 3.11+ ; 机器上没有也行 —— 包内带便携运行时 3.12.14 (麒麟/统信自带多为 3.7/3.9, 跑不了本项目依赖) 3.12.x
内存 16 GB 32 GB
磁盘 5 GB + 三维资产 1 GB 另加模型 30–60 GB (SSD)
显卡 (只影响问答/本地审核) 无 (CPU 慢档, 首答 30–60 s) NVIDIA ≥ 12 GB; ≥ 24 GB 可开 27B 升档
Ollama 可选; 离线安装包在 vendor/ollama/ (Windows 1.5 GB / Linux 1.4 GB, 单独交付不在主包) 同左

安装目录不要带空格和中文 (例 D:\guanlan\app 或 /opt/guanlan)。

3. 安装 (首次, 约 10 分钟)

3.1 Windows

  1. 解压 ..._program.zip 到 D:\guanlan\app; 再解压 ..._viewer.zip (得 release\viewer\)、..._deliverables.zip (得 release\如东\)。
  2. 双击 install.bat (或 powershell -ExecutionPolicy Bypass -File install.ps1)。脚本会: 列出机器上所有 Python 并选 ≥3.11 → 没有就解包内便携运行时 → 建 .venv → 从 wheels\win_amd64 离线装依赖 → 写配置 → 装 Ollama (若 vendor\ollama\OllamaSetup.exe 在位, 静默安装) → 自检。
    • 多版本机器指定: install.ps1 -Python "C:\Python312\python.exe"
    • 强制用包内运行时: install.ps1 -UseBundledPython
    • 跳过 Ollama: install.ps1 -SkipOllama
  3. 双击 check.bat 全绿 → start.bat。

3.2 银河麒麟 / 统信 UOS / 其它 Linux

tar 或 unzip 解包到 /opt/guanlan     # 目录不要带空格与中文
cd /opt/guanlan && sh install.sh      # 自动识别发行版与架构, 选 Python, 离线装依赖
# 多版本机器指定: GUANLAN_PY=/usr/bin/python3.11 sh install.sh
.venv/bin/python guanlan.py serve     # 启动; 停止用 ... stop

install.sh 找不到 3.11+ 时自动解包内便携运行时 (vendor/python/cpython-3.12*-<架构>-*.tar.gz), 不需要联网、不需要编译。 Ollama (可选): 包内有 vendor/ollama/ollama-linux-amd64.tar.zst 时

sudo tar -I zstd -C /usr -xf vendor/ollama/ollama-linux-amd64.tar.zst
sudo useradd -r -s /bin/false -m -d /usr/share/ollama ollama    # 已有则跳过
ollama serve &

麒麟/统信若无 zstd: sudo yum install zstd 或 sudo apt install zstd。

3.3 模型 (离线)

在有网机器上 ollama pull qwen3:8b deepseek-r1:14b bge-m3 (显存 ≥24 GB 再 qwen3.8:27b), 然后把整个模型目录拷到内网机同位置:

  • Windows %USERPROFILE%\.ollama\models · Linux /usr/share/ollama/.ollama/models 或 ~/.ollama/models 拷完 ollama list 能看到模型即可。没有模型时问答不可用, 其余页面照常。

3.4 离线件怎么来的 (维护方用)

在有网机器上: python scripts/fetch_offline_deps.py all --targets win_amd64,linux_x86_64,linux_aarch64 下载各平台轮子 + 便携 Python + Ollama 安装包, 校验值写进 vendor/MANIFEST.json。

4. 日常使用

  • 启动: 双击 start.bat (约 10–30 s, 自动打开浏览器到 http://127.0.0.1:28084/)。
  • 停止: 双击 stop.bat。
  • 自检: 双击 check.bat (Python/依赖/数据/发布件/端口/模型/模型可用性检查)。
  • 状态: 终端里 .venv\Scripts\python.exe guanlan.py status。
  • 所有服务只监听本机 (127.0.0.1); 局域网他人访问需要另行配置, 本版不开。

4.1 门户与工作台怎么看

  • 门户每页首屏一句话; "经验发现" 与 "案例" 页的每条结论旁有三枚标签: 证据级 (定论 / 准定论·预警 / 候选 / 参考 / 数据不足 / 撤回)、审级、处置措施 (谁、什么时候、做什么)。候选不进业主正文。
  • 工作台 /detail/: 系统矩阵 (38 台 × 九系统判级) → 点台号看证据窗; 检修助手 (检修四链); 问答区: 选模型 (默认 8B; 复杂问题会自动升档到 27B 并在尾注标明), 回答后自动附"结构化事实契约"引文块; 引不到契约条时会明写"未被契约背书"。汇报纸可导出。
  • /cms/: 每台机组六层判读, 机制未定不点零件。
  • 运维控制台 (2026-09-12 新增; 2026-09-16 起菜单入口为门户「数据重算」): 停/启服务 · 执行重算 · 清除产物 —— 一个按钮一件事。 按钮按真实状态启用 (不能做的动作是灰的; 后端同样校验并返回 409, 直接打 API 也绕不过); "启动服务"起来后会自动打开门户; "停止组件服务"保留控制台本身(否则点完页面就没了); "清除产物"是直接删除、不留备份(2026-09-16 用户令; 要随包件用 scripts\products_restore_missing.py --stash <交付包.zip> 从交付包补齐), 不动 data\raw\。 页面同时显示各服务端口状态、产物件数、逐件来源台账、验收锚点, 以及当前任务的进度/退出码/日志尾巴。

4.2 问答的可信边界

  • 台号与数字必须能回抓到源记录, 回抓不到的句子被校闸拦下并提示; 两档模型都拦则不出文并给原因 (不会硬编)。
  • 模型只转述本体与契约, 不产生新判级; 答案里出现的判级词都来自契约。
  • 模型未启动或崩溃时页面提示"本机模型未启动"(HTTP 503), 不会静默改用别的来源。

5. 离线模型

档 模型 用途 显存
默认问答 qwen3:8b 所有提问首选 ≥ 6 GB (CPU 可跑, 慢)
升档 qwen3.8:27b 8B 校闸没过时自动重答一次 ≥ 20 GB
审核票 deepseek-r1:14b (+ 27B 第二票) 交叉审核初筛 (离线审级, 非独立审级) ≥ 10 GB
检索 bge-m3 向量检索 2 GB

配置在 configs\models.json; 换模型 = 改这里 + ollama pull, 不改任何结论。 模型闸 (src\ontology\llm_gate.py) 对每次调用: 固定随机种子与温度 (同问同证据同答) · 同一时刻只一个生成请求 · 瞬断自动重试一次 · 连续 3 次失败熔断 60 s 并明示 · 每次调用写审计日志 logs\llm_audit.jsonl (模型摘要、提示指纹、参数、耗时、输出指纹)。 已知答案回放: 服务运行中执行 .venv\Scripts\python.exe guanlan.py qa --n 6 --budget 300, 六道固定问题必须出文、引用期望结论编号、校闸全过、在预算内 → 结果在 logs\known_answer_*.json。换模型或升级后必跑。

6. 目录结构

D:\guanlan\app\
  guanlan.py            启动器 (check / serve / status / stop / open / qa)
  start.bat stop.bat check.bat install.ps1
  configs\serve.json    端口、发布目录、Python 路径
  configs\models.json   模型档
  configs\{farms,contracts,canonical}\   场配置、数据契约、canonical 字典
  src\                  分析代码 (windscada / windcms / ontology / sop)
  scripts\              服务与工具脚本
  outputs\rudong\       如东产物: windscada (parquet) / ontology (本体) / sop (findings) / guanlan (事实契约) / windcms / m5_cms_tcm
  release\              门户 portal.html / 仿真服务 / viewer 三维资产 / 如东 治理清单交付件
  resources\            仿真回放资产
  wheels\win_amd64\     离线依赖轮子
  logs\  run\           日志 (各服务 + 模型审计) / 运行时 pid
  docs\                 本说明书、系统设计与样板、系统工程意见

7. 配置

  • 端口: configs\serve.json。注意 v0.1 里网关的上游端口表 (scripts\guanlan_gateway.py ROUTES) 仍是硬编码, 改端口须两处同步 (v0.2 合并)。
  • 数据目录: 本版程序与数据在同一目录; 升级时按 §8 备份 outputs\ 与 release\。
  • 编码: 启动器与批处理已设 PYTHONUTF8=1; 若终端显示乱码, 先 chcp 65001。

8. 每期数据分析与升级

  • 本版 (v0.1) 包内不含从原始 SCADA 重生成产物的链 → 2026-09-12 更新: 重算链已进包。 一条命令: .venv\Scripts\python.exe scripts\rebuild_all.py (含 SCADA 侧 10 个构建器, 逐台读 ~14 GB, 约 15 分钟; 只换了台账类数据时加 --skip-scada, 约 2 分钟); 等价操作: 运维控制台 /ops → "执行重算"。 链路: 放数据 → 三门台账 → 月度派生件 → 补齐缺件 → 本体(码表/铺开/决策链/趋势/检索/参数表) → 本体审计, 并自动重启组件服务 (网关保留, 所以控制台页面不会断)。 两条必须如实知道的边界: ① 随包里有一批产物没有生成端 (如 pitch_daily、pc_monthly_bins、 CMS/TCM 兼容链), 重算后再由随包件补齐 —— 每件的来源逐条记在 outputs\rudong\_provenance.json (raw-derived = 由 data\raw 重算 / shipped = 用随包件补齐); ② 补齐后某页仍无数据, 看 docs\重算缺口与补件清单_v0.1.md (哪件缺 · 卡住哪个页面 · 找谁补 · 补齐判据)。
  • 新一期数据的分析仍可由维护方 (Claude + 工程师) 在分析机上执行, 以更新包交付: 包含新的 outputs\rudong\ 与 release\ 及变化摘要、审级件、人裁记录。有了重算链, 现场换数据也可自行重算, 步骤与验收见 docs\重算操作手册_v0.1.md (§0 一条命令 · §0b 控制台 · §5b 清产物/恢复)。
  • 应用更新包: stop.bat → 把当前 outputs\ 与 release\ 整目录复制到 D:\guanlan\backup\<日期>\ → 解压更新包覆盖 → check.bat → start.bat → 打开 /api/version 核对指纹与更新说明一致。
  • 程序升级: 同上, 先备份再覆盖程序文件; 数据不动; 升级后必跑 check.bat 与 guanlan.py qa。回滚 = 用备份目录覆盖回去。
  • 每期出门前的审级 (离线): 本地两票初筛 + 工程师审; 确诊与含经济数字的结论额外要求数据回抓、两票一致、签字。

9. 常见故障

现象 原因 处理
start.bat 报端口占用 别的程序占了 28084/18033/18020/18791/18792/64292 stop.bat 后重试; 仍占则改 configs\serve.json (见 §7)
页面显示"本机模型未启动" / 问答 503 Ollama 没起或模型没拉 开始菜单启动 Ollama; ollama list 确认模型; check.bat
问答很慢 (> 1 min) CPU 档或显存不足 看 check.bat 的探针耗时; 显存 < 12 GB 时只用 8B, 关掉升档 (models.json profiles)
治理清单页 not found release\如东\ 未解压 解压 _deliverables.zip 到程序目录
三维页空白 release\viewer\ 未解压 解压 _viewer.zip
中文乱码 终端编码 chcp 65001; 启动器已强制 UTF-8
杀毒软件拦截 嵌入 Python 或 Ollama 被误报 把 D:\guanlan 加入信任目录
服务起了页面打不开 浏览器代理把 127.0.0.1 也走代理 浏览器代理例外加 127.0.0.1

日志: logs\gateway.log logs\detail.log logs\cms.log … ; 模型调用: logs\llm_audit.jsonl。

10. 版本与校验

  • 版本号在 VERSION; 包内 SHA256SUMS.txt 列出三个 zip 的校验值, 解压前请核对 (certutil -hashfile <文件> SHA256)。
  • http://127.0.0.1:28084/api/version 显示代码指纹、门户指纹、事实契约条数与 sha。

11. 已知限制 (v0.1, 如实)

  • 本版打包与验证在 macOS 分析机上完成 (同一套 Python 代码, 启动器与安装逻辑为跨平台); Windows 与国产化 Linux 的首装尚未在真实目标机上跑过 —— 首装时请把 check.bat / install.sh 的输出反馈给维护方。
  • Ollama 离线包体积 1.4–1.6 GB, 不在主程序包内, 单独交付 (或用 scripts/fetch_offline_deps.py 自取)。
  • 工作台服务是单文件大程序 (5,000 行), 计划 P2 拆分; 不影响使用。
  • 不含从原始数据重生成产物的链 (P0); 不含训练回路。
  • 问答复杂题 (逐台列举类) 在 27B 升档下可能需要 5–15 分钟。