镭内容科技（Ray Content Technologies）是做什么的？

提供 DITA XML / Markdown 内容平台（写管用平台 4.2）、自研 AI 创新翻译平台与 Oxygen XML 解决方案；同时是 Oxygen 增值经销商、Antenna House 中国代理与 Cortona3D 代理商。

是否提供 Adobe FrameMaker 到 DITA XML 的内容迁移？

提供。我们对全量文档做结构化评估，把 FrameMaker、Word、InDesign 内容迁移为 DITA XML，保留标题层级、表格、交叉引用与图片，并在迁移过程中抽取术语库。

支持哪些语言的交付？

支持 80+ 语言，其中中文 / English / Русский 为常规并行交付语种；官方网站本身提供中英俄三语。

◆ 镭内容出色中心

OG-RAG AI 知识检索服务
管理员手册

客户版 v5.10.1 2026-09-01 修订部署 · 配置 · 运维 · 升级

第 1 章　系统概述

1.1 系统是什么

OG-RAG 是一套部署在用户自己服务器上的企业知识检索增强服务：把用户的本地资料（DITA XML、Markdown、Word、PDF、HTML）建成索引，接入用户自己的 LLM（如本地 deepseek 代理），为 AI 对话提供"基于企业资料的准确回答 + 可点击的来源链接"。

🔒 数据不出内网 — 资料、索引、数据库全部在本地；LLM 用用户自己的代理和密钥，北京镭不接触任何数据。

1.2 组件

组件	文件	端口	作用
检索问答服务	`OG-RAG-Service.exe`	5200	核心服务：检索、问答、来源链接、管理接口
资料入库工具	`OG-RAG-Pipeline.exe`	—	扫描资料目录、入库、建索引、建知识图谱
管理台	`static\admin.html`	—	浏览器打开的配置与运维界面
启动脚本	`START-Service.bat`	—	启动服务（请用它，不要直接双击 exe）
授权文件	`license.lic`	—	见第 8 章，勿删勿改

1.3 不在本手册范围

Oxygen XML Editor 插件对接、AI Positron 集成属于另一部署场景，本场景无需关注。

第 2 章　部署要求与安装（六步）

📋 前提：Windows 10/11 或 Server 2016+，64 位；磁盘剩余 ≥ 1.5 GB；用户的 LLM 代理已启动且兼容 OpenAI 协议。

步骤 1：放置交付包

将交付包整体拷贝到目标位置，例如 F:\OG-RAG-Release。路径不要含中文和空格。

步骤 2：确认授权文件

确认根目录存在 license.lic（随包提供）。缺失则服务无法启动，联系北京镭获取。

步骤 3：编辑 .env

用记事本或 VS Code 打开 .env，填写：

# ── 用户的 LLM（地址必须带 /v1 后缀）────────────────────────
OPENAI_API_BASE=http://localhost:5001/v1
OPENAI_API_KEY=用户的密钥（本地代理无鉴权则填任意非空串）
DEFAULT_MODEL=deepseek-pro

# ── 本地资料 ───────────────────────────────────────────────
TOP_DIR=F:/用户的资料目录
DB_PATH=metadata.db

# ── 文档中心前端（生成来源链接用，见第 6 章）─────────────────
PORTAL_DOC_BASE=https://用户的文档中心地址/#/dashboard/workplace
FLASK_PUBLIC_URL=http://本服务器IP:5200

# ── 管理台口令（自行设定强口令）─────────────────────────────
ADMIN_TOKEN=设置一个强口令

步骤 4：首次入库建索引

OG-RAG-Pipeline.exe extract
OG-RAG-Pipeline.exe reindex

extract 扫描 TOP_DIR 解析入库；reindex 重建检索索引。文档量万级时各需数分钟，完成后记录"DB总记录"数。

步骤 5：启动服务

双击 START-Service.bat，窗口保持开启。启动日志应依次出现：

OK: MODEL_LOCAL_PATH                        ← 模型加载成功
OK Indexes loaded (NNNNN docs)              ← 索引加载，N 应与步骤 4 一致
 * Running on http://0.0.0.0:5200           ← 服务就绪

步骤 6：验收

浏览器访问 http://127.0.0.1:5200/health：status=running、documents 与步骤 4 一致、faiss 与 bm25 均为 true。

Invoke-RestMethod -Uri http://127.0.0.1:5200/chat -Method Post `
  -ContentType "application/json" `
  -Body '{"query":"用户资料里真实存在的一个问题","token":"u001","no_history":true}'

返回含 answer 与 sources 即全链路打通。

2.1 （生产推荐）注册为 Windows 服务

nssm install OGRAG-Service "F:\OG-RAG-Release\OG-RAG-Service.exe"
nssm set OGRAG-Service AppDirectory "F:\OG-RAG-Release"
nssm start OGRAG-Service

开机自启、崩溃自愈。此后"重启服务" = nssm restart OGRAG-Service。

2.2 防火墙

跨机访问需在 Windows 防火墙放行 TCP 5200；仅本机使用则不必放行。

第 3 章　配置完整体系：.env 与管理台的关系

3.1 一套配置，两个入口

Windows 系统环境变量（优先级最高，一般不设）
        ↓
.env 文件（交付目录下，持久化存储）
   ↑ 手工编辑：可改全部配置项
   ↑ 管理台写回：只能改 14 个白名单项
        ↓
服务启动时一次性读入 → 运行期间不再重读
        ↓
管理台（admin.html）：可视化编辑界面
   保存时同时做两件事：改运行中进程的内存值 + 写回 .env

3.2 管理员必须理解的三个规则

⚡ 规则 1：改完必须重启服务。
管理台保存后页面显示立即变化，但绝大多数配置（DB_PATH、TOP_DIR、PORTAL_DOC_BASE、LLM 配置、性能参数）是在服务启动时读一次的，不重启不影响实际行为。标准动作：保存 → 重启服务 → 访问 /health 复核。

⚡ 规则 2：管理台只能改白名单内的 14 项（见 4.1）。白名单外的配置（FLASK_PUBLIC_URL、ADMIN_TOKEN、视觉模型等）只能手工编辑 .env。

⚡ 规则 3：.env 手工编辑四条规范。

每个键全文件只出现一次——同名键出现多次时，最后一条生效；
值里不要带键名——DB_PATH=metadata.db 这一行里等号右边只写 metadata.db，不要再写 DB_PATH=；
改前在命令行执行 set 键名 确认无输出——Windows 系统环境变量会压过 .env；
路径用正斜杠 /，结尾不要斜杠，如 F:/docs/manuals。

3.3 修改配置的标准流程

管理台修改（白名单内） 或  记事本修改 .env（任意项）
重启服务（关窗口重开 START-Service.bat，或 nssm restart）
看启动日志横幅行确认：DB=... TOP_DIR=... Model=...
发一条真实问答验证效果

第 4 章　配置项全表

4.1 管理台可编辑的 14 项（白名单）

分组	键	作用	注意事项
数据路径	`DB_PATH`	元数据库（SQLite）路径	与 TOP_DIR 必须配套（同一批资料）
	`TOP_DIR`	资料根目录，extract 扫描与文件直链的根	改库必须连它一起改
	`OUTPUT_DIR`	DITA 发布输出目录（WebHelp/HTML5）	见第 6 章，影响来源链接形态
	`MODEL_LOCAL_PATH`	本地向量模型目录	保持交付原样，勿改
门户配置	`PORTAL_DOC_BASE`	文档中心门户地址	见第 6 章
	`PORTAL_PRO_ID`	门户项目 ID（链接 proId 参数）	与文档中心约定
	`PORTAL_IMG_BASE`	预留项	当前版本无需配置
LLM 配置	`DEFAULT_MODEL`	传给上游 LLM 的模型名	与用户 LLM 代理支持的模型一致
	`OPENAI_API_BASE`	LLM 代理地址	必须带 /v1 后缀
	`OPENAI_API_KEY`	LLM 密钥	界面脱敏显示；改后须重启
性能参数	`MAX_CONTEXT_CHARS`	单文档上下文截断长度（默认 256000）	一般不动
	`MAX_STEPS_CHARS`	步骤字段截断长度（默认 2900）	一般不动
	`OG_TOP_K`	知识图谱检索节点数（默认 8）	一般不动
	`OG_MAX_EDGES`	图谱扩展边数（默认 5）	一般不动

4.2 只能手工编辑 .env 的配置项

键	默认值	作用
`FLASK_PUBLIC_URL`	空	本服务的可访问地址（如 `http://172.18.11.248:5200`）。来源链接里的文件直链用它拼。不配 → 链接拼错域名，全部 404
`ADMIN_TOKEN`	空	管理台登录口令。生产必配；修改需同步管理台页面中保存的口令
`MAX_CONTEXTS`	15	每次送入 LLM 的检索片段数
`FLASK_SECRET_KEY`	内置	会话密钥，生产建议自行设置
`VISION_API_KEY`	空	视觉问答密钥。不配置则视觉功能自动关闭，不影响主流程
`VISION_API_BASE`	智谱官方地址	视觉模型端点
`VISION_MODEL`	glm-4.6v	视觉模型名
`VISION_MAX_TOKENS` / `VISION_TIMEOUT`	1400 / 99	视觉请求参数

4.3 两条关键配置纪律

① TOP_DIR 与 DB_PATH 必须配套（指向同一批资料）。混配必然出现错误命中——换资料的操作流程见 5.5。

② MODEL_LOCAL_PATH 保持交付原样。它指向模型内层目录，改错会导致模型加载失败、检索不可用。

第 5 章　日常运维：管理台与资料更新

5.1 核心心智模型：两个 EXE 各管什么、何时启用哪个

理解两个 EXE 的分工，是避免绝大多数运维事故的关键：

OG-RAG-Pipeline.exe（离线批处理，用完即走，不常驻）
   资料文件 ──【extract】──▶ 数据库 ──【reindex】──▶ 检索索引文件
                                    ──【hypergraph】─▶ 知识图谱文件

OG-RAG-Service.exe（在线服务，常驻运行）
   启动时：把数据库 + 索引 + 图谱一次性加载进内存（形成快照）
   运行中：只读这份内存快照来检索问答 —— 不会自动发现任何新资料

三条规范：

新资料进入系统的唯一通道是 extract。 reindex 的含义是"从数据库重建索引"——库里没有的内容，重建一百次也不会有。extract 才是扫描文件、写入数据库的那一步；
Service 启动后看到的是启动那一刻的快照。 之后无论 extract 入了多少新资料，运行中的 Service 一概看不见——必须重启才能加载；
资料变更的完整动作永远是四步：extract → reindex → 重启 Service → /health 验证。缺任何一步等于没做。

启用时机决策表

发生了什么	需要执行什么	为什么
首次部署	`extract` + `reindex`，然后启动 Service	库和索引都是空的
往 TOP_DIR 放入/修改/删除了资料文件	`extract` → `reindex` → 重启 Service	extract 把文件变化写进库；reindex 让索引跟上库；重启让 Service 加载新索引
只改了 .env 配置（没动资料）	只需重启 Service	配置在启动时读取
切换整套资料（换业务域）	改配置 → 删缓存 → `extract` → `reindex` → `hypergraph` → 重启	完整流程见 5.5
想重建知识图谱（资料未变）	`hypergraph` → 重启 Service	图谱独立于库和索引
什么都没变，Service 进程挂了	只需重启 Service	内存快照随进程消失，重新加载即可

案例（"只 reindex 没 extract"）

📋 事故经过 — 将含 631 条问答的 FAQ.dita 放入 TOP_DIR 后，只执行了"重建索引"。之后用户提问——问题与 FAQ 标题逐字相同——AI 依然乱答，甚至编造了产品中根本不存在的 API。

🔍 原因 — extract 从未执行，FAQ 从未入库；reindex 只能在旧库的 113 条记录上原地重建，新文件与它无关。

👁️ 现象 — /health 的 documents 数没有增加；DEBUG 日志 Top doc_types 里没有 faq 类型。

💡 教训 — 资料变更，extract 是不可省略的第一步。管理台上对应的按钮是"数据提取"，不是"重建索引"。

✅ 正确操作

:: 进入交付目录（根据实际路径调整）
cd /d F:\aiRobot\AISearch\release

:: ① 入库（关键，别只 reindex）
OG-RAG-Pipeline.exe extract
::    看输出统计：应有 faq 类记录约 631 条

:: ② 重建索引 + 重启服务
OG-RAG-Pipeline.exe reindex
::    关掉服务窗口，重新 START-Service.bat
::    启动日志 OK Indexes loaded 的数量应比之前多 600+

:: ③ 验收（逐字问题应第一名命中）
curl "http://127.0.0.1:5200/debug_score?q=在NEX2.0中如何清空某个明细下指定业务类型的所有数据"

资料是否真正进系统：两个黄金验证标准

/health 的 documents 数 = 你预期的总记录数（新增了 N 条就该涨 N）
curl "http://127.0.0.1:5200/debug_score?q=新资料里的关键词" 能命中新文档

5.2 管理台（admin.html）

浏览器打开 F:\Release\static\admin.html，输入 .env 中的 ADMIN_TOKEN。

管理台页面直接请求本机 :5200 的 /admin/* 接口，Service 必须在运行中才能使用。

5.3 管理台按钮与命令行对照

管理台按钮	等价命令行	用途
数据提取	`OG-RAG-Pipeline.exe extract`	扫描 TOP_DIR 入库
重建索引	`OG-RAG-Pipeline.exe reindex`	重建 FAISS/BM25 检索索引
重建超图	`OG-RAG-Pipeline.exe hypergraph`	重建知识图谱
全流水线	以上三个依次执行	一键全流程
清除缓存	—	只清查询缓存，不删索引

按钮依赖同目录的 OG-RAG-Pipeline.exe。按钮无响应时：确认文件存在且与 Service 同目录、查杀软隔离区，或改用命令行手工执行。

5.4 资料更新（日常增量）

⚠️ 第 2 步"数据提取"（extract）不可省略——只点"重建索引"新资料永远进不了系统（原理见 5.1）。

新文档放入 TOP_DIR
管理台点"数据提取"（或命令行 extract）
点"重建索引"（或 reindex）
重启 Service
/health 确认 documents 已更新
GET /debug_score?q=新文档关键词 确认可检索到

5.5 切换整套资料（换业务域）

修改 TOP_DIR 和 DB_PATH（指向新目录与新库）
删除交付目录下全部 6 个缓存文件：
del faiss_index.bin doc_ids.npy doc_texts.npy df_meta.pkl bm25_cache.pkl combined_text_version.txt
extract → reindex → hypergraph（换库时索引和图谱都要重建）
重启 Service，/health 复核

多套资料并行：复制多份交付目录（每份独立 .env + DB + 缓存），同机并行需为每套分配不同端口。

第 6 章　门户与文档中心对接（来源链接）

AI 回答附带的"参考来源"链接由三个配置联动生成。客户部署时三者必须配齐：

配置	指向	缺失的后果
`PORTAL_DOC_BASE`	用户文档中心门户地址	门户详情链接为空
`OUTPUT_DIR`	DITA 发布输出目录	链接永远走不到已发布的 HTML 页面
`FLASK_PUBLIC_URL`	本服务自身的可访问地址	文件直链拼错域名，全部 404

6.1 链接生成的三级优先级

① 发布 HTML 链接（最佳）——OUTPUT_DIR 中扫描到该文档的发布结果时：
   PORTAL_DOC_BASE/#/proMan/workplaceDetail?url=...&dir=...&proId=...
   用户在文档中心直接阅读渲染好的 HTML 页面
② WebHelp 目录模式——资料路径含 update_NNN/ 结构时，同样生成门户详情链接
③ 文件直链（降级）——以上都不满足时：
   FLASK_PUBLIC_URL/ditasrc/相对路径
   用户可下载查看原始文件（DITA 源文件浏览器无法直接渲染）

6.2 达到最佳体验的操作

在 Oxygen（或用户的发布流水线）中将 DITA 发布为 WebHelp 或 HTML5，输出目录即 OUTPUT_DIR
重启服务，启动日志应出现：[output_index] Built: N entries from <OUTPUT_DIR>，N > 0
验证：curl "http://127.0.0.1:5200/debug_score?q=任一关键词"，返回的 url 应为门户详情页链接

6.3 前提

门户链接的路由格式（/#/proMan/workplaceDetail?...）与文档中心前端配套。若用户使用自研文档中心前端，请联系北京镭确认兼容性。

第 7 章　补丁升级流程

北京镭发布补丁包（zip）时，按以下步骤操作（全程停机 < 5 分钟）：

:: ① 停服务：关闭 OG-RAG-Service 窗口（或 nssm stop OGRAG-Service）

:: ② 备份旧文件（在交付目录下）：
ren OG-RAG-Service.exe OG-RAG-Service.exe.bak

:: ③ 从补丁包拷入新文件（覆盖到交付目录）

:: ④ 校验完整性（可选但建议）：
certutil -hashfile OG-RAG-Service.exe SHA256
::    与补丁说明中的哈希值一致才继续

:: ⑤ 启动服务：
START-Service.bat

:: ⑥ 验证：确认启动日志正常，并按补丁说明中的验证方法确认修复生效

✅ 规则：

补丁只需替换包内列出的文件，其余不动；
补丁不影响 license.lic、.env、数据库与索引——全部原地保留；
不需要、也不要对系统做任何 Python 层面的操作；
验证不通过时回滚：停服务 → 删除新文件 → 把 .bak 改回原名 → 重启，然后联系北京镭（附启动日志）。

第 8 章　授权文件须知

系统在交付包根目录带有授权文件 license.lic。

三条须知：

勿删、勿改、勿移动。该文件是服务启动的必要条件；用编辑器改动其中任何字符都会导致启动被拒绝；
到期行为：授权到期后，运行中的服务不会被中途掐断，但下次重启时拒绝启动。请在北京镭提醒的到期时间前完成续期；
续期：联系北京镭获取新的 license.lic，直接覆盖旧文件并重启服务即可。续期不涉及其他任何变更。

授权相关启动报错时的处置：服务无法启动且日志含 LICENSE 字样 → 不要尝试自行修复该文件，联系北京镭。

第 9 章　常见故障排查

#	症状	原因	处置
1	启动即退出，日志含 `LICENSE`	授权文件缺失/被改/到期	见第 8 章，联系北京镭
2	启动日志模型加载失败	`MODEL_LOCAL_PATH` 被改动	恢复交付默认值，重启
3	`/health` 显示 `documents=0`	库不存在或为空	确认 DB_PATH；`extract` → `reindex` → 重启
4	回答乱答、命中无关资料	TOP_DIR 与 DB_PATH 不配套	按 5.5 完整换库流程重做
5	`/chat` 报 LLM 连接失败 / 401	① OPENAI_API_BASE 漏 `/v1`；② LLM 代理未启动；③ 密钥错误	① 补 `/v1`；② `Invoke-RestMethod http://localhost:5001/v1/models` 自测；③ 改密钥后重启
6	管理台改了配置没效果	漏了重启；或 .env 中同键多行	见 3.2 规则 1 与规则 3
7	管理台流水线按钮无响应	Pipeline.exe 缺失/被隔离/不同目录	恢复文件、加杀软白名单，或命令行手工执行
8	来源链接全部指向同一门户首页	旧版本行为	联系北京镭获取 v5.10.1+ 补丁
9	来源链接 404	`FLASK_PUBLIC_URL` 未配或配成门户域名	配为本服务地址（见 6.1），重启
10	来源链接指向文件但浏览器只能下载	走的是第③级文件直链降级	按 6.2 完成 WebHelp/HTML5 发布
11	EXE 无法启动 / DLL 加载失败	交付包损坏（传输中断/磁盘写满）	重新拷贝完整包；磁盘剩余 ≥ 1.5 GB；查杀软隔离
12	每次启动都重建索引（Cache stale）	版本升级或换库后索引不一致	正常机制，重建完下次即直接加载，无需干预
13	视觉问答不可用	未配置 VISION_API_KEY 或视觉代理未启动	配置后重启
14	:5001 端口被占用或异常	本场景不使用 :5001	`netstat -ano \| findstr :5001` 核查，关闭误启的程序
15	问题与资料内容完全匹配，AI 却乱答甚至编造	资料未入库（只 reindex 没 extract），或入库后未重启 Service	查 `/health` documents 是否含新资料 → 补 `extract` → `reindex` → 重启（见 5.1 事故案例）

第 10 章　运维检查清单

10.1 每次启动

license.lic 在交付包根目录（未改名、未改动）
.env 中 OPENAI_API_BASE 指向用户的 LLM 且带 /v1
用户的 LLM 代理已启动
启动日志有 OK Indexes loaded (N docs)，N > 0
/health 返回 status=running 且 documents 与库一致
管理台可登录（ADMIN_TOKEN 有效）

10.2 资料变更后

extract 日志中新文档出现
reindex 完成（换库时 hypergraph 也已重建）
Service 已重启
/health documents 已更新
/debug_score 验证新文档可命中

10.3 配置变更后

若用管理台：提示"已写入 .env"
Service 已重启
改动项经实际问答验证生效

第 11 章　安全须知

口令：ADMIN_TOKEN 按生产标准设强口令；修改需同步 .env 与管理台页面保存值；
密钥卫生：任何在聊天、截图、工单中外泄过的密钥（OPENAI_API_KEY、ADMIN_TOKEN 等），先作废轮换再使用；
网络面：:5200 仅对需要访问的网段开放；管理台无 HTTPS，如需公网暴露请前置反向代理加 TLS；
文件保护：license.lic 加入杀软与备份策略的监控范围，防误删；
补丁来源：只应用北京镭正式渠道发布的补丁包，应用前核对补丁说明中的 SHA256。

附录 A　检索机制参考

A.1 支持的文档格式与检索权重

格式	扩展名	类型	检索权重
DITA Topic	`.dita` `.xml`	topic	1.0×（基准）
DITA FAQ	`.dita`（含 faq section）	faq	1.4×
DITA 参数表	`.dita`（含 `<dl>`）	parameter	1.35×
Word	`.docx`	word	1.25×
PDF	`.pdf`	pdf	1.25×
Markdown	`.md`	markdown	1.25×
HTML	`.html` `.htm`	html	1.25×

A.2 检索得分组成

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

A.3 AI 问答主接口

POST http://<服务器IP>:5200/chat
Content-Type: application/json

{ "query": "定期维护保养包括哪些内容？",
  "token": "user-session-001",
  "no_history": true }

响应字段	说明
`answer`	HTML 格式完整回答（含参考来源列表）
`sources`	来源文档列表（title / url / doc_type，最多 8 条有效来源）
`og_rag`	知识图谱检索是否启用

纯检索接口：POST /search，Body { "query": "关键词", "top_k": 5 }。

运维接口：GET /health（状态验收）｜GET /debug_index（索引状态）｜GET /debug_score?q=词&rowid=123（单文档得分）｜POST /clear_cache（清查询缓存）。

附录 B　快速命令卡

:: ── 资料 ────────────────────────────────────────────
OG-RAG-Pipeline.exe extract            :: 入库
OG-RAG-Pipeline.exe reindex            :: 重建索引
OG-RAG-Pipeline.exe hypergraph         :: 重建知识图谱

:: ── 服务 ────────────────────────────────────────────
START-Service.bat                      :: 启动服务
nssm restart OGRAG-Service             :: （已注册服务时）重启

:: ── 验证 ────────────────────────────────────────────
curl http://127.0.0.1:5200/health
curl "http://127.0.0.1:5200/debug_score?q=关键词"

:: ── 换库（先改 TOP_DIR/DB_PATH，再执行）──────────────
del faiss_index.bin doc_ids.npy doc_texts.npy df_meta.pkl bm25_cache.pkl combined_text_version.txt

:: ── 补丁 ────────────────────────────────────────────
ren OG-RAG-Service.exe OG-RAG-Service.exe.bak     :: 备份
certutil -hashfile OG-RAG-Service.exe SHA256      :: 校验

附录 C　DITA FAQ 模板使用指南

读者：内容作者 / 文档工程师 v1.0 · 2026-09-01 配合管理员手册第 5 章使用

C.1 模板长什么样（最小完整示例）

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<reference id="product_faq" xml:lang="zh-CN">
  <title>产品常见问题</title>
  <shortdesc>本文档包含产品常见问题及其解答。</shortdesc>
  <prolog>
    <metadata>
      <prodinfo><prodname>产品名称</prodname></prodinfo>
      <keywords>
        <keyword>权限</keyword>
        <keyword>审批流</keyword>
      </keywords>
    </metadata>
  </prolog>
  <refbody>

    <!-- 每条 FAQ = 一个 section，三条规则：id 以 faq_ 开头、
         title 写问题原文、用 faq-entry 包裹问答 -->
    <section id="faq_如何启用韩文语言环境">
      <title>如何启用韩文语言环境？是否需要额外收费？</title>
      <sectiondiv outputclass="faq-entry">
        <p outputclass="faq-question">如何启用韩文语言环境？是否需要额外收费？</p>
        <p outputclass="faq-answer">1. 后台租户多语言设置中，新增并启用韩语选项。</p>
        <p outputclass="faq-answer">2. 后台新翻译工作台中，导入语言包或手动翻译。</p>
        <p outputclass="faq-answer">3. 租户多语言设置和翻译工作台功能不收费。</p>
      </sectiondiv>
    </section>

  </refbody>
</reference>

C.2 为什么是这个结构（系统如何识别）

入库程序靠以下特征识别 FAQ，命中任一即按 FAQ 处理：

识别特征	模板中的位置
`sectiondiv` 的 outputclass 含 "faq"	`<sectiondiv outputclass="faq-entry">`
`section` 的 id 以 `faq_` 开头	`<section id="faq_...">`

识别后，每条 section 拆成一条独立检索记录，字段映射如下：

模板内容	入库字段	对检索的作用
section 的 `<title>`（问题）	title	用户提问 ≈ 问题原文，标题匹配是命中的主力
`<p outputclass="faq-question">`	context	问题文本再次参与语义匹配
全部 `<p outputclass="faq-answer">`	steps（答案）	以 ANSWER 标签进入嵌入文本，也是 AI 回答的素材
answer 前 150 字	shortdesc	来源列表摘要
—（自动标记）	doc_type = faq	检索打分 ×1.4，同等相关度下 FAQ 优先于普通文档
prolog 的 keywords	keywords	补充匹配词（见 C.4 节建议）

一句话：问题怎么写，决定了用户怎么问能撞上；答案怎么写，决定了 AI 怎么答。

C.3 编写规则（必须遵守）

C.3.1 结构规则

一条 FAQ 一个 <section>，不要把多个问题合并在一个 section 里——系统按 section 拆分，合并会导致一个问题命中时带出无关答案；
section id 以 faq_ 开头且全文唯一。id 是入库主键的一部分，重复会导致后一条静默覆盖前一条（数据丢失无报错）。批量生成时建议对 id 做去重校验；
<title> 写问题原文，用用户的真实问法（"如何…？""…是什么原因？"），不要写成主题词（"韩文语言环境设置"）——标题与用户提问越像，命中越准；
问题用 <p outputclass="faq-question">，答案用 <p outputclass="faq-answer">，outputclass 拼写必须精确（全小写、带连字符）；
答案分点时每点一个 faq-answer 段落；条目型内容（<li>、<stentry>）也会被自动收入答案；
文件根元素用 reference（当前模板）即可；encoding 声明 UTF-8。

C.3.2 数据质量红线（真实事故总结）

#	红线	违反后果
1	UTF-8 无乱码。从 Excel/其他系统导出后必须抽查	乱码答案会被 AI 原样放大（案例：`最大数据量并瓷瓒ㄉ舷蕖�`）
2	答案完整，生成后检查末尾是否截断	答案断在半句话，AI 也只能答半句
3	不引用不存在的图。写了"如下图所示"就必须真的有 `<image>`	AI 会说"见图"而无图可看
4	脱敏：内部员工姓名、内部邮箱、内部审批路径不得写入	会随 AI 回答泄露给客户（案例：答案中出现"发邮件给李某某申请"）
5	一个英文单词不要拆进两个段落（如"普通用"+"户可以…"）	轻微影响匹配
6	标题里避免错别字（如 Tirgger）	削弱精确匹配

提升检索质量的建议（可选但推荐）

prolog 里补 <keywords>：产品名、模块名、常见同义词。当前模板没有 keywords，系统只靠自动拆出的 6 个问题词做补充匹配，补充后精度明显提升；
<prodname> 写实：多产品共存时用于区分产品线；
相关问题拆开写："A 是什么？B 怎么办？"两个问题合一条，不如拆成两条——单问题单答案的命中率最高。

C.5 入库与验收

文件放入资料目录（TOP_DIR）后，四步缺一不可：

:: ① 入库（新文件进数据库——只重建索引不会有新内容！）
OG-RAG-Pipeline.exe extract

:: ② 重建索引
OG-RAG-Pipeline.exe reindex

:: ③ 重启服务（运行中的服务只看启动时的快照）
START-Service.bat

:: ④ 验收（两条黄金标准）
curl http://127.0.0.1:5200/health
::    documents 应增加 N 条（N = 文件的 FAQ 条数）

curl "http://127.0.0.1:5200/debug_score?q=某条FAQ标题里的关键词"
::    对应条目应排第一，且得分明显领先（×1.4 权重可见）

最后做真实问答验收，挑三种风格各一条：

精确型：有唯一确定答案的问题（预期 AI 给出原文数字/结论）；
流程型：分步骤答案的问题（预期步骤完整、顺序正确）；
边界型：答案是"不支持/不可以"的问题（预期 AI 明确说"不支持"，而不是编一个变通方案）。

C.6 来源链接的粒度说明

同一文件里的所有 FAQ 条目共享同一个文件路径：

文档中心已发布（推荐）：来源链接指向门户详情页，带条目级 id 参数，用户点击直达对应条目；
未发布（降级）：来源链接指向 .dita 源文件本身，同文件的所有 FAQ 链接相同，用户得到的是整个文件。

FAQ 属于高频点击内容，强烈建议纳入文档中心发布流程。

C.7 常见错误速查

症状	原因	处置
入库后 FAQ 条数为 0	outputclass 拼写错误 / id 未以 faq_ 开头	对照 C.2 节识别特征检查
条数少于文件中的问题数	section id 重复被静默覆盖	去重后重新 extract + reindex
AI 答非所问、编造内容	只 reindex 没 extract，或未重启服务	按 C.5 节四步重做
回答里出现乱码	源文件编码污染	修源头重新生成，不要手改
FAQ 排在普通文档后面	未识别为 faq 类型（走了普通 topic 解析）	检查识别特征；/debug_score 看 doc_type

文档结束 · OG-RAG 管理员手册（客户版）v5.10.1 · 2026-09-01 修订
附录C：DITA FAQ 模板使用指南 v1.0 · 配合第 5 章使用

OG-RAG AI 知识检索服务管理员手册

第 1 章 系统概述