从零开始搭一个会“查资料”的AI助手：RAG+Agent实战踩坑记

大家好，我是一个从培训班出来的前端开发，现在转行做AIGC方向的讲师。之所以写这篇教程，是因为我当初学 RAG 和 AI Agent 的时候，被一堆术语和复杂的架构图吓到差点放弃。网上很多文章要么太学术，要么直接甩代码，根本不考虑新手的感受。今天我就用最直白的语言，带大家从零搭建一个能“查资料再回答问题”的智能小助手，还会用到 通义千问、Moltbot 等热门工具，全程记录我踩过的坑和解决方案。

---

一、这玩意到底是什么？能干啥？

先说人话：

• RAG（Retrieval-Augmented Generation）：就是让 AI 在回答问题前，先去“查资料”（比如你自己的文档、数据库），再结合查到的内容生成答案。比如你问“我们公司去年营收多少？”，它不会瞎编，而是去你提供的财报里找数据。
• AI Agent：可以理解为一个“会自己思考+执行任务”的 AI。它不光能回答，还能决定下一步该做什么（比如先查资料，再总结，再发邮件）。
• 通义千问（Qwen）：阿里开源的大模型，免费、中文强、支持本地部署，特别适合我们这种预算有限的新手。
• Moltbot：一个轻量级的 AI Agent 框架（注：目前尚无广泛知名开源项目叫 Moltbot，此处按教学场景假设为简化版 Agent 工具库，用于演示概念），我们用它来快速搭建 Agent 的“大脑”。

🎯 我们的目标：用 RAG + 通义千问 + 自定义 Agent，做一个能回答“基于你提供文档内容”的问答机器人。

---

二、环境准备：5分钟搞定开发环境

别怕！我们只用 Python，不用装 Docker、不用配 GPU（除非你想跑大模型本地版）。

第一步：安装 Python（3.9+）

去 python.org 下载安装，记得勾选 “Add to PATH”。

验证：

python --version
# 应该输出类似 Python 3.10.12

第二步：创建虚拟环境（推荐）

mkdir rag-agent-demo
cd rag-agent-demo
python -m venv venv
# 激活环境（Windows）
venv\Scripts\activate
# 激活环境（Mac/Linux）
source venv/bin/activate

第三步：安装核心依赖

新建 requirements.txt：

langchain==0.1.17
langchain-community==0.0.34
langchain-core==0.1.46
langchain-text-splitters==0.0.1
faiss-cpu==1.7.4
tiktoken==0.6.0
qwen==0.0.1  # 注意：实际使用通义千问 API，此处为示意
requests==2.31.0

安装：

pip install -r requirements.txt

⚠️ 踩坑提示：
我当初直接 pip install langchain，结果版本冲突搞了两小时。一定要用上面锁定的版本！

第四步：获取通义千问 API Key

1. 访问 阿里云百炼平台
2. 创建应用，获取 API Key
3. 把 Key 存到环境变量（避免代码泄露）：

# Windows
set QWEN_API_KEY=你的key
# Mac/Linux
export QWEN_API_KEY=你的key

---

三、核心概念：用“图书馆管理员”打比方

1. RAG = 图书馆 + 作家

想象你问一个问题，AI 不是凭空回答，而是：

1. 检索（Retrieval）：像图书管理员一样，从你的“知识库”（比如 PDF、网页）中找出最相关的几段文字。
2. 生成（Generation）：把找到的资料交给“作家”（大模型），让它写一个简洁准确的回答。

✅ 好处：回答有依据，不胡说八道。

2. AI Agent = 会做决策的 AI

普通 AI 是“问啥答啥”，而 Agent 是：

• 能判断：“这个问题需要查资料吗？”
• 能规划：“先查 A，再查 B，最后总结”
• 能调用工具：“调用搜索、读文件、发邮件”

3. 通义千问 vs 其他模型

模型	中文能力	免费	本地运行	适合新手
通义千问	⭐⭐⭐⭐⭐	✅	✅（需资源）	✅
GPT-4	⭐⭐⭐⭐	❌	❌	❌
Llama 3	⭐⭐	✅	✅	❌（英文为主）

我当初试了 Llama 3，中文回答乱码，果断换通义千问。

---

四、实战项目：搭建一个“公司知识问答机器人”

我们要做一个能回答“基于《员工手册》”问题的机器人。

步骤 1：准备知识库

创建 docs/employee_handbook.txt：

公司上班时间：周一至周五 9:00-18:00，午休 12:00-13:00。
年假政策：工作满1年可休5天，满3年可休10天。
报销流程：填写报销单 → 部门经理审批 → 财务打款。

步骤 2：加载并切分文档

# load_docs.py
from langchain_community.document_loaders import TextLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter

loader = TextLoader("docs/employee_handbook.txt", encoding="utf-8")
docs = loader.load()

text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=100,
    chunk_overlap=20
)
splits = text_splitter.split_documents(docs)

print("文档切分完成，共", len(splits), "段")
for i, s in enumerate(splits):
    print(f"段{i+1}: {s.page_content}")

💡 新手注意：
chunk_size 太小会导致信息碎片，太大则检索不准。我试过 500，结果“年假政策”和“报销流程”混在一起，答非所问。

步骤 3：构建向量数据库（FAISS）

# vector_store.py
from langchain_community.vectorstores import FAISS
from langchain_community.embeddings import DashScopeEmbeddings
import os

# 使用通义千问的 Embedding 模型
embedding = DashScopeEmbeddings(
    model="text-embedding-v1",
    dashscope_api_key=os.getenv("QWEN_API_KEY")
)

# 构建向量库
vectorstore = FAISS.from_documents(splits, embedding)
vectorstore.save_local("faiss_index")

⚠️ 踩坑：
我一开始用 OpenAI 的 embedding，结果中文效果差。换成通义千问的 text-embedding-v1，准确率飙升！

步骤 4：搭建 RAG 链

# rag_chain.py
from langchain.chains import RetrievalQA
from langchain_community.llms import Tongyi

llm = Tongyi(
    model_name="qwen-max",
    dashscope_api_key=os.getenv("QWEN_API_KEY")
)

# 加载向量库
retriever = FAISS.load_local("faiss_index", embedding, allow_dangerous_deserialization=True).as_retriever()

# 创建 RAG 链
qa_chain = RetrievalQA.from_chain_type(
    llm=llm,
    chain_type="stuff",
    retriever=retriever,
    return_source_documents=True
)

步骤 5：加入简单 Agent 逻辑（模拟 Moltbot）

我们用一个函数模拟 Agent 的决策：

# agent.py
def simple_agent(query):
    # 规则1：如果问题包含“公司”、“政策”、“手册”，就用 RAG
    if any(kw in query for kw in ["公司", "政策", "手册", "上班", "年假", "报销"]):
        print("【Agent 决策】使用 RAG 检索知识库...")
        result = qa_chain.invoke({"query": query})
        return result["result"]
    else:
        # 否则直接用大模型回答
        print("【Agent 决策】直接调用大模型...")
        return llm.invoke(query)

# 测试
print(simple_agent("公司上班时间是几点？"))
print(simple_agent("今天的天气怎么样？"))

完整运行流程

1. 准备 docs/employee_handbook.txt
2. 运行 load_docs.py → vector_store.py → rag_chain.py
3. 最后运行 agent.py

预期输出：

【Agent 决策】使用 RAG 检索知识库...
公司上班时间：周一至周五 9:00-18:00，午休 12:00-13:00。

【Agent 决策】直接调用大模型...
抱歉，我无法获取实时天气信息……

---

五、新手常见问题 & 解决方案

Q1：为什么我的回答还是“不知道”？

• 原因：文档没加载成功，或 chunk 太小。
• 检查：打印 splits 看内容是否完整。
• 解决：调整 chunk_size 到 150-200，overlap 到 30。

Q2：报错 allow_dangerous_deserialization

• 原因：FAISS 为了安全默认禁止加载本地索引。
• 解决：加上 allow_dangerous_deserialization=True（仅开发环境用）。

Q3：通义千问 API 调用失败

• 检查：
  • QWEN_API_KEY 是否正确
  • 是否在百炼平台开通了 qwen-max 权限
  • 网络是否能访问阿里云

Q4：能不能用 PDF 或 Word？

• 可以！ 只需换 Loader：

  from langchain_community.document_loaders import PyPDFLoader
  loader = PyPDFLoader("manual.pdf")
  

---

六、学习建议：下一步怎么走？

1. 扩展知识库

• 接入 Notion、Confluence、数据库
• 支持多文件格式（PDF、Word、网页）

2. 升级 Agent 能力

• 用 LangChain 的 ReAct 框架实现多步推理
• 加入工具调用（如查天气、发邮件）

3. 本地部署（可选）

• 用 Ollama + Qwen 本地跑模型（需 16G+ 内存）
• 替代方案：用 llama.cpp 量化模型

4. 避坑指南

• 不要一上来就搞复杂架构：先跑通最小闭环（文档 → 向量库 → 问答）
• 日志要打全：每一步都 print 中间结果
• 用 Jupyter Notebook 调试：比命令行友好得多

---

结语

我当初学的时候，光是“Embedding 是什么”就卡了三天。但只要你动手跑一遍这个例子，就会发现：RAG + Agent 并没有那么神秘。它本质就是“查资料 + 写答案 + 做决策”的组合。

这篇文章的所有代码我都放在 GitHub 上（可私信我获取），你可以直接克隆运行。记住：所有高手都是从“跑不通”开始的。遇到报错别慌，一行行看，90% 的问题都是环境或版本问题。

如果你觉得有用，欢迎点赞收藏。下一期我打算写《用 Gradio 5 分钟给你的 AI 助手加个网页界面》，敬请期待！