← blog 架构与系统 · 2026-04-21
enterprise RAG architecture
企业知识库 RAG 服务的整体架构：FastAPI 混合检索管线、数据模型、三级缓存策略与集中配置说明。
System Overview
graph TD
Client["API Client"] -->|HTTP| Server
subgraph Server["FastAPI Server (uvicorn, port 8080)"]
H["/health"]
R["/retrieve /retrieve/by-skill /retrieve/by-module"]
HR["HybridRetriever (L1 QueryResultCache)"]
R --> HR
end
HR --> BM25["BM25Retriever (in-memory) L3 Cache"]
HR --> EMB["DashScope Embedding + Vector Search (pgvector)"]
HR --> RER["DashScope Reranker"]
BM25 --> PG[(PostgreSQL + pgvector L2 Storage)]
EMB --> PG
RER --> PGRetrieval Pipeline
by-skill 流程
graph TD
Q["Query: Token管理"] --> L1["1. L1 Cache Check (query + top_k → result)"]
L1 -->|hit| RET["return cached result"]
L1 -->|miss| EXP["2. Query Expansion (SKILL_POINT_SYNONYMS) → [Token管理, Token, JWT, AccessToken, ...]"]
EXP --> BM["BM25 (in-memory) L3 Cache"]
EXP --> DEN["Dense Vector Search search_similar_chunks (pgvector)"]
BM --> RRF["3. RRF Fusion (k=60) score = Σ 1/(k + rank)"]
DEN --> RRF
RRF --> RER["4. DashScope Rerank qwen-rerank model"]
RER --> CACHE["5. Cache result (TTL 5min) return top_k results"]by-module 流程
graph TD
Q["Query: 用户认证"] --> L1["1. L1 Cache Check"]
L1 -->|miss| SBM["2. search_by_module() (pgvector) → PostgreSQL WHERE module = ?"]
SBM --> RER["3. DashScope Rerank"]
RER --> CACHE["4. Cache + return"]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 返回的检索结果。
content: str # 块文本内容
metadata: dict # 元数据
score: float # 相似度分数Caching Strategy
| 层级 | 组件 | 缓存内容 | TTL | 说明 |
|---|---|---|---|---|
| L1 | QueryResultCache | 完整检索结果 | 5min | 相同 query 直接返回 |
| L2 | PostgreSQL + pgvector | 向量 + BM25 数据 | 持久化 | 数据库层 |
| L3 | BM25Retriever (in-memory) | BM25 倒排索引 | 进程内 | API 启动时从 DB 加载 |
Configuration
所有参数集中在 config.toml：
[retrieval]
top_k = 5 # 默认返回文档数
rerank_pool_size = 15 # Reranking 候选池大小
[matching]
module_match_threshold = 0.7 # 模块识别相似度阈值
[rrf]
k = 60 # RRF 融合参数
[dashscope]
api_key = "${DASHSCOPE_API_KEY}" # 环境变量
embedding_model = "text-embedding-v3"
reranker_model = "qwen-rerank"
[database]
url = "${ENTERPRISE_KB_DATABASE_URL}" # 环境变量Document Format
Markdown 文档需包含 YAML front-matter：
---
skill_points:
- 用户登录
- Token管理
module: 用户认证
score_points:
- 基本: 是否理解登录流程原理
---
# 用户认证模块
## 功能规范
### 1. 登录流程
...Front-matter 字段
| 字段 | 类型 | 说明 |
|---|---|---|
skill_points | list[string] | 关联的技能点列表 |
module | string | 所属模块名（唯一） |
score_points | list[string] | 评分要点 |
CLI Index Builder
# 全量重建
uv run python scripts/build_index.py --source ./enterprise-kb/
# 增量更新（目前为提示模式）
uv run python scripts/build_index.py --source ./enterprise-kb/ --incrementalGit Hook
将 hooks/post-commit 复制到 .git/hooks/post-commit 即可在每次提交后自动增量更新索引。