这次我们来看一个完整的 LangChain 实战教程从零基础入门到构建 RAG 应用、部署本地大模型再到开发 Agent 智能体。这个教程的重点不是概念有多复杂而是能不能在普通开发环境下快速跑通整个流程。如果你关心本地部署、显存占用、批量任务和接口调用这篇文章可以直接收藏。我们将覆盖 LangChain 的核心功能、RAG 知识库构建、Ollama 本地大模型部署以及 Agent 智能体开发每个环节都会给出可执行的代码示例和验证步骤。本文适合有一定 Python 基础希望快速上手大模型应用开发的读者。我们将使用主流开源工具避免依赖云端 API全部流程可在本地或内网环境完成。下面先快速看一下这个教程的核心能力速览。1. 核心能力速览能力项说明技术栈LangChain RAG Ollama Agent主要功能文档问答、知识检索、本地模型推理、智能任务规划硬件需求CPU 可运行GPU 加速可选显存需求按模型大小调整部署方式本地命令行启动支持 Web 服务和 API 接口批量任务支持文档批量处理、多轮对话、任务队列适合场景企业知识库、本地问答系统、自动化助手开发这个教程的亮点在于全链路本地化从文档加载、向量检索到模型推理都不需要外网依赖。Ollama 负责本地大模型管理LangChain 提供应用框架RAG 增强知识检索Agent 实现复杂任务规划。2. 适用场景与使用边界这个教程适合以下场景企业内部知识库问答系统开发个人学习助手或资料检索工具本地化大模型应用原型验证需要数据隐私保护的对话系统不适合的场景高并发生产环境需额外优化多模态识别需扩展图像、音频处理实时性要求极高的任务使用边界方面涉及用户文档处理时必须确保数据授权和隐私合规。如果用于企业环境建议在内网部署避免敏感信息外泄。3. 环境准备与前置条件开始前请确保你的开发环境满足以下条件操作系统Windows 10/11, macOS 10.15, 或 Ubuntu 18.04推荐使用 Linux 或 macOS 以获得更好的兼容性Python 环境Python 3.8-3.113.12 需验证库兼容性建议使用 conda 或 venv 创建虚拟环境硬件要求内存至少 8GB推荐 16GB 以上存储至少 10GB 可用空间用于模型和文档GPU可选如有 NVIDIA GPU 可加速推理网络要求能访问 PyPI 和 GitHub用于安装依赖如需下载大模型确保网络稳定下面是一个快速环境检查脚本可以验证基础条件# 检查 Python 版本 python --version # 检查 pip 是否可用 pip --version # 检查 GPU 驱动如有 NVIDIA 显卡 nvidia-smi如果缺少某些组件先安装或升级后再继续。4. 安装部署与启动方式我们将分步骤安装所需的四个核心组件LangChain、向量数据库、Ollama 和 Agent 相关库。4.1 创建虚拟环境# 创建并激活虚拟环境 python -m venv langchain_env source langchain_env/bin/activate # Linux/macOS # 或 langchain_env\Scripts\activate # Windows # 升级 pip pip install --upgrade pip4.2 安装 LangChain 及相关库# 安装 LangChain 核心库 pip install langchain # 安装社区扩展工具、加载器等 pip install langchain-community # 安装文本拆分和向量化工具 pip install langchain-text-splitters # 安装 OpenAI 兼容接口用于本地模型调用 pip install openai版本兼容性提示如果使用 LangChain 1.3.11建议搭配 langchain-community 0.3.5避免接口冲突。4.3 安装向量数据库本地开发推荐使用 ChromaDB轻量且无需外部服务pip install chromadb4.4 安装 OllamaOllama 是管理本地大模型的核心工具安装方式因系统而异Linux/macOS# 一键安装 curl -fsSL https://ollama.ai/install.sh | sh # 启动 Ollama 服务 ollama serveWindows从 Ollama 官网下载安装包双击安装后Ollama 会自动在后台运行国内镜像加速如下载慢# 使用国内镜像源 export OLLAMA_HOST0.0.0.0 export OLLAMA_MODELS/path/to/your/models4.5 下载大模型Ollama 支持多种开源模型推荐从中小模型开始测试# 下载 Llama3 8B 模型约 4.7GB ollama pull llama3:8b # 或下载更小的 Gemma 2B 模型约 1.5GB ollama pull gemma:2b # 查看已下载模型 ollama list4.6 验证安装创建一个简单的测试脚本验证环境# test_env.py import langchain import chromadb import requests print(LangChain version:, langchain.__version__) # 测试 Ollama 服务是否正常 try: response requests.get(http://localhost:11434/api/tags, timeout5) print(Ollama service:, OK if response.status_code 200 else Failed) except: print(Ollama service: Not running) print(Environment check completed.)运行python test_env.py确认所有组件正常。5. 功能测试与效果验证现在开始实际的功能测试我们将按照 RAG 构建 → 本地模型调用 → Agent 开发的顺序进行。5.1 RAG 知识库构建实战RAGRetrieval-Augmented Generation的核心是将外部知识库与生成模型结合。下面构建一个简单的文档问答系统。步骤1准备文档创建示例文档目录和测试文件mkdir -p documents echo LangChain 是一个用于开发大语言模型应用的框架。 documents/doc1.txt echo Ollama 可以方便地在本地运行大语言模型。 documents/doc2.txt echo RAG 技术通过检索外部知识增强模型回答的准确性。 documents/doc3.txt步骤2构建向量数据库# build_rag.py from langchain_community.document_loaders import TextLoader from langchain_text_splitters import CharacterTextSplitter from langchain_community.vectorstores import Chroma from langchain_community.embeddings import OllamaEmbeddings # 1. 加载文档 documents [] for file_path in [documents/doc1.txt, documents/doc2.txt, documents/doc3.txt]: loader TextLoader(file_path, encodingutf-8) documents.extend(loader.load()) # 2. 分割文本 text_splitter CharacterTextSplitter(chunk_size200, chunk_overlap50) texts text_splitter.split_documents(documents) # 3. 创建嵌入模型使用 Ollama 的本地嵌入 embeddings OllamaEmbeddings(modelllama3:8b) # 4. 构建向量数据库 vectorstore Chroma.from_documents( documentstexts, embeddingembeddings, persist_directory./chroma_db ) print(向量数据库构建完成共处理, len(texts), 个文本块)步骤3测试检索功能# test_retrieval.py from langchain_community.vectorstores import Chroma from langchain_community.embeddings import OllamaEmbeddings # 加载已有的向量数据库 embeddings OllamaEmbeddings(modelllama3:8b) vectorstore Chroma(persist_directory./chroma_db, embedding_functionembeddings) # 测试检索 query 什么是 LangChain results vectorstore.similarity_search(query, k2) print(查询:, query) print(检索结果:) for i, doc in enumerate(results): print(f{i1}. {doc.page_content})运行后应该能看到相关的文档片段被检索出来。5.2 Ollama 本地大模型调用现在测试本地模型的对话能力# test_ollama.py from langchain_community.llms import OllamaLLM # 初始化本地模型 llm OllamaLLM(modelllama3:8b) # 简单对话测试 response llm.invoke(请用中文简单介绍你自己) print(模型回复:, response) # 带上下文的多轮对话 messages [ {role: user, content: 什么是人工智能}, {role: assistant, content: 人工智能是模拟人类智能的技术。}, {role: user, content: 它有哪些应用领域} ] context_response llm.invoke(\n.join([f{msg[role]}: {msg[content]} for msg in messages])) print(多轮对话回复:, context_response)5.3 RAG 与模型集成将检索器和生成模型结合实现知识增强的问答# rag_qa.py from langchain.chains import RetrievalQA from langchain_community.llms import OllamaLLM from langchain_community.vectorstores import Chroma from langchain_community.embeddings import OllamaEmbeddings # 加载组件 llm OllamaLLM(modelllama3:8b) embeddings OllamaEmbeddings(modelllama3:8b) vectorstore Chroma(persist_directory./chroma_db, embedding_functionembeddings) # 创建 RAG 链 qa_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, retrievervectorstore.as_retriever(), return_source_documentsTrue ) # 测试知识增强问答 question Ollama 有什么功能 result qa_chain.invoke({query: question}) print(问题:, question) print(回答:, result[result]) print(参考文档:) for doc in result[source_documents]: print(-, doc.page_content[:100] ...)5.4 Agent 智能体开发Agent 能够使用工具完成复杂任务。下面创建一个能调用计算器和网络搜索的智能体# simple_agent.py from langchain.agents import AgentType, initialize_agent, Tool from langchain_community.llms import OllamaLLM from langchain.utilities import WikipediaAPIWrapper # 初始化模型 llm OllamaLLM(modelllama3:8b, temperature0) # 定义工具 def calculator(input_str): 简单的计算器工具 try: return str(eval(input_str)) except: return 计算错误请检查表达式 wikipedia WikipediaAPIWrapper() tools [ Tool( nameCalculator, funccalculator, description用于数学计算输入数学表达式如 2 2 ), Tool( nameWikipedia, funcwikipedia.run, description用于查询百科知识输入要查询的主题 ) ] # 创建智能体 agent initialize_agent( tools, llm, agentAgentType.ZERO_SHOT_REACT_DESCRIPTION, verboseTrue ) # 测试智能体 result agent.run(计算 15 的平方然后查询人工智能的发展历史) print(智能体执行结果:, result)6. 接口 API 与批量任务将上述功能封装成 API 服务方便其他系统调用。6.1 创建 FastAPI 服务# api_server.py from fastapi import FastAPI from pydantic import BaseModel from langchain_community.llms import OllamaLLM from langchain_community.vectorstores import Chroma from langchain_community.embeddings import OllamaEmbeddings from langchain.chains import RetrievalQA app FastAPI(titleLangChain API Server) # 全局变量实际生产环境需要更好的初始化方式 llm None qa_chain None class QueryRequest(BaseModel): question: str use_rag: bool True class BatchRequest(BaseModel): questions: list[str] use_rag: bool True app.on_event(startup) async def startup_event(): 服务启动时初始化模型和向量库 global llm, qa_chain llm OllamaLLM(modelllama3:8b) embeddings OllamaEmbeddings(modelllama3:8b) vectorstore Chroma(persist_directory./chroma_db, embedding_functionembeddings) qa_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, retrievervectorstore.as_retriever() ) app.post(/query) async def query_ai(request: QueryRequest): 单条问答接口 if request.use_rag and qa_chain: result qa_chain.invoke({query: request.question}) return {answer: result[result], type: rag} else: result llm.invoke(request.question) return {answer: result, type: direct} app.post(/batch_query) async def batch_query(request: BatchRequest): 批量问答接口 results [] for question in request.questions: if request.use_rag and qa_chain: result qa_chain.invoke({query: question}) results.append({question: question, answer: result[result]}) else: result llm.invoke(question) results.append({question: question, answer: result}) return {batch_results: results} if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)6.2 启动 API 服务# 安装 FastAPI 依赖 pip install fastapi uvicorn # 启动服务 python api_server.py服务启动后可以通过 http://localhost:8000/docs 查看 API 文档。6.3 测试 API 调用# test_api.py import requests import json # 单条问答测试 def test_single_query(): url http://localhost:8000/query data {question: 什么是 RAG 技术, use_rag: True} response requests.post(url, jsondata) print(单条问答结果:) print(json.dumps(response.json(), indent2, ensure_asciiFalse)) # 批量问答测试 def test_batch_query(): url http://localhost:8000/batch_query data { questions: [ LangChain 是什么, Ollama 有什么功能, 如何构建 RAG 系统 ], use_rag: True } response requests.post(url, jsondata) print(\n批量问答结果:) print(json.dumps(response.json(), indent2, ensure_asciiFalse)) if __name__ __main__: test_single_query() test_batch_query()6.4 批量任务处理对于大量文档处理可以使用批量任务队列# batch_processor.py import os import time from concurrent.futures import ThreadPoolExecutor from langchain_community.document_loaders import TextLoader from langchain_text_splitters import CharacterTextSplitter class DocumentProcessor: def __init__(self, input_dir, output_dir, max_workers3): self.input_dir input_dir self.output_dir output_dir self.max_workers max_workers os.makedirs(output_dir, exist_okTrue) def process_single_file(self, filename): 处理单个文件 try: file_path os.path.join(self.input_dir, filename) loader TextLoader(file_path, encodingutf-8) documents loader.load() # 文本分割 text_splitter CharacterTextSplitter(chunk_size500, chunk_overlap50) chunks text_splitter.split_documents(documents) # 保存处理结果 output_file os.path.join(self.output_dir, fprocessed_{filename}) with open(output_file, w, encodingutf-8) as f: for i, chunk in enumerate(chunks): f.write(fChunk {i1}:\n{chunk.page_content}\n\n) return f成功处理 {filename}生成 {len(chunks)} 个片段 except Exception as e: return f处理 {filename} 失败: {str(e)} def process_batch(self): 批量处理所有文件 files [f for f in os.listdir(self.input_dir) if f.endswith(.txt)] print(f发现 {len(files)} 个待处理文件) with ThreadPoolExecutor(max_workersself.max_workers) as executor: results list(executor.map(self.process_single_file, files)) # 输出处理结果 for result in results: print(result) # 使用示例 if __name__ __main__: processor DocumentProcessor(documents, processed_docs) processor.process_batch()7. 资源占用与性能观察本地部署大模型应用时资源管理很重要。下面介绍如何监控和优化性能。7.1 监控资源占用查看 Ollama 资源使用# 查看 Ollama 进程资源占用 ps aux | grep ollama # 查看 GPU 使用情况如有 NVIDIA 显卡 nvidia-smiPython 内存监控# resource_monitor.py import psutil import time def monitor_system(): 监控系统资源使用 memory psutil.virtual_memory() cpu_percent psutil.cpu_percent(interval1) print(f内存使用: {memory.percent}%) print(fCPU 使用: {cpu_percent}%) # 查看 Python 进程内存 process psutil.Process() memory_info process.memory_info() print(f进程内存: {memory_info.rss / 1024 / 1024:.2f} MB) # 在任务执行前后调用监控 monitor_system() # 执行你的 LangChain 任务 monitor_system()7.2 性能优化建议模型选择优化开发测试阶段使用小模型如 Gemma 2B生产环境根据需求选择模型大小使用量化模型减少显存占用批量处理优化# 优化批量处理控制并发数 from langchain.callbacks import StreamingStdOutCallbackHandler llm OllamaLLM( modelllama3:8b, callbacks[StreamingStdOutCallbackHandler()], num_thread4, # 控制线程数 temperature0.1 # 降低随机性提高一致性 )向量数据库优化# 使用更高效的嵌入模型 from langchain_community.embeddings import HuggingFaceEmbeddings embeddings HuggingFaceEmbeddings( model_namesentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 )8. 常见问题与排查方法问题现象可能原因排查方式解决方案Ollama 服务启动失败端口被占用或权限问题检查 11434 端口是否被占用更换端口或终止冲突进程模型下载缓慢网络连接问题检查网络状态和下载速度使用国内镜像源或代理显存不足模型太大或并发任务过多检查 nvidia-smi 显存使用换用小模型或减少批量大小向量检索结果不准文本分割不合理或嵌入模型不适配检查文本分割参数和嵌入质量调整 chunk_size 或换用其他嵌入模型Agent 工具调用失败工具定义错误或模型不理解工具使用检查工具描述和模型回复优化工具描述增加示例API 服务无法访问防火墙或端口配置问题检查服务日志和网络连接配置防火墙规则或更换端口8.1 详细排查步骤Ollama 服务问题排查# 检查 Ollama 服务状态 systemctl status ollama # Linux # 或查看进程 ps aux | grep ollama # 检查端口占用 netstat -tulpn | grep 11434 lsof -i :11434 # 重启 Ollama 服务 ollama serve模型加载问题排查# 检查模型是否可用 from langchain_community.llms import OllamaLLM try: llm OllamaLLM(modelllama3:8b) response llm.invoke(test) print(模型加载成功) except Exception as e: print(f模型加载失败: {e})向量数据库问题排查# 检查向量数据库完整性 from langchain_community.vectorstores import Chroma try: vectorstore Chroma(persist_directory./chroma_db) print(向量数据库加载成功) print(文档数量:, vectorstore._collection.count()) except Exception as e: print(f向量数据库加载失败: {e})9. 最佳实践与使用建议基于实际项目经验总结以下最佳实践9.1 开发阶段建议项目结构规范my_langchain_project/ ├── docs/ # 文档目录 ├── src/ # 源代码 ├── models/ # 模型文件如需要 ├── data/ # 数据文件 │ ├── raw/ # 原始数据 │ ├── processed/ # 处理后的数据 │ └── vector_db/ # 向量数据库 ├── tests/ # 测试代码 └── requirements.txt配置管理# config.py import os from dataclasses import dataclass dataclass class Config: model_name: str llama3:8b chunk_size: int 500 chunk_overlap: int 50 temperature: float 0.1 vector_db_path: str ./vector_db property def ollama_base_url(self): return os.getenv(OLLAMA_BASE_URL, http://localhost:11434) config Config()9.2 生产环境部署建议安全配置API 服务添加认证中间件限制访问 IP 范围使用 HTTPS 加密传输定期更新依赖库性能监控# 添加性能监控 import time from functools import wraps def timing_decorator(func): wraps(func) def wrapper(*args, **kwargs): start_time time.time() result func(*args, **kwargs) end_time time.time() print(f{func.__name__} 执行时间: {end_time - start_time:.2f}秒) return result return wrapper # 使用装饰器监控关键函数 timing_decorator def rag_query(question): # 你的 RAG 查询逻辑 pass9.3 数据合规与隐私保护处理用户数据前获取明确授权敏感信息脱敏处理定期清理临时文件和日志重要数据加密存储10. 总结与下一步这个 LangChain 实战教程覆盖了从基础环境搭建到复杂应用开发的全流程。最值得尝试的是 RAG 与本地大模型的结合既能利用外部知识又能保证数据隐私。最先应该验证的是 Ollama 模型的基本对话能力确保本地推理环境正常。然后逐步添加文档检索功能最后开发具备工具调用能力的 Agent。最容易踩的坑是版本兼容性和资源管理建议严格按照文中版本搭配并监控系统资源使用。后续可以继续扩展的方向包括集成多模态模型处理图像和音频开发 Web 界面提升用户体验优化向量检索算法提高准确率实现分布式部署支持高并发建议将本文中的代码示例保存为独立文件按顺序测试每个功能模块。遇到问题时参考第 8 节的排查方法多数常见问题都能找到解决方案。这个技术栈的优势在于全链路可控适合需要数据隐私或定制化需求的场景。随着应用的深入你会发现 LangChain 生态还有更多强大的工具和模式等待探索。