开发文档 · 先定边界再实现

# X-Financial 轻量知识库归集与问答优化方案

本方案不把 X-Financial 改造成专业知识库平台，而是在现有 `LightRAG`、`Hermes`、`AgentRun` 和知识库 UI 上补齐最薄弱的归集、分块、召回和证据回答能力。 Yuxi 只作为成熟设计参考，借鉴其统一解析、分块预设和评估思想。

保留现有 LightRAG 轻量 Parser 条款级分块 混合召回 证据化回答
核心目标
准、快、可解释
改造范围
归集与召回链路，不重做平台
并发预期
5-10 用户查询可降级、有上限

## 定位与边界

知识库在 X-Financial 中是业务辅助能力，不是独立知识管理产品。 因此实现必须克制：不引入重型多租户平台，不替换现有业务数据模型， 不把知识库 UI 做成复杂后台，只补齐影响问答质量的关键薄层。

轻量优先

### 要解决的问题

- Word、PDF、Excel 等文件进入 RAG 前缺少统一结构。
- 制度类文档如果按普通 chunk 切分，条款容易被切散。
- 问答质量依赖向量召回，缺少关键词、标题、条款补召回。
- 效果优化缺少固定评测集，容易靠体感判断。

### 保留的现有能力

- `KnowledgeService` 继续负责文件库和状态入口。
- `KnowledgeRagService` 继续封装 LightRAG 查询和入库。
- `KnowledgeIndexTaskManager` 继续承接 Hermes 增量任务。
- 前端知识管理继续保持简单文件夹与文件列表形态。

### 明确不做

- 不整体引入 Yuxi 平台。
- 不把存储改成 Milvus + Neo4j。
- 不一次性接入全量 OCR 引擎。
- 不新增复杂多租户知识库后台。

## 轻量架构

新增能力只放在 LightRAG 前后两侧：前侧负责把文件变成稳定 Markdown 和业务友好 chunk， 后侧负责混合召回、证据重排和可靠回答。LightRAG 仍是主召回核心。

薄层增强
原始文件 ├── docx / pdf / xlsx / pptx / csv / txt ↓ 轻量 Parser ├── 统一 Markdown ├── 表格上下文 └── 页码 / sheet / 条款路径 ↓ Chunk Preset ├── laws：制度条款 ├── qa：常见问答 └── table：表格行组 ↓ 现有 LightRAG / Qdrant ↓ 混合召回 ├── LightRAG 语义召回 ├── 标题与条款关键词召回 └── 轻量重排 top 3-5 ↓ 证据化回答 ├── 命中证据 ├── 直接结论 └── 缺失信息说明

## Yuxi 借鉴点

Yuxi 的价值不在于整套平台，而在于成熟的归集分层思想： 文件先解析成 Markdown，再按场景分块，再索引，再评估。 这些思想可以小规模落地到现有服务内。

借鉴而非搬运

### 统一 Parser

学习 Yuxi 把多格式文件统一转 Markdown 的入口设计，但只实现 X-Financial 当前需要的格式。

### 分块 Preset

借鉴 RAGFlow-like preset。先做 `laws`、`qa`、`table` 三类。

### 两阶段状态

内部区分解析和索引。UI 仍可显示简单归纳状态，后台记录真实失败点。

### 轻量评测

不做评估平台，只维护 JSON 用例和脚本，持续检查召回与回答质量。

Yuxi README Yuxi unified parser Yuxi chunk presets Yuxi laws parser

## 模块设计

新增模块必须小而清楚，避免把逻辑继续堆进单个 Service。 单个核心文件控制在 800 行以内，优先按解析、分块、召回、评测拆分。

职责拆分
knowledge_parser.py
负责把 docx、pdf、xlsx、csv、txt 等文件转成 Markdown。 输出正文、标题路径、页码、sheet、表头、解析告警。
knowledge_chunking.py
根据文件夹、文件类型和文档特征选择分块策略。 第一批只实现制度、问答、表格三类。
knowledge_retrieval.py
在 LightRAG 命中结果外补充关键词、条款标题和文件名召回。 最终输出小而准的证据块。
knowledge_eval.py
读取轻量评测用例，检查 expected 文件、关键词、证据和答案约束。 用于每次调整参数后的回归验证。

## 召回与回答策略

目标不是让模型更会猜，而是让系统给模型更可靠的证据。 制度问题优先命中条款，表格问题保留表头与行上下文，回答必须暴露依据和缺失信息。

证据优先

### 召回层

- LightRAG 继续提供语义召回。
- 条款号、标题、文件名、关键词做补召回。
- 召回候选数量有上限，避免并发下无限扩张。

### 重排层

- 优先保留含问题关键词、标题路径和条款语义的块。
- 制度类按条款完整度加权。
- 最终给回答链路 3-5 条高质量证据。

### 回答层

- 能直接基于证据回答时，不强制二次模型整理。
- 模型只做压缩表达，不凭空补事实。
- 证据不足时明确说明缺什么。

## 实施路线

分四步小步交付。每一步都能单独验证，不把解析、索引、召回和评测揉成一次大改。

渐进落地
P0 / 文档落地
先明确轻量边界 完成本文档，确认不做重平台、不替换存储、不一次性引入复杂 OCR。
P1 / 统一解析
补齐文件归集质量 新增 Parser，把 Word、PDF、Excel、CSV、TXT 稳定转为 Markdown，并保存解析产物供索引复用。
P2 / 场景分块
提升制度与表格命中率 实现 laws、qa、table 三类分块。制度按章、节、条、款保留完整语义，表格保留 sheet、表头和行上下文。
P3 / 混合召回
减少答偏和漏召回 在 LightRAG 命中外补充关键词、条款标题、文件名召回，输出可控数量的证据块。
P4 / 轻量评测
把效果优化变成可回归 建设 30-50 条远光软件制度风格问答用例，覆盖报销、差旅、发票、预算、税务等高频问题。

## 验收标准

验收不只看页面状态，而要看文件是否真实入库、召回是否命中文档依据、 回答是否引用证据，以及并发访问时是否能稳定降级。

真实验证
Word、PDF、Excel、CSV、TXT 文件能生成可读 Markdown，且解析产物可复用。
制度类文件能按章、节、条、款形成相对完整的证据块。
Excel 表格问答能保留 sheet、表头、关键列和业务行上下文。
Hermes 增量任务能区分解析失败、索引失败和归纳失败。
常见制度问答优先返回证据化直接答案，模型超时时仍有可读降级答案。
5-10 个用户同时访问时，查询候选数、重排数、模型调用数都有明确上限。
轻量评测集覆盖至少 30 条问题，并记录命中文件、关键词和答案约束。
不引入 Yuxi 平台级依赖，不改变现有知识库 UI 的主体交互。

后续实现时，优先在现有定向测试基础上补充 Parser、Chunking、Retrieval 和 Knowledge Eval 的小测试。 后端验证优先在 Docker 容器 `x-financial-main` 中运行。