手写代码频繁报错？教你用 LANGCHAIN构建本地知识库实现高精度问答

手写代码最让人头疼的不是逻辑本身，而是没完没了的报错。很多时候，你只是调错了一个参数名，或者记错了某个类的引入路径，终端里就弹出长长一串红字。

去问通用大模型？往往更崩溃。大模型的训练数据有截止时间，而且它喜欢“一本正经地胡说八道”。拿 LangChain 来说，版本迭代快，0.1 到 0.3 的接口变动很大。你问它一个关于检索链的写法，它随手给你一段一年前的老代码，跑起来直接报 `ImportError: cannot import name ‘RetrievalQA’`。

要解决这个问题，最实在的办法就是用 LangChain 自己做一套本地知识库，把最新的官方文档、API 参考手册或者你自己的项目规范喂给它。大模型每次写代码前，先去你的本地库里查最新资料，再基于事实生成答案。

但是，很多人搭出来的知识库依然频繁翻车：要么检索不到准确代码，要么模型给出的建议完全牛头不对马嘴。我自己在这个方向上调试了很久，发现高精度的问答系统不是随便跑通一段 Demo 就行，核心在于文本切分、混合检索、重排筛选这三个关键环节。

为什么你的本地知识库问答总给错代码？

很多人做本地知识库，就是把整个官方文档或者几十个 Markdown 文件直接塞进向量库，接着就写检索代码。这样跑出来的系统，准确率往往很低。

原因主要有三点：

1.代码被拦腰切断：通用文本切分工具按字数生搬硬套，可能一个函数上半截在块 A，下半截在块 B，中间的参数说明和逻辑链条断了。

2.符号与专有名词检索失真：纯向量检索看的是语义相似度，但在代码排错场景下，报错信息往往是精确的字符串，比如 `AttributeError: module ‘langchain’ has no attribute ‘llms’`。纯向量模型很难准确匹配这些专有符号。

3.噪音文档稀释注意力：单次检索召回 10 个片段，里面如果混杂了 5 个不相关的过时说明，大模型就会被这些噪音带偏。

想要得到高精度的代码答疑，必须在每一个环节选对工具和参数。

关键组件与切分策略选型

构建本地知识库时，不能盲目堆砌组件。下面是我在不同规模项目里测试对比得出的选型参考：

除了工具选型，切分参数设置直接决定了检索结果的质量。很多人习惯用默认参数，这往往是准确率低下的根源：

手把手构建高精度问答链路

先做环境准备，然后做文档切分，接着做混合向量化，最后组装问答链路。按照这个顺序，能帮你最快搭出一套可用的系统。

第一步：精准加载与结构化切分

技术文档不同于小说，它包含代码块、列表和标题层级。如果直接当成纯文本切分，文档原有的层级关系就会丢失。

建议使用带语言感知的切分器。如果是 Markdown 文档，先按标题层级分割，再按字符数切分；如果是纯代码文件，直接使用针对特定编程语言的切分器。

from langchain_community.document_loaders import DirectoryLoader, TextLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter, Language

# 1. 加载本地知识库目录下的 markdown 与 python 文件
loader = DirectoryLoader(
    "./my_code_docs", 
    glob="**/*.md", 
    loader_cls=TextLoader, 
    loader_kwargs={"encoding": "utf-8"}
)
raw_docs = loader.load()

# 2. 针对代码文档设置切分规则，优先在函数和类边界切分
code_splitter = RecursiveCharacterTextSplitter.from_language(
    language=Language.PYTHON,
    chunk_size=500,
    chunk_overlap=100
)
split_docs = code_splitter.split_documents(raw_docs)

核心提示：`chunk_overlap` 一定不能设为 0。保持 15% 到 20% 的重叠率，可以保证处于切分边界的代码行不会丢失上下文关联。

第二步：向量化与本地存储

在 Embedding 模型的选择上，本地运行建议选择中文与英文代码表现均稳定的开源模型，例如 `BAAI/bge-small-zh-v1.5`，也可以直接使用云端 API。本地向量库首选 Chroma，无需配置复杂的后台进程。

from langchain_community.embeddings import HuggingFaceBgeEmbeddings
from langchain_community.vectorstores import Chroma

embedding_model = HuggingFaceBgeEmbeddings(
    model_name="BAAI/bge-small-zh-v1.5",
    model_kwargs={"device": "cpu"},
    encode_kwargs={"normalize_embeddings": True}
)

vectorstore = Chroma.from_documents(
    documents=split_docs,
    embedding=embedding_model,
    persist_directory="./chroma_db"
)

第三步：用混合检索替代单一向量检索

纯向量检索经常在搜代码时掉链子。比如你搜 `VectorStoreRetriever`，向量模型可能根据“存储”语义召回一大堆关于数据落盘的文档，却漏掉了真正包含该类定义的页面。

高精度的关键在于“关键词检索 + 向量检索”。在 LangChain 中，把 BM25 检索器与向量检索器结合，构建集成检索器（EnsembleRetriever）：

from langchain.retrievers import EnsembleRetriever
from langchain_community.retrievers import BM25Retriever

# 1. 建立 BM25 关键词检索器
bm25_retriever = BM25Retriever.from_documents(split_docs)
bm25_retriever.k = 5

# 2. 建立向量检索器
vector_retriever = vectorstore.as_retriever(search_kwargs={"k": 5})

# 3. 组合两者，平分权重
hybrid_retriever = EnsembleRetriever(
    retrievers=[bm25_retriever, vector_retriever],
    weights=[0.5, 0.5]
)

这样做的好处很明显：BM25 负责锁定精密的报错类名和参数变量，向量检索负责抓取自然语言描述的语义，两者互补。

第四步：引入重排过滤噪音

召回 10 个候选块之后，不要一股脑丢给大模型。大模型的长文本理解能力虽然在变强，但“迷失在中间”（Lost in the Middle）的问题依然存在。

先做一次重排（Rerank），把真正能解答问题的 2 到 3 个片段挑出来放在最前排：

from langchain.retrievers.document_compressors import CrossEncoderReranker
from langchain_community.cross_encoders import HuggingFaceCrossEncoder
from langchain.retrievers import ContextualCompressionRetriever

# 初始化本地轻量级重排模型
rerank_model = HuggingFaceCrossEncoder(model_name="BAAI/bge-reranker-base")
compressor = CrossEncoderReranker(model=rerank_model, top_n=3)

# 包装成带压缩重排的最终检索器
final_retriever = ContextualCompressionRetriever(
    base_compressor=compressor,
    base_retriever=hybrid_retriever
)

测试数据显示，加入重排后，相关上下文在首位的命中率通常能从 60% 增加到 88% 以上。这意味着大模型看到的参考材料更加精准。

第五步：严格限制 Prompt，杜绝幻觉

最后一步是组装生成链。想要代码不报错，Prompt 必须写得极其明确，禁止模型自己脑补旧版本的写法。

from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_core.runnables import RunnablePassthrough
from langchain_openai import ChatOpenAI

prompt_template = """你是一个严谨的代码审查与答疑助手。
请完全基于以下提供的参考文档回答用户的代码问题或解决报错。
如果参考文档中没有明确写出的方法或类名，请直接说明“现有本地文档中未提及该用法”，绝不要自行捏造或使用过期的第三方库代码。

【参考文档】:
{context}

【用户问题】:
{question}

请给出正确的代码示例并解释报错原因："""

prompt = ChatPromptTemplate.from_template(prompt_template)
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)

def format_docs(docs):
    return "nn".join(doc.page_content for doc in docs)

# 用 LCEL 语法组装流水线
rag_chain = (
    {"context": final_retriever | format_docs, "question": RunnablePassthrough()}
    | prompt
    | llm
    | StrOutputParser()
)

必须把 `temperature` 设为 0。写业务代码需要的是确定性和合规性，不需要大模型的发散思维。

三个极易踩坑的细节

按照上面的步骤搭完后，如果你测试时依然遇到回答不准或者代码报错，重点检查以下三个地方：

1.绝对不要用已废弃的旧链语法：网上很多教程还在教你用 `from langchain.chains import RetrievalQA`。这种老写法在最新的 LangChain 中早已被标记废弃，代码不易维护且难以在中间插入重排逻辑。统一使用 LangChain 表达语言（LCEL）组装管道，不仅结构清晰，单步调试也更简单。

2.文档清洗必须剔除无关格式：很多官方文档导出的 HTML 或者 Markdown 里有大量的导航栏、页脚、点赞按钮文字。这些垃圾文字一旦被切块并向量化，就会经常误触发检索。把文档喂给切分器前，先写个简单的脚本去掉页面导航与版权声明。

3.针对报错排查保留文件名元数据：当你的代码库有多个版本时，必须在文档的 `metadata` 里注明版本号或模块名。在检索时加入元数据过滤（Metadata Filtering），避免模型把 v1 版本的解决方案拿去修 v2 版本的 Bug。

构建本地知识库不是一劳永逸的事情。只要把文档预处理做好，把混合检索和重排步骤落到实处，本地模型就能真正变成一个熟悉你私有项目规范、查错精准的得力搭档。