LangChain与RAG实战：本地部署大模型应用开发指南

1. 先搞清楚这套组合到底解决什么问题

如果你正在接触大模型应用开发，大概率会听到 LangChain、RAG、Ollama、Agent 这几个词混在一起出现。这套组合最核心的价值是让开发者能在普通机器上，用相对可控的成本搭建具备专业知识问答、逻辑推理和任务执行能力的 AI 应用。

LangChain 负责把大模型、工具、数据源和任务流程串联起来；RAG（检索增强生成）解决的是让大模型能基于你的私有资料回答问题，而不是仅靠预训练知识；Ollama 让你不用依赖云端 API，在本地就能部署运行开源大模型；Agent 则是让模型不仅能回答问题，还能按步骤执行复杂任务。

我一般会建议先明确你的需求场景：是需要给团队建一个内部知识库，还是想做一个能自动处理工单的助手，或是需要模型能调用外部工具完成数据分析。不同的场景下，这套技术栈的配置重点和复杂度差异很大。

2. 环境准备：别一上来就装最新版

LangChain 的版本兼容性是需要优先关注的点。特别是社区插件（langchain-community）和主框架的版本匹配问题，如果装错，经常会出现导入失败或功能不可用。

对于刚入门的项目，我更建议先锁定一个稳定版本组合。例如 LangChain 0.1.x 系列配 langchain-community 0.0.x，避免直接追新。实际部署时，先用虚拟环境隔离测试：

python -m venv langchain-env source langchain-env/bin/activate # Windows 用 langchain-env\Scripts\activate pip install langchain==0.1.10 langchain-community==0.0.20

Ollama 的安装要注意网络问题。官方服务器在国外，国内直连下载模型容易中断或极慢。解决方式不是找那些来路不明的加速工具，而是用国内镜像源或手动导入模型文件。

以 Hermes 模型为例，可以先从托管平台下载模型文件（.bin 或 .gguf 格式），然后通过 Ollama 的本地创建功能加载：

# 创建模型配置文件 Modelfile FROM ./hermes-model.gguf PARAMETER temperature 0.7 PARAMETER num_ctx 4096 # 本地创建模型 ollama create my-hermes -f Modelfile

低配置电脑部署时要重点关注显存和内存。如果显卡显存小于 8GB，就选参数量 7B 以下的模型；纯 CPU 运行需要 16GB 以上内存，并且处理速度会慢很多。第一次测试时，先用小参数模型确认基础功能，再考虑升级。

3. RAG 知识库构建：从单文件到批量处理

RAG 的核心思路是先把你的文档转换成可检索的片段，再让模型根据检索到的内容生成答案。这个过程中最容易出问题的是文档加载、文本分割和向量化这三个环节。

3.1 文档加载的格式兼容性

不同格式的文档需要不同的加载器。PDF 文档要注意扫描版和文字版的区别，扫描版需要先做 OCR 识别；Word 文档要注意旧版 .doc 和新版 .docx 的兼容性；网页内容要注意编码和 HTML 结构解析。

我一般会先用 LangChain 的自动检测功能试加载，但更稳妥的做法是明确指定加载器：

from langchain_community.document_loaders import PyPDFLoader, UnstructuredWordDocumentLoader # PDF 加载 loader = PyPDFLoader("manual.pdf") documents = loader.load() # Word 加载 loader = UnstructuredWordDocumentLoader("report.docx") documents = loader.load()

加载后一定要检查文档内容是否完整，特别是表格、代码块和特殊符号是否被正确解析。

3.2 文本分割的参数设置

分割长度直接影响检索效果。太短会丢失上下文，太长会引入噪声。一般根据模型上下文长度和文档特点调整：

• 技术文档：chunk_size=512-800，重叠 100-150 字符保留技术术语连续性
• 普通文章：chunk_size=800-1000，重叠 80-120 字符
• 对话记录：按对话轮次分割，保留完整问答对

from langchain.text_splitter import RecursiveCharacterTextSplitter splitter = RecursiveCharacterTextSplitter( chunk_size=800, chunk_overlap=100, length_function=len, separators=["\n\n", "\n", "。", "！", "？", "；", "，", " "] ) chunks = splitter.split_documents(documents)

分割后要抽样检查边界处理是否合理，避免一个完整句子被切到两个片段中。

3.3 向量数据库选型和配置

本地测试阶段可以用 Chroma 这种轻量级向量库，生产环境再考虑 Weaviate 或 Qdrant。关键是要确保嵌入模型（embedding model）与检索需求的匹配度。

中文文档优先选多语言嵌入模型，比如 bge-large-zh 或 m3e-large。如果只用 OpenAI 的 text-embedding-ada-002，对中文的语义捕捉可能不够精准。

from langchain_community.embeddings import HuggingFaceEmbeddings from langchain_community.vectorstores import Chroma embeddings = HuggingFaceEmbeddings(model_name="BAAI/bge-large-zh") vectorstore = Chroma.from_documents(chunks, embeddings, persist_directory="./chroma_db")

向量库创建后，要用一些典型问题测试检索效果，确认返回的文档片段确实相关。

4. Ollama 本地模型部署：参数调优比模型选择更重要

很多人纠结要选哪个模型，但实际测试中发现，同一个模型在不同参数下的表现差异可能比不同模型之间的差异还大。

4.1 模型选择的实用建议

• 通用对话：Llama 3 8B、Qwen 7B、Hermes 7B
• 代码生成：CodeLlama 7B、DeepSeek-Coder 7B
• 中文优化：Qwen 7B、ChatGLM3 6B、Baichuan2 7B

低配置环境优先考虑 7B 参数模型，CPU 模式也能勉强运行。有 GPU 但显存不足时，可以用量化版本（q4、q5）。

4.2 关键参数的实际影响

温度（temperature）控制创造性，但同时也影响稳定性。任务型应用设 0.1-0.3，创意写作设 0.7-0.9。上下文长度（num_ctx）要根据实际需求设置，不是越大越好，长上下文会显著增加内存占用。

最大生成长度（num_predict）要合理限制，避免生成无关内容。一般对话设 512-1024，长文生成设 2048 以上。

from langchain_community.llms import OllamaLLM llm = OllamaLLM( model="qwen:7b", temperature=0.3, num_predict=512, num_ctx=2048 )

4.3 性能监控和优化

本地运行时要实时监控资源占用。GPU 模式看显存使用率，CPU 模式看内存和 CPU 占用。如果发现资源占用持续增长，可能是内存泄漏或上下文累积问题。

长时间运行任务时，要设置合理的超时和重试机制，避免单个请求卡死整个应用。

5. Agent 开发：从简单工具调用到复杂任务规划

Agent 的核心是让模型能够按需使用工具完成任务。开发时要区分单工具调用和多步骤规划两种场景。

5.1 工具封装的关键点

每个工具都要有清晰的描述，说明它能做什么、输入输出格式是什么。工具函数内部要有充分的错误处理，避免因为工具异常导致整个 Agent 崩溃。

from langchain.agents import tool @tool def search_technical_docs(query: str) -> str: """在技术文档中搜索相关信息，输入搜索关键词，返回相关文档片段""" try: # 实现搜索逻辑 results = vectorstore.similarity_search(query, k=3) return "\n\n".join([doc.page_content for doc in results]) except Exception as e: return f"搜索失败：{str(e)}"

5.2 Agent 类型选择

• ReAct Agent：适合需要推理的多步骤任务，能解释每一步的思考过程
• OpenAI Functions Agent：工具调用标准化，适合结构化任务
• Self-ask with Search：专门优化搜索类任务

初学者建议从 ReAct Agent 开始，它的思考过程更透明，便于调试。

5.3 任务规划和控制

复杂任务要拆分成子任务，并设置检查点。避免让 Agent 一次性处理过于复杂的请求。重要任务要加入人工确认环节，特别是涉及数据修改或外部操作时。

我一般会设置最大步数限制，防止 Agent 陷入无限循环。同时记录完整的执行轨迹，便于问题排查和效果分析。

6. 完整项目集成：从 Demo 到可用的系统

单个组件测试通过后，需要把它们集成为一个完整的系统。这个阶段最容易出现接口不一致、数据流转错误和性能瓶颈。

6.1 架构设计考虑

小型项目可以用单进程架构，所有组件在同一环境中运行。中型项目建议将向量数据库、模型服务、应用逻辑分离，通过 API 通信。

关键是要设计清晰的数据流：用户输入 → 意图识别 → 检索增强 → 模型生成 → 结果后处理 → 输出展示。每个环节都要有日志记录和错误处理。

6.2 性能优化策略

RAG 系统的瓶颈通常在检索阶段。可以采取的优化措施包括：

• 向量索引优化：使用 HNSW 等高效索引算法
• 多路检索：结合关键词检索和向量检索
• 结果缓存：对常见问题缓存答案，减少模型调用
• 异步处理：批量请求并行处理

6.3 测试和验证

不要只测试理想情况，要专门设计边界案例：

• 知识库外的问题：模型应该诚实回答"不知道"
• 模糊查询：测试检索系统的容错能力
• 长文本处理：检查上下文长度限制下的表现
• 并发请求：验证系统稳定性

建立一套评估指标，包括回答准确率、响应时间、资源占用等，便于后续优化。

7. 常见问题排查指南

实际部署中遇到的问题往往不是功能问题，而是环境、配置和数据问题。

7.1 启动失败排查顺序

1. 检查 Python 环境和包版本是否兼容
2. 确认 Ollama 服务是否正常运行：ollama list
3. 验证向量数据库路径和权限
4. 检查模型文件是否完整下载
5. 查看详细错误日志定位具体问题

7.2 性能问题排查

如果响应慢，按这个顺序检查：

1. 模型加载时间：首次加载需要时间，后续请求应该快很多
2. 检索速度：向量检索耗时与数据库大小相关
3. 生成速度：与模型大小和生成长度正相关
4. 网络延迟：如果使用远程服务，网络可能是瓶颈

7.3 质量问题的调试

回答不准确或无关时：

1. 先检查检索结果：检索到的文档片段是否相关
2. 再检查提示词设计：是否清晰传达了任务要求
3. 最后调整模型参数：温度、top_p 等影响生成质量

记录完整的请求响应流水线，包括检索到的文档、发送给模型的提示词、模型的原始输出等，便于分析问题根源。

这套技术栈的真正价值不在于单个组件的强大，而在于它们组合后能够解决实际业务问题。建议先从一个小而具体的场景开始，把整个流程跑通，再逐步扩展功能复杂度。