OG-RAG AI 知识检索服务
EXE 部署与操作用户手册

01系统架构总览

EXE 交付版由 三个可执行文件 构成完整链路，外加一个嵌入模型目录与一套数据文件：

三个 EXE 的分工

核心设计原则（与源码版一致，仍然适用）

02交付物与目录结构 EXE

交付包解压后即为完整运行环境，无需安装 Python、无需 pip install。目录结构（扁平布局，数据文件与 EXE 同级）：

OG-RAG-Release/                    ← 交付根目录（可整体拷贝到任意位置）
├─ OG-RAG-Service.exe              ← RAG 核心服务（:5200）
├─ OG-RAG-Access-Proxy.exe         ← Oxygen 接入代理（:5001）
├─ OG-RAG-Pipeline.exe             ← 流水线工具（命令行）
├─ START-Service.bat               ← 一键启动服务
├─ START-Proxy.bat                 ← 一键启动代理
├─ .env                            ← 配置文件（首次使用前必须填写密钥）
├─ admin.html                      ← 管理控制台页面（浏览器打开）
├─ model_distiluse/
│   └─ distiluse-base-multilingual-cased-v2/   ← 嵌入模型（注意嵌套层级）
├─ metadata.db                     ← 文档元数据库（随交付内容而定）
├─ faiss_index.bin                 ← FAISS 向量索引
├─ og_hypergraph.pkl               ← OG-RAG 超图
└─ doc_ids.npy / doc_texts.npy / df_meta.pkl / bm25_cache.pkl / combined_text_version.txt

03快速开始

04配置文件 .env 详解

.env 位于 EXE 同级目录，Service 与 Proxy 两个 EXE 共用同一份文件。修改后需重启对应 EXE 生效。

4.1 核心必填项

# ─── LLM 接入（Service 使用）───────────────────────────────────────────
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_API_BASE=http://localhost:5003/v1    # 本地 LLM 代理地址（DeepSeek / Kimi 等）
DEFAULT_MODEL=deepseek-v4-flash           # 使用的模型名称

# ─── 文档数据库（最重要，见下方警告）────────────────────────────────────
DB_PATH=metadata.db                        # SQLite 数据库（相对 EXE 目录，或绝对路径）
TOP_DIR=F:/your-project/docs             # 文档根目录（Pipeline 扫描此目录）

4.2 接入代理项（Oxygen 集成必需）EXE

# ─── Moonshot / Kimi 上游（Proxy 使用）─────────────────────────────────
MOONSHOT_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   # 必填，无默认值

# ─── OG-RAG 注入开关（Proxy 使用）──────────────────────────────────────
OGRAG_ENABLED=true          # 启用 OG-RAG 检索
OGRAG_INJECT=true           # 自动向每次对话注入检索片段（默认 false，必须显式开启！）
OGRAG_ENDPOINT=http://127.0.0.1:5200   # 指向 Service
OGRAG_DB_PATH=metadata.db   # DB 直查路径（与 DB_PATH 一致）
PROXY_HOST=0.0.0.0          # 代理监听地址；仅本机使用可改 127.0.0.1

4.3 服务与门户配置

FLASK_SECRET_KEY=your-secret-key-here
FLASK_PUBLIC_URL=https://www.raycontentech.com   # 服务公网地址，用于生成图片/文件 URL
PORTAL_DOC_BASE=https://www.raycontentech.com/leiPage/#/dashboard/workplace
PORTAL_PRO_ID=                                    # 门户项目 ID（可选）
OUTPUT_DIR=F:/outputDir                          # WebHelp 输出目录（可选）

4.4 视觉理解（图片问答）

VISION_API_KEY=your-glm-api-key
VISION_API_BASE=http://127.0.0.1:8000/v1         # 视觉模型代理地址
VISION_MODEL=glm-4.6v
VISION_MAX_TOKENS=1400
VISION_TIMEOUT=99

不配置 VISION_API_KEY 时，图片问答功能自动禁用，其他功能不受影响。

4.5 检索调优参数

MAX_CONTEXTS=15                        # 注入 LLM 的最大文档片段数
MAX_CONTEXT_CHARS=8899                 # 单文档上下文最大字符数
MAX_STEPS_CHARS=2900                   # steps 字段截断长度
EXPAND_CONFIDENCE_THRESHOLD=0.55       # 低于此置信度时触发查询扩展
OG_TOP_K=8                             # OG-RAG 超图检索 top-k
MODEL_LOCAL_PATH=model_distiluse/distiluse-base-multilingual-cased-v2

05数据入库与索引维护 EXE

源码版的三个脚本（handleOriginData.py、update_index.py、build_hypergraph.py）在 EXE 版中合并为 OG-RAG-Pipeline.exe 的三个子命令。在交付目录下打开命令行执行：

5.1 支持的文档格式

5.2 标准入库流程

# 第 1 步：入库（扫描 TOP_DIR → 写入 DB）
OG-RAG-Pipeline.exe extract

# 第 2 步：重建索引（生成 FAISS / BM25 缓存）
OG-RAG-Pipeline.exe reindex

# 第 3 步：重建超图（可选，OG-RAG 关系增强）
OG-RAG-Pipeline.exe hypergraph

# 第 4 步：重启 Service 使新索引生效

5.3 正常入库输出示例

============================================================
handleOriginData v2.6 (HTML enhanced)
  DB=metadata.db  TOP_DIR=F:/git/AI/AUTODEMO
============================================================
  [DITA] 1.5.2 定期维护保养.dita → 1 topic + 28 parameter rows
  [MD]   WHY.md → 3 chunks
============================================================
处理完成:  总文件数 2   DB总记录 31  (FAQ=0 Parameter=28 MD=3)
============================================================

5.4 管理控制台联动 EXE

浏览器打开交付目录中的 admin.html 管理控制台，其中的流水线按钮（数据提取 / 重建索引 / 重建超图 / 全流水线）正是调用 OG-RAG-Pipeline.exe 的对应子命令。因此：

• OG-RAG-Pipeline.exe 必须与 OG-RAG-Service.exe 放在同一目录，否则控制台按钮无效；
• 流水线执行期间避免同时手工运行同名子命令；
• 控制台的"清除缓存"按钮调用 Service 的 /admin/clear_cache，只清查询缓存，不删索引。

5.5 入库字段说明

06服务启动与验证

6.1 启动顺序

6.2 Service 正常启动日志

======================================================================
OG-RAG Portal-Ready Service v5.13 (+parameter Oxygen link fix)
======================================================================
  DB=metadata.db  Model=deepseek-v4-flash
  MAX_CONTEXTS=15  EXPAND_CONFIDENCE_THRESHOLD=0.55
  Vision: ENABLED (glm-4.6v)
======================================================================
Loading embedding model ...
  OK: MODEL_LOCAL_PATH              ← 模型路径正确才会有这行
OK jieba pre-warmed
  Cache valid: 23213 docs (Word/MD=57, Parameter=13490)
OK Indexes loaded (23213 docs)
[HypergraphBuilder] Loaded from og_hypergraph.pkl: 52082 nodes, 104250 edges
OK OG-RAG: 52082 nodes, 104250 edges
 * Running on http://0.0.0.0:5200

6.3 验收：Service /health（:5200）

GET http://127.0.0.1:5200/health

6.4 验收：Proxy /health（:5001）EXE

GET http://127.0.0.1:5001/health

{
  "status": "healthy",
  "version": "1.7-kimi-ograg",       ← 必须是 1.7，低于此版本说明端口被旧进程占用
  "ograg": {
    "enabled": true,
    "inject": true,                  ← 必须为 true，否则 Oxygen 拿不到 RAG 内容
    "endpoint": "http://127.0.0.1:5200",
    "db_exists": true
  }
}

6.5 索引缓存管理

以下缓存文件位于 EXE 同级目录，更换 DB_PATH 后必须全部删除（或在管理控制台执行重建）：

:: 删除缓存（Windows，在交付目录下执行）
del faiss_index.bin doc_ids.npy doc_texts.npy df_meta.pkl bm25_cache.pkl combined_text_version.txt

6.6 注册为 Windows 服务（可选，生产推荐）

双击启动适合测试与演示；生产环境建议使用 NSSM 将两个 EXE 注册为 Windows 服务，实现开机自启与崩溃自愈：

nssm install OGRAG-Service "F:\OG-RAG-Release\OG-RAG-Service.exe"
nssm install OGRAG-Proxy   "F:\OG-RAG-Release\OG-RAG-Access-Proxy.exe"
nssm set OGRAG-Proxy DependOnService OGRAG-Service

07Oxygen AI 集成 EXE

Oxygen XML Editor 的 AI Positron 插件通过 :5001 接入代理使用本系统。代理对每次对话做两件事：

1. 自动注入（OGRAG_INJECT=true）：用用户问题检索 OG-RAG，把最相关的知识库片段作为系统消息注入上下文，模型回答时优先参考并注明来源；
2. 工具拦截（OGRAG_INTERCEPT_TOOLS=true）：模型调用 search_in_project、get_related_resources_overview_from_project 等 4 个检索类工具时，由代理直接在企业知识库执行并回传结果，无需客户端参与。

7.1 AI Positron 配置

在 Oxygen 的 Preferences → AI Positron 中，将 OpenAI 兼容端点指向代理：

7.2 客户端工具注意事项 重要

AI Positron 自带的 Run command line（命令行执行）等客户端工具不在代理可拦截的检索工具集合内。模型一旦选择它，就会改用 shell 命令检索本地项目文件，完全绕开 OG-RAG。代理日志会记录：

工具 ['run_command_line'] 含非检索类调用，透传给客户端执行

规避方法（二选一或并用）：

• 在 AI Positron 设置中禁用 Run command line 类工具；
• 添加自定义指令："检索项目内容时，只使用 search_in_project 等检索工具，禁止运行命令行。"

7.3 端到端验证

08API 接口说明

8.1 Service 接口（:5200）

POST /chat 请求示例

{
  "query": "定期维护保养的时间间隔是多少？",
  "token": "user-session-001",
  "no_history": true
}

8.2 Proxy 接口（:5001）EXE

注意：RAG 核心 Service 本身不提供 /v1/chat/completions；OpenAI 兼容端点只存在于 Proxy。对接第三方应用时一律接 :5001。

09多环境部署（Demo vs 生产隔离）

9.1 为什么需要隔离

生产库（如 ABB、XHSC 项目）包含数万条文档记录。若 Demo 演示指向同一库，检索将返回无关的生产数据，演示效果失真，客户数据也存在泄露风险。

9.2 隔离原则（EXE 版）

每个独立文档集合 = 一份独立的交付目录（EXE + .env + DB + 缓存）

EXE 从自身所在目录读取 .env 与数据文件，因此多环境隔离在 EXE 版中极为简单：整目录复制一份，改 .env 即可，各环境互不干扰。

9.3 推荐目录结构

F:/rag-environments/
├─ autodemo/                  ← Demo 环境（完整交付目录副本）
│   ├─ OG-RAG-Service.exe / OG-RAG-Access-Proxy.exe / OG-RAG-Pipeline.exe
│   ├─ .env                   ← DB_PATH=autodemo.db, TOP_DIR=./docs
│   ├─ autodemo.db
│   ├─ docs/                  ← TOP_DIR
│   └─ model_distiluse/ ...
├─ abb-production/            ← ABB 生产环境（另一份完整副本）
│   ├─ ... .env → DB_PATH=abb_metadata.db ...
└─ xhsc-localization/         ← XHSC 本地化环境

9.4 切换环境步骤

10常见故障排查

故障 1：Oxygen 拿不到 RAG 内容（代理 /health 显示 inject=false）EXE

症状：Oxygen 提问正常返回，但回答不引用企业知识库；代理日志从无 已注入 N 条。

根本原因（按概率排序）：

1. :5001 被旧进程占用——机器上残留旧版 python 代理，Windows 允许重复绑定，新连接被旧进程抢走。判定：netstat -ano | findstr :5001 出现两个 LISTENING；/health 的 version 低于 1.7-kimi-ograg。处置：按 PID 结束旧进程，重启 EXE 代理。
2. .env 中 OGRAG_INJECT 未显式设为 true（该开关默认为 false）。
3. MOONSHOT_API_KEY 为空——代理无法调用上游，但此情形会报 401/鉴权错误而非静默。

故障 2：模型在 Oxygen 里用"Run command line"乱搜本地文件EXE

症状：代理日志出现 工具 ['run_command_line'] 含非检索类调用，透传给客户端执行。

原因：AI Positron 自带的命令行工具不在代理可拦截的检索工具集合内，模型选择它即绕开 OG-RAG。

修复：在 AI Positron 设置中禁用 Run command line，或加自定义指令强制使用检索工具（见第 07 章）。

故障 3：Moonshot 429 错误EXE

故障 4：服务启动日志显示模型加载失败EXE

原因：MODEL_LOCAL_PATH 指向了外层 model_distiluse/ 目录，而真正的模型（含 config.json）在内层 distiluse-base-multilingual-cased-v2/ 子目录。

修复：将 MODEL_LOCAL_PATH 改为指到含 config.json 的那一层（见 4.5 节），重启 Service。

故障 5：管理控制台流水线按钮无响应EXE

原因：打包版中流水线按钮通过调用 OG-RAG-Pipeline.exe 实现。若该文件缺失、被杀软隔离，或与 Service 不在同一目录，按钮即失效。

修复：确认三个 EXE 同目录；检查杀软隔离区；或在命令行手工执行对应子命令（第 05 章）验证工具本身可用。

故障 6：AI 回答内容来自无关的旧项目数据

根本原因：DB_PATH 指向旧生产库，而非当前 TOP_DIR 对应的数据库。

修复：修正 .env 使二者配套 → 删除全部缓存 → OG-RAG-Pipeline.exe extract + reindex → 重启 Service。

故障 7：新增/修改的文档未被检索到

故障 8：服务启动后 documents=0

原因：DB_PATH 指向的数据库文件不存在或为空。修复：确认 .env 中 DB_PATH 相对 EXE 目录解析后的实际位置，先运行 OG-RAG-Pipeline.exe extract 建库。

故障 9：每次启动都重建索引（Cache stale）

原因：combined_text_version.txt 中的 schema 版本与程序内置版本不一致（版本升级后正常现象）。这是自动重建机制，无需干预，重建完成后下次启动即可直接加载。

故障 10：视觉理解模块不可用

排查：确认 .env 已配置 VISION_API_KEY；用 POST /debug_vision 测试连通性；确认视觉代理（:8000）已启动。

故障 11：EXE 无法启动 / 提示 DLL 加载失败EXE

原因：交付包不完整（常见于传输中断或磁盘写满导致的文件损坏）。

修复：重新拷贝完整交付包；确认部署目录所在磁盘剩余空间 ≥ 1.5 GB；确认未在杀毒软件拦截日志中发现 EXE 被隔离。

11已知问题归档

BUG-001：DB_PATH 与 TOP_DIR 不匹配导致检索污染

BUG-002：parameter 行 Oxygen 官方链接持续失效

BUG-004：context_tok 集合导致 RAM 暴涨

EXE 版已内置修复的打包问题 EXE

12运维检查清单

12.1 日常启动检查

• .env 中 DB_PATH 与 TOP_DIR 指向同一业务域
• DB 文件存在且非空（extract 日志中的"DB总记录" > 0）
• MODEL_LOCAL_PATH 指向含 config.json 的内层模型目录
• MOONSHOT_API_KEY / OPENAI_API_KEY 已填写且有效
• :5001 与 :5200 各只有一个 LISTENING（netstat 验证，无旧进程残留）
• Service /health 中 documents > 0 且 status=running
• Proxy /health 中 version=1.7-kimi-ograg 且 ograg.inject=true

12.2 文档更新后操作流程

• 将新文档复制到 TOP_DIR
• 运行 OG-RAG-Pipeline.exe extract（或管理控制台"数据提取"按钮）
• 确认入库日志中新文档出现
• 运行 OG-RAG-Pipeline.exe reindex 重建索引
• 重启 Service，访问 /health 确认 documents 数量已更新
• 用 /debug_score?q=新文档关键词 确认可被检索到

12.3 切换 DB（环境切换）后操作流程

• 修改目标环境目录 .env 中的 DB_PATH 和 TOP_DIR
• 删除全部 6 个缓存文件（见 6.5 节）
• 运行 OG-RAG-Pipeline.exe extract（如目标 DB 为新建）
• 重启 Service 与 Proxy
• 访问 /health 确认 documents 数量符合预期

13附录：字段与检索参考

13.1 doc_type 检索权重倍数

13.2 检索得分组成

总得分 = FAISS 语义得分 (×0.35)
       + BM25 关键词得分 (×0.25)
       + 字段精确匹配加分（title / parent_title / prodinfo / keywords / context）
       × doc_type 权重倍数

13.3 查询扩展触发条件

以下情况不触发查询扩展（即使置信度低于阈值）：

• 查询长度 ≤ 4 字且不含空格
• 查询包含 : 或 =（参数名查询）
• 查询与已知文档标题完全匹配

13.4 Oxygen 官方链接生成规则

生成链接格式：https://www.oxygenxml.com/doc/{guide}/topics/{slug}.html