自建本地模型-Agent-知识库实战指南
从零自建本地模型 + Agent + 知识库:环境、选型、踩坑与完整清单
本文按"从零到跑通"的顺序,讲清楚 Python 环境怎么装、本地大模型怎么跑、每个工具为什么这么选,并附上所有踩过的坑与完整依赖清单。
一、Python 环境:不要装在全局里
1.1 装 Python
建议用 Python 3.12。这个版本生态最稳,LangChain、Chroma、akshare 兼容性都比较好。
- Windows:去 python.org 下载 3.12 安装包,安装时务必勾选 “Add Python to PATH”。
- macOS / Linux:可用系统自带 Python 或通过 pyenv、apt、brew 安装。
验证:
python --version
1.2 创建虚拟环境
不要直接往全局 Python 里装包。每个项目单独一个 venv,避免包冲突。
cd your_project
python -m venv .venv
激活:
# Windows CMD
.venv\Scripts\activate
# Windows PowerShell
.venv\Scripts\Activate.ps1
# macOS / Linux
source .venv/bin/activate
激活后终端前面会出现 (.venv)。
1.3 升级 pip
pip install --upgrade pip
坑 1:pip 版本太旧会导致某些 wheel 装不上。 尤其是 chromadb、sentence-transformers 这类带二进制依赖的包。
1.4 安装依赖
pip install langgraph langchain langchain-ollama langchain-community \
sentence-transformers chromadb \
requests beautifulsoup4 lxml \
akshare
坑 2:langchain 和 langchain-community 版本不匹配会报 ImportError。 建议一次性装完,让 pip 自己解依赖。
坑 3:sentence-transformers 首次下载模型会很慢。 后面会讲怎么离线放本地。
二、本地大模型:Ollama + Qwen2.5
2.1 为什么选 Ollama
本地跑模型有几个常见方案:Ollama、llama.cpp、vLLM、Text Generation WebUI。
| 方案 | 适合谁 | 不选它的理由 |
|---|---|---|
| Ollama | 个人、本地 Agent、断网可用 | 分布式/高并发场景不够强 |
| llama.cpp | 想手动调量化、裁剪 | 配置复杂 |
| vLLM | 多并发服务 | 需要 GPU 服务器,太重 |
| Text Generation WebUI | 想可视化调试 | 依赖多、维护成本高 |
选 Ollama 的理由很直接:一行命令拉模型、自动量化、自动走 GPU、自带 OpenAI 兼容 API、数据不出本机。
2.2 安装 Ollama
去 ollama.com 下载对应系统安装包。
Windows 双击安装;macOS 拖进 Applications;Linux 可用:
curl -fsSL https://ollama.com/install.sh | sh
验证:
ollama --version
2.3 拉模型
ollama pull qwen2.5:7b
qwen2.5:7b 大约 4.7GB,中文能力强,7B 规模在 8GB 显存或 16GB 内存机器上都能跑。
显存/内存不够可以换:
qwen2.5:3b:更低配机器qwen2.5:0.5b:纯尝鲜
2.4 跑起来
命令行对话:
ollama run qwen2.5:7b
API 调用(Agent 里用这个):
curl http://localhost:11434/api/generate \
-d '{"model":"qwen2.5:7b","prompt":"你好","stream":false}'
2.5 确认是否走 GPU
另开一个终端:
ollama ps
如果日志里出现 CUDA、Metal、GPU 字样,说明走了加速;否则可能退到 CPU,速度会慢很多。
2.6 模型存放路径
Windows 默认在 C:\Users\用户名\.ollama\models,容易占满 C 盘。
可设置环境变量:
OLLAMA_MODELS=D:\AI\Models\Ollama
设置后重启 Ollama,再把旧 models 目录搬过去即可。
坑 4:Ollama 装完默认后台常驻。 如果机器内存紧张,不需要时可以关掉,避免占用。
三、工具选型依据:为什么这么搭
3.1 Agent 框架:选 LangGraph
对比 AutoGen、CrewAI、LangGraph:
- AutoGen:适合快速做对话式 Demo,但已进入维护模式。
- CrewAI:上手简单,适合角色分工式任务,但对"人工审批 + 状态恢复"支持不如 LangGraph 原生。
- LangGraph:图式编排、状态持久化、
interrupt()人工审批、时间旅行回滚,最适合"需要人把关的本地 Agent"。
这套系统要求联网必须授权、行情数字必须精准、知识库必须本地,所以选 LangGraph。
3.2 向量数据库:选 Chroma
对比 FAISS、Chroma、Milvus:
- FAISS:只是检索库,没有持久化、没有元数据过滤,要自己维护向量到文档的映射。
- Milvus:适合生产级大规模部署,但需要 Docker、etcd、MinIO,对个人本地项目太重。
- Chroma:几行代码就能跑,自带持久化、支持 metadata 过滤,适合个人知识库、中小规模文档。
所以选 Chroma。
3.3 嵌入模型:选 bge-small-zh
中文知识库场景,bge-small-zh 体积小、中文语义匹配效果好,适合本地离线运行。
3.4 联网搜索:不用 baidusearch,改用 requests + BeautifulSoup
坑 5:baidusearch 返回结果少且不稳定。 后来直接用 requests 抓百度搜索结果页,再用 BeautifulSoup + lxml 解析标题、摘要和链接,可控性高很多。
3.5 行情数据:必须用 akshare
坑 6:行情数字不能靠新闻摘要。 之前用百度搜索抓新闻,点位是二手转述、链接是百度跳转、美股经常缺失。换成 akshare 后直接取交易所/门户原始行情数据,休市时也会返回最近已收盘数据。
四、知识库构建
入库脚本的核心思路是按格式分目录:四类文档各放各的目录(text / pdfs / mds / docx),每种格式走各自的 loader,解析后统一切分、灌进同一个 Chroma;入库前先把旧向量库整个删掉重建,避免重复片段。运行前请在脚本同级目录准备好这四个文件夹,并把对应文档丢进去。
4.1 目录规划:一种格式一个目录
build_index.py 同级目录下:
text/ # 纯文本 .txt(制度说明、FAQ、流程)
pdfs/ # PDF(合同、制度文档,需带文字层,扫描件要先 OCR)
mds/ # Markdown .md
docx/ # Word .docx
chroma_db/ # 向量库输出目录(脚本自动建,已存在则先删后建)
models/bge-small-zh/ # 嵌入模型,需提前离线下载到本地
原则:一种后缀对应一个目录,loader 各管各的,新增格式就再加一个目录 + 一个
load_xxx函数,互不干扰。
4.2 build 入库脚本(核心)
新建 build_index.py,整份如下,运行 python build_index.py 即可重建知识库:
# -*- coding: utf-8 -*-
import shutil, os
# 离线 + 镜像:首次下载 bge 模型用国内镜像;已下载到本地则强制离线,避免联网卡住
os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"
os.environ["HF_HUB_OFFLINE"] = "1"
from langchain_community.document_loaders import (
DirectoryLoader,
TextLoader,
PyPDFLoader,
UnstructuredMarkdownLoader,
UnstructuredWordDocumentLoader,
)
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_community.embeddings import HuggingFaceEmbeddings
from langchain_community.vectorstores import Chroma
TXT_DIR = "text"
PDF_DIR = "pdfs"
MD_DIR = "mds"
DOCX_DIR = "docx"
DB_DIR = "chroma_db"
def load_txt(directory: str):
loader = DirectoryLoader(
directory,
glob="**/*.txt",
recursive=True,
loader_cls=TextLoader,
loader_kwargs={"encoding": "utf-8"},
)
return loader.load()
def load_pdf(directory: str):
loader = DirectoryLoader(
directory,
glob="**/*.pdf",
recursive=True,
loader_cls=PyPDFLoader,
)
docs = loader.load()
# 过滤掉扫描版 / 空白页解析出来的空内容
return [d for d in docs if d.page_content.strip()]
def load_md(directory: str):
loader = DirectoryLoader(
directory,
glob="**/*.md",
recursive=True,
loader_cls=UnstructuredMarkdownLoader,
)
return loader.load()
def load_docx(directory: str):
loader = DirectoryLoader(
directory,
glob="**/*.docx",
recursive=True,
loader_cls=UnstructuredWordDocumentLoader,
)
return loader.load()
def build_kb():
docs = (
load_txt(TXT_DIR)
+ load_pdf(PDF_DIR)
+ load_md(MD_DIR)
+ load_docx(DOCX_DIR)
)
splitter = RecursiveCharacterTextSplitter(
chunk_size=500,
chunk_overlap=80,
separators=["
", "
", "。", ";", " ", ""],
)
chunks = splitter.split_documents(docs)
txt_n = sum(1 for c in chunks if c.metadata.get("source", "").endswith(".txt"))
pdf_n = sum(1 for c in chunks if c.metadata.get("source", "").endswith(".pdf"))
md_n = sum(1 for c in chunks if c.metadata.get("source", "").endswith(".md"))
docx_n = sum(1 for c in chunks if c.metadata.get("source", "").endswith(".docx"))
embeddings = HuggingFaceEmbeddings(model_name="./models/bge-small-zh")
# 入库前先删旧库,避免重复 from_documents 造成冗余片段
if os.path.exists(DB_DIR):
shutil.rmtree(DB_DIR)
print("已删除旧向量库,重建中...")
Chroma.from_documents(
documents=chunks,
embedding=embeddings,
persist_directory=DB_DIR,
)
print(
f"知识库构建完成,共 {len(chunks)} 个片段 "
f"(txt:{txt_n}, pdf:{pdf_n}, md:{md_n}, docx:{docx_n})"
)
if __name__ == "__main__":
build_kb()
要点:
- 离线 + 镜像双保险:脚本开头设
HF_ENDPOINT(首次拉模型走国内镜像)和HF_HUB_OFFLINE="1"(模型已在本地时强制离线,不再联网、不会卡)。 - 按格式分 loader:
.txt用TextLoader、.pdf用PyPDFLoader、.md用UnstructuredMarkdownLoader、.docx用UnstructuredWordDocumentLoader,各管各目录。 - PDF 空页过滤:
load_pdf里if d.page_content.strip(),把扫描版 / 空白页解析出的空片段直接丢弃。 - 统一切分:
chunk_size=500 / chunk_overlap=80,separators里显式加了中文句号、分号,中文文档断句更自然。 - 入库前删旧库重建:
shutil.rmtree(DB_DIR)保证每次跑都是干净全量重建,杜绝重复片段。 - 分格式统计:跑完打印各格式入库片段数,方便核对是否有格式漏掉。
4.3 多格式解析需要的额外依赖
四个 loader 对应的包要装齐(详见第六章依赖清单):
pip install pypdf unstructured
PyPDFLoader依赖pypdf;UnstructuredMarkdownLoader和UnstructuredWordDocumentLoader都依赖unstructured。装这两个后,txt / pdf / md / docx 四种格式即可全部入库。
4.4 检索时按后缀过滤
入库时每个片段都带了 source 元数据(含后缀),query_company_kb 里可传 filter 缩小范围,例如只搜 Word 制度文档:
retriever = vectorstore.as_retriever(
search_type="similarity",
search_kwargs={"k": 5, "filter": {"source": {"$regex": "docx$"}}},
)
坑 7:bge-small-zh 要提前下载。 首次运行会从 HuggingFace 拉模型,网络不通时用脚本里的 HF_ENDPOINT 镜像;如果模型已手动下到 ./models/bge-small-zh,则配合 HF_HUB_OFFLINE="1" 走纯离线。
坑 8:chunk_size 不能太大也不能太小。 这里取 500/80,中文制度文档比较合适;若源码类文档也想入库,可单独再加一个 code 目录,给它 1000~1200 的更大粒度,避免把函数截断。
坑 11:扫描版 PDF 没有文字层。 PyPDFLoader 对纯图片 PDF 解析出来是空的,会被 4.2 里的 strip() 过滤掉而静默漏入库;这类要先用 OCR 把 PDF 转成文本,放进 text 目录再入库。
坑 12:txt 源码非 UTF-8 编码。 TextLoader(encoding="utf-8") 遇到 GBK 文件会抛 UnicodeDecodeError;可在 loader_kwargs 里补 autodetect_encoding=True,或提前把文件转成 UTF-8。
坑 13:重复入库产生冗余片段。 旧版每次直接 from_documents 会把同一文件写进库里多份;本版已在入库前 shutil.rmtree(DB_DIR) 全量重建解决,改文档后直接重跑 python build_index.py 即可。
五、Agent 工具设计
5.1 query_company_kb
优先查本地知识库,覆盖公司制度、Android/AOSP 源码片段。
5.2 web_search
联网搜索,带 interrupt() 授权闸门。并行发起多个搜索时,恢复必须按 it.id 广播,否则只有一个工具能恢复,其余卡死。
坑 9:LangGraph 多并行中断恢复必须用 id 广播。 不能只传 {"approved": True},要用 {it.id: {"approved": approved} for it in state.interrupts}。
5.3 get_market_quote
行情、汇率、油价走 akshare。每个市场独立 try/except,一个失败不影响其他。
坑 10:akshare 接口名会随版本变化。 报错时用 pip show akshare 看版本,再去官网查对应函数名替换。
六、完整依赖清单
python 3.12
ollama
qwen2.5:7b
bge-small-zh
langgraph
langchain
langchain-ollama
langchain-community
sentence-transformers
chromadb
requests
beautifulsoup4
lxml
akshare
# 多格式文档解析(build_index.py 用)
pypdf
unstructured
七、踩坑总览
| 坑 | 现象 | 解决 |
|---|---|---|
| 全局装包冲突 | 不同项目包版本打架 | 每个项目用 python -m venv .venv |
| pip 太旧 | wheel 安装失败 | pip install --upgrade pip |
| langchain 版本不匹配 | ImportError | 一次性装完 langchain 全家桶 |
| baidusearch 不稳定 | 结果少、格式乱 | 改用 requests + BeautifulSoup |
| 行情数据不准 | 新闻摘要二手转述 | 数字走 akshare |
| akshare 接口变动 | 某版本后函数名变了 | 独立 try/except + 查官网 |
| bge 模型下载慢 | 首次运行卡住 | 提前离线下载到本地目录 |
| Ollama 占 C 盘 | models 目录越来越大 | 设置 OLLAMA_MODELS 环境变量 |
| 多中断卡死 | 并行搜索只恢复一个 | 恢复时用 {it.id: value} 广播 |
| 递归超限 | RecursionLimit 报错 | 设 recursion_limit=12 |
| thread_id 不固定 | 每次都是新对话、丢上下文 | 每次用同一个 thread_id |
| 入库只认单目录单格式 | Word/PDF 文档漏入库 | 按格式分目录(text/pdfs/mds/docx)各走各 loader |
| 扫描 PDF 解析为空 | 纯图片 PDF 无文字层 | 先 OCR 转文本再入库 |
| 源码编码报错 | UnicodeDecodeError | autodetect_encoding=True |
八、一句话选型原则
- 模型本地跑:Ollama + Qwen2.5,数据不出本机、断网可用。
- Agent 要可控:LangGraph,支持人工审批、状态恢复、图式编排。
- 知识库要轻量:Chroma + bge-small-zh,几行代码就能持久化。
- 数字要精准:行情、汇率、油价走 akshare,不用新闻摘要凑数。
- 联网要授权:所有外部请求必须经过
interrupt()人工确认。
更多推荐


所有评论(0)