Architecture#

System Overview#

1
┌─────────────────────────────────────────────────────────┐
2
│                    API Client                            │
3
└─────────────────────┬───────────────────────────────────┘
4
                      │ HTTP
5
                      ▼
6
┌─────────────────────────────────────────────────────────┐
7
│                   FastAPI Server                          │
8
│                  (uvicorn, port 8080)                    │
9
│                                                          │
10
│  ┌─────────────┐    ┌──────────────────────────────┐    │
11
│  │  /health   │    │  /retrieve/by-skill          │    │
12
│  │  /retrieve │───▶│  /retrieve/by-module         │    │
13
│  └─────────────┘    └──────────┬───────────────────┘    │
14
│                                │                         │
15
│                     ┌──────────▼───────────────────┐     │
16
│                     │     HybridRetriever          │     │
17
│                     │  (L1 QueryResultCache)       │     │
18
│                     └──────────┬───────────────────┘     │
19
└───────────────────────────────┬┼──────────────────────────┘
20
                                │
21
        ┌───────────────────────┼───────────────────────┐
22
        │                       │                        │
23
        ▼                       ▼                        ▼
24
┌───────────────┐    ┌────────────────────┐   ┌──────────────┐
25
│ BM25Retriever│    │ DashScope Embedding │   │DashScope    │
26
│  (in-memory) │    │  +  Vector Search   │   │ Reranker    │
27
│   L3 Cache   │    │  (pgvector)         │   │             │
28
└───────┬───────┘    └──────────┬─────────┘   └──────┬──────┘
29
        │                       │                     │
30
        └───────────────────────┼─────────────────────┘
31
                                │
32
                                ▼
33
                    ┌───────────────────────┐
34
                    │  PostgreSQL + pgvector │
35
                    │  L2 Storage           │
36
                    └───────────────────────┘

Retrieval Pipeline#

by-skill 流程#

1
Query: "Token管理"
2
    │
3
    ▼
4
┌─────────────────────────────┐
5
│ 1. L1 Cache Check           │ ──hit──▶ return cached result
6
│    (query + top_k → result) │
7
└─────────────┬───────────────┘
8
              │ miss
9
              ▼
10
┌─────────────────────────────┐
11
│ 2. Query Expansion          │ ──▶ ["Token管理", "Token", "JWT", "AccessToken", ...]
12
│    (SKILL_POINT_SYNONYMS)   │
13
└─────────────┬───────────────┘
14
              │
15
    ┌────────┴────────┐
16
    ▼                 ▼
17
┌────────────┐   ┌─────────────────────┐
18
│ BM25       │   │ Dense Vector Search  │
19
│ (in-memory)│   │ search_similar_chunks│
20
│ L3 Cache   │   │ (pgvector)           │
21
└─────┬──────┘   └──────────┬──────────┘
22
      │                    │
23
      └─────────┬──────────┘
24
                ▼
25
┌─────────────────────────────┐
26
│ 3. RRF Fusion (k=60)       │
27
│    score = Σ 1/(k + rank)  │
28
└─────────────┬───────────────┘
29
              │
30
              ▼
31
┌─────────────────────────────┐
32
│ 4. DashScope Rerank         │
33
│    qwen-rerank model        │
34
└─────────────┬───────────────┘
35
              │
36
              ▼
37
┌─────────────────────────────┐
38
│ 5. Cache result (TTL 5min) │
39
│    return top_k results    │
40
└─────────────────────────────┘

by-module 流程#

1
Query: "用户认证"
2
    │
3
    ▼
4
┌─────────────────────────────┐
5
│ 1. L1 Cache Check           │
6
└─────────────┬───────────────┘
7
              │ miss
8
              ▼
9
┌─────────────────────────────┐
10
│ 2. search_by_module()       │ ──▶ PostgreSQL WHERE module = ?
11
│    (pgvector)               │
12
└─────────────┬───────────────┘
13
              │
14
              ▼
15
┌─────────────────────────────┐
16
│ 3. DashScope Rerank         │
17
└─────────────┬───────────────┘
18
              │
19
              ▼
20
┌─────────────────────────────┐
21
│ 4. Cache + return           │
22
└─────────────────────────────┘

Data Models#

Chunk (storage)#

数据库存储的文档块。

字段	类型	说明
`content`	string	块文本内容
`chunk_index`	int	块序号
`level`	int	标题层级 (2=##, 3=###)
`parent_heading`	string	父标题
`heading_path`	string	完整路径
`source`	string	来源文档名
`module`	string	模块名
`skill_points`	list[string]	技能点列表
`score_points`	list[string]	评分要点
`embedding`	vector(1536)	块级向量
`bm25_score`	float	BM25 分数

RetrievedDocument (API response)#

API 返回的检索结果。

1
content: str                    # 块文本内容
2
metadata: dict                  # 元数据
3
score: float                    # 相似度分数

Caching Strategy#

层级	组件	缓存内容	TTL	说明
L1	`QueryResultCache`	完整检索结果	5min	相同 query 直接返回
L2	PostgreSQL + pgvector	向量 + BM25 数据	持久化	数据库层
L3	`BM25Retriever` (in-memory)	BM25 倒排索引	进程内	API 启动时从 DB 加载

Configuration#

所有参数集中在 config.toml：

1
[retrieval]
2
top_k = 5               # 默认返回文档数
3
rerank_pool_size = 15   # Reranking 候选池大小
4

5
[matching]
6
module_match_threshold = 0.7  # 模块识别相似度阈值
7

8
[rrf]
9
k = 60                  # RRF 融合参数
10

11
[dashscope]
12
api_key = "${DASHSCOPE_API_KEY}"      # 环境变量
13
embedding_model = "text-embedding-v3"
14
reranker_model = "qwen-rerank"
15

16
[database]
17
url = "${ENTERPRISE_KB_DATABASE_URL}"  # 环境变量

Document Format#

Markdown 文档需包含 YAML front-matter：

1
---
2
skill_points:
3
  - 用户登录
4
  - Token管理
5
module: 用户认证
6
score_points:
7
  - 基本: 是否理解登录流程原理
8
---
9
# 用户认证模块
10

11
## 功能规范
12

13
### 1. 登录流程
14
...

Front-matter 字段#

字段	类型	说明
`skill_points`	list[string]	关联的技能点列表
`module`	string	所属模块名（唯一）
`score_points`	list[string]	评分要点

CLI Index Builder#

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