建立具程式感知的 RAG 管線

這篇教你用 LangChain 建立能讀取 Python 與 Markdown 檔案的程式感知 RAG 管線，完成分段、向量索引與檢索問答。

這篇給想把專案文件、程式碼與說明文件一起做檢索問答的開發者。你照著做完，會得到一條可運作的 LangChain RAG 流程，能載入檔案、依 token 切塊、建立向量索引，並用你的文件回答問題。

如果你手上有 API key、一些 .py 與 .md 檔案，這份操作指南可以直接照做到底。每一步都會產出一個具名成果，方便你逐段驗收，不會只停在概念說明。

開始之前

• Python 3.10+
• LangChain 套件可安裝的開發環境
• OpenAI、Anthropic 或其他相容的 LLM API key
• 同一供應商的 embeddings API key，或本機 embeddings 模型
• 一組包含 .py 與 .md 的測試文件
• Git 已安裝，可用來抓取範例專案或自己的文件庫

Step 1: 安裝 LangChain 套件

目的：先把專案需要的核心套件裝好，讓後續能載入檔案、切塊、做向量化與檢索。

pip install langchain langchain-community langchain-text-splitters langchain-openai faiss-cpu tiktoken

具名產出：LangChain 工作環境。驗收時，你應該看到安裝完成且沒有錯誤，執行 python -c "import langchain" 也能正常通過。

Step 2: 載入 Python 與 Markdown 檔案

目的：把原始文件轉成 LangChain 可處理的文件物件，讓程式碼與說明文字都能進入檢索流程。

from langchain_community.document_loaders import DirectoryLoader, TextLoader

py_loader = DirectoryLoader("./docs", glob="**/*.py", loader_cls=TextLoader)
md_loader = DirectoryLoader("./docs", glob="**/*.md", loader_cls=TextLoader)

python_docs = py_loader.load()
markdown_docs = md_loader.load()
all_docs = python_docs + markdown_docs

具名產出：原始文件清單。你應該看到非空的文件陣列，而且每個文件都帶有來自原始檔案的內容。

Step 3: 依 token 切分文件

目的：用 token 感知的方式切塊，避免把函式、段落或設定說明切得太碎，讓模型更容易理解上下文。

from langchain_text_splitters import RecursiveCharacterTextSplitter

splitter = RecursiveCharacterTextSplitter.from_tiktoken_encoder(
    chunk_size=800,
    chunk_overlap=120,
)
chunks = splitter.split_documents(all_docs)

具名產出：Token 切塊集合。你應該看到切塊數量多於原始檔案數，而且每塊大小接近你的 token 目標，不會在函式中段或段落中段亂斷。

Step 4: 建立向量索引

目的：把切塊轉成 embeddings，存進可檢索的向量資料庫，讓語意搜尋可以找到最相關的內容。

from langchain_openai import OpenAIEmbeddings
from langchain_community.vectorstores import FAISS

embeddings = OpenAIEmbeddings()
vectorstore = FAISS.from_documents(chunks, embeddings)
retriever = vectorstore.as_retriever(search_kwargs={"k": 4})

具名產出：FAISS 向量索引。驗收時，你應該看到索引建立成功，並且對一個測試查詢呼叫 retriever 時，能回傳前幾個最相關的切塊。

Step 5: 接上檢索問答鏈

目的：把檢索結果交給模型生成答案，讓回答盡量引用你自己的文件，而不是只給泛泛而談的內容。

from langchain_openai import ChatOpenAI
from langchain.chains import RetrievalQA

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
qa = RetrievalQA.from_chain_type(llm=llm, retriever=retriever)

result = qa.invoke({"query": "這個程式庫主要做什麼？"})
print(result["result"])

具名產出：RAG 問答鏈。你應該看到答案明確參照你的文件內容，而不是只有通用型回覆，且檢索到的上下文要和問題對得上。

Step 6: 驗證切塊品質與檢索結果

目的：確認程式感知切分與 token 切塊，真的有提升程式碼問題的回答品質。

請用幾個有針對性的提問測試，例如函式名稱、安裝步驟、架構說明，然後比對檢索到的切塊和最後答案。如果模型漏掉重點，就把 chunk size 調小、把 overlap 調大，或加入檔案類型與路徑的 metadata 篩選。

具名產出：檢索品質報告。你應該看到程式碼與文件問題的答案更精準，碎片化片段變少，排進前幾名的內容也更相關。

常見錯誤

• 拿字元切分直接處理程式碼。修法：改用 token 感知切分器，並依函式長度調整 chunk size。
• 單一切塊塞太多內容。修法：降低 chunk size，並增加 overlap，讓檢索回來的上下文更聚焦。
• 沒有先檢查檢索來源。修法：先印出 top-k 切塊，再讓模型生成答案，確認上下文真的對題。

接下來可以看什麼

這條管線跑通後，下一步可以加上 metadata 篩選、來源引用、向量庫持久化與評估測試，讓你的文件量變大時，仍能持續量化檢索品質。