Raycontentech OG-RAG 系统设计文档

版本：v1.0  |  日期：2026-07-18  |  编写依据：F:iRobot\AISearch 目录实际文件清单 + 本项目历史会话中的实测验证结果

目录

1. 系统定位
2. 数据与索引层
3. AI 对话搜索设计（已验证）
4. Oxygen AI 对接场景
5. AI 翻译平台对接场景
6. 整体风险与依赖清单
7. 建议后续路线
8. 附录：部署运维手册

0. 系统定位

OG-RAG 是 Raycontentech 自建的企业知识检索系统，服务于 F:iRobot\AISearch（11,568 篇文档，含 XDocs 5.4 专有资料、DITA 语料、MCU 翻译QA样例等），核心特征是在传统向量+关键词混合检索之外，叠加了一层超图本体（hypergraph ontology）用于捕捉文档间的关系型知识——这是"本体增强"一词的实际所指，区别于普通RAG。

系统本身与接入它的LLM代理是解耦的两层：

• OG-RAG 服务本身（:5200，handleData_v4.py）—— 独立于任何大模型，谁都可以接
• 接入层（本会话验证过的是 kimi3proxy.py / Kimi代理，:5001）—— 负责把OG-RAG检索结果转换成特定大模型能理解的上下文注入或工具调用结果

这个解耦是"AI对话搜索模型无关"这个说法成立的基础，也是后续Oxygen/翻译平台能各自接入的前提。

1. 数据与索引层

1.1 存储：metadata.db（SQLite）—— 已验证

以下表结构和行数来自本会话 inspect_db_schema.py 的实际探测结果，已验证：

1.2 索引构建流水线 —— 据文件名推测，未逐行核实代码

注：model_distiluse确认是多语言embedding模型（distiluse-base-multilingual-cased-v2是sentence-transformers系列的标准多语言模型），这一点对第4节"翻译平台对接"很重要——理论上向量检索本身具备跨语言语义匹配能力，但这个能力在当前OG-RAG的/search端点里是否被用于跨语言检索，未经本会话验证。

1.3 检索服务：handleData_v4.py（:5200，waitress部署）

• og_retriever.py：推测承载混合检索逻辑（历史会话口述为"FAISS+BM25+hypergraph"三路融合，即hybrid_search_v5），未在本次核实源码
• 已知修复历史（本会话/既往会话已验证应用）：
  • 正文截断 500→3000 字符（fix_context_truncation.py，已应用，索引已重建）
  • doc_type打分偏置：parameter类文档+0.45分排斥topic类文档（PATCH1，已应用，服务已重启生效）
• 已知未修复项（未验证）：
  • 整句连续子串匹配疑因context内嵌换行符失败（PATCH3已就绪，未应用、未验证——本会话通过绕开该问题的方式规避，见第2节，没有直接验证PATCH3本身是否有效）
  • og_retriever.py具体打分权重（标题×4/终评×1.35/rerank×1.05）来自既往会话口述，本次未复核源码
• /search端点：本会话代理接入并验证过能返回结果（_ograg_http_search）
• 疑似存在/chat端点（门户演示用，历史会话口述其含DB关键词直查通道，与/search是两套检索逻辑）——这个差异本身未在本会话实测复核，仅作为历史发现记录
• corrections_routes.py：存在独立路由文件，具体端点/参数未测试

1.4 运维层

admin_routes.py + AdminPanel.html/AdminPanel.jsx（管理控制台）、migrate_db.py/update_index.py/output_index.py（索引维护工具）、win_utf8.py（Windows编码兼容）、wsgi.py（生产部署入口）。_archive/目录里有大量带日期的历史版本（03/12～04/16一路到当前），说明这套系统持续迭代了至少数月。

1.5 诚实列出的空白/待验证项

• corrections表有索引基础设施但0行数据，语义检索能力完全未经实测
• miss_log表0行，说明检索失效的运营反馈闭环目前没有被实际使用
• og_retriever.py混合检索的具体实现和打分公式本次会话未逐行核实，前几节所有相关表述基于既往口述，不是本会话读代码得出的
• /chat与/search两套逻辑的差异未实测复核

2. AI对话搜索设计（本会话实际实现并验证过的部分）

这是唯一一层全程有实测验证、有日志/断言测试为证的部分，其余各层多少都有推测成分。

2.1 架构

两条通道互补，不是二选一：

• Route A（工具拦截）：Kimi主动调用search_in_project/get_related_resources_overview_from_project等检索类工具时，代理拦截并路由到OG-RAG；写工具（save_document等）透传给Oxygen客户端本地执行，代理不碰
• Route B（请求级注入）：OGRAG_INJECT=true时，每轮对话取最后一条用户消息，自动查OG-RAG，结果以system消息注入——不依赖模型是否"想到"要检索，强制生效

2.2 版本演进（v1.1→v1.7，每版解决的问题）

2.3 关键教训：DB直查修复的完整试错过程

这个过程本身是本文档最有实证价值的部分，值得写进设计文档作为"如何验证RAG真正生效"的方法论参考：

1. 第一次假设：认为OG-RAG的hybrid打分体系有偏置，加SQLite确定性直查能绕开——test_acceptance.py第一次运行失败，验收目标文档using_a_catalog.dita未进入DB直查返回的前10
2. 诊断：发现naive词频求和被"how/do/make/of/the/my/new/document/type"这类通用词主导，真正有区分度的"XDocs"等词权重被稀释；还发现大小写不一致bug（SQL LIKE不敏感但Python count()敏感）
3. 修复后重测：加停用词过滤+IDF加权后，test_acceptance.py通过
4. 进一步验证：用dump_injected_context.py把实际注入模型的system消息全文打印出来，逐token比对Oxygen真实答案里的10个特征细节，发现7个不在注入文本里——证明"检索到了正确文档"不等于"注入内容完整覆盖了答案"，此前一轮判定为"PASS"是过早的结论，本文档予以修正
5. 溯源排查：通过日志关键词排查Kimi是否调用过本地文件读取工具，结果显示日志里唯一一条相关记录（get_document_content）本身处于权限被拒绝状态，无法确认是否是文件读取工具补上了缺失细节——最终建议的对照实验（OGRAG_ENABLED=false重新提问）尚未执行，结论待补
6. 根因修复：确认是预览窗口600字符对大文档不够用，且5篇文档均分预算进一步压缩——改为2500字符窗口+按排名非线性分配预算

3. Oxygen AI 对接场景说明

3.1 已验证生效的场景：知识问答

用户在AI Positron对话里提问，Route B强制注入，Route A按需拦截工具调用。已用真实验收案例验证（XDocs catalog配置问题，见2.3），当前已知限制是大文档的注入完整性依赖v1.6的预算分配策略，未对所有文档规模做穷尽测试。

依赖条件：

• Oxygen AI Positron的模型连接指向Kimi代理（:5001）而非直连Moonshot API
• 代理与OG-RAG（:5200）同机部署，SQLite直查依赖本地文件系统只读访问权限
• OGRAG_ENABLED/OGRAG_INJECT环境变量正确配置

3.2 部分可用/需先修复的场景：新建文档时的内容复用

结论（本次评估的核心发现）：理论上，本体增强（hypergraph）能在字面用词不重合的情况下发现概念相关的既有内容，这是"新建文档找可复用素材"场景最需要的能力（新草稿的措辞不可能和既有文档字面重合）。但截至v1.6，专门服务这个场景的工具find_similar_reusable_content是硬编码假数据桩，从未真正接入OG-RAG——v1.7已修复代码，但尚未实测验证。

另需注意：Route B注入只在用户通过对话触发AI（如"帮我写一篇关于XX的topic"）时生效，Oxygen纯UI"新建空白文档"动作不经过AI对话，不会触发任何RAG检索——这是"新建文档获益"必须加的限定条件，不能笼统宣称。

依赖条件（新增）：

• v1.7补丁需应用并通过实测（对照建议：用语料库里确实存在但你会用不同措辞提问的主题，验证find_similar_reusable_content返回的channel字段是http_hybrid且命中正确文档）
• 依赖og_retriever.py的hybrid检索确实启用了hypergraph关系检索——这一层本身未核实

3.3 未涉及场景

Schema组件解析（get_sch_component_details/get_xsd_component_details）、AI动作管理、文档保存/校验等工具目前是mock实现或纯本地逻辑，与OG-RAG无关，不在本文档讨论范围。

4. AI翻译平台对接场景说明

4.1 设计方案：讯谷代理 v6.1（两级检索）

• 第一级（确定性，corrections表）：术语/既有译法查询，命中即强约束，可直接喂给讯谷的terminology参数
• 第二级（现有ograg_search()，metadata表）：语境/风格补充，弱约束，仅作背景参考

代码已交付（ograg_translate_bridge.py），设计上模型无关，理论上任何走该代理的翻译请求都能获益。

4.2 可行性的真实前提——当前不满足，需先完成

corrections表当前0行。这意味着"术语一致性"这个最有价值的收益点，在种子数据灌入之前是0，不是"部分可用"，是完全不可用。已交付配套方案：

• seed_corrections.py：把XHSC/ABB既有QA审校产出（既往会话已确认这些流水线真实存在且在产出数据）导入corrections表
• validate_translation_rag.py：量化验证检索命中率，避免灌完数据后仍然是"设想生效"而非"实测生效"

4.3 一个此次文件清单核实后发现的新信息

corrections表配套的独立FAISS索引（corrections_faiss.bin等）说明系统设计时就打算让这张表支持语义检索，不只是字面匹配。这意味着4.1节设计的"第一级：确定性LIKE匹配"只是当前ograg_translate_bridge.py用的临时策略，未来如果corrections_routes.py里的语义检索端点跑起来了，术语匹配的召回能力会比现在的字面LIKE匹配更强（能处理"源文措辞和术语库里存的版本不完全一致"的情况）——但这是尚未验证的潜力，不是当前已实现能力。

4.4 依赖条件汇总

• corrections表需要先灌入种子数据（当前0行，价值为0）
• 讯谷代理的/v1/translate端点需要实际支持接收terminology参数并让模型真正遵循（本会话只验证了"检索层能否挖出术语"，未验证"模型是否采纳"）
• 若要用语义检索能力，需先确认corrections_routes.py的实际API可用性（未测试）

5. 整体风险与依赖清单

6. 建议后续路线（按价值/成本排序）

1. 执行OGRAG_ENABLED=false对照实验，补上2.3节遗留的未完成验证
2. 实测v1.7的find_similar_reusable_content修复（Oxygen新建文档场景）
3. 灌corrections表种子数据并跑validate_translation_rag.py（翻译平台场景，当前价值瓶颈）
4. 核实og_retriever.py混合检索的实际打分逻辑与corrections_routes.py的语义检索端点（消除本文档里标注"未验证"的部分）
5. 启用miss_log记录机制，为后续检索质量优化提供真实数据而非推测

7. 附录：部署运维手册

详见独立文档 AI 搜索部署手册 V3.1（已作为附件提供），包含：

• 部署架构总览（Windows 2019 云服务器 + Apache 反向代理）
• 各租户配置清单（镭内容/销售易双租户隔离）
• 核心文件清单（必须存在 vs 运行时生成）
• DITA 内容变更流程（Admin Console 操作指南）
• 迭代新功能部署流程（代码更新 vs 索引重建）
• 新租户移植流程（含一次性 Fix 清单）
• Apache 路由配置规范
• 故障排查手册（含 V3.1 视觉模型配置）
• .env 配置参考（含 VISION_API_KEY 等新增项）
• 版本变更日志