Enterprise KB RAG#

企业知识库 RAG 系统 — 提供标准化 REST API，通过混合检索（BM25 + 向量 + RRF + 重排）查询企业内部最佳实践和技术规范。

快速开始#

1. 安装依赖#

1
uv sync

2. 配置环境变量#

必需的环境变量在 config.toml 中配置，无需复制 .env：

1
[database]
2
url = "postgresql+asyncpg://postgres:YOUR_PASSWORD@localhost:5432/AI-Interview"
3

4
[dashscope]
5
api_key = "YOUR_DASHSCOPE_API_KEY"

3. 初始化数据库#

确保 PostgreSQL 已安装并启用 pgvector 扩展（PostgreSQL 15+）：

1
CREATE EXTENSION IF NOT EXISTS vector;
2
CREATE DATABASE AI-Interview;

4. 构建索引#

1
# 全量重建（会清空现有数据）
2
uv run python scripts/build_index.py --source ./enterprise-kb/
3

4
# 增量更新（暂未实现）
5
uv run python scripts/build_index.py --source ./enterprise-kb/ --incremental

5. 启动服务#

1
uv run python -m enterprise_kb.api

项目结构#

1
enterprise-kb/
2
├── enterprise-kb/              # Markdown 源文档（知识库内容）
3
├── src/enterprise_kb/
4
│   ├── api.py                 # FastAPI 服务与路由
5
│   ├── cache.py               # L1 查询结果缓存（TTL 5min）
6
│   ├── config.py              # 配置加载（config.toml）
7
│   ├── models.py             # 数据模型（Chunk、RetrievedDocument）
8
│   ├── markdown_parser.py     # Markdown 解析与分块
9
│   ├── storage.py             # PostgreSQL + pgvector 存储层
10
│   ├── bm25_retriever.py      # BM25 稀疏检索（内存索引）
11
│   ├── embedding_service.py   # DashScope text-embedding-v3 向量化
12
│   ├── reranker.py           # DashScope qwen3-rerank 重排序
13
│   ├── fusion.py             # RRF（Reciprocal Rank Fusion）融合
14
│   └── retriever.py          # HybridRetriever 编排层
15
├── scripts/
16
│   └── build_index.py         # CLI 索引构建工具
17
├── tests/                      # 测试套件
18
├── config.toml                 # 配置文件
19
└── pyproject.toml

命令参考#

命令	说明
`uv sync`	安装依赖
`uv run pytest tests/ -v`	运行全部测试
`uv run python scripts/build_index.py --source ./enterprise-kb/`	全量重建索引
`uv run python -m enterprise_kb.api`	启动 API 服务（默认 `0.0.0.0:8080`）

知识库文档格式#

知识库文档放在 enterprise-kb/ 目录下，以 Markdown + YAML front-matter 编写：

1
---
2
skill_points:
3
  - Redis数据类型
4
  - 缓存穿透
5
module: Redis缓存
6
score_points:
7
  - "基础: 能否正确选择 String/Hash 类型并说明适用场景"
8
  - "进阶: 能否设计缓存穿透防御方案"
9
---
10
# Redis缓存模块
11

12
## 功能规范
13

14
### 数据类型与适用场景
15

16
#### String
17
最基础类型，最大 512MB...
18

19
#### Hash
20
适合存储对象结构...

front-matter 字段：

字段	必填	说明
`skill_points`	是	技能点列表，供 `/retrieve/by-skill` 检索
`module`	是	模块名称，供 `/retrieve/by-module` 检索
`score_points`	是	评分要点，格式 `"级别: 描述"`

正文标题层级：

层级	行为
`#`	文档标题，跳过
`##`	父级上下文，不单独成块
`###`	上下文前缀，每个 `####` chunk 的内容前缀
`####`	最小分块单位，每个 `####` 及下内容合成一个 chunk

检索流程#

by-skill 流程（按技能点检索）：

1
请求: POST /retrieve/by-skill
2
  │
3
  ├─ 1. 元数据预过滤 → 从 DB 筛选 skill_points 匹配的 chunk IDs
4
  ├─ 2. BM25 稀疏检索 → 在过滤出的 IDs 中用 rank_bm25 计算
5
  ├─ 3. 向量检索 → 在过滤出的 IDs 中用 pgvector 余弦距离
6
  ├─ 4. RRF 融合 → k=60，混合稀疏+密集排序
7
  └─ 5. 重排序 → DashScope qwen3-rerank 输出最终顺序

by-module 流程（按模块检索）：

1
请求: POST /retrieve/by-module
2
  │
3
  ├─ 1. 元数据预过滤 → 从 DB 筛选 module 匹配的 chunk IDs
4
  ├─ 2. 向量检索 → 在过滤出的 IDs 中用 pgvector
5
  └─ 3. 重排序 → DashScope qwen3-rerank