RAG on 姚玉亮的网络日志

赢家的提示词只有 200 字：周末亚马逊活动的三点收获

Fri, 04 Sep 2026 11:00:00 +0800

周末去亚马逊参加了场线下活动。一天下来笔记记了不少，回来翻的时候发现，真正值得写的就三件：两件来自王老师的分享，一件来自活动组织的一场掼蛋游戏。

这三件事看着不相干，但我连起来想了一路，发现它们其实在回答同一个问题：AI 时代做系统，复杂度应该放在哪儿。

一、垃圾文档会精准投毒

王老师讲 RAG 的时候说了一句大白话，我印象很深：知识库问答做不好，先别急着调检索算法，回头看看库里都放了些什么。

这话值得展开。RAG 的流程是先检索、后生成，模型本身不判断检索结果的对错：检索到什么，它就顺着什么讲，还能讲得头头是道。库里要是有份过时的制度、一份新旧口径打架的规范、一份扫描得糊成一团的 PDF，它们不会安静躺着：总会在某次检索里被命中，然后被模型一本正经地引用出去。

所以垃圾文档的问题不是拉低平均分，是投毒：专挑你最需要正确答案的那次查询起作用。

这块我有体感。自己做知识库问答服务那阵子就发现，检索质量的上限由数据治理决定，换模型、调分块策略，都只是在脏数据上打转。对策也没什么玄技，全是纪律：入库要有门槛，来源、格式、时效过得去才放进来；过期文档定期下线，别想着"万一有用"；口径打架必须裁决一个，不能新旧都留着，让检索随机翻牌。

宁可库里 100 份干净的，不要 1000 份说不清的。

二、200 字的提示词，赢了 700 字的

活动下午组织了场游戏：写提示词，驱动模型打掼蛋。

结果有点反直觉。赢家的提示词普遍只有 100 到 200 字，说说目标、风格和几条底线就完了。写得最认真的一位，700 字左右的战术大全，拆牌逻辑、记牌策略、队友配合全写了，没赢。

为什么？我的理解是：现在的模型跟去年不是一回事了。掼蛋这种规则清晰的游戏，算牌、拆牌这些基本功模型自己就会，你再教一遍就是多余的。更糟的是，700 字里那些硬规则会互相打架，把模型天然的判断力框死了，等于在用去年的弱模型标准，调教今年的强模型。

掼蛋是游戏，但规律通用：提示词里最贵的成分不是技巧，是对模型的不信任。

我现在的做法是，每次换更强的模型，第一件事把存量提示词拿出来重测，逐条问"这条还需要吗"，先删后加。删完经常发现，效果反而更好。

三、不要相信用户的 query

这句还是王老师说的，观点很挑衅。

用户带着模糊的意图来，写出来的 query 往往不是他真正想问的：词不对，粒度不对，缺限定。传统做法是工程补救：建同义词库、写纠错规则、训意图分类器，一个 bad case 补一条规则。代码越垒越高，而且系统变聪明的速度，取决于工程师排期的速度。

现在更划算的做法：把 query 交给模型扩写。一句模糊的话，发散成好几路检索形态（同义改写、上位扩展、拆解子问题、补充限定词），并行去检索，召回合并之后再生成。

我觉得这里最值钱的不是扩写本身，是升级路径变了。以前系统变聪明靠写代码、发版本；现在扩写是模型做的，模型升级那天，你这套扩写自动跟着变好，一行代码不用改。写死的规则不会自己长大，模型驱动的能力会。

当然工程不是没事干了。评测集、兜底逻辑、召回质量的度量，这些还是工程的活，只是"理解用户"这类事的实现权交给了模型，验收的责任留给人。

连起来看

回来路上我把这三件事过了一遍，发现它们指向同一个选择：复杂度放在哪。

垃圾文档的对策，是把功夫下在数据治理上，不是算法缝补；掼蛋的输赢，说明模型自己会的东西别硬教，700 字不如 200 字；query 扩写说明，系统能力可以长在模型上，跟着模型自动升级。

我的结论：数据自己养好，理解和发散交给模型，代码只留它真正不可替代的那部分。模型接下来还会继续变强：把系统里会自己变强的部分交给模型，你的系统就免费跟着变强。

别把复杂度锁死在代码和长提示词里。这是我这个周末最大的收获。

RAG 评测：如何客观衡量知识库问答的效果

Sat, 09 Aug 2025 10:30:00 +0800

“到底准不准”，一开始答不上来

知识库问答服务上线后，业务方问得最多的一句话是：“你们这个问答到底准不准？“我们只能拿几个 case 演示一下，说"挺准的”。这个答案撑不住正式验收。更麻烦的是，换了切片策略、换了 embedding 模型、加了 rerank 之后，效果到底是变好还是变坏，光靠人工抽几条根本看不出来。

后来我主导建了一套离线评测，思路不复杂：把 RAG 拆成"检索"和"生成"两段，分开打分。混在一起评，出了问题分不清是没召回，还是 LLM 没把上下文用对。

两段，各自怎么打分

检索段评召回：给定一个问题，期望命中哪些 chunk，看实际召回的 top-k 里中了几个。

生成段评答案：给定问题、召回上下文、标准答案，让 LLM 当裁判，从忠实度、相关度、完整度三个维度打分。忠实度（faithfulness）看的是有没有胡说：每句话是否都能在上下文里找到依据。

两个环节都依赖一份标注集。我们从真实用户 query 里抽了 300 条，请领域同事标注：每条 query 对应的标准 chunk 和参考答案。300 条不算多，但覆盖了高频问法、长尾术语、跨文档问题三类，做回归够用了。

指标怎么算

检索指标用 Recall@k 和 MRR。Recall@k 衡量前 k 个结果里有没有标准答案，MRR 还考虑第一个正确结果出现的位置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


func RetrievalMetrics(expectIDs []string, rankedIDs []string, k int) (recall float64, mrr float64) {
 gold := make(map[string]struct{}, len(expectIDs))
 for _, id := range expectIDs { gold[id] = struct{}{} }

 hit := 0
 firstHit := -1
 for i, id := range rankedIDs {
 if i >= k { break }
 if _, ok := gold[id]; ok {
 hit++
 if firstHit == -1 { firstHit = i + 1 }
 }
 }
 recall = float64(hit) / float64(len(gold))
 if firstHit > 0 { mrr = 1.0 / float64(firstHit) }
 return
}

生成段用 LLM-as-Judge。Prompt 要求裁判输出 JSON，方便程序解析：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


const judgeTpl = `你是严格的问答评测员。请根据"参考上下文"判断"模型回答"的质量。

问题：%s
参考上下文：
%s
参考答案：
%s
模型回答：
%s

请从以下三个维度打分（0-5，整数），并给出一句话理由：
- faithfulness：回答是否完全基于参考上下文，有没有编造
- relevance：是否回答了问题
- completeness：是否覆盖了参考答案的要点

只输出 JSON：{"faithfulness":N,"relevance":N,"completeness":N,"reason":"..."}`

跑评测时，我们把整个 RAG 链路当作黑盒，但在内部埋点把召回的 chunk IDs 也记录下来，这样一次跑批同时产出检索和生成两组指标：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


type EvalResult struct {
 QueryID string
 RecallAt5 float64
 MRR float64
 Faithfulness int
 Relevance int
 Completeness int
}

func (e *Evaluator) RunOne(ctx context.Context, caseItem Case) EvalResult {
 // 跑 RAG，同时拿到答案和召回的 chunk IDs
 answer, retrieved, err := e.rag.AnswerWithTrace(ctx, caseItem.Query)
 if err != nil { return EvalResult{} }

 recall, mrr := RetrievalMetrics(caseItem.GoldChunkIDs, retrieved, 5)
 scores := e.judge.Score(ctx, caseItem, answer)

 return EvalResult{
 QueryID: caseItem.ID, RecallAt5: recall, MRR: mrr,
 Faithfulness: scores.Faithfulness, Relevance: scores.Relevance,
 Completeness: scores.Completeness,
 }
}

最后在 CI 里挂了一个回归任务：每次改 Prompt、换 embedding 模型、调切片大小，自动跑一遍这 300 条，指标和基线对比，Recall 或 Faithfulness 掉超过 2 个百分点就卡住合并。

四个坑

第一个坑是裁判自己就不稳。同一个回答，GPT-4 这次打 4 分、下次打 5 分，基本看运气。我们的对策：温度设 0，Prompt 里给每个分数档位写明确的描述（比如 faithfulness=5 表示"每句话都能在上下文找到依据”），重跑一致性从 70% 提到 88% 左右。再往下抠就没必要了，评测是用来做相对比较的，不是给绝对值盖章。

第二个坑是位置偏见。裁判会偏心上下文里靠前的证据。评测时把召回的 chunk 随机打乱顺序再喂给裁判，别让检索顺序带偏打分。

第三个坑是标注集会过期。文档库一更新，老问题的 gold chunk 可能就失效了。我们每季度 review 一次，顺手把新出现的 bad case 补进集子，标注集从 300 涨到了 500。别指望一步到位，真实失败案例持续沉淀，集子才活得下去。

第四个是框架取舍。RAGAS、TruLens 这类都看过，RAGAS 概念清晰，但在中文和企业术语上，它的指标和人工判断偏差不小。最后我们只借鉴了它的指标定义，Prompt 自己写，可控性更好。

后来

这套评测后来成了改动前的必答题。知识库问答服务几次大的 Prompt 和切片策略调整，都是它拦住了"感觉变好、实际变差"的改动。要说原则就两条：检索和生成分开评，不然定位不了问题；手里得有一份能持续回归的标注集，每次改动才有数字可比。

封面图：kstepanoff / Flickr · CC BY 2.0

RAG 系统中的文档分块策略与效果对比

Fri, 21 Mar 2025 10:30:00 +0800

定长切分出的乱子

数据集管理服务承接了大量 PDF/Word 学术文档的解析与向量化，供知识库问答服务的知识问答使用。最早的分块是图省事的做法：文档解析出纯文本后，直接按 500 字符定长切。

效果很不稳定。表格被腰斩，段落从中间断开，跨页的章节标题和正文落到了两个块里。召回时就出现一种很气人的情况：答案明明在文档里，就是没召回到。

后来我主导把分块链路重做了一遍，对比了几种策略在学术 PDF 和制度类文档上的效果，这篇把做法和踩的坑记下来。

分块抽成了一个接口

我们把分块抽象成一个 Chunker 接口，上层按文档类型选不同实现：

1
2
3
4
5
6
7
8
9


type Chunk struct {
 ID string
 Text string
 Metadata map[string]any
}

type Chunker interface {
 Split(ctx context.Context, doc *ParsedDoc) ([]Chunk, error)
}

ParsedDoc 不是纯文本，是解析阶段留下的结构化结果：段落、标题层级、表格、页码。分块能不能利用上文档结构，差别就在这里。

落地了三种 Chunker。

第一种是固定窗口 + overlap：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


type FixedChunker struct {
 Size int // 字符数
 Overlap int
}

func (c *FixedChunker) Split(_ context.Context, doc *ParsedDoc) ([]Chunk, error) {
 text := strings.Join(doc.Paragraphs, "\n")
 var chunks []Chunk
 for i := 0; i < len(text); i += c.Size - c.Overlap {
 end := i + c.Size
 if end > len(text) {
 end = len(text)
 }
 chunks = append(chunks, Chunk{Text: text[i:end]})
 if end == len(text) {
 break
 }
 }
 return chunks, nil
}

实现最简单，对纯文本类的制度文档勉强可用，对学术 PDF 里的表格几乎无药可救。

第二种是递归字符分块。按分隔符优先级（\n## 、\n### 、\n\n、\n、。）递归切，尽量落在自然边界上。我们参考 LangChain 的 RecursiveCharacterTextSplitter 思路写了 Go 版本，对带 Markdown 标题层级的文档，效果明显好过固定窗口。

第三种是结构化分块，最终成了学术 PDF 的主策略。解析阶段 PDF 经 Layout 识别后，每个元素带类型（heading/paragraph/table）和层级，分块规则是：

每个 chunk 以一个标题为起点，把其下的段落、表格、子标题内容聚合，直到超过最大 token 数；
表格整体作为一个独立 chunk，不与正文混切，表格前补一行"表 X：标题"作为上下文；
chunk metadata 里写入 title_path（如"第三章 > 3.2 实验设计"），召回后拼 Prompt 时用上。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


func (s *StructuredChunker) splitByHeadings(blocks []Block) []Chunk {
 var chunks []Chunk
 var cur *ChunkBuf
 for _, b := range blocks {
 if b.Type == BlockHeading && b.Level <= s.MaxLevel {
 if cur != nil {
 chunks = append(chunks, cur.Build())
 }
 cur = NewChunkBuf(b.Text, b.Level)
 continue
 }
 if b.Type == BlockTable {
 chunks = append(chunks, Chunk{
 Text: tableToText(b.Table),
 Metadata: map[string]any{"type": "table", "title": b.Table.Title},
 })
 continue
 }
 cur.Append(b.Text)
 if cur.TokenCount() > s.MaxTokens {
 chunks = append(chunks, cur.Build())
 cur = cur.CarryOver()
 }
 }
 if cur != nil {
 chunks = append(chunks, cur.Build())
 }
 return chunks
}

Embedding 阶段所有 chunk 统一过向量模型，写入向量库时带上 metadata，检索时用 metadata 做过滤和重排。

四个坑

token 估算比想得麻烦。一开始按字符数估算长度，实际中文一个汉字往往对应 1 个以上 token，结果超长 chunk 被 embedding 接口截断。改用和 embedding 模型一致的 tokenizer 做长度控制，才算对齐。

overlap 也不是越大越好。它能缓解边界信息丢失，但代价是相邻 chunk 高度相似，召回时占满 top-k 却没提供新信息。后来我们在结构化分块里把 overlap 设成了 0，靠标题路径提供上下文；只有固定窗口策略才保留 10%~15%。

表格要单独处理。转文本时如果直接用空格拼接列，语义全乱。我们统一转成 Markdown 表格，前面加一句标题；超宽表格按列拆成多个子表。对"某指标在某条件下的数值"这类问题，这招对召回准确率的提升最明显。

还有 metadata。title_path、页码、文档 ID 这些字段，在检索后拼上下文时能明显减少幻觉，做溯源和高亮也靠它。

后来

没有万能分块尺寸，策略得跟着文档类型走。结构化文档优先用结构信息，纯文本用递归字符分块兜底，表格单独成块。在数据集管理服务里，我们按文档类型路由 Chunker，分块结果和 metadata 一起入库，知识库问答服务的问答命中率比定长切分改善了不少。

封面图：duh.denise / Flickr · CC BY 2.0

light_rag 轻量检索在知识库问答中的集成

Mon, 03 Feb 2025 10:30:00 +0800

跨文档的问题，向量检索接不住

知识库问答服务最早的 RAG 方案很朴素：向量检索加 TopK 拼接。用户问题向量化，去 Milvus 里查最相似的 chunk，拼进 prompt 喂给模型。单文档、短问答的场景，这套够用。

跨文档的问题就不行了。比如问"A 公司和 B 公司在 2023 年有哪些合作项目"，向量检索只能捞回包含关键词的片段，两份文档各说各的，实体关系对不上。

我们调研过 GraphRAG，效果确实不错，但太重：要构建完整的知识图谱、做社区检测、生成层级摘要，索引一次几个小时，资源消耗也大。我们的知识库大多是几百到几千篇文档的规模，用 GraphRAG 属于大炮打蚊子。

light_rag 正好填了这个空。

GraphRAG 太重，纯向量太轻

它的核心思想是轻量级的图谱增强检索，做三件事：

实体和关系抽取：文档入库时用 LLM 抽取实体和关系，存进图结构，KV 存储就够，不依赖 Neo4j；
双重检索：查询时同时做向量检索（低层，找具体片段）和图谱检索（高层，找实体关联），结果去重合并；
增量更新：新文档只抽取新的实体和关系，不需要重建整个图谱。

落地时拆成两个服务：数据集管理服务用 Python（FastAPI）集成 light_rag 做索引构建，知识库问答服务（Go）通过 HTTP 调检索接口。索引数据存 MongoDB，向量存 Qdrant。

索引：入库时抽实体和关系

Python 侧的索引服务，主要活儿是把 light_rag 的存储都指到自己的基础设施上：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44


from lightrag import LightRAG, QueryParam
from lightrag.llm import openai_complete_if_cache, openai_embed
from lightrag.utils import EmbeddingFunc
import numpy as np

async def llm_model_func(prompt, system_prompt=None, history_messages=[], **kwargs):
 return await openai_complete_if_cache(
 "gpt-4o-mini",
 prompt,
 system_prompt=system_prompt,
 history_messages=history_messages,
 api_key=settings.OPENAI_API_KEY,
 base_url=settings.OPENAI_BASE_URL,
 **kwargs,
 )

async def embedding_func(texts):
 resp = await openai_embed(
 texts,
 model="text-embedding-3-small",
 api_key=settings.OPENAI_API_KEY,
 base_url=settings.OPENAI_BASE_URL,
 )
 return np.array(resp)

def get_rag(workspace: str) -> LightRAG:
 return LightRAG(
 working_dir=f"./rag_data/{workspace}",
 llm_model_func=llm_model_func,
 embedding_func=EmbeddingFunc(
 embedding_dim=1536,
 max_token_size=8192,
 func=embedding_func,
 ),
 kv_storage="MongoKVStorage",
 vector_storage="QdrantVectorDBStorage",
 graph_storage="NetworkXStorage",
 )

@app.post("/index/{kb_id}")
async def index_document(kb_id: str, doc: DocumentRequest):
 rag = get_rag(kb_id)
 await rag.ainsert(doc.content)
 return {"status": "ok", "chunks": doc.chunk_count}

知识库问答服务 Go 侧调用检索：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


type LightRAGClient struct {
 baseURL string
 client *http.Client
}

type RetrieveRequest struct {
 Query string `json:"query"`
 Mode string `json:"mode"` // "hybrid", "local", "global", "naive"
 TopK int `json:"top_k"`
 KnowledgeID string `json:"knowledge_base_id"`
}

type RetrieveResult struct {
 Context string `json:"context"`
 Sources []Source `json:"sources"`
}

func (c *LightRAGClient) Retrieve(ctx context.Context, req RetrieveRequest) (*RetrieveResult, error) {
 body, _ := json.Marshal(req)
 httpReq, err := http.NewRequestWithContext(ctx, "POST",
 c.baseURL+"/retrieve", bytes.NewReader(body))
 if err != nil {
 return nil, err
 }
 httpReq.Header.Set("Content-Type", "application/json")

 resp, err := c.client.Do(httpReq)
 if err != nil {
 return nil, err
 }
 defer resp.Body.Close()

 var result RetrieveResult
 if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
 return nil, err
 }
 return &result, nil
}

在知识库问答服务主流程中根据问题类型选择检索模式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


func (h *Handler) selectRAGMode(query string) string {
 // 简单事实性问题用 local，跨文档关联用 hybrid/global
 if isSimpleFactual(query) {
 return "local"
 }
 if containsMultiEntityQuery(query) {
 return "hybrid"
 }
 return "hybrid"
}

result, err := h.ragClient.Retrieve(ctx, RetrieveRequest{
 Query: req.Query,
 Mode: h.selectRAGMode(req.Query),
 TopK: 5,
 KnowledgeID: req.KnowledgeBaseID,
})

几笔权衡

实体抽取是按文档烧 LLM 的。每篇文档入库都要调一次模型抽实体，库一大，API 费用肉眼可见。我们用 gpt-4o-mini 做抽取，比 GPT-4o 低一个量级，质量也够用。特别大的知识库，建议先做文档过滤，只索引高价值内容。

检索模式有讲究。naive 就是纯向量检索，local 侧重实体关联，global 侧重社区关系摘要，hybrid 是两者结合。实测 hybrid 效果最好，延迟也最高，要多花 300 到 800 毫秒。延迟敏感的场景我们默认 local，复杂问题才上 hybrid。

图谱存储选型，light_rag 默认用 NetworkX，图在内存里，重启后从 KV 存储恢复。万级实体以内没问题，十万级以上建议换 Neo4j。我们的规模在万级以内，NetworkX 足够，就不多背一个图数据库了。

并发索引会打架。多篇文档同时 ainsert 有写冲突，light_rag 内部用文件锁兜底，我们在数据集管理服务用 pond 池控制同一知识库的并发索引数，避免锁竞争。

还有它和现有 RAG 的关系：light_rag 没有替代原有的向量检索，而是作为可选检索器接进来。不需要图谱的简单知识库，配置里选"纯向量模式"，就不引入这笔额外的索引开销。

平衡点在哪

light_rag 值得选，是因为它位置选得好：夹在传统向量 RAG 和重型 GraphRAG 中间。图谱增强补上了跨文档关联，增量更新和轻量存储又没让索引流程变得难以承受。几百到几千篇文档的企业知识库，它的投入产出比是合适的。至于效果和延迟怎么平衡，检索模式可以切，留给具体场景自己挑。

封面图：archer10 (Dennis) / Flickr · CC BY-SA 2.0

企业级 LLM 问答服务架构总览

Wed, 18 Dec 2024 10:30:00 +0800

各自管 Key 的日子

2024 年初，公司内部好几条业务线都想接大模型：客服要做智能问答，研发要做代码助手，数据团队要做自然语言查数。各团队自己调 OpenAI 或本地部署的模型，结果就是 Key 管理混乱，提示词和知识库没法复用，鉴权和审计更谈不上。

所以我们做了一个企业级的知识库问答服务：对上提供统一 API，对下屏蔽不同模型供应商的差异，RAG 检索增强、多轮对话、工具调用、流式输出都收进来。

六层，各管一摊

服务用 Go（Gin）做网关层，从上到下分六层：

接入层：统一鉴权（复用统一认证中心的 JWT）、限流、SSE 流式输出；
会话层：多轮对话历史管理、Token 预算控制、对话摘要；
检索层：混合检索（BM25 + 向量）、light_rag 轻量检索、知识图谱增强；
模型层：统一 LLM 适配层，封装 OpenAI、Azure、VLLM、HuggingFace 等，支持多模型路由和降级；
工具层：MCP 工具调用、Function Calling、外部 API 编排；
数据层：PostgreSQL 存对话和元数据，Milvus/Qdrant 存向量，Redis 做缓存和会话状态。文档解析和向量化不在本服务里，交给数据集管理服务做（eino + pond 高并发），问答服务只做检索和生成，职责清楚。

网关入口

路由注册和中间件链长这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


func NewRouter(h *Handler, auth *AuthMiddleware) *gin.Engine {
 r := gin.New()
 r.Use(gin.Recovery(), zaplogger.GinLogger(), auth.Verify())

 v1 := r.Group("/api/v1")
 {
 v1.POST("/chat/completions", h.ChatCompletions) // 类 OpenAI 接口
 v1.POST("/chat/stream", h.ChatStream) // SSE 流式
 v1.GET("/conversations/:id", h.GetConversation)
 v1.POST("/conversations/:id/messages", h.SendMessage)
 v1.POST("/tools/call", h.CallTool) // MCP 工具
 }
 return r
}

对话主流程

编排长这样（伪代码，展示核心链路）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45


func (h *Handler) ChatStream(c *gin.Context) {
 var req ChatRequest
 if err := c.ShouldBindJSON(&req); err != nil {
 respondError(c, 400, err)
 return
 }

 // 1. 加载历史 + 滑动窗口裁剪
 history, err := h.convSvc.LoadHistory(c, req.ConversationID, req.TokenBudget)
 if err != nil {
 respondError(c, 500, err)
 return
 }

 // 2. RAG 检索
 contexts, err := h.retriever.Retrieve(c, req.Query, req.KnowledgeBaseIDs,
 retriever.WithHybrid(true), retriever.WithTopK(5))
 if err != nil {
 // 检索降级：不阻断主流程，用纯对话兜底
 h.log.Warn("retrieve failed, fallback to chat-only", zap.Error(err))
 }

 // 3. 构造消息
 messages := h.promptBuilder.Build(req.Query, history, contexts, req.SystemPrompt)

 // 4. 选择模型 + 流式生成
 model := h.router.Route(req.Model, req.Priority)
 stream, err := h.llm.ChatCompletionStream(c, model, messages)
 if err != nil {
 respondError(c, 502, err)
 return
 }

 // 5. SSE 推流 + 异步落库
 c.Stream(func(w io.Writer) bool {
 chunk, ok := <-stream
 if !ok {
 go h.convSvc.SaveMessage(req.ConversationID, messages, accumulated)
 return false
 }
 accumulated += chunk.Content
 c.SSEvent("message.delta", chunk)
 return true
 })
}

四个权衡

SSE 的错误处理是个坑：Header 一旦写出去，就回不去标准 JSON 错误了。所以先同步等模型连接成功（拿到第一个 chunk 或错误），再切换到 SSE 流；生成中途出错，用 event: error 事件推给客户端，客户端统一按事件处理。

检索不能绑架主流程。向量库偶尔抖动超时，不能让整个问答跟着挂。检索设了 800ms 超时，超时就走纯对话模式，并在响应头标注 X-Retrieval-Mode: fallback，前端可以提示用户：这条答案没过知识库。

对话历史不全塞 Redis。长对话的内存占用大，最后是 PostgreSQL 持久化 + Redis 缓存最近 N 轮的混合策略，超出窗口的历史通过摘要压缩。

模型路由先规则后智能。简单问题给便宜模型，复杂问题路由到强模型。路由策略初期基于规则（关键词 + 长度），后续计划加一个小模型做意图分类。

后来

回头看，这个服务的价值不在封装了多少个模型，而在把鉴权、检索、上下文、工具调用这些共性能力沉淀成平台，让业务方只需要关心自己的知识库和提示词。统一接入后，Key 管理、成本统计、审计日志都有了着落，新业务接入 LLM 的周期从周级降到了天级。

封面图：robert.claypool / Flickr · CC BY 2.0