# knowledgeRag

**Repository Path**: xie-wu0001/knowledge-rag

## Basic Information

- **Project Name**: knowledgeRag
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-07
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Knowledge RAG CLI

这是一个带交互式终端界面的企业知识检索工具。它通过可配置的 OpenAI Compatible Embedding API 生成向量，将向量和来源定位保存到嵌入式 Qdrant 本地向量库，同时使用 SQLite FTS5 建立关键词索引。提问时融合语义与关键词结果，再调用可配置的 OpenAI Compatible 大模型重排候选资料并生成回答。

## 界面能力

直接执行 `knowledge-rag` 即可打开 PowerShell/终端主界面，无需记忆命令：

```text
╭────────────────────────────────────╮
│           Knowledge RAG            │
│       企业知识检索命令行工具       │
╰────────────────────────────────────╯

知识目录       D:\knowledge-rag\knowledge
向量库目录     D:\knowledge-rag\data\qdrant
Qdrant 集合    rag_knowledge
回答模型       DeepSeek / deepseek-chat  已配置
Embedding      硅基流动 / BAAI/bge-m3  已配置
向量存储       Qdrant Embedded
索引状态       本地就绪  文档 36  片段 528  向量 528  关键词 528

> 请选择操作
  > 开始知识问答
    同步本地知识库
    查看索引状态
    初始化与存储检查
    管理已索引文档
    查看使用帮助
    退出
```

主要交互功能：

- 配置统一从 `.env` 或系统环境变量读取，不在终端界面内编辑
- 首页展示实际服务商、模型、本地向量库路径、文档数、向量数和关键词片段数
- 同步时展示校验、解析、Embedding、向量写入和清单更新阶段
- 问答时展示历史问题改写、混合召回、大模型重排、相邻片段扩展和回答阶段
- 问答使用 Markdown 排版，来源通过表格展示源文件、位置和相关度
- 问题、回答、参考来源和历史会话统一保留在 CMD 可滚动页面中
- 支持当前进程内连续对话，自动保留最近 10 轮，并只用历史改写当前检索问题
- 删除索引和强制重建前提供二次确认
- 错误面板提供处理建议，详细日志保存到 `data/knowledge-rag.log`
- 保留传统子命令，并提供适合自动化任务的 `--plain` 模式

## 知识库内容结构

本工具的 `knowledge` 目录承载泛微 E9/E10 二次开发知识，按主题分目录组织。目录级索引统一维护在 `knowledge/知识库目录.md`，新增或调整文档后应同步更新该索引：

| 目录 | 内容 |
|---|---|
| `平台体系/` | E10 参数与实体关系、数据库操作规范、WeaResult 返回规范 |
| `考勤领域/` | E9 考勤（kq_* 体系）与 E10 出勤（attend_* 体系）分开沉淀，含二开钩子速查 |
| `开发指引/E10/` | 后端二次开发规范、接口开发与发布、自定义 action |
| `开发笔记/` | E9/E10 开发笔记、文件上传下载指南 |
| `诊断与排障/` | E-cology 性能宕机日志分析方法 |
| `通用工具 util/` | dataSet、docUtil、ftlUtil 工具源码与说明 |
| `案例分享/` | 项目实战案例与可复用源码 |
| `其他 other/` | 预留目录 |

维护约定：往 `knowledge` 放入新文档后，先更新 `知识库目录.md` 登记，再执行一次增量同步（见下文），新内容即可被检索。

## 文档格式

- Word `.docx`
- Excel `.xlsx`、`.xlsm`、`.xls`
- Markdown `.md`、`.markdown`
- 纯文本 `.txt`
- Java `.java`
- Python `.py`
- JavaScript `.js`

旧版 Word `.doc` 无法可靠地通过 `python-docx` 解析，请先在 Word 或 LibreOffice 中转换为 `.docx`。

TXT、Markdown 和源码文件优先按 `UTF-8 BOM`、`UTF-8` 解码，并兼容 `GB18030/GBK`。单个文本文件无法解码时，本次同步会记录中文错误日志并继续处理其他文件。

## 环境要求

- Python 3.11 或更高版本
- 一个支持 `/embeddings` 的 OpenAI Compatible API
- 一个支持 `/chat/completions` 的 OpenAI Compatible API
- 本机对 `data` 目录具有读写权限

嵌入式 Qdrant 随 Python 项目依赖安装，无需 Docker、独立服务或额外的向量数据库部署。

## 安装

在项目目录执行：

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
Copy-Item .env.example .env
notepad .env
```

填写 `.env` 后启动：

```powershell
knowledge-rag
```

也可以不安装命令入口：

```powershell
python -m knowledge_rag
```

## 首次配置

工具不提供配置向导。首次使用时，请复制配置模板并手动编辑：

```powershell
Copy-Item .env.example .env
notepad .env
```

至少确认并填写以下通用配置：

```dotenv
EMBEDDING_PROVIDER=硅基流动
EMBEDDING_BASE_URL=https://api.siliconflow.cn/v1
EMBEDDING_API_KEY=你的Embedding服务密钥
EMBEDDING_MODEL=BAAI/bge-m3
EMBEDDING_DIMENSION=1024

LLM_PROVIDER=DeepSeek
LLM_BASE_URL=https://api.deepseek.com
LLM_API_KEY=你的大模型服务密钥
LLM_MODEL=deepseek-chat
```

其余配置可以保留模板默认值。`.env` 已被 `.gitignore` 排除，请勿把真实密钥提交到代码仓库。

如果服务参数同时存在于系统环境变量和 `.env`，系统环境变量优先。

配置不完整时，程序会列出缺失项和实际读取的 `.env` 路径，然后直接退出，不会询问或修改配置。填写完成后重新执行 `knowledge-rag` 即可。

`EMBEDDING_PROVIDER` 和 `LLM_PROVIDER` 用于界面和日志展示；真正决定请求目标的是对应的 `BASE_URL`、`API_KEY` 和 `MODEL`。Base URL 应包含服务商要求的 OpenAI 兼容 API 前缀，程序会在其后调用 `embeddings` 或 `chat/completions`。

旧版 `DEEPSEEK_*` 和 `SILICONFLOW_*` 字段已经废弃，程序不会读取这些字段。

## 推荐工作流程

### 1. 初始化

在主菜单选择“初始化与存储检查”，工具会：

- 创建 `knowledge` 和 `data` 目录
- 创建 `data/qdrant` 下的嵌入式 Qdrant 向量库
- 在集合不存在时创建 1024 维 Cosine 集合
- 初始化本地 SQLite 索引清单和 FTS5 关键词索引

### 2. 放入知识文档

将 Word、Excel、Markdown、TXT、Java、Python 或 JavaScript 文件放到 `knowledge` 目录，可以使用任意层级的子目录。

### 3. 同步知识库

在主菜单选择“同步知识库”，然后选择：

- 增量同步：只处理新增、修改和删除的文件，日常使用推荐
- 强制重建：忽略文件哈希，重新调用 Embedding API 生成全部文档向量

同步完成后会展示新增、更新、未变化、删除和失败数量。单个文件失败不会中断其他文件。升级到混合检索后的第一次增量同步会为旧文档补建关键词索引；向量完整时不会重复调用 Embedding API。

### 4. 知识问答

在主菜单选择“知识问答”并输入问题。回答下方固定显示：

```text
参考来源
资料1  考勤/员工考勤规则.docx
       第三章 请假规则 / 第18～21段

资料2  代码/AttendanceService.java
       AttendanceService / calculateWorkHours() / 第86～114行
```

回答结束后可以选择继续提问或返回主菜单。工具会在当前 CLI 进程内保留最近 10 轮问答，利用历史对话把“它有哪些限制”这类追问改写为独立检索问题。历史回答不会发送给最终回答步骤，也不能替代知识依据；每轮回答仍只引用当前问题实际召回的源文件和位置。

知识问答不会切换到独立全屏查看器。问题、运行进度、回答和参考来源会依次追加到同一个 CMD 页面，可以直接使用 CMD 滚动条或鼠标滚轮查看。再次从主菜单进入知识问答时，程序会先恢复当前进程内最近 10 轮问题、回答和参考来源；`--plain` 模式仍保持普通文本输出，便于重定向或管道处理。

每轮问答的检索流程如下：原始问题与历史改写问题分别执行向量和关键词召回，使用 RRF 融合结果，进行内容去重和单文件配额控制，然后额外调用一次当前配置的大模型完成候选资料重排。重排失败时自动回退到 RRF 顺序。最终回答中的 `[资料N]` 会由程序校验，只展示模型实际引用的来源；引用缺失或越界时拒绝输出未经引用的回答。

在提问框输入 `/clear` 可以随时清空当前会话。返回主菜单不会清空历史；退出程序后历史自动丢弃，不会写入 SQLite、Qdrant 或其他本地文件。`knowledge-rag ask "问题"` 和 `--plain` 模式仍是单轮问答，不保留会话。

## 来源定位规则

- Word：标题路径、段落范围；只有文档包含显式分页符或 Word 保存的渲染分页标记时才附页码
- Excel：工作表名称、行号范围
- Markdown：标题路径、行号范围
- 纯文本：文件名、识别到的标题或章节、行号范围
- Java：类名、可识别的方法名、行号范围
- Python：类名、函数或异步函数名、行号范围；语法不完整时降级为缩进定位
- JavaScript：类名、普通函数、类方法或常见箭头函数名、行号范围

## 传统子命令

子命令默认仍使用 Rich 面板、动态进度和确认提示：

```powershell
knowledge-rag init
knowledge-rag sync
knowledge-rag sync --force
knowledge-rag ask "泛微流程提交前应该如何校验必填字段？"
knowledge-rag status
knowledge-rag remove "开发规范/流程接口.md"
```

强制重建和删除操作默认要求确认。

## 脚本与自动化模式

`--plain` 关闭颜色、交互提示和动态进度条。全局参数必须放在子命令之前：

```powershell
knowledge-rag --plain status
knowledge-rag --plain sync
knowledge-rag --plain ask "你的问题"
knowledge-rag --plain remove "开发规范/流程接口.md" --yes
```

在 `--plain` 模式中：

- `ask` 必须直接提供问题
- `remove` 必须提供 `--yes`
- 命令不会等待用户输入
- 输出被管道重定向时也会自动采用纯文本模式

## 自定义配置文件

`--env-file` 必须放在子命令之前：

```powershell
knowledge-rag --env-file D:\config\knowledge-rag.env
knowledge-rag --env-file D:\config\knowledge-rag.env status
```

## 增量同步机制

本地 `data/index_manifest.sqlite3` 保存文件哈希、相对路径、同步状态和用于关键词检索的知识片段。每次同步会：

1. 扫描支持的文件并计算 SHA-256。
2. 文件哈希、向量数量和关键词片段数量均一致时跳过该文件。
3. 只有关键词索引缺失时重新解析文档并补建 FTS5，不调用 Embedding API。
4. 对新增、变化或向量缺失的文件重新解析并调用 Embedding API。
5. 分批写入本地向量；写入失败时回滚本次新增数据。
6. 事务化替换该文件的 SQLite 关键词片段，再更新清单。
7. 清理已经从知识目录删除的向量和关键词片段。

程序会记录 Embedding 服务商、Base URL、模型、维度和切片参数的配置指纹。任一项变化后，状态界面会显示“待同步”，问答入口会暂停使用旧索引；执行普通增量同步即可重建本地向量集合。只有全部文档同步成功后才会提交新指纹，任何失败都会继续保持“待同步”。切换 `QDRANT_COLLECTION` 后，增量同步也会根据实际向量数量补齐新集合。

## 数据边界

- 所有文档切片会发送给当前配置的 Embedding API 以生成向量。
- 文档切片、来源元数据和向量保存在本机 `QDRANT_PATH` 目录。
- 提问时只有召回的知识片段和问题会发送给当前配置的大模型 API，不会发送整个知识库。
- 本地 SQLite 关键词索引保存切分后的文档正文，但不保存 API Key。
- `.env` 在本地保存 API Key，应限制项目目录的文件访问权限。

使用前请确认知识文档允许发送给上述远程 API，并允许在本机向量库中保存。

## 主要配置

| 配置项 | 默认值 | 说明 |
|---|---:|---|
| `LLM_PROVIDER` | `DeepSeek` | 大模型服务商显示名称 |
| `LLM_API_KEY` | 无 | 大模型服务 API Key |
| `LLM_BASE_URL` | `https://api.deepseek.com` | OpenAI Compatible 大模型 API 地址 |
| `LLM_MODEL` | `deepseek-chat` | 回答模型名称 |
| `LLM_TEMPERATURE` | `0` | 最终回答随机度，知识问答建议保持 0 |
| `LLM_MAX_TOKENS` | `3000` | 最终回答最大输出 token 数 |
| `REWRITE_TEMPERATURE` | `0` | 历史问题改写随机度 |
| `REWRITE_MAX_TOKENS` | `200` | 问题改写最大输出 token 数 |
| `RERANK_TEMPERATURE` | `0` | 候选资料重排随机度 |
| `RERANK_MAX_TOKENS` | `1200` | 重排 JSON 最大输出 token 数 |
| `EMBEDDING_PROVIDER` | `硅基流动` | Embedding 服务商显示名称 |
| `EMBEDDING_API_KEY` | 无 | Embedding 服务 API Key |
| `EMBEDDING_BASE_URL` | `https://api.siliconflow.cn/v1` | OpenAI Compatible Embedding API 地址 |
| `EMBEDDING_MODEL` | `BAAI/bge-m3` | Embedding 模型名称 |
| `EMBEDDING_DIMENSION` | `1024` | Qdrant 向量维度 |
| `QDRANT_COLLECTION` | `rag_knowledge` | Qdrant 集合名称 |
| `QDRANT_PATH` | `data/qdrant` | 嵌入式 Qdrant 本地持久化目录 |
| `KNOWLEDGE_DIR` | `knowledge` | 知识文档目录 |
| `DATA_DIR` | `data` | 本地清单和日志目录 |
| `CHUNK_SIZE` | `1200` | 单个知识片段最大字符数 |
| `CHUNK_OVERLAP` | `150` | 相邻知识片段重叠字符数 |
| `EMBEDDING_BATCH_SIZE` | `16` | 单次 Embedding 请求的文本数量 |
| `RETRIEVAL_TOP_K` | `6` | 默认召回片段数量 |
| `RETRIEVAL_CANDIDATE_K` | `20` | 每路向量召回的候选数量 |
| `KEYWORD_TOP_K` | `20` | 每路关键词召回的候选数量 |
| `RETRIEVAL_SCORE_THRESHOLD` | `0.35` | 最低相似度阈值 |
| `RRF_K` | `60` | 向量与关键词排名融合常数 |
| `MAX_RESULTS_PER_SOURCE` | `3` | 进入重排前单个源文件的最大候选数 |
| `ADJACENT_CHUNKS` | `1` | 每个命中向前、向后扩展的片段数 |
| `MAX_CONTEXT_CHARS` | `16000` | 发送给回答模型的最大知识上下文字符数 |
| `REQUEST_TIMEOUT_SECONDS` | `60` | OpenAI Compatible API 请求超时秒数 |
| `API_MAX_RETRIES` | `3` | 网络错误、HTTP 429 和服务端错误的最大重试次数 |

如果问题经常无法召回正确资料，可先将 `RETRIEVAL_SCORE_THRESHOLD` 调低到 `0.25`；如果召回噪声较多，可逐步调高。

## 常见问题

### 本地 Qdrant 无法打开

检查 `QDRANT_PATH` 所在目录是否具有读写权限，并确认没有另一个 `knowledge-rag` 进程同时占用同一个向量库目录。

### 本地清单片段数与向量数不一致

直接执行普通增量同步。工具会逐个核对文档在本地向量库中的实际数量，并自动重建缺失或不完整的文档索引。

### 本地清单片段数与关键词片段数不一致

直接执行普通增量同步。向量完整时工具只会补建 SQLite 关键词索引，不会重新调用 Embedding API。

### 同步失败但界面没有显示完整堆栈

这是预期行为。界面只显示可操作的错误信息，详细中文 `error` 日志保存在 `data/knowledge-rag.log`。

### PowerShell 中没有颜色或交互菜单

请在支持 ANSI 的现代 PowerShell 或 Windows Terminal 中运行。输出被重定向或通过管道传递时，工具会自动切换到纯文本输出。