从零自建本地模型 + 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 转文本再入库
源码编码报错UnicodeDecodeErrorautodetect_encoding=True

八、一句话选型原则

  • 模型本地跑:Ollama + Qwen2.5,数据不出本机、断网可用。
  • Agent 要可控:LangGraph,支持人工审批、状态恢复、图式编排。
  • 知识库要轻量:Chroma + bge-small-zh,几行代码就能持久化。
  • 数字要精准:行情、汇率、油价走 akshare,不用新闻摘要凑数。
  • 联网要授权:所有外部请求必须经过 interrupt() 人工确认。
Logo

有“AI”的1024 = 2048,欢迎大家加入2048 AI社区

更多推荐