企业官网建设流程全解析

这次我们来看一个完整的 LangChain 实战教程，从零基础入门到构建 RAG 应用、部署本地大模型，再到开发 Agent 智能体。这个教程的重点不是概念有多复杂，而是能不能在普通开发环境下快速跑通整个流程。

如果你关心本地部署、显存占用、批量任务和接口调用，这篇文章可以直接收藏。我们将覆盖 LangChain 的核心功能、RAG 知识库构建、Ollama 本地大模型部署，以及 Agent 智能体开发，每个环节都会给出可执行的代码示例和验证步骤。

本文适合有一定 Python 基础，希望快速上手大模型应用开发的读者。我们将使用主流开源工具，避免依赖云端 API，全部流程可在本地或内网环境完成。下面先快速看一下这个教程的核心能力速览。

1. 核心能力速览

这个教程的亮点在于全链路本地化：从文档加载、向量检索到模型推理，都不需要外网依赖。Ollama 负责本地大模型管理，LangChain 提供应用框架，RAG 增强知识检索，Agent 实现复杂任务规划。

2. 适用场景与使用边界

这个教程适合以下场景：

• 企业内部知识库问答系统开发
• 个人学习助手或资料检索工具
• 本地化大模型应用原型验证
• 需要数据隐私保护的对话系统

不适合的场景：

• 高并发生产环境（需额外优化）
• 多模态识别（需扩展图像、音频处理）
• 实时性要求极高的任务

使用边界方面，涉及用户文档处理时，必须确保数据授权和隐私合规。如果用于企业环境，建议在内网部署，避免敏感信息外泄。

3. 环境准备与前置条件

开始前，请确保你的开发环境满足以下条件：

操作系统

• Windows 10/11, macOS 10.15+, 或 Ubuntu 18.04+
• 推荐使用 Linux 或 macOS 以获得更好的兼容性

Python 环境

• Python 3.8-3.11（3.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 pip

4.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 chromadb

4.4 安装 Ollama

Ollama 是管理本地大模型的核心工具，安装方式因系统而异：

Linux/macOS

# 一键安装 curl -fsSL https://ollama.ai/install.sh | sh # 启动 Ollama 服务 ollama serve

Windows

• 从 Ollama 官网下载安装包
• 双击安装后，Ollama 会自动在后台运行

国内镜像加速（如下载慢）：

# 使用国内镜像源 export OLLAMA_HOST=0.0.0.0 export OLLAMA_MODELS=/path/to/your/models

4.5 下载大模型

Ollama 支持多种开源模型，推荐从中小模型开始测试：

# 下载 Llama3 8B 模型（约 4.7GB） ollama pull llama3:8b # 或下载更小的 Gemma 2B 模型（约 1.5GB） ollama pull gemma:2b # 查看已下载模型 ollama list

4.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", timeout=5) 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 知识库构建实战

RAG（Retrieval-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, encoding="utf-8") documents.extend(loader.load()) # 2. 分割文本 text_splitter = CharacterTextSplitter(chunk_size=200, chunk_overlap=50) texts = text_splitter.split_documents(documents) # 3. 创建嵌入模型（使用 Ollama 的本地嵌入） embeddings = OllamaEmbeddings(model="llama3:8b") # 4. 构建向量数据库 vectorstore = Chroma.from_documents( documents=texts, embedding=embeddings, 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(model="llama3:8b") vectorstore = Chroma(persist_directory="./chroma_db", embedding_function=embeddings) # 测试检索 query = "什么是 LangChain？" results = vectorstore.similarity_search(query, k=2) print("查询:", query) print("检索结果:") for i, doc in enumerate(results): print(f"{i+1}. {doc.page_content}")

运行后应该能看到相关的文档片段被检索出来。

5.2 Ollama 本地大模型调用

现在测试本地模型的对话能力：

# test_ollama.py from langchain_community.llms import OllamaLLM # 初始化本地模型 llm = OllamaLLM(model="llama3: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(model="llama3:8b") embeddings = OllamaEmbeddings(model="llama3:8b") vectorstore = Chroma(persist_directory="./chroma_db", embedding_function=embeddings) # 创建 RAG 链 qa_chain = RetrievalQA.from_chain_type( llm=llm, chain_type="stuff", retriever=vectorstore.as_retriever(), return_source_documents=True ) # 测试知识增强问答 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(model="llama3:8b", temperature=0) # 定义工具 def calculator(input_str): """简单的计算器工具""" try: return str(eval(input_str)) except: return "计算错误，请检查表达式" wikipedia = WikipediaAPIWrapper() tools = [ Tool( name="Calculator", func=calculator, description="用于数学计算，输入数学表达式如 '2 + 2'" ), Tool( name="Wikipedia", func=wikipedia.run, description="用于查询百科知识，输入要查询的主题" ) ] # 创建智能体 agent = initialize_agent( tools, llm, agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION, verbose=True ) # 测试智能体 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(title="LangChain 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(model="llama3:8b") embeddings = OllamaEmbeddings(model="llama3:8b") vectorstore = Chroma(persist_directory="./chroma_db", embedding_function=embeddings) qa_chain = RetrievalQA.from_chain_type( llm=llm, chain_type="stuff", retriever=vectorstore.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, host="0.0.0.0", port=8000)

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, json=data) print("单条问答结果:") print(json.dumps(response.json(), indent=2, ensure_ascii=False)) # 批量问答测试 def test_batch_query(): url = "http://localhost:8000/batch_query" data = { "questions": [ "LangChain 是什么？", "Ollama 有什么功能？", "如何构建 RAG 系统？" ], "use_rag": True } response = requests.post(url, json=data) print("\n批量问答结果:") print(json.dumps(response.json(), indent=2, ensure_ascii=False)) 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_workers=3): self.input_dir = input_dir self.output_dir = output_dir self.max_workers = max_workers os.makedirs(output_dir, exist_ok=True) def process_single_file(self, filename): """处理单个文件""" try: file_path = os.path.join(self.input_dir, filename) loader = TextLoader(file_path, encoding="utf-8") documents = loader.load() # 文本分割 text_splitter = CharacterTextSplitter(chunk_size=500, chunk_overlap=50) chunks = text_splitter.split_documents(documents) # 保存处理结果 output_file = os.path.join(self.output_dir, f"processed_{filename}") with open(output_file, 'w', encoding='utf-8') as f: for i, chunk in enumerate(chunks): f.write(f"Chunk {i+1}:\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_workers=self.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-smi

Python 内存监控

# resource_monitor.py import psutil import time def monitor_system(): """监控系统资源使用""" memory = psutil.virtual_memory() cpu_percent = psutil.cpu_percent(interval=1) print(f"内存使用: {memory.percent}%") print(f"CPU 使用: {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( model="llama3:8b", callbacks=[StreamingStdOutCallbackHandler()], num_thread=4, # 控制线程数 temperature=0.1 # 降低随机性，提高一致性 )

向量数据库优化

# 使用更高效的嵌入模型 from langchain_community.embeddings import HuggingFaceEmbeddings embeddings = HuggingFaceEmbeddings( model_name="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2" )

8. 常见问题与排查方法

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(model="llama3: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 查询逻辑 pass

9.3 数据合规与隐私保护

• 处理用户数据前获取明确授权
• 敏感信息脱敏处理
• 定期清理临时文件和日志
• 重要数据加密存储

10. 总结与下一步

这个 LangChain 实战教程覆盖了从基础环境搭建到复杂应用开发的全流程。最值得尝试的是 RAG 与本地大模型的结合，既能利用外部知识，又能保证数据隐私。

最先应该验证的是 Ollama 模型的基本对话能力，确保本地推理环境正常。然后逐步添加文档检索功能，最后开发具备工具调用能力的 Agent。

最容易踩的坑是版本兼容性和资源管理，建议严格按照文中版本搭配，并监控系统资源使用。

后续可以继续扩展的方向包括：

• 集成多模态模型处理图像和音频
• 开发 Web 界面提升用户体验
• 优化向量检索算法提高准确率
• 实现分布式部署支持高并发

建议将本文中的代码示例保存为独立文件，按顺序测试每个功能模块。遇到问题时，参考第 8 节的排查方法，多数常见问题都能找到解决方案。

这个技术栈的优势在于全链路可控，适合需要数据隐私或定制化需求的场景。随着应用的深入，你会发现 LangChain 生态还有更多强大的工具和模式等待探索。