learn-lightrag

用 Go 从零渐进构建一个 LightRAG（HKUDS, EMNLP'25）。每节加一个机制——从最小 RAG 闭环到双层检索四种模式——并对照上游 Python 源码。

Build LightRAG (HKUDS, EMNLP'25) from scratch in Go, session by session — from a minimum RAG loop all the way to dual-level retrieval across four query modes, with the upstream Python source on the side.

English version below · README.en.md

LightRAG 是 GraphRAG 家族的开源实现：先从文档抽实体/关系建知识图谱，再用「向量检索 + 图遍历」双层并取做问答。这个仓库不是教你「用 LightRAG」，而是教你「它是怎么从零长出来的」。

11 节 Go 实现 + 端到端集成 + 2 篇附录 + 多模型指南，每节单独成模块，互不依赖。看完 11 节你能徒手画出 LightRAG 的全栈架构图。

LightRAG is an open-source GraphRAG: extract entities/relations into a knowledge graph during ingestion, then answer queries by combining vector retrieval over chunks with graph traversal over the KG. This repo is not about using LightRAG — it's about how it grows from scratch.

11 Go chapters + end-to-end integration + 2 appendices + multi-model guide. Each chapter is its own self-contained module — no cross-imports. After 11 chapters you can sketch LightRAG's full architecture from memory.

git clone https://github.com/Ding-Ye/learn-lightrag.git
cd learn-lightrag/agents/s01-minimum-loop

# 用真 OpenAI（需要 OPENAI_API_KEY）
export OPENAI_API_KEY=sk-...
go run . -q "Who is Scrooge?"

# 完全离线（默认 mock provider + mock embedder，CI 用的就是这个）
go run . -provider mock -q "Who is Scrooge?"

# 跑测试
go test -v ./...

需要 Go ≥ 1.22。/ Go ≥ 1.22 required.

s02 的 OpenAIProvider 和 s06 的 OpenAIEmbedder 都接收 WithBaseURL(...)，所以任意 OpenAI-compatible 端点都是 1 行切换：

export DEEPSEEK_API_KEY=sk-...
# 在你的 demo / pipeline 里：
# prov := NewOpenAIProvider(WithBaseURL("https://api.deepseek.com/v1"),
#                            WithModel("deepseek-chat"),
#                            WithAPIKey(os.Getenv("DEEPSEEK_API_KEY")))

支持 8 个 profile：OpenAI / DeepSeek / Moonshot / Qwen (DashScope) / Groq / OpenRouter / 自托管 vLLM / Anthropic（OpenRouter 代理或 80 行原生 adapter）。详见 多模型接入指南。

cd web
npm install
npm run dev    # http://localhost:3000

双语 Markdown 渲染 + 上游源码侧栏对照。

✅ = 已完成 / shipped；⏳ = 计划中 / planned。

learn-lightrag/
├── agents/sNN-<slug>/      # 每节一个独立 Go 模块（自包含，无跨节 import）
│   └── s01-minimum-loop/
├── docs/{zh,en}/           # 双语文档，每节一对 .md，标题数自动比对
├── upstream-readings/      # 上游源码节选，带注解
├── web/                    # Next.js 15 文档站
├── .github/workflows/      # CI: go vet+build+test 矩阵 / 双语对齐 / web 构建
├── go.work                 # 多模块工作区
└── .learn/                 # 元数据（research-notes / plan / state）

上游 LightRAG 是 Python，我们用 Go 重写不是为了"性能更好"——而是为了"语义更显式"：

• 类型替代 dict：上游 dict[str, Any] 散落各处，Go 强制 struct 命名所有字段。
• 接口替代 callable：上游 llm_model_func: Callable 在 Go 里是 Provider interface，编译期就能换实现。
• goroutine + context 替代 asyncio：取消语义显式可见，不再有 PipelineCancelledException 这种异常代控制流。
• stdlib 优先：除 pkoukk/tiktoken-go(s04) 外不引入任何第三方库，最大化代码可读性。

The upstream is Python; we rewrite in Go not for "better performance" but for more explicit semantics: types replace dicts, interfaces replace callables, context.Context replaces asyncio.CancelledError, stdlib-first.

• HKUDS/LightRAG：上游实现 + EMNLP'25 paper。MIT licensed.
• shareAI-lab/learn-claude-code：教学法启发——「心智模型 → ASCII 图 → 30-60 行核心代码 → 与上一节的 diff → 动手试 → 上游源码导读」六段式骨架完全照搬。
• learn-repo-generator skill：自动化生成本仓库的工具链。

MIT — see LICENSE. 上游 LightRAG 同为 MIT，本仓库的 derivative 合规。