庫(kù)問答系統(tǒng)實(shí)戰(zhàn)：從零搭建并用Deepseek驅(qū)動(dòng))
在業(yè)務(wù)中接入大模型時(shí)很多同學(xué)都會(huì)走到同一步希望大模型能回答自己企業(yè)內(nèi)部文檔里的問題。但直接提問會(huì)發(fā)現(xiàn)模型既不了解你的業(yè)務(wù)也容易一本正經(jīng)地編造答案。要解決這個(gè)問題RAG 是目前最實(shí)用、成本最低的方案。本文將基于一套完整可運(yùn)行的代碼帶你從零搭建一個(gè)RAG知識(shí)庫(kù)問答系統(tǒng)并把 Deepseek 作為最終生成模型接入其中從原理到落地一次性講透。先說一下本文適合誰對(duì)大模型感興趣但還沒系統(tǒng)接觸過 RAG 的開發(fā)者、正在做企業(yè)知識(shí)庫(kù)需求的后端工程師、想在自己電腦上跑通一套完整問答系統(tǒng)的學(xué)習(xí)者。讀完本文你會(huì)理解 RAG 的完整處理鏈路掌握文檔加載、文本切分、向量化、向量檢索、Prompt 組裝、大模型生成這幾個(gè)關(guān)鍵環(huán)節(jié)并拿到一套可以擴(kuò)展成真實(shí)項(xiàng)目的基礎(chǔ)源碼。1. RAG 到底是什么為什么大模型需要它1.1 從大模型的“知識(shí)缺陷”說起大模型雖然能寫文章、寫代碼、做翻譯但有一個(gè)天然缺陷它的知識(shí)來自訓(xùn)練數(shù)據(jù)存在明顯的“知識(shí)截止時(shí)間”。如果你的問題涉及企業(yè)最新制度、某個(gè)產(chǎn)品的使用手冊(cè)、某個(gè)系統(tǒng)的內(nèi)部操作說明大模型很可能會(huì)回答一個(gè)看似合理、實(shí)則錯(cuò)誤的內(nèi)容這就是常說的“幻覺”問題。舉個(gè)例子你問“公司請(qǐng)休假制度是什么”模型可能會(huì)編造一套看似標(biāo)準(zhǔn)的制度而它根本沒有見過你公司的文檔。此時(shí)你不可能為了這個(gè)問題重新訓(xùn)練一個(gè)大模型成本太高也不現(xiàn)實(shí)。RAG 的解決思路很直接與其讓模型“背”下所有知識(shí)不如在它回答問題之前先幫它找到相關(guān)資料。這就好比考試時(shí)允許翻書模型不用死記硬背只需要根據(jù)“查到的那幾頁”來組織答案。1.2 RAG 的完整定義與核心流程RAG全稱 Retrieval-Augmented Generation檢索增強(qiáng)生成。它是一種將信息檢索與文本生成相結(jié)合的架構(gòu)先從外部知識(shí)庫(kù)中檢索出與用戶問題相關(guān)的文檔片段再將片段與問題一起交給大模型讓模型基于這些片段生成回答。標(biāo)準(zhǔn) RAG 的處理流程可以拆成八個(gè)環(huán)節(jié)文檔加載讀取內(nèi)部文檔支持 txt、PDF、Word、Markdown 等格式。文本切分長(zhǎng)文檔不能整體向量化需要按一定策略切分成 chunk文本塊。向量化使用 embedding 模型將每個(gè) chunk 轉(zhuǎn)換為向量向量可以理解為一段文本的語義坐標(biāo)。向量存儲(chǔ)將向量和原文一起存入向量數(shù)據(jù)庫(kù)例如 Chroma、FAISS、Milvus。問題向量化用戶提問時(shí)將問題也轉(zhuǎn)換為向量。相似度檢索計(jì)算問題向量與知識(shí)庫(kù)向量的相似度返回最相關(guān)的 Top K 個(gè)片段。Prompt 組裝將系統(tǒng)提示詞、檢索到的片段、用戶問題拼接成一個(gè)完整的 Prompt。生成回答將 Prompt 發(fā)送給大模型模型基于片段內(nèi)容生成最終答案。1.3 RAG 與模型微調(diào)的區(qū)別很多初學(xué)者會(huì)把 RAG 和微調(diào)搞混。簡(jiǎn)單來說微調(diào)是修改模型的“記憶”RAG 是給模型“查資料”。兩者各有適用場(chǎng)景對(duì)比維度RAG微調(diào)成本較低無需訓(xùn)練顯卡較高需要訓(xùn)練資源和數(shù)據(jù)準(zhǔn)備知識(shí)更新替換文檔即可實(shí)時(shí)生效需要重新訓(xùn)練周期長(zhǎng)可解釋性回答可溯源到具體文檔片段相對(duì)難以解釋模型參考了什么幻覺控制通過限定參考片段效果明顯降低有限模型仍可能生成非訓(xùn)練知識(shí)適用場(chǎng)景企業(yè)知識(shí)庫(kù)、文檔問答、實(shí)時(shí)信息改變模型語氣風(fēng)格、專業(yè)術(shù)語理解、特定格式輸出真實(shí)項(xiàng)目中RAG 和微調(diào)也經(jīng)常配合使用。如果模型本身對(duì)你所在行業(yè)的術(shù)語理解較弱可以先用部分?jǐn)?shù)據(jù)微調(diào)模型再疊加 RAG 讓模型獲取最新知識(shí)。但對(duì)大多數(shù)知識(shí)庫(kù)問答需求來說RAG 是首選中低成本方案。2. 系統(tǒng)方案設(shè)計(jì)與技術(shù)選型2.1 方案目標(biāo)我們要搭建的這套系統(tǒng)需要滿足以下需求支持把本地文檔導(dǎo)入知識(shí)庫(kù)。文檔必須支持持續(xù)追加和更新不需要重訓(xùn)練模型。用戶提問后系統(tǒng)能檢索到相關(guān)文檔片段并在回答中給出依據(jù)。最終生成模型使用 Deepseek API保證中文效果且調(diào)用簡(jiǎn)單。整個(gè)系統(tǒng)可以本地運(yùn)行不依賴大型 GPU 環(huán)境。2.2 總體架構(gòu)根據(jù)需求系統(tǒng)的整體架構(gòu)可以這樣設(shè)計(jì)用戶提問Web界面 / 命令行 ↓ 中文問題向量化本地Embedding模型 ↓ Chroma向量庫(kù)相似度檢索 ↓ 返回 Top-K 相關(guān)文檔片段 ↓ 組裝 Prompt系統(tǒng)提示詞 參考片段 用戶問題 ↓ 調(diào)用 Deepseek Chat API ↓ 生成最終回答并返回給用戶在這個(gè)架構(gòu)中文檔離線處理鏈路把原始知識(shí)庫(kù)轉(zhuǎn)換為向量索引在線問答鏈路負(fù)責(zé)檢索與生成。兩條鏈路合起來就是一套完整的 RAG 系統(tǒng)。2.3 技術(shù)棧說明本方案涉及的主要技術(shù)組件如下模塊技術(shù)選型選擇原因文檔加載Python 內(nèi)置文件讀取輕量零依賴適合 txt 文檔入門文本切分LangChain Text Splitters成熟的切分策略支持重疊窗口向量化模型sentence-transformers bge-small-zh-v1.5中文效果好本地運(yùn)行免費(fèi)向量數(shù)據(jù)庫(kù)Chroma輕量級(jí)無需獨(dú)立服務(wù)適合快速開發(fā)生成模型Deepseek Chat API中文能力強(qiáng)兼容 OpenAI 協(xié)議接入成本低Web 展示層Streamlit用 Python 快速搭建交互界面為什么使用 Deepseek 作為生成模型這是很多讀者關(guān)心的問題。Deepseek 的 API 調(diào)用方式與 OpenAI 協(xié)議兼容只需要安裝 openai SDK 并修改 base_url 和 api_key 就能完成接入非常省事。同時(shí)Deepseek 在中文理解與生成上的表現(xiàn)足夠優(yōu)秀適合中文知識(shí)庫(kù)問答場(chǎng)景。相比本地部署一個(gè)十幾B或幾十B的大模型API 方式對(duì)電腦性能要求極低個(gè)人開發(fā)者和中小規(guī)模應(yīng)用都能低成本使用。為什么 embedding 模型選用本地部署原因也很實(shí)際。如果每次寫文檔和提問都調(diào)用外部 embedding 接口會(huì)產(chǎn)生持續(xù)費(fèi)用同時(shí)還會(huì)把文檔內(nèi)容送到第三方服務(wù)。使用本地 bge-small-zh-v1.5 模型只需要首次運(yùn)行下載模型文件之后便可以在完全離線的狀態(tài)下完成向量化成本低、隱私性也更好。3. 環(huán)境準(zhǔn)備與項(xiàng)目結(jié)構(gòu)3.1 安裝 Python 與依賴本文示例以 Python 3.9 及以上版本為例。老規(guī)矩先創(chuàng)建一個(gè)獨(dú)立的虛擬環(huán)境避免依賴污染系統(tǒng)環(huán)境python -m venv rag-demo-env source rag-demo-env/bin/activate # Windows 下為 rag-demo-env\Scripts\activate然后安裝依賴包pip install openai sentence-transformers chromadb langchain-text-splitters streamlit python-dotenv如果你的環(huán)境安裝速度較慢可以更換為國(guó)內(nèi) pip 鏡像源pip install -i https://pypi.tuna.tsinghua.edu.cn/simple openai sentence-transformers chromadb langchain-text-splitters streamlit python-dotenv這里不鎖定具體版本號(hào)因?yàn)檫@些庫(kù)的迭代速度較快建議使用當(dāng)前最新穩(wěn)定版即可。如果后續(xù)遇到某個(gè)庫(kù)升級(jí)導(dǎo)致接口變動(dòng)可以回到對(duì)應(yīng)官方文檔確認(rèn)最新用法。3.2 項(xiàng)目目錄結(jié)構(gòu)完整源碼建議按照下面的目錄結(jié)構(gòu)保存rag-demo/ ├── .env # API Key 等敏感配置不提交到倉(cāng)庫(kù) ├── requirements.txt # 依賴清單 ├── config.py # 全局配置 ├── ingest.py # 文檔加載與向量庫(kù)構(gòu)建 ├── retriever.py # 檢索模塊 ├── rag.py # RAG 問答主流程 ├── app.py # Streamlit Web 界面 └── data/ # 存放私有文檔 ├── 公司介紹.txt └── product_faq.txtrequirements.txt 文件內(nèi)容如下openai1.0.0 sentence-transformers2.2.0 chromadb0.4.0 langchain-text-splitters0.0.1 streamlit1.30.0 python-dotenv1.0.04. 核心代碼實(shí)現(xiàn)從文檔到知識(shí)庫(kù)4.1 全局配置 config.py代碼的第一步是寫一個(gè)配置模塊把路徑、模型名稱、檢索參數(shù)等集中管理起來。這樣后續(xù)修改參數(shù)時(shí)不需要翻遍每個(gè)文件。# 文件路徑rag-demo/config.py import os from dotenv import load_dotenv # 加載 .env 文件中的環(huán)境變量 load_dotenv() # 知識(shí)庫(kù)文檔目錄 KNOWLEDGE_BASE_DIR data # Chroma 向量庫(kù)持久化目錄 CHROMA_DIR ./chroma_db # 向量庫(kù)集合名稱 COLLECTION_NAME rag_demo # 本地 Embedding 模型名稱 EMBEDDING_MODEL_NAME BAAI/bge-small-zh-v1.5 # 檢索返回的片段數(shù)量 TOP_K 3 # 文檔切分參數(shù) CHUNK_SIZE 500 CHUNK_OVERLAP 50 # Deepseek API 配置 DEEPSEEK_API_KEY os.getenv(DEEPSEEK_API_KEY, ) DEEPSEEK_BASE_URL os.getenv(DEEPSEEK_BASE_URL, https://api.deepseek.com) DEEPSEEK_MODEL os.getenv(DEEPSEEK_MODEL, deepseek-chat)有一處要重點(diǎn)說明DEEPSEEK_API_KEY 不建議硬編碼在代碼文件中應(yīng)該寫在項(xiàng)目根目錄的 .env 文件里并確保 .env 被加入 .gitignore。這樣可以避免 API Key 意外提交到公開倉(cāng)庫(kù)造成安全風(fēng)險(xiǎn)。.env 文件的格式如下DEEPSEEK_API_KEY你的Deepseek_API_Key關(guān)于 Deepseek API 的使用請(qǐng)前往 Deepseek 官方開放平臺(tái)注冊(cè)并創(chuàng)建 API Key。使用 API 會(huì)產(chǎn)生少量費(fèi)用具體計(jì)費(fèi)標(biāo)準(zhǔn)以官方頁面為準(zhǔn)建議先小額充值并查看接口文檔中的價(jià)格說明。4.2 文檔加載與向量化入庫(kù) ingest.pyingest.py 的作用是讀取 data 目錄下的文檔進(jìn)行切分、向量化然后寫入向量數(shù)據(jù)庫(kù)。這是整個(gè) RAG 系統(tǒng)的離線構(gòu)建階段。# 文件路徑rag-demo/ingest.py import os from typing import List from langchain_text_splitters import CharacterTextSplitter from sentence_transformers import SentenceTransformer import chromadb import config def load_documents(data_dir: str) - List[str]: 讀取 data 目錄下的所有 txt 文件返回文檔內(nèi)容列表。 docs [] for filename in os.listdir(data_dir): if filename.endswith(.txt): filepath os.path.join(data_dir, filename) with open(filepath, r, encodingutf-8) as f: content f.read() if content.strip(): docs.append(content) print(f已加載文檔: {filename}) return docs def split_text(documents: List[str]) - List[str]: 將長(zhǎng)文檔切分成指定大小的文本塊 chunk。 splitter CharacterTextSplitter( separator\n, chunk_sizeconfig.CHUNK_SIZE, chunk_overlapconfig.CHUNK_OVERLAP, length_functionlen, ) chunks [] for doc in documents: chunks.extend(splitter.split_text(doc)) return chunks def build_vector_store(chunks: List[str]): 將文本塊向量化并寫入 Chroma 向量庫(kù)。 # 加載本地 embedding 模型首次運(yùn)行會(huì)自動(dòng)下載 print(正在加載 embedding 模型...) embedder SentenceTransformer(config.EMBEDDING_MODEL_NAME) # 生成向量 print(正在生成向量...) embeddings embedder.encode(chunks, show_progress_barTrue).tolist() # 創(chuàng)建 Chroma 客戶端持久化到本地目錄 client chromadb.PersistentClient(pathconfig.CHROMA_DIR) # 如果集合已存在先刪除避免重復(fù)插入 existing_collections client.list_collections() for col in existing_collections: if col.name config.COLLECTION_NAME: client.delete_collection(config.COLLECTION_NAME) print(已刪除舊的向量庫(kù)集合) collection client.create_collection( nameconfig.COLLECTION_NAME, metadata{hnsw:space: cosine}, # 使用余弦相似度 ) # 寫入向量庫(kù)id 使用序號(hào)方便管理 ids [str(i) for i in range(len(chunks))] # 這里直接把原始文本和向量一起存入 collection.add( idsids, embeddingsembeddings, documentschunks, ) print(f向量庫(kù)構(gòu)建完成共寫入 {len(chunks)} 個(gè)文本塊) if __name__ __main__: all_docs load_documents(config.KNOWLEDGE_BASE_DIR) if not all_docs: raise ValueError(fdata 目錄下沒有找到可用文檔請(qǐng)檢查目錄: {config.KNOWLEDGE_BASE_DIR}) all_chunks split_text(all_docs) print(f文檔切分完成共得到 {len(all_chunks)} 個(gè)文本塊) build_vector_store(all_chunks)這段代碼的重點(diǎn)有幾個(gè)。文本切分參數(shù)值得專門調(diào)試。CHUNK_SIZE 表示每個(gè)文本塊的最大字符數(shù)CHUNK_OVERLAP 表示相鄰塊之間重疊的字符數(shù)。重疊的部分可以讓切塊邊界處的語義不丟失尤其是當(dāng)問題和答案分別跨越兩個(gè)塊邊界時(shí)重疊能明顯提升召回效果。實(shí)際項(xiàng)目中500 到 800 字是比較常見的塊大小過小會(huì)導(dǎo)致檢索上下文不足過大則會(huì)讓單塊包含太多無關(guān)信息降低檢索精度。Chroma 的持久化方式在代碼中使用了 PersistentClient向量庫(kù)數(shù)據(jù)會(huì)保存到 ./chroma_db 目錄。這樣下次啟動(dòng)系統(tǒng)時(shí)不需要重新構(gòu)建向量庫(kù)直接讀取即可。如果知識(shí)庫(kù)文檔發(fā)生了更新重新運(yùn)行一次 ingest.py 即可不必重啟任何服務(wù)。4.3 檢索模塊 retriever.pyretriever.py 負(fù)責(zé)接收用戶問題將其向量化后在 Chroma 中檢索最相關(guān)的 Top K 個(gè)片段。# 文件路徑rag-demo/retriever.py import chromadb from sentence_transformers import SentenceTransformer import config def get_embedder(): 獲取共享的 embedding 模型實(shí)例避免多次重復(fù)加載。 return SentenceTransformer(config.EMBEDDING_MODEL_NAME) def search(query: str, top_k: int None): 根據(jù)用戶問題檢索知識(shí)庫(kù)返回相關(guān)片段列表。 if top_k is None: top_k config.TOP_K # 加載向量庫(kù) client chromadb.PersistentClient(pathconfig.CHROMA_DIR) collection client.get_collection(config.COLLECTION_NAME) # 對(duì)用戶問題進(jìn)行向量化 embedder get_embedder() query_embedding embedder.encode([query]).tolist() # 執(zhí)行相似度檢索 results collection.query( query_embeddingsquery_embedding, n_resultstop_k, ) documents results.get(documents, [[]])[0] distances results.get(distances, [[]])[0] return documents, distances這里需要留意一個(gè)問題每次調(diào)用 get_embedder 都會(huì)重新加載一次模型。在 Streamlit 這種 Web 服務(wù)中頻繁加載模型會(huì)拖慢速度。實(shí)際開發(fā)時(shí)可以把 embedder 設(shè)計(jì)成全局單例或者放到內(nèi)存緩存中。我在這里保留簡(jiǎn)單寫法是為了讓流程更清晰后面工程優(yōu)化部分再討論如何改進(jìn)。Chroma 的 query 接口返回結(jié)果中documents 是對(duì)應(yīng)的原始文本內(nèi)容distances 是余弦距離。距離越小表示相似度越高后續(xù)可以把距離信息一并展示幫助用戶判斷答案的可信度。4.4 RAG 問答主流程 rag.pyrag.py 是系統(tǒng)的核心負(fù)責(zé)把檢索結(jié)果和用戶問題組裝成 Prompt然后調(diào)用 Deepseek 生成回答。# 文件路徑rag-demo/rag.py from openai import OpenAI import config from retriever import search # 初始化 Deepseek 客戶端兼容 OpenAI SDK client OpenAI( api_keyconfig.DEEPSEEK_API_KEY, base_urlconfig.DEEPSEEK_BASE_URL, ) def build_prompt(query: str, context_docs: list) - str: 組裝發(fā)送給大模型的 Prompt。 system_prompt ( 你是一個(gè)專業(yè)的知識(shí)庫(kù)問答助手。 請(qǐng)根據(jù)提供的參考資料回答用戶問題。 必須優(yōu)先參考參考資料中的內(nèi)容不要臆造答案。 如果參考資料無法回答該問題請(qǐng)直接說明知識(shí)庫(kù)中暫未找到相關(guān)信息。 ) context \n\n.join(context_docs) user_prompt f請(qǐng)根據(jù)以下參考資料回答用戶問題。 【參考資料】 {context} 【用戶問題】 {query} 請(qǐng)用中文回答如果引用了參考資料可以說明信息來源于哪個(gè)部分。 return system_prompt, user_prompt def ask(query: str) - dict: Retrieve Generate 完整流程。 # 檢索相關(guān)片段 docs, distances search(query) # 組裝 Prompt system_prompt, user_prompt build_prompt(query, docs) # 調(diào)用 Deepseek 生成回答 response client.chat.completions.create( modelconfig.DEEPSEEK_MODEL, temperature0.3, messages[ {role: system, content: system_prompt}, {role: user, content: user_prompt}, ], ) answer response.choices[0].message.content return { answer: answer, source_documents: docs, distances: distances, } if __name__ __main__: question input(請(qǐng)輸入你的問題) result ask(question) print(\n 回答 ) print(result[answer]) print(\n 引用片段 ) for i, doc in enumerate(result[source_documents]): print(f\n[{i 1}] {doc[:200]})Deepseek 的接入方式與 OpenAI 幾乎一致核心代碼只有這么幾行。這里給出的 model 名稱是 deepseek-chat對(duì)應(yīng) Deepseek 的對(duì)話模型。temperature 設(shè)置為 0.3會(huì)讓回答更加穩(wěn)定、更貼近參考資料內(nèi)容。如果你想獲得更有創(chuàng)造性的回答可以調(diào)高到 0.7 左右但在知識(shí)庫(kù)問答場(chǎng)景下推薦保持低 temperature以減少胡說八道的概率。Prompt 的設(shè)計(jì)值得仔細(xì)思考。系統(tǒng)提示詞明確要求“必須優(yōu)先參考參考資料中的內(nèi)容不要臆造答案”這一步是抑制幻覺的關(guān)鍵。如果直接把問題和檢索片段丟給模型而不加任何約束模型仍然可能傾向使用自己的知識(shí)回答。所以在 RAG 系統(tǒng)中Prompt 不是隨便拼一段文字而是需要反復(fù)打磨的工程質(zhì)量項(xiàng)。4.5 Streamlit Web 界面 app.py最后寫一個(gè)簡(jiǎn)單的 Web 界面讓系統(tǒng)可以被同事或用戶直接使用。# 文件路徑rag-demo/app.py import streamlit as st import config from rag import ask st.set_page_config(page_titleRAG 知識(shí)庫(kù)問答系統(tǒng), page_icon, layoutwide) st.title( RAG 知識(shí)庫(kù)問答系統(tǒng)) st.caption(基于 Deepseek Chroma 構(gòu)建的私有知識(shí)庫(kù)問答系統(tǒng)) query st.text_area(請(qǐng)輸入你的問題, height100) if st.button(獲取答案, typeprimary): if not query.strip(): st.warning(請(qǐng)輸入問題內(nèi)容) elif not config.DEEPSEEK_API_KEY: st.error(未檢測(cè)到 DEEPSEEK_API_KEY請(qǐng)檢查 .env 文件配置) else: with st.spinner(正在檢索并生成回答...): result ask(query.strip()) st.subheader(回答) st.write(result[answer]) with st.expander(查看參考文檔片段): for i, (doc, dist) in enumerate(zip(result[source_documents], result[distances])): st.markdown(f**片段 {i 1}**距離{dist:.4f}) st.text(doc[:500])這個(gè)界面就是典型的“輸入框 按鈕 結(jié)果展示”結(jié)構(gòu)沒有復(fù)雜的前端依賴。st.expander 折疊展示參考片段讓用戶既能看答案也能核對(duì)答案的出處符合 RAG 可溯源的優(yōu)勢(shì)。5. 運(yùn)行系統(tǒng)與效果驗(yàn)證5.1 準(zhǔn)備示例文檔在 data 目錄下創(chuàng)建兩個(gè)測(cè)試文檔這里以一個(gè)虛構(gòu)的公司場(chǎng)景為例# 文件路徑rag-demo/data/公司介紹.txt 某某科技有限公司成立于2018年總部位于上海主營(yíng)業(yè)務(wù)是企業(yè)級(jí)人工智能解決方案定制服務(wù)。 公司核心技術(shù)團(tuán)隊(duì)來自國(guó)內(nèi)一線互聯(lián)網(wǎng)公司與高校實(shí)驗(yàn)室在自然語言處理、知識(shí)圖譜、大模型應(yīng)用方向有豐富經(jīng)驗(yàn)。 公司的主要產(chǎn)品包括智能客服系統(tǒng)、知識(shí)庫(kù)問答平臺(tái)、數(shù)據(jù)中臺(tái)建設(shè)服務(wù)。 截至2025年公司已服務(wù)超過200家中小企業(yè)客戶覆蓋零售、金融、教育等行業(yè)。# 文件路徑rag-demo/data/product_faq.txt 問知識(shí)庫(kù)問答平臺(tái)支持哪些文檔格式 答平臺(tái)支持 txt、PDF、Word、Markdown 等常見格式推薦使用 Markdown 或 txt 以獲得最佳解析效果。 問平臺(tái)的數(shù)據(jù)是否安全 答平臺(tái)支持私有化部署文檔向量化和檢索過程可以在企業(yè)內(nèi)部網(wǎng)絡(luò)獨(dú)立完成只有最終生成回答時(shí)會(huì)調(diào)用大模型 API。 問知識(shí)庫(kù)更新需要重新訓(xùn)練模型嗎 答不需要。知識(shí)庫(kù)問答系統(tǒng)采用 RAG 架構(gòu)只需要更新向量庫(kù)即可讓模型基于最新文檔回答問題。5.2 初始化知識(shí)庫(kù)在項(xiàng)目根目錄執(zhí)行python ingest.py正常情況下會(huì)看到類似輸出已加載文檔: 公司介紹.txt 已加載文檔: product_faq.txt 文檔切分完成共得到 6 個(gè)文本塊 正在加載 embedding 模型... 正在生成向量... 向量庫(kù)構(gòu)建完成共寫入 6 個(gè)文本塊首次運(yùn)行會(huì)下載 bge-small-zh-v1.5 模型文件大小在 100MB 左右需要保持網(wǎng)絡(luò)暢通。下載完成后模型會(huì)緩存在本地之后運(yùn)行不會(huì)再重復(fù)下載。5.3 啟動(dòng) Web 界面streamlit run app.py瀏覽器會(huì)自動(dòng)打開 Streamlit 提供的本地地址默認(rèn)是 http://localhost:8501。可以看到一個(gè)簡(jiǎn)潔的問答界面輸入問題后點(diǎn)擊“獲取答案”。嘗試提問“公司知識(shí)庫(kù)平臺(tái)支持哪些文檔格式”預(yù)期回答會(huì)參考 product_faq.txt 中的內(nèi)容并明確指出支持 txt、PDF、Word、Markdown 等格式。如果提問“公司成立于哪一年”系統(tǒng)應(yīng)該從公司介紹文檔中檢索到對(duì)應(yīng)信息并給出答案。在“查看參考文檔片段”區(qū)域你會(huì)看到檢索到的原始片段和對(duì)應(yīng)的相似度距離這能幫助你判斷系統(tǒng)是否真正用上了知識(shí)庫(kù)內(nèi)容。6. 常見問題與排查思路在實(shí)際運(yùn)行中很多問題其實(shí)是共通的。下面把高頻問題整理成表格再逐個(gè)展開。問題現(xiàn)象常見原因解決思路首次運(yùn)行下載模型失敗網(wǎng)絡(luò)不穩(wěn)定或 HuggingFace 地址無法訪問使用鏡像地址或手動(dòng)下載模型到本地向量庫(kù)查詢報(bào)錯(cuò) Collection not found未執(zhí)行 ingest.py 或目錄不一致執(zhí)行 ingest.py 構(gòu)建向量庫(kù)檢查 CHROMA_DIR檢索結(jié)果與問題無關(guān)chunk 過大、top_k 過小、文檔格式混亂調(diào)整 CHUNK_SIZE、增大 TOP_K清洗文檔Deepseek API 返回 401 錯(cuò)誤API Key 不正確或未加載成功檢查 .env 文件確認(rèn) load_dotenv 生效回答沒有引用知識(shí)庫(kù)內(nèi)容Prompt 約束不夠或檢索片段為空加強(qiáng) system prompt檢查檢索結(jié)果Chroma old database version 報(bào)錯(cuò)向量庫(kù)版本升級(jí)不兼容刪除 chroma_db 目錄后重新 ingest6.1 首次運(yùn)行模型下載失敗bge-small-zh-v1.5 模型默認(rèn)從 HuggingFace 下載。如果你的網(wǎng)絡(luò)環(huán)境無法穩(wěn)定訪問可以設(shè)置鏡像環(huán)境變量export HF_ENDPOINThttps://hf-mirror.com然后在終端重新運(yùn)行 ingest.py。設(shè)置鏡像環(huán)境變量的目的是解決下載通道問題屬于開發(fā)過程中的常規(guī)操作。模型下載完成后可以不再依賴外網(wǎng)。另一種方式是從其他方式下載模型文件后把模型目錄放到本地然后在 config.py 中將 EMBEDDING_MODEL_NAME 改為模型所在的本地路徑。例如EMBEDDING_MODEL_NAME ./models/bge-small-zh-v1.56.2 檢索結(jié)果不理想檢索結(jié)果差通常不是單一原因造成的需要按照順序排查幾個(gè)關(guān)鍵參數(shù)。先檢查 TOP_K。如果設(shè)置為 1結(jié)果可能只覆蓋一個(gè)片段信息量不足如果設(shè)置為 5又可能混入大量不相關(guān)內(nèi)容。對(duì)于短文檔3 是合理的起點(diǎn)。再檢查 CHUNK_SIZE。如果文檔本身是 FAQ 格式每條問答很短那么把 CHUNK_SIZE 設(shè)置成 500會(huì)把多個(gè)問答切進(jìn)同一個(gè)塊導(dǎo)致檢索時(shí)指向內(nèi)容不準(zhǔn)確。對(duì)這種結(jié)構(gòu)化文檔建議將 chunk_size 調(diào)小比如 200 到 300并去掉過大的 overlap。最重要的還是文檔清洗。如果原始文檔包含大量頁眉頁腳、特殊符號(hào)、亂碼向量化效果會(huì)明顯變差。在真實(shí)項(xiàng)目中文檔預(yù)處理往往占用整個(gè) RAG 項(xiàng)目一半以上的工作量這是很正常的現(xiàn)象。6.3 Deepseek API 接入問題如果調(diào)用時(shí)報(bào) 401最直接的排查方式是打印 config.DEEPSEEK_API_KEY確認(rèn) .env 是否被正確加載。.env 文件必須和運(yùn)行命令所在目錄一致也就是項(xiàng)目根目錄。如果報(bào)連接超時(shí)先確認(rèn)網(wǎng)絡(luò)環(huán)境能夠訪問 Deepseek API。同時(shí)可以在代碼中打印 DEEPSEEK_BASE_URL確認(rèn)沒有因?yàn)橹暗捻?xiàng)目設(shè)置而覆蓋成了其他地址。6.4 向量庫(kù)版本兼容問題Chroma 版本迭代較快不同版本生成的數(shù)據(jù)庫(kù)文件可能不兼容出現(xiàn)類似“old database version”的報(bào)錯(cuò)時(shí)最簡(jiǎn)單的處理是備份并刪除 chroma_db 目錄然后重新運(yùn)行 ingest.py。這只是開發(fā)階段的做法生產(chǎn)環(huán)境中應(yīng)該提前規(guī)劃向量庫(kù)的升級(jí)策略例如使用獨(dú)立的向量數(shù)據(jù)庫(kù)服務(wù)。7. 最佳實(shí)踐與工程化建議文章到這里整套代碼已經(jīng)能跑通了。但如果你想把這個(gè) Demo 變成真正可用的系統(tǒng)還需要注意下面幾個(gè)工程問題。7.1 把 Prompt 單獨(dú)管理不要把 Prompt 字符串散落在業(yè)務(wù)代碼里。隨著項(xiàng)目迭代Prompt 的調(diào)整頻率很高應(yīng)該單獨(dú)提取為一個(gè)配置文件或 Prompt 管理模塊。某些團(tuán)隊(duì)還會(huì)為不同場(chǎng)景編寫多套 Prompt比如“摘要模式”“對(duì)比模式”“嚴(yán)格引用模式”然后用模版變量動(dòng)態(tài)切換。7.2 增加檢索結(jié)果的引用溯源RAG 的核心優(yōu)勢(shì)之一就是可解釋性。在 Web 界面和 API 返回中都應(yīng)該保留 source_documents 字段最好把文檔名、頁碼、片段位置一起返回。這樣用戶能夠點(diǎn)擊查看原文運(yùn)營(yíng)人員也能快速發(fā)現(xiàn)錯(cuò)誤片段并及時(shí)修正知識(shí)庫(kù)。7.3 完善文檔更新機(jī)制目前 ingest.py 每次都會(huì)刪除舊集合重新寫入。當(dāng)知識(shí)庫(kù)規(guī)模變大后應(yīng)該改成增量更新根據(jù)文檔的 hash 值或更新時(shí)間只處理變更部分。向量庫(kù)中也要增加元數(shù)據(jù)字段比如來源文件名、更新時(shí)間、部門標(biāo)簽方便按條件過濾。7.4 引入重排Rerank提升精度向量檢索拿到的 Top K 片段里可能順序并不完全符合語義相關(guān)度。更成熟的方案是在向量檢索之后增加一個(gè) rerank 模型對(duì)候選片段重新打分。比如本地部署 bge-reranker-base 模型先用向量召回 20 個(gè)候選再重排取前 3 個(gè)送給大模型。實(shí)踐表明加一層 rerank 后回答準(zhǔn)確率往往會(huì)有明顯提升。7.5 從 RAG 走向 Agentic RAG目前實(shí)現(xiàn)的是標(biāo)準(zhǔn) RAG每次提問只做一次檢索。當(dāng)問題復(fù)雜時(shí)例如“對(duì)比公司產(chǎn)品 A 和產(chǎn)品 B 的區(qū)別”或者“找出去年所有投訴工單中的高頻問題”單次檢索可能不夠。Agentic RAG 的核心思想是讓大模型具備“工具調(diào)用”能力它可以決定先搜索什么、搜索幾次、是否改寫問題、是否需要查看多個(gè)文檔后再綜合回答。這個(gè)方向可以作為下一步的進(jìn)階學(xué)習(xí)目標(biāo)。本質(zhì)上是把 RAG 的“搜索鏈路”從固定流程升級(jí)成由模型驅(qū)動(dòng)的動(dòng)態(tài)流程對(duì) Prompt 設(shè)計(jì)和工具調(diào)用的工程質(zhì)量要求更高。7.6 安全與合規(guī)注意事項(xiàng)涉及到 API 調(diào)用、內(nèi)部文檔時(shí)有幾個(gè)安全底線需要堅(jiān)持。第一API Key 絕不硬編碼在源碼中.env 文件必須加入 .gitignore第二生產(chǎn)環(huán)境建議通過獨(dú)立的密鑰管理服務(wù)接收 API Key由后端服務(wù)統(tǒng)一調(diào)用不要把密鑰直接暴露給前端第三企業(yè)內(nèi)部敏感文檔如果涉及數(shù)據(jù)保密要求需要確認(rèn)是否允許調(diào)用外部大模型 API。如果嚴(yán)格禁止外部傳輸則應(yīng)該采用本地部署的模型替換 Deepseek API把整個(gè)鏈路都收斂在內(nèi)網(wǎng)環(huán)境中完成。8. 從入門到落地下一步可以做什么至此你已經(jīng)親手搭完了一套完整的 RAG 知識(shí)庫(kù)問答系統(tǒng)從文檔加載、切分、向量化、檢索到 Prompt 組裝和 Deepseek 生成回答所有環(huán)節(jié)都是可運(yùn)行、可擴(kuò)展的。相比直接調(diào)用大模型接口“硬問”這套方案讓模型真正學(xué)會(huì)利用你的私有資料來回答問題。如果你打算繼續(xù)深入有兩條推薦路線。一條是優(yōu)化檢索質(zhì)量嘗試引入 rerank、多路召回、元數(shù)據(jù)過濾讓召回結(jié)果更精準(zhǔn)另一條是走向 Agentic RAG讓模型能自主規(guī)劃?rùn)z索步驟處理更復(fù)雜的多跳問答任務(wù)。兩條路線都不需要重新訓(xùn)練模型完全符合 RAG 低成本的核心理念。構(gòu)建知識(shí)庫(kù)本身也是一門細(xì)活。文檔清洗、文本切分、領(lǐng)域詞表、Prompt 調(diào)優(yōu)每一個(gè)環(huán)節(jié)都會(huì)影響最終回答質(zhì)量。不要指望運(yùn)行一遍代碼就得到完美效果真正的項(xiàng)目落地就是在這些細(xì)節(jié)里不斷打磨的過程。希望這份手把手教程能幫你邁出扎實(shí)的第一步也歡迎把你在搭建過程中遇到的問題留在評(píng)論區(qū)大家互相交流排錯(cuò)經(jīng)驗(yàn)。 RAG知識(shí)庫(kù)問答系統(tǒng)實(shí)戰(zhàn)：從零搭建并用Deepseek驅(qū)動(dòng)
在業(yè)務(wù)中接入大模型時(shí)很多同學(xué)都會(huì)走到同一步希望大模型能回答自己企業(yè)內(nèi)部文檔里的問題。但直接提問會(huì)發(fā)現(xiàn)模型既不了解你的業(yè)務(wù)也容易一本正經(jīng)地編造答案。要解決這個(gè)問題RAG 是目前最實(shí)用、成本最低的方案。本文將基于一套完整可運(yùn)行的代碼帶你從零搭建一個(gè)RAG知識(shí)庫(kù)問答系統(tǒng)并把 Deepseek 作為最終生成模型接入其中從原理到落地一次性講透。先說一下本文適合誰對(duì)大模型感興趣但還沒系統(tǒng)接觸過 RAG 的開發(fā)者、正在做企業(yè)知識(shí)庫(kù)需求的后端工程師、想在自己電腦上跑通一套完整問答系統(tǒng)的學(xué)習(xí)者。讀完本文你會(huì)理解 RAG 的完整處理鏈路掌握文檔加載、文本切分、向量化、向量檢索、Prompt 組裝、大模型生成這幾個(gè)關(guān)鍵環(huán)節(jié)并拿到一套可以擴(kuò)展成真實(shí)項(xiàng)目的基礎(chǔ)源碼。1. RAG 到底是什么為什么大模型需要它1.1 從大模型的“知識(shí)缺陷”說起大模型雖然能寫文章、寫代碼、做翻譯但有一個(gè)天然缺陷它的知識(shí)來自訓(xùn)練數(shù)據(jù)存在明顯的“知識(shí)截止時(shí)間”。如果你的問題涉及企業(yè)最新制度、某個(gè)產(chǎn)品的使用手冊(cè)、某個(gè)系統(tǒng)的內(nèi)部操作說明大模型很可能會(huì)回答一個(gè)看似合理、實(shí)則錯(cuò)誤的內(nèi)容這就是常說的“幻覺”問題。舉個(gè)例子你問“公司請(qǐng)休假制度是什么”模型可能會(huì)編造一套看似標(biāo)準(zhǔn)的制度而它根本沒有見過你公司的文檔。此時(shí)你不可能為了這個(gè)問題重新訓(xùn)練一個(gè)大模型成本太高也不現(xiàn)實(shí)。RAG 的解決思路很直接與其讓模型“背”下所有知識(shí)不如在它回答問題之前先幫它找到相關(guān)資料。這就好比考試時(shí)允許翻書模型不用死記硬背只需要根據(jù)“查到的那幾頁”來組織答案。1.2 RAG 的完整定義與核心流程RAG全稱 Retrieval-Augmented Generation檢索增強(qiáng)生成。它是一種將信息檢索與文本生成相結(jié)合的架構(gòu)先從外部知識(shí)庫(kù)中檢索出與用戶問題相關(guān)的文檔片段再將片段與問題一起交給大模型讓模型基于這些片段生成回答。標(biāo)準(zhǔn) RAG 的處理流程可以拆成八個(gè)環(huán)節(jié)文檔加載讀取內(nèi)部文檔支持 txt、PDF、Word、Markdown 等格式。文本切分長(zhǎng)文檔不能整體向量化需要按一定策略切分成 chunk文本塊。向量化使用 embedding 模型將每個(gè) chunk 轉(zhuǎn)換為向量向量可以理解為一段文本的語義坐標(biāo)。向量存儲(chǔ)將向量和原文一起存入向量數(shù)據(jù)庫(kù)例如 Chroma、FAISS、Milvus。問題向量化用戶提問時(shí)將問題也轉(zhuǎn)換為向量。相似度檢索計(jì)算問題向量與知識(shí)庫(kù)向量的相似度返回最相關(guān)的 Top K 個(gè)片段。Prompt 組裝將系統(tǒng)提示詞、檢索到的片段、用戶問題拼接成一個(gè)完整的 Prompt。生成回答將 Prompt 發(fā)送給大模型模型基于片段內(nèi)容生成最終答案。1.3 RAG 與模型微調(diào)的區(qū)別很多初學(xué)者會(huì)把 RAG 和微調(diào)搞混。簡(jiǎn)單來說微調(diào)是修改模型的“記憶”RAG 是給模型“查資料”。兩者各有適用場(chǎng)景對(duì)比維度RAG微調(diào)成本較低無需訓(xùn)練顯卡較高需要訓(xùn)練資源和數(shù)據(jù)準(zhǔn)備知識(shí)更新替換文檔即可實(shí)時(shí)生效需要重新訓(xùn)練周期長(zhǎng)可解釋性回答可溯源到具體文檔片段相對(duì)難以解釋模型參考了什么幻覺控制通過限定參考片段效果明顯降低有限模型仍可能生成非訓(xùn)練知識(shí)適用場(chǎng)景企業(yè)知識(shí)庫(kù)、文檔問答、實(shí)時(shí)信息改變模型語氣風(fēng)格、專業(yè)術(shù)語理解、特定格式輸出真實(shí)項(xiàng)目中RAG 和微調(diào)也經(jīng)常配合使用。如果模型本身對(duì)你所在行業(yè)的術(shù)語理解較弱可以先用部分?jǐn)?shù)據(jù)微調(diào)模型再疊加 RAG 讓模型獲取最新知識(shí)。但對(duì)大多數(shù)知識(shí)庫(kù)問答需求來說RAG 是首選中低成本方案。2. 系統(tǒng)方案設(shè)計(jì)與技術(shù)選型2.1 方案目標(biāo)我們要搭建的這套系統(tǒng)需要滿足以下需求支持把本地文檔導(dǎo)入知識(shí)庫(kù)。文檔必須支持持續(xù)追加和更新不需要重訓(xùn)練模型。用戶提問后系統(tǒng)能檢索到相關(guān)文檔片段并在回答中給出依據(jù)。最終生成模型使用 Deepseek API保證中文效果且調(diào)用簡(jiǎn)單。整個(gè)系統(tǒng)可以本地運(yùn)行不依賴大型 GPU 環(huán)境。2.2 總體架構(gòu)根據(jù)需求系統(tǒng)的整體架構(gòu)可以這樣設(shè)計(jì)用戶提問Web界面 / 命令行 ↓ 中文問題向量化本地Embedding模型 ↓ Chroma向量庫(kù)相似度檢索 ↓ 返回 Top-K 相關(guān)文檔片段 ↓ 組裝 Prompt系統(tǒng)提示詞 參考片段 用戶問題 ↓ 調(diào)用 Deepseek Chat API ↓ 生成最終回答并返回給用戶在這個(gè)架構(gòu)中文檔離線處理鏈路把原始知識(shí)庫(kù)轉(zhuǎn)換為向量索引在線問答鏈路負(fù)責(zé)檢索與生成。兩條鏈路合起來就是一套完整的 RAG 系統(tǒng)。2.3 技術(shù)棧說明本方案涉及的主要技術(shù)組件如下模塊技術(shù)選型選擇原因文檔加載Python 內(nèi)置文件讀取輕量零依賴適合 txt 文檔入門文本切分LangChain Text Splitters成熟的切分策略支持重疊窗口向量化模型sentence-transformers bge-small-zh-v1.5中文效果好本地運(yùn)行免費(fèi)向量數(shù)據(jù)庫(kù)Chroma輕量級(jí)無需獨(dú)立服務(wù)適合快速開發(fā)生成模型Deepseek Chat API中文能力強(qiáng)兼容 OpenAI 協(xié)議接入成本低Web 展示層Streamlit用 Python 快速搭建交互界面為什么使用 Deepseek 作為生成模型這是很多讀者關(guān)心的問題。Deepseek 的 API 調(diào)用方式與 OpenAI 協(xié)議兼容只需要安裝 openai SDK 并修改 base_url 和 api_key 就能完成接入非常省事。同時(shí)Deepseek 在中文理解與生成上的表現(xiàn)足夠優(yōu)秀適合中文知識(shí)庫(kù)問答場(chǎng)景。相比本地部署一個(gè)十幾B或幾十B的大模型API 方式對(duì)電腦性能要求極低個(gè)人開發(fā)者和中小規(guī)模應(yīng)用都能低成本使用。為什么 embedding 模型選用本地部署原因也很實(shí)際。如果每次寫文檔和提問都調(diào)用外部 embedding 接口會(huì)產(chǎn)生持續(xù)費(fèi)用同時(shí)還會(huì)把文檔內(nèi)容送到第三方服務(wù)。使用本地 bge-small-zh-v1.5 模型只需要首次運(yùn)行下載模型文件之后便可以在完全離線的狀態(tài)下完成向量化成本低、隱私性也更好。3. 環(huán)境準(zhǔn)備與項(xiàng)目結(jié)構(gòu)3.1 安裝 Python 與依賴本文示例以 Python 3.9 及以上版本為例。老規(guī)矩先創(chuàng)建一個(gè)獨(dú)立的虛擬環(huán)境避免依賴污染系統(tǒng)環(huán)境python -m venv rag-demo-env source rag-demo-env/bin/activate # Windows 下為 rag-demo-env\Scripts\activate然后安裝依賴包pip install openai sentence-transformers chromadb langchain-text-splitters streamlit python-dotenv如果你的環(huán)境安裝速度較慢可以更換為國(guó)內(nèi) pip 鏡像源pip install -i https://pypi.tuna.tsinghua.edu.cn/simple openai sentence-transformers chromadb langchain-text-splitters streamlit python-dotenv這里不鎖定具體版本號(hào)因?yàn)檫@些庫(kù)的迭代速度較快建議使用當(dāng)前最新穩(wěn)定版即可。如果后續(xù)遇到某個(gè)庫(kù)升級(jí)導(dǎo)致接口變動(dòng)可以回到對(duì)應(yīng)官方文檔確認(rèn)最新用法。3.2 項(xiàng)目目錄結(jié)構(gòu)完整源碼建議按照下面的目錄結(jié)構(gòu)保存rag-demo/ ├── .env # API Key 等敏感配置不提交到倉(cāng)庫(kù) ├── requirements.txt # 依賴清單 ├── config.py # 全局配置 ├── ingest.py # 文檔加載與向量庫(kù)構(gòu)建 ├── retriever.py # 檢索模塊 ├── rag.py # RAG 問答主流程 ├── app.py # Streamlit Web 界面 └── data/ # 存放私有文檔 ├── 公司介紹.txt └── product_faq.txtrequirements.txt 文件內(nèi)容如下openai1.0.0 sentence-transformers2.2.0 chromadb0.4.0 langchain-text-splitters0.0.1 streamlit1.30.0 python-dotenv1.0.04. 核心代碼實(shí)現(xiàn)從文檔到知識(shí)庫(kù)4.1 全局配置 config.py代碼的第一步是寫一個(gè)配置模塊把路徑、模型名稱、檢索參數(shù)等集中管理起來。這樣后續(xù)修改參數(shù)時(shí)不需要翻遍每個(gè)文件。# 文件路徑rag-demo/config.py import os from dotenv import load_dotenv # 加載 .env 文件中的環(huán)境變量 load_dotenv() # 知識(shí)庫(kù)文檔目錄 KNOWLEDGE_BASE_DIR data # Chroma 向量庫(kù)持久化目錄 CHROMA_DIR ./chroma_db # 向量庫(kù)集合名稱 COLLECTION_NAME rag_demo # 本地 Embedding 模型名稱 EMBEDDING_MODEL_NAME BAAI/bge-small-zh-v1.5 # 檢索返回的片段數(shù)量 TOP_K 3 # 文檔切分參數(shù) CHUNK_SIZE 500 CHUNK_OVERLAP 50 # Deepseek API 配置 DEEPSEEK_API_KEY os.getenv(DEEPSEEK_API_KEY, ) DEEPSEEK_BASE_URL os.getenv(DEEPSEEK_BASE_URL, https://api.deepseek.com) DEEPSEEK_MODEL os.getenv(DEEPSEEK_MODEL, deepseek-chat)有一處要重點(diǎn)說明DEEPSEEK_API_KEY 不建議硬編碼在代碼文件中應(yīng)該寫在項(xiàng)目根目錄的 .env 文件里并確保 .env 被加入 .gitignore。這樣可以避免 API Key 意外提交到公開倉(cāng)庫(kù)造成安全風(fēng)險(xiǎn)。.env 文件的格式如下DEEPSEEK_API_KEY你的Deepseek_API_Key關(guān)于 Deepseek API 的使用請(qǐng)前往 Deepseek 官方開放平臺(tái)注冊(cè)并創(chuàng)建 API Key。使用 API 會(huì)產(chǎn)生少量費(fèi)用具體計(jì)費(fèi)標(biāo)準(zhǔn)以官方頁面為準(zhǔn)建議先小額充值并查看接口文檔中的價(jià)格說明。4.2 文檔加載與向量化入庫(kù) ingest.pyingest.py 的作用是讀取 data 目錄下的文檔進(jìn)行切分、向量化然后寫入向量數(shù)據(jù)庫(kù)。這是整個(gè) RAG 系統(tǒng)的離線構(gòu)建階段。# 文件路徑rag-demo/ingest.py import os from typing import List from langchain_text_splitters import CharacterTextSplitter from sentence_transformers import SentenceTransformer import chromadb import config def load_documents(data_dir: str) - List[str]: 讀取 data 目錄下的所有 txt 文件返回文檔內(nèi)容列表。 docs [] for filename in os.listdir(data_dir): if filename.endswith(.txt): filepath os.path.join(data_dir, filename) with open(filepath, r, encodingutf-8) as f: content f.read() if content.strip(): docs.append(content) print(f已加載文檔: {filename}) return docs def split_text(documents: List[str]) - List[str]: 將長(zhǎng)文檔切分成指定大小的文本塊 chunk。 splitter CharacterTextSplitter( separator\n, chunk_sizeconfig.CHUNK_SIZE, chunk_overlapconfig.CHUNK_OVERLAP, length_functionlen, ) chunks [] for doc in documents: chunks.extend(splitter.split_text(doc)) return chunks def build_vector_store(chunks: List[str]): 將文本塊向量化并寫入 Chroma 向量庫(kù)。 # 加載本地 embedding 模型首次運(yùn)行會(huì)自動(dòng)下載 print(正在加載 embedding 模型...) embedder SentenceTransformer(config.EMBEDDING_MODEL_NAME) # 生成向量 print(正在生成向量...) embeddings embedder.encode(chunks, show_progress_barTrue).tolist() # 創(chuàng)建 Chroma 客戶端持久化到本地目錄 client chromadb.PersistentClient(pathconfig.CHROMA_DIR) # 如果集合已存在先刪除避免重復(fù)插入 existing_collections client.list_collections() for col in existing_collections: if col.name config.COLLECTION_NAME: client.delete_collection(config.COLLECTION_NAME) print(已刪除舊的向量庫(kù)集合) collection client.create_collection( nameconfig.COLLECTION_NAME, metadata{hnsw:space: cosine}, # 使用余弦相似度 ) # 寫入向量庫(kù)id 使用序號(hào)方便管理 ids [str(i) for i in range(len(chunks))] # 這里直接把原始文本和向量一起存入 collection.add( idsids, embeddingsembeddings, documentschunks, ) print(f向量庫(kù)構(gòu)建完成共寫入 {len(chunks)} 個(gè)文本塊) if __name__ __main__: all_docs load_documents(config.KNOWLEDGE_BASE_DIR) if not all_docs: raise ValueError(fdata 目錄下沒有找到可用文檔請(qǐng)檢查目錄: {config.KNOWLEDGE_BASE_DIR}) all_chunks split_text(all_docs) print(f文檔切分完成共得到 {len(all_chunks)} 個(gè)文本塊) build_vector_store(all_chunks)這段代碼的重點(diǎn)有幾個(gè)。文本切分參數(shù)值得專門調(diào)試。CHUNK_SIZE 表示每個(gè)文本塊的最大字符數(shù)CHUNK_OVERLAP 表示相鄰塊之間重疊的字符數(shù)。重疊的部分可以讓切塊邊界處的語義不丟失尤其是當(dāng)問題和答案分別跨越兩個(gè)塊邊界時(shí)重疊能明顯提升召回效果。實(shí)際項(xiàng)目中500 到 800 字是比較常見的塊大小過小會(huì)導(dǎo)致檢索上下文不足過大則會(huì)讓單塊包含太多無關(guān)信息降低檢索精度。Chroma 的持久化方式在代碼中使用了 PersistentClient向量庫(kù)數(shù)據(jù)會(huì)保存到 ./chroma_db 目錄。這樣下次啟動(dòng)系統(tǒng)時(shí)不需要重新構(gòu)建向量庫(kù)直接讀取即可。如果知識(shí)庫(kù)文檔發(fā)生了更新重新運(yùn)行一次 ingest.py 即可不必重啟任何服務(wù)。4.3 檢索模塊 retriever.pyretriever.py 負(fù)責(zé)接收用戶問題將其向量化后在 Chroma 中檢索最相關(guān)的 Top K 個(gè)片段。# 文件路徑rag-demo/retriever.py import chromadb from sentence_transformers import SentenceTransformer import config def get_embedder(): 獲取共享的 embedding 模型實(shí)例避免多次重復(fù)加載。 return SentenceTransformer(config.EMBEDDING_MODEL_NAME) def search(query: str, top_k: int None): 根據(jù)用戶問題檢索知識(shí)庫(kù)返回相關(guān)片段列表。 if top_k is None: top_k config.TOP_K # 加載向量庫(kù) client chromadb.PersistentClient(pathconfig.CHROMA_DIR) collection client.get_collection(config.COLLECTION_NAME) # 對(duì)用戶問題進(jìn)行向量化 embedder get_embedder() query_embedding embedder.encode([query]).tolist() # 執(zhí)行相似度檢索 results collection.query( query_embeddingsquery_embedding, n_resultstop_k, ) documents results.get(documents, [[]])[0] distances results.get(distances, [[]])[0] return documents, distances這里需要留意一個(gè)問題每次調(diào)用 get_embedder 都會(huì)重新加載一次模型。在 Streamlit 這種 Web 服務(wù)中頻繁加載模型會(huì)拖慢速度。實(shí)際開發(fā)時(shí)可以把 embedder 設(shè)計(jì)成全局單例或者放到內(nèi)存緩存中。我在這里保留簡(jiǎn)單寫法是為了讓流程更清晰后面工程優(yōu)化部分再討論如何改進(jìn)。Chroma 的 query 接口返回結(jié)果中documents 是對(duì)應(yīng)的原始文本內(nèi)容distances 是余弦距離。距離越小表示相似度越高后續(xù)可以把距離信息一并展示幫助用戶判斷答案的可信度。4.4 RAG 問答主流程 rag.pyrag.py 是系統(tǒng)的核心負(fù)責(zé)把檢索結(jié)果和用戶問題組裝成 Prompt然后調(diào)用 Deepseek 生成回答。# 文件路徑rag-demo/rag.py from openai import OpenAI import config from retriever import search # 初始化 Deepseek 客戶端兼容 OpenAI SDK client OpenAI( api_keyconfig.DEEPSEEK_API_KEY, base_urlconfig.DEEPSEEK_BASE_URL, ) def build_prompt(query: str, context_docs: list) - str: 組裝發(fā)送給大模型的 Prompt。 system_prompt ( 你是一個(gè)專業(yè)的知識(shí)庫(kù)問答助手。 請(qǐng)根據(jù)提供的參考資料回答用戶問題。 必須優(yōu)先參考參考資料中的內(nèi)容不要臆造答案。 如果參考資料無法回答該問題請(qǐng)直接說明知識(shí)庫(kù)中暫未找到相關(guān)信息。 ) context \n\n.join(context_docs) user_prompt f請(qǐng)根據(jù)以下參考資料回答用戶問題。 【參考資料】 {context} 【用戶問題】 {query} 請(qǐng)用中文回答如果引用了參考資料可以說明信息來源于哪個(gè)部分。 return system_prompt, user_prompt def ask(query: str) - dict: Retrieve Generate 完整流程。 # 檢索相關(guān)片段 docs, distances search(query) # 組裝 Prompt system_prompt, user_prompt build_prompt(query, docs) # 調(diào)用 Deepseek 生成回答 response client.chat.completions.create( modelconfig.DEEPSEEK_MODEL, temperature0.3, messages[ {role: system, content: system_prompt}, {role: user, content: user_prompt}, ], ) answer response.choices[0].message.content return { answer: answer, source_documents: docs, distances: distances, } if __name__ __main__: question input(請(qǐng)輸入你的問題) result ask(question) print(\n 回答 ) print(result[answer]) print(\n 引用片段 ) for i, doc in enumerate(result[source_documents]): print(f\n[{i 1}] {doc[:200]})Deepseek 的接入方式與 OpenAI 幾乎一致核心代碼只有這么幾行。這里給出的 model 名稱是 deepseek-chat對(duì)應(yīng) Deepseek 的對(duì)話模型。temperature 設(shè)置為 0.3會(huì)讓回答更加穩(wěn)定、更貼近參考資料內(nèi)容。如果你想獲得更有創(chuàng)造性的回答可以調(diào)高到 0.7 左右但在知識(shí)庫(kù)問答場(chǎng)景下推薦保持低 temperature以減少胡說八道的概率。Prompt 的設(shè)計(jì)值得仔細(xì)思考。系統(tǒng)提示詞明確要求“必須優(yōu)先參考參考資料中的內(nèi)容不要臆造答案”這一步是抑制幻覺的關(guān)鍵。如果直接把問題和檢索片段丟給模型而不加任何約束模型仍然可能傾向使用自己的知識(shí)回答。所以在 RAG 系統(tǒng)中Prompt 不是隨便拼一段文字而是需要反復(fù)打磨的工程質(zhì)量項(xiàng)。4.5 Streamlit Web 界面 app.py最后寫一個(gè)簡(jiǎn)單的 Web 界面讓系統(tǒng)可以被同事或用戶直接使用。# 文件路徑rag-demo/app.py import streamlit as st import config from rag import ask st.set_page_config(page_titleRAG 知識(shí)庫(kù)問答系統(tǒng), page_icon, layoutwide) st.title( RAG 知識(shí)庫(kù)問答系統(tǒng)) st.caption(基于 Deepseek Chroma 構(gòu)建的私有知識(shí)庫(kù)問答系統(tǒng)) query st.text_area(請(qǐng)輸入你的問題, height100) if st.button(獲取答案, typeprimary): if not query.strip(): st.warning(請(qǐng)輸入問題內(nèi)容) elif not config.DEEPSEEK_API_KEY: st.error(未檢測(cè)到 DEEPSEEK_API_KEY請(qǐng)檢查 .env 文件配置) else: with st.spinner(正在檢索并生成回答...): result ask(query.strip()) st.subheader(回答) st.write(result[answer]) with st.expander(查看參考文檔片段): for i, (doc, dist) in enumerate(zip(result[source_documents], result[distances])): st.markdown(f**片段 {i 1}**距離{dist:.4f}) st.text(doc[:500])這個(gè)界面就是典型的“輸入框 按鈕 結(jié)果展示”結(jié)構(gòu)沒有復(fù)雜的前端依賴。st.expander 折疊展示參考片段讓用戶既能看答案也能核對(duì)答案的出處符合 RAG 可溯源的優(yōu)勢(shì)。5. 運(yùn)行系統(tǒng)與效果驗(yàn)證5.1 準(zhǔn)備示例文檔在 data 目錄下創(chuàng)建兩個(gè)測(cè)試文檔這里以一個(gè)虛構(gòu)的公司場(chǎng)景為例# 文件路徑rag-demo/data/公司介紹.txt 某某科技有限公司成立于2018年總部位于上海主營(yíng)業(yè)務(wù)是企業(yè)級(jí)人工智能解決方案定制服務(wù)。 公司核心技術(shù)團(tuán)隊(duì)來自國(guó)內(nèi)一線互聯(lián)網(wǎng)公司與高校實(shí)驗(yàn)室在自然語言處理、知識(shí)圖譜、大模型應(yīng)用方向有豐富經(jīng)驗(yàn)。 公司的主要產(chǎn)品包括智能客服系統(tǒng)、知識(shí)庫(kù)問答平臺(tái)、數(shù)據(jù)中臺(tái)建設(shè)服務(wù)。 截至2025年公司已服務(wù)超過200家中小企業(yè)客戶覆蓋零售、金融、教育等行業(yè)。# 文件路徑rag-demo/data/product_faq.txt 問知識(shí)庫(kù)問答平臺(tái)支持哪些文檔格式 答平臺(tái)支持 txt、PDF、Word、Markdown 等常見格式推薦使用 Markdown 或 txt 以獲得最佳解析效果。 問平臺(tái)的數(shù)據(jù)是否安全 答平臺(tái)支持私有化部署文檔向量化和檢索過程可以在企業(yè)內(nèi)部網(wǎng)絡(luò)獨(dú)立完成只有最終生成回答時(shí)會(huì)調(diào)用大模型 API。 問知識(shí)庫(kù)更新需要重新訓(xùn)練模型嗎 答不需要。知識(shí)庫(kù)問答系統(tǒng)采用 RAG 架構(gòu)只需要更新向量庫(kù)即可讓模型基于最新文檔回答問題。5.2 初始化知識(shí)庫(kù)在項(xiàng)目根目錄執(zhí)行python ingest.py正常情況下會(huì)看到類似輸出已加載文檔: 公司介紹.txt 已加載文檔: product_faq.txt 文檔切分完成共得到 6 個(gè)文本塊 正在加載 embedding 模型... 正在生成向量... 向量庫(kù)構(gòu)建完成共寫入 6 個(gè)文本塊首次運(yùn)行會(huì)下載 bge-small-zh-v1.5 模型文件大小在 100MB 左右需要保持網(wǎng)絡(luò)暢通。下載完成后模型會(huì)緩存在本地之后運(yùn)行不會(huì)再重復(fù)下載。5.3 啟動(dòng) Web 界面streamlit run app.py瀏覽器會(huì)自動(dòng)打開 Streamlit 提供的本地地址默認(rèn)是 http://localhost:8501。可以看到一個(gè)簡(jiǎn)潔的問答界面輸入問題后點(diǎn)擊“獲取答案”。嘗試提問“公司知識(shí)庫(kù)平臺(tái)支持哪些文檔格式”預(yù)期回答會(huì)參考 product_faq.txt 中的內(nèi)容并明確指出支持 txt、PDF、Word、Markdown 等格式。如果提問“公司成立于哪一年”系統(tǒng)應(yīng)該從公司介紹文檔中檢索到對(duì)應(yīng)信息并給出答案。在“查看參考文檔片段”區(qū)域你會(huì)看到檢索到的原始片段和對(duì)應(yīng)的相似度距離這能幫助你判斷系統(tǒng)是否真正用上了知識(shí)庫(kù)內(nèi)容。6. 常見問題與排查思路在實(shí)際運(yùn)行中很多問題其實(shí)是共通的。下面把高頻問題整理成表格再逐個(gè)展開。問題現(xiàn)象常見原因解決思路首次運(yùn)行下載模型失敗網(wǎng)絡(luò)不穩(wěn)定或 HuggingFace 地址無法訪問使用鏡像地址或手動(dòng)下載模型到本地向量庫(kù)查詢報(bào)錯(cuò) Collection not found未執(zhí)行 ingest.py 或目錄不一致執(zhí)行 ingest.py 構(gòu)建向量庫(kù)檢查 CHROMA_DIR檢索結(jié)果與問題無關(guān)chunk 過大、top_k 過小、文檔格式混亂調(diào)整 CHUNK_SIZE、增大 TOP_K清洗文檔Deepseek API 返回 401 錯(cuò)誤API Key 不正確或未加載成功檢查 .env 文件確認(rèn) load_dotenv 生效回答沒有引用知識(shí)庫(kù)內(nèi)容Prompt 約束不夠或檢索片段為空加強(qiáng) system prompt檢查檢索結(jié)果Chroma old database version 報(bào)錯(cuò)向量庫(kù)版本升級(jí)不兼容刪除 chroma_db 目錄后重新 ingest6.1 首次運(yùn)行模型下載失敗bge-small-zh-v1.5 模型默認(rèn)從 HuggingFace 下載。如果你的網(wǎng)絡(luò)環(huán)境無法穩(wěn)定訪問可以設(shè)置鏡像環(huán)境變量export HF_ENDPOINThttps://hf-mirror.com然后在終端重新運(yùn)行 ingest.py。設(shè)置鏡像環(huán)境變量的目的是解決下載通道問題屬于開發(fā)過程中的常規(guī)操作。模型下載完成后可以不再依賴外網(wǎng)。另一種方式是從其他方式下載模型文件后把模型目錄放到本地然后在 config.py 中將 EMBEDDING_MODEL_NAME 改為模型所在的本地路徑。例如EMBEDDING_MODEL_NAME ./models/bge-small-zh-v1.56.2 檢索結(jié)果不理想檢索結(jié)果差通常不是單一原因造成的需要按照順序排查幾個(gè)關(guān)鍵參數(shù)。先檢查 TOP_K。如果設(shè)置為 1結(jié)果可能只覆蓋一個(gè)片段信息量不足如果設(shè)置為 5又可能混入大量不相關(guān)內(nèi)容。對(duì)于短文檔3 是合理的起點(diǎn)。再檢查 CHUNK_SIZE。如果文檔本身是 FAQ 格式每條問答很短那么把 CHUNK_SIZE 設(shè)置成 500會(huì)把多個(gè)問答切進(jìn)同一個(gè)塊導(dǎo)致檢索時(shí)指向內(nèi)容不準(zhǔn)確。對(duì)這種結(jié)構(gòu)化文檔建議將 chunk_size 調(diào)小比如 200 到 300并去掉過大的 overlap。最重要的還是文檔清洗。如果原始文檔包含大量頁眉頁腳、特殊符號(hào)、亂碼向量化效果會(huì)明顯變差。在真實(shí)項(xiàng)目中文檔預(yù)處理往往占用整個(gè) RAG 項(xiàng)目一半以上的工作量這是很正常的現(xiàn)象。6.3 Deepseek API 接入問題如果調(diào)用時(shí)報(bào) 401最直接的排查方式是打印 config.DEEPSEEK_API_KEY確認(rèn) .env 是否被正確加載。.env 文件必須和運(yùn)行命令所在目錄一致也就是項(xiàng)目根目錄。如果報(bào)連接超時(shí)先確認(rèn)網(wǎng)絡(luò)環(huán)境能夠訪問 Deepseek API。同時(shí)可以在代碼中打印 DEEPSEEK_BASE_URL確認(rèn)沒有因?yàn)橹暗捻?xiàng)目設(shè)置而覆蓋成了其他地址。6.4 向量庫(kù)版本兼容問題Chroma 版本迭代較快不同版本生成的數(shù)據(jù)庫(kù)文件可能不兼容出現(xiàn)類似“old database version”的報(bào)錯(cuò)時(shí)最簡(jiǎn)單的處理是備份并刪除 chroma_db 目錄然后重新運(yùn)行 ingest.py。這只是開發(fā)階段的做法生產(chǎn)環(huán)境中應(yīng)該提前規(guī)劃向量庫(kù)的升級(jí)策略例如使用獨(dú)立的向量數(shù)據(jù)庫(kù)服務(wù)。7. 最佳實(shí)踐與工程化建議文章到這里整套代碼已經(jīng)能跑通了。但如果你想把這個(gè) Demo 變成真正可用的系統(tǒng)還需要注意下面幾個(gè)工程問題。7.1 把 Prompt 單獨(dú)管理不要把 Prompt 字符串散落在業(yè)務(wù)代碼里。隨著項(xiàng)目迭代Prompt 的調(diào)整頻率很高應(yīng)該單獨(dú)提取為一個(gè)配置文件或 Prompt 管理模塊。某些團(tuán)隊(duì)還會(huì)為不同場(chǎng)景編寫多套 Prompt比如“摘要模式”“對(duì)比模式”“嚴(yán)格引用模式”然后用模版變量動(dòng)態(tài)切換。7.2 增加檢索結(jié)果的引用溯源RAG 的核心優(yōu)勢(shì)之一就是可解釋性。在 Web 界面和 API 返回中都應(yīng)該保留 source_documents 字段最好把文檔名、頁碼、片段位置一起返回。這樣用戶能夠點(diǎn)擊查看原文運(yùn)營(yíng)人員也能快速發(fā)現(xiàn)錯(cuò)誤片段并及時(shí)修正知識(shí)庫(kù)。7.3 完善文檔更新機(jī)制目前 ingest.py 每次都會(huì)刪除舊集合重新寫入。當(dāng)知識(shí)庫(kù)規(guī)模變大后應(yīng)該改成增量更新根據(jù)文檔的 hash 值或更新時(shí)間只處理變更部分。向量庫(kù)中也要增加元數(shù)據(jù)字段比如來源文件名、更新時(shí)間、部門標(biāo)簽方便按條件過濾。7.4 引入重排Rerank提升精度向量檢索拿到的 Top K 片段里可能順序并不完全符合語義相關(guān)度。更成熟的方案是在向量檢索之后增加一個(gè) rerank 模型對(duì)候選片段重新打分。比如本地部署 bge-reranker-base 模型先用向量召回 20 個(gè)候選再重排取前 3 個(gè)送給大模型。實(shí)踐表明加一層 rerank 后回答準(zhǔn)確率往往會(huì)有明顯提升。7.5 從 RAG 走向 Agentic RAG目前實(shí)現(xiàn)的是標(biāo)準(zhǔn) RAG每次提問只做一次檢索。當(dāng)問題復(fù)雜時(shí)例如“對(duì)比公司產(chǎn)品 A 和產(chǎn)品 B 的區(qū)別”或者“找出去年所有投訴工單中的高頻問題”單次檢索可能不夠。Agentic RAG 的核心思想是讓大模型具備“工具調(diào)用”能力它可以決定先搜索什么、搜索幾次、是否改寫問題、是否需要查看多個(gè)文檔后再綜合回答。這個(gè)方向可以作為下一步的進(jìn)階學(xué)習(xí)目標(biāo)。本質(zhì)上是把 RAG 的“搜索鏈路”從固定流程升級(jí)成由模型驅(qū)動(dòng)的動(dòng)態(tài)流程對(duì) Prompt 設(shè)計(jì)和工具調(diào)用的工程質(zhì)量要求更高。7.6 安全與合規(guī)注意事項(xiàng)涉及到 API 調(diào)用、內(nèi)部文檔時(shí)有幾個(gè)安全底線需要堅(jiān)持。第一API Key 絕不硬編碼在源碼中.env 文件必須加入 .gitignore第二生產(chǎn)環(huán)境建議通過獨(dú)立的密鑰管理服務(wù)接收 API Key由后端服務(wù)統(tǒng)一調(diào)用不要把密鑰直接暴露給前端第三企業(yè)內(nèi)部敏感文檔如果涉及數(shù)據(jù)保密要求需要確認(rèn)是否允許調(diào)用外部大模型 API。如果嚴(yán)格禁止外部傳輸則應(yīng)該采用本地部署的模型替換 Deepseek API把整個(gè)鏈路都收斂在內(nèi)網(wǎng)環(huán)境中完成。8. 從入門到落地下一步可以做什么至此你已經(jīng)親手搭完了一套完整的 RAG 知識(shí)庫(kù)問答系統(tǒng)從文檔加載、切分、向量化、檢索到 Prompt 組裝和 Deepseek 生成回答所有環(huán)節(jié)都是可運(yùn)行、可擴(kuò)展的。相比直接調(diào)用大模型接口“硬問”這套方案讓模型真正學(xué)會(huì)利用你的私有資料來回答問題。如果你打算繼續(xù)深入有兩條推薦路線。一條是優(yōu)化檢索質(zhì)量嘗試引入 rerank、多路召回、元數(shù)據(jù)過濾讓召回結(jié)果更精準(zhǔn)另一條是走向 Agentic RAG讓模型能自主規(guī)劃?rùn)z索步驟處理更復(fù)雜的多跳問答任務(wù)。兩條路線都不需要重新訓(xùn)練模型完全符合 RAG 低成本的核心理念。構(gòu)建知識(shí)庫(kù)本身也是一門細(xì)活。文檔清洗、文本切分、領(lǐng)域詞表、Prompt 調(diào)優(yōu)每一個(gè)環(huán)節(jié)都會(huì)影響最終回答質(zhì)量。不要指望運(yùn)行一遍代碼就得到完美效果真正的項(xiàng)目落地就是在這些細(xì)節(jié)里不斷打磨的過程。希望這份手把手教程能幫你邁出扎實(shí)的第一步也歡迎把你在搭建過程中遇到的問題留在評(píng)論區(qū)大家互相交流排錯(cuò)經(jīng)驗(yàn)。