文章目录
- 《RAG Agent本地实战》第2章 补充内容（理论+全量实战代码）
- 2.1 基础开发环境（本地必装）
- 理论知识
- 详细实战步骤+代码/命令
- 步骤1：Anaconda安装（Windows/macOS通用）
- 步骤2：创建虚拟环境（核心！）
- 步骤3：PyCharm配置Python解释器（替代VS Code，适配本地实战）
- 步骤4：pip镜像源永久配置（解决下载慢）
- 步骤5：核心依赖库批量安装（完整requirements.txt）
- 验证环境
- 2.2 本地大模型部署（CPU/GPU双适配）
- 理论知识
- 详细实战步骤+代码
- 步骤1：Ollama安装
- 步骤2：拉取并启动本地大模型（一键命令）
- 步骤3：本地API接口调试（验证模型服务）
- 步骤4：纯Python调用量化模型（无Ollama，CPU/GPU切换）
- 2.3 本地向量数据库搭建（轻量版）
- 理论知识
- 详细实战步骤+代码
- 场景：构建本地知识库，检索与“RAG流程”相关的文本
- 1. Chroma（最推荐，零配置）
- 2. FAISS（纯CPU，高速检索）
- 3. Milvus Lite（轻量版，可扩展）
- 2.4 本地Agent框架配置（简化版）
- 理论知识
- 详细实战步骤+代码
- 场景：构建本地RAG Agent，回答关于“RAG实战”的问题
- 1. LangChain Community（本地版）
- 2. LlamaIndex（RAG专用，更简洁）
- 2.5 本地数据处理工具准备
- 理论知识
- 详细实战步骤+代码
- 场景：解析本地PDF文档，分割为语义块，生成向量入库
- 扩展：Word文档解析+多格式支持
- 总结
- 核心关键点回顾
- 落地验证标准
《RAG Agent本地实战》第2章 补充内容（理论+全量实战代码）
以下内容既保留原章节的实战导向，又补充了关键理论和落地细节，新手可直接跟着操作。
2.1 基础开发环境（本地必装）
理论知识
- Python版本选择逻辑：AI生态的核心库（如
transformers、langchain、bitsandbytes）对Python 3.12的适配滞后（截至2026年，部分量化库仍未完全支持3.12）
- 而3.9-3.11是“兼容性+性能”的黄金区间，既支持最新的AI库特性，又避免依赖报错。
- Python版本选择逻辑：AI生态的核心库（如
- Anaconda核心价值：虚拟环境本质是“隔离的Python解释器+依赖库集合”，
解决本地多项目（如同时做RAG和大模型微调）的依赖冲突（比如A项目需要langchain 0.1，B项目需要langchain 0.3）。
- Anaconda核心价值：虚拟环境本质是“隔离的Python解释器+依赖库集合”，
- pip镜像源原理：PyPI官方源部署在海外，国内访问存在网络延迟/丢包，镜像源（如阿里云、清华源）是官方包的“国内缓存节点”，可将下载速度提升10-100倍。
详细实战步骤+代码/命令
步骤1：Anaconda安装（Windows/macOS通用）
下载：官网（https://www.anaconda.com/download）下载对应系统版本（Windows选exe，macOS选pkg），安装时勾选“Add Anaconda to PATH”（Windows）/默认安装（macOS）。
验证安装：终端/CMD输入以下命令，显示版本即成功：
conda--version
步骤2：创建虚拟环境（核心！）
# 创建名为rag_agent的环境，指定Python 3.10conda create-nrag_agentpython=3.10-y# 激活环境（Windows）conda activate rag_agent# 激活环境（macOS/Linux）sourceactivate rag_agent# 验证环境（显示Python路径为rag_agent环境下）whichpython# macOS/Linuxwhere python# Windows步骤3：PyCharm配置Python解释器（替代VS Code，适配本地实战）
PyCharm是功能更全面的IDE，对Python项目支持更友好，尤其适合复杂RAG Agent项目的代码管理、调试与运行，无需额外安装过多插件即可满足需求。
1. 安装PyCharm：官网（https://www.jetbrains.com/pycharm/download/）下载，新手可选免费社区版（Community），功能完全覆盖本地RAG实战；安装时默认勾选“创建桌面快捷方式”“关联.py文件”即可。
2. 配置虚拟环境：打开PyCharm后，依次点击「File」→「Settings」（Windows）/「PyCharm」→「Settings」（macOS）→「Project: 项目名称」→「Python Interpreter」；点击右上角齿轮图标→「Add」→选择「Conda Environment」→「Existing environment」；浏览找到Anaconda虚拟环境路径（通常为Anaconda安装目录/envs/rag_agent/python.exe），选中后点击「OK」完成配置，此时PyCharm会自动关联该环境的所有依赖库。
3. 代码运行与调试：PyCharm自带代码运行和调试功能，无需额外插件。创建.py文件后，右键点击代码区域选择「Run 文件名」即可运行；如需调试，可在代码行号左侧点击设置断点，再选择「Debug 文件名」，支持单步执行、变量监控等功能，适配RAG项目的代码排查需求。
4. 安装VS Code后，安装插件：Python（微软官方）、Code Runner（一键运行代码）；
5. 打开VS Code→ 左下角“Python 3.x.x” → 选择“rag_agent”环境的Python解释器（路径通常为Anaconda安装目录/envs/rag_agent/bin/python）；
步骤4：pip镜像源永久配置（解决下载慢）
Windows：在
C:\Users\你的用户名\下新建pip文件夹，创建pip.ini文件，写入：index-url=https://mirrors.aliyun.com/pypi/simple/ trusted-host=mirrors.aliyun.comtimeout=6000macOS/Linux：在
~目录下创建.pip文件夹，创建pip.conf文件，写入上述内容；
步骤5：核心依赖库批量安装（完整requirements.txt）
创建requirements.txt文件，内容如下（覆盖后续所有章节基础依赖）：
# 基础依赖python-dotenv>=1.0.0numpy>=1.24.0pandas>=2.0.0# 大模型相关transformers>=4.35.0torch>=2.1.0bitsandbytes>=0.41.0accelerate>=0.24.0# 向量数据库chromadb>=0.4.19faiss-cpu>=1.7.4pymilvus>=2.4.0# Agent框架langchain-community>=0.0.28llama-index>=0.9.0# 数据处理PyMuPDF>=1.23.0python-docx>=1.1.0jieba>=0.42.1unstructured[local-inference]>=0.10.30# 嵌入模型sentence-transformers>=2.2.2# 调试工具requests>=2.31.0postman-code-generators>=1.0.0执行安装命令：
pipinstall-rrequirements.txt验证环境
创建test_env.py，在PyCharm中右键点击文件选择「Run test_env」，运行无报错即环境正常：
importtorchimportlangchainimportchromadbimportfitz# PyMuPDFimportsysdeftest_pytorch_import():"""测试PyTorch是否成功导入"""asserttorch.__version__isnotNonedeftest_pytorch_version():"""测试PyTorch版本信息"""version=torch.__version__print(f"PyTorch版本：{version}")assertisinstance(version,str)deftest_other_packages():"""测试其他包是否成功导入"""asserthasattr(langchain,'__version__')assertchromadbisnotNoneassertfitzisnotNoneif__name__=="__main__":print("PyTorch版本：",torch.__version__)print("Python解释器版本：",sys.version)print("环境配置成功！")2.2 本地大模型部署（CPU/GPU双适配）
理论知识
- 模型量化（INT4/INT8）原理：原始大模型权重是FP16/FP32精度（占用显存高），量化是将权重压缩为4/8位整数，显存占用降低4-8倍（如Qwen-1.8B FP16需4G显存，INT4仅需1G），牺牲1-5%的精度换本地可部署性，完全满足RAG场景的问答需求。
- Ollama核心优势：封装了模型下载、量化、CUDA/CPU适配、API服务，无需手动配置
transformers的AutoModel/AutoTokenizer，一行命令即可启动模型并提供REST API，是本地部署的“懒人神器”。
- Ollama核心优势：封装了模型下载、量化、CUDA/CPU适配、API服务，无需手动配置
- 模型选型核心原则：
优先选中文优化模型（Qwen-1.8B/ChatGLM3-6B），避免Llama3的中文适配问题；
显存<8G选1.8B量级模型，显存8-16G选6B/8B量级模型；
无GPU（纯CPU）需保证内存≥16G，否则模型加载失败。
详细实战步骤+代码
步骤1：Ollama安装
Windows/macOS：官网（https://ollama.com/download）下载安装包，一键安装；
验证安装：终端输入
ollama -v，显示版本即成功。
步骤2：拉取并启动本地大模型（一键命令）
| 模型名称 | 拉取+启动命令 | 硬件要求 |
|---|---|---|
| Qwen-1.8B-Chat（推荐） | ollama run qwen:1.8b-chat | CPU：16G内存；GPU：2G显存 |
| ChatGLM3-6B | ollama run chatglm3:6b | CPU：32G内存；GPU：8G显存 |
| Llama 3-8B-Instruct（需授权） | ollama run llama3:8b-instruct | CPU：32G内存；GPU：8G显存 |
| 运行效果：终端显示“>>>”即模型启动成功，可直接输入问题测试（如“介绍RAG技术”）。 |
步骤3：本地API接口调试（验证模型服务）
Ollama默认提供http://localhost:11434的API服务，用Python验证：
importrequestsimportjson# 调用Ollama的Qwen-1.8B模型defcall_ollama_model(prompt):url="http://localhost:11434/api/generate"headers={"Content-Type":"application/json"}data={"model":"qwen:1.8b-chat",# 对应启动的模型名称"prompt":prompt,"stream":False,# 关闭流式输出，方便测试"temperature":0.7# 生成随机性}response=requests.post(url,headers=headers,json=data)ifresponse.status_code==200:returnresponse.json()["response"]else:returnf"调用失败：{response.status_code}"# 测试if__name__=="__main__":result=call_ollama_model("什么是RAG？用简单的话解释")print("模型回答：\n",result)步骤4：纯Python调用量化模型（无Ollama，CPU/GPU切换）
若不想用Ollama，直接用transformers调用量化模型（以Qwen-1.8B为例）：
fromtransformersimportAutoModelForCausalLM,AutoTokenizerimporttorch# 加载模型和Tokenizermodel_name="Qwen/Qwen-1.8B-Chat"tokenizer=AutoTokenizer.from_pretrained(model_name,trust_remote_code=True)# 配置量化（CPU/GPU适配）device="cuda"iftorch.</
