Ch21: WeKnora 源码走读导言——克隆、目录地图与调试环境

Part 8: WeKnora 源码走读（大师路径 · 阶段 D） 前置：Ch06 架构 + Ch14 动手实验 后续：Ch22 一次问答的完整旅程 系列目录：README · 大师成长路径

结论先行：成为 RAG 大师的最后一段路是 读得懂生产级代码。本章不教算法，教你怎么在 WeKnora 仓库里 不迷路——克隆、目录地图、一次 grep 定位、本地断点该打在哪。

一、你在 Part 8 要达成什么

Part 8 假设你已读完：Ch01–Ch06（概念+架构）、Ch14（环境跑通）。否则请先补 Ch14。

二、克隆与本地环境（15 分钟）

git clone https://github.com/Tencent/WeKnora.git
cd WeKnora
cp .env.example .env
# 填入 LLM / Embedding Key；本地可 Ollama + DeepSeek API

docker compose up -d    # 推荐首次验证
# 或 make dev-start（以仓库 README 为准）

大师习惯：fork 到自己账号，分支命名 feat/your-topic，PR 前先 git fetch upstream && git rebase upstream/main。

三、目录地图（按「管线」而非字母排序）

WeKnora/
├── cmd/                    # 进程入口（API server、worker…）
├── internal/
│   ├── handler/            # HTTP 层：参数校验、状态码
│   ├── application/
│   │   ├── service/        # 业务编排：一次「问答」的逻辑在这里串起来
│   │   └── repository/     # 数据库读写
│   ├── infrastructure/
│   │   └── docparser/      # Go 侧文档解析、chunk（与 Python 衔接）
│   └── types/              # 接口定义、DTO
├── pkg/ 或 internal/ 下     # 检索、融合、分块等（版本间可能在 pkg/ 或 internal/）
│   ├── eventmanager/       # 事件总线
│   ├── retriever/          # BM25 / vector / graph
│   ├── fusion/             # RRF
│   ├── rerank/             # 复合 Rerank
│   └── chunker/            # 自适应分块
├── docreader/              # Python 微服务：Excel/PDF/OCR 等
├── frontend/               # Vue 3 + Pinia
└── docker/                 # 部署

注意：开源项目目录会 refactor。本章给出 职能地图；若路径不一致，用 grep -r "RRF\|ReciprocalRank" . 找真实包名。

四、三条「grep 定位法」（issue 来了先用这个）

示例：

cd WeKnora
rg -l "ReciprocalRank\|RRF" --glob '*.go'
rg -l "ChunkSize\|chunker" --glob '*.go'
rg -l "DISPIMG\|excel" docreader/

五、读源码的推荐顺序（Part 8 章节对应）

六、调试技巧

1. 日志：启动 API 时开 debug；检索请求带 trace_id（若有）串联三路。
2. 最小复现：单知识库 + 单文档 + 单 query，排除 Agent/联网干扰。
3. 对比实验：改代码前后用 Ch20 Benchmark 跑 10 条。
4. 读 PR： weknora-practice 15 案 = 真实改动锚点。

章末 · 大师自检

• 本地 Docker 全栈跑通一次问答
• 不看文档说出 handler / service / docreader 各负责什么
• 用 rg 找到项目中 RRF 相关 Go 文件至少 1 个
• 说明 Part 8 与 Ch06 的关系：Ch06 讲 设计，Part 8 讲 代码在哪

延伸阅读

• Ch06 架构
• 精读: WeKnora
• WeKnora 实战 case-index