跳转至

指南 02 · 知识库问答（RAG）

本章演示如何让 Agent 基于你自己的知识库回答问题（检索增强生成）。链路是：

知识文档 → 切分(splitter) → 向量化(embedder) → 入库(store)
                                        │
用户问题 → 检索(retriever) → KnowledgeBaseSearch 节点 → 检索文本注入 ChatLLM(context=...) → Answer

框架的 retrieval 能力包把「切分 / 向量化 / 存储 / 检索 / 导入」抽象成协议 + 内置实现，并配套 KnowledgeBaseSearch 节点接入工作流。协议细节见专题 · RAG 检索管线。

1. 导入知识并构建 retriever

from agentframework.retrieval import (
    HashEmbedder,
    MemoryVectorStore,
    RecursiveCharacterSplitter,
    create_retriever,
    ingest_document,
)

store = MemoryVectorStore()  # 内置内存向量库（演示）
embedder = HashEmbedder(dimension=32)  # 内置哈希 embedder（离线可跑，非语义）
splitter = RecursiveCharacterSplitter(chunk_size=50, chunk_overlap=10)

# 导入一段知识（自动 切分→embed→入库；同 source 重导幂等）
ingest_document(
    long_text,
    store=store,
    embedder=embedder,
    source="zhijin_guide",
    splitter=splitter,
)

# 构建检索器：纯向量（默认 bm25_weight=0.0）
retriever = create_retriever(store, embedder, top_k=2)

上例 HashEmbedder 是确定性哈希，只保证精确词匹配、不具语义，供无外部依赖的演示/测试。要语义检索，把它换成真实中文 embedding 实现（实现 BaseEmbedder 即可，见RAG 管线）。

2. 接入工作流

KnowledgeBaseSearch 检索当前问题 → 把拼接的检索文本 kb.text 注入 ChatLLM(context=...)：

from agentframework import Workflow, serve
from agentframework.nodes import Answer, ChatLLM, KnowledgeBaseSearch

wf = Workflow(name="kb_qa")
wf.add_node(KnowledgeBaseSearch(name="kb", retriever=retriever))  # query 缺省取最近 user 消息
wf.add_node(
    ChatLLM(
        name="llm",
        chat_model=model,
        context=wf.ref("kb.text"),  # 检索文本作为参考上下文
        output=False,  # 收口，由 Answer 输出
    )
)
wf.add_node(Answer(name="ans", text=wf.ref("llm.reply")))
wf.add_edge("kb", "llm")
wf.add_edge("llm", "ans")

app = wf.compile()
serve({"app-kb": app}, host="0.0.0.0", port=8080)

KnowledgeBaseSearch 输出：

输出 类型 说明
results list 引用列表 [{source, chunk_index, text, score}]
text str 拼接检索文本（[来源-块#n] 内容，块间空行），供 LLM 上下文
has_results bool 是否有检索结果

query 不传时，节点会自动取对话历史最后一条 user 消息作为检索词，所以「先问、再检索」的对话天然可用。

3. 完整可运行示例

本站收录了完整可运行源码与运行说明：

  • kb_qa 示例：从 CSV 文档导入到 serve 的全流程——导入公积金问答知识 → 建 KnowledgeBaseSearch → ChatLLM(context=...) → Answer → 起网关，交互提问即可看到带知识库引用的回答。
  • rag_kb 示例：真实第三方向量库（ChromaDB 持久化）全流程——实现框架 VectorStore 协议对接 chromadb.PersistentClient，展示「切分 → embed → ChromaDB 落盘 → 带引用检索」的完整能力（需 pip install chromadb）。

下一步