LangChain 从入门到实战精通

# 基础链搭建代码示例
import os
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

os.environ["OPENAI_API_KEY"] = "你的API_KEY"

model = ChatOpenAI(model="gpt-4o-mini", temperature=0)
prompt = ChatPromptTemplate.from_template("请用一句话解释：{topic}")
chain = prompt | model

resp = chain.invoke({"topic": "什么是LangChain"})
print(resp.content)
# 效果说明：返回一个可读的解释文本

1.3 关键注意点

LangChain 不替代模型，它是模型应用编排层。
先学会 Prompt -> Model -> Output 三件套，再上 RAG/Agent。

二、为什么项目里会引入 LangChain

生活类比

不用 LangChain 直接调模型 API,就像自己手写一封信、贴邮票、跑邮局寄信——每次都要重复所有环节。而 LangChain 就像顺丰的标准化寄件流程:填单、取件、运输、签收都有固定接口,换个收件人(换模型)也只改地址,不用重学一遍流程。

2.1 核心价值

统一接口：多模型（OpenAI/Anthropic/本地模型）切换成本低
组件化：Prompt、Retriever、Tool、Memory 可插拔
可观测：支持 tracing、日志、错误恢复
工程化友好：适合 API 服务化与持续迭代

2.2 基础开发流程（完整）

环境搭建
安装依赖
配置 API Key / Base URL
初始化模型
组装 Prompt/Chain
联调与测试
增加检索、工具、记忆
服务化与监控

2.3 完整入门流程代码

python

# 基础开发流程代码示例
import os
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

# 1) 配置环境变量
os.environ["OPENAI_API_KEY"] = "你的API_KEY"

# 2) 初始化模型
llm = ChatOpenAI(
    model="gpt-4o-mini",
    temperature=0.2,   # 输出稳定性更高
    max_tokens=300,    # 控制最大输出长度
    timeout=30,        # 网络超时
)

# 3) Prompt 模板
prompt = ChatPromptTemplate.from_template(
    "你是资深工程师。请用3点解释 {topic}，每点不超过20字。"
)

# 4) 组装链
chain = prompt | llm | StrOutputParser()

# 5) 执行测试
result = chain.invoke({"topic": "LangChain的核心价值"})
print(result)
# 效果说明：输出格式稳定、可直接展示到前端

三、核心包与安装建议

核心概念

LangChain 采用分包设计:核心抽象在 langchain-core,模型厂商适配在 langchain-openai 等独立包,社区集成在 langchain-community。按需安装,避免臃肿。

生活类比

LangChain 的分包就像买手机套餐:langchain-core 是必选的主卡(基础通话),langchain-openai 是加装的流量包(接哪家模型就装哪个),langchain-community 是增值服务包(各种第三方集成)。你不会为了打电话就买下所有增值服务。

3.1 Python 版本与核心依赖

Python：建议 3.10+
核心包：
- langchain
- langchain-core
- langchain-openai
- langchain-community
RAG 常用：
- chromadb
- faiss-cpu
- pypdf

3.2 安装命令（pip + 镜像）

bash

# 标准安装
pip install -U langchain langchain-core langchain-openai langchain-community
pip install -U chromadb faiss-cpu pypdf fastapi uvicorn python-dotenv

# 国内镜像（避免下载失败）
pip install -U langchain langchain-openai -i https://pypi.tuna.tsinghua.edu.cn/simple

四、环境验证与避坑

核心概念

装完包别急着写业务,先用一段「导入 + 打印版本号」的代码确认环境可用。版本能打印出来,说明安装、路径、虚拟环境都没问题。

4.1 标准导入与验证

python

# 导入验证代码示例
import langchain
import langchain_core
import langchain_openai

print("langchain:", langchain.__version__)
print("langchain_core:", langchain_core.__version__)
print("langchain_openai:", langchain_openai.__version__)
# 效果说明：能输出版本号即环境可用

4.2 新手常见误区与避坑

依赖冲突：统一升级到最新版，必要时新建虚拟环境
API Key 未生效：确认 OPENAI_API_KEY 在当前进程可见
网络超时：设置 timeout，并加重试机制

五、模型、消息与 Prompt 模板

核心概念

这是 LangChain 的入门三件套:模型(ChatModel)负责生成,Prompt 模板负责组织提问,消息(Message)负责区分「谁在说话」。掌握它们就能写出第一个稳定的链。

生活类比

Prompt 模板就像填空式的请假条模板:「我因{原因},请假{天数}天」。你只要每次填入不同的原因和天数,格式永远规范统一——不用每次都从头手写一整段话,还能保证不漏字段。

5.1 核心概念速记

LLM / ChatModel：负责生成内容
PromptTemplate：参数化提示词
Message：system/human/ai 消息结构
Chain：把多个步骤串起来
Tool：可调用的函数能力

5.2 PromptTemplate 基础与动态模板

python

# PromptTemplate 基础代码示例
from langchain_core.prompts import PromptTemplate

tpl = PromptTemplate.from_template(
    "请将下面内容改写为更专业语气：\n{text}"
)
print(tpl.format(text="这个功能挺好用的。"))
# 效果说明：输出渲染后的 prompt 文本

5.3 条件模板（通过分支实现）

python

# 条件模板代码示例
from langchain_core.prompts import ChatPromptTemplate

def build_prompt(level: str):
    if level == "beginner":
        return ChatPromptTemplate.from_template("请用新手能懂的方式解释：{topic}")
    return ChatPromptTemplate.from_template("请从工程实践角度深入解释：{topic}")

prompt = build_prompt("beginner")
print(prompt.format_messages(topic="向量数据库"))
# 效果说明：根据 level 返回不同复杂度提示词

5.4 批量模板生成

python

# 批量模板调用示例
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
prompt = ChatPromptTemplate.from_template("一句话总结：{topic}")
chain = prompt | llm

inputs = [{"topic": "RAG"}, {"topic": "Agent"}, {"topic": "Tool Calling"}]
responses = chain.batch(inputs)
for r in responses:
    print(r.content)
# 效果说明：一次请求批量处理多个输入，效率更高

5.5 参数说明（常用）

model：模型名称，如 gpt-4o-mini
temperature：随机性，0~2，越低越稳定
max_tokens：单次最大输出长度
timeout：请求超时秒数

六、结构化输出与解析器

核心概念

默认模型返回一段自然语言文本,而生产系统需要能直接入库、能被接口消费的结构化数据(JSON/对象)。结构化输出让模型「按你定义的字段」返回,省去手写解析。

生活类比

自然语言输出像口头汇报:「这周我做了登录和支付,大概花了三天」——听着懂,但没法直接存进 Excel。结构化输出像填标准报表:任务名、状态、耗时各占一格。前者靠人脑理解,后者机器直接读。

6.1 为什么要结构化输出

在生产中，返回 JSON 比自然语言更易存储、校验、接口传输。

6.2 Pydantic 结构化输出

python

# 结构化输出代码示例
from typing import List
from pydantic import BaseModel, Field
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

class Plan(BaseModel):
    title: str = Field(description="任务标题")
    steps: List[str] = Field(description="执行步骤")

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
structured_llm = llm.with_structured_output(Plan)
prompt = ChatPromptTemplate.from_template("给我一个学习{topic}的3步计划")

chain = prompt | structured_llm
data = chain.invoke({"topic": "LangChain"})
print(data)
# 效果说明：得到 Plan 对象而不是纯文本

6.3 常见问题

输出字段缺失：在提示词中补充字段约束
解析失败：降低温度并强化格式要求

七、Runnable 与 LCEL

核心概念

LCEL(LangChain Expression Language)用一个竖线 | 把组件像管道一样串起来:prompt | model | parser。每个组件都是 Runnable,天然支持 invoke/batch/stream/并行,是 LangChain 现代写法的基石。

生活类比

LCEL 的 | 就像工厂流水线的传送带:上一道工序(prompt 生成提问)的产出,自动流到下一道(model 生成答案),再流到下一道(parser 提取纯文本)。你只管把工位排好,原料放上传送带,末端就拿到成品——不用手动搬运每个中间产物。

7.1 核心说明

LCEL（LangChain Expression Language）通过 | 把组件串联：
prompt | model | parser

7.2 Runnable 组合示例

python

# Runnable 与 LCEL 代码示例
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from langchain_core.output_parsers import StrOutputParser

prompt = ChatPromptTemplate.from_template("把这句话翻译成英文：{text}")
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
parser = StrOutputParser()

chain = prompt | llm | parser
print(chain.invoke({"text": "今天心情很好"}))
# 效果说明：输出纯字符串结果

7.3 并行与映射

python

# 并行执行示例
from langchain_core.runnables import RunnableParallel
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from langchain_core.output_parsers import StrOutputParser

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
parser = StrOutputParser()

zh = ChatPromptTemplate.from_template("翻译为中文：{text}") | llm | parser
en = ChatPromptTemplate.from_template("翻译为英文：{text}") | llm | parser

parallel = RunnableParallel(to_zh=zh, to_en=en)
print(parallel.invoke({"text": "LangChain improves LLM engineering."}))
# 效果说明：一次输入，同时得到两个方向的结果

八、链式调用与组合模式

核心概念

当一个任务需要多个步骤依次完成(先生成标题 → 再写摘要),就用链式组合。经典有 LLMChain(单步)、SimpleSequentialChain(单入单出串行)、SequentialChain(多入多出串行)。

生活类比

链式调用就像做菜的工序:洗菜 → 切菜 → 下锅 → 装盘,每一步的产出是下一步的输入。SimpleSequentialChain 是一条直线做完一道菜;SequentialChain 则像同时备好多种配料、多个成品端上桌的宴席流程。

8.1 LLMChain / SequentialChain 说明

LLMChain：单步骤处理
SimpleSequentialChain：多个步骤串行
SequentialChain：多输入多输出串行

8.2 对比代码示例

python

# Chain 对比代码示例
from langchain_openai import OpenAI
from langchain.chains import LLMChain, SimpleSequentialChain
from langchain.prompts import PromptTemplate

llm = OpenAI(temperature=0)

p1 = PromptTemplate(input_variables=["topic"], template="给出{topic}的一个标题")
c1 = LLMChain(llm=llm, prompt=p1)

p2 = PromptTemplate(input_variables=["title"], template="根据标题写一句摘要：{title}")
c2 = LLMChain(llm=llm, prompt=p2)

pipeline = SimpleSequentialChain(chains=[c1, c2], verbose=True)
print(pipeline.run("LangChain学习路线"))
# 效果说明：先生成标题，再生成摘要

8.3 复杂 Chain（分支/循环/多模型）

python

# 分支 + 多模型联动思路示例
# 注意：示例展示架构思想，可在 LCEL 中通过 RunnableBranch/自定义函数实现
"""
1) 输入问题
2) 分类器判断：技术类/业务类
3) 技术类走模型A，业务类走模型B
4) 统一后处理并输出
"""
# 效果说明：复杂业务中可按任务类型切模型和处理路径

九、向量、Embedding 与 Retriever

核心概念

让模型「读懂」你的私有文档,靠的是把文字转成数字向量(Embedding),存进向量库,再用问题的向量去找语义最接近的片段。这就是 RAG 的检索地基。

生活类比

Embedding 就像给每段文字标上GPS 坐标:意思相近的文字,坐标也挨得近。检索(Retriever)就是「以问题为圆心画个圈,把圈内最近的几段文字捞出来」。所以「什么用于存储信息」能精准找到「数据库用于存储数据」——它们坐标相邻,哪怕一个字都不重合。

检索链路一图看懂

text

   原始文档                  向量库                    问题
 ┌──────────┐   Embedding   ┌──────────┐            ┌────────┐
 │ 一堆文本  │ ───────────▶ │ 向量+原文 │            │ 用户提问│
 └──────────┘   (切块+编码)  └────┬─────┘            └───┬────┘
                                  │                      │ Embedding
                                  │   相似度检索(找最近)  ▼
                                  └────────────────▶ ┌────────┐
                                                     │ 命中片段│
                                                     └───┬────┘
                                                         ▼
                                                   交给模型生成答案

9.1 核心说明

RAG 基础链路：文档 -> 向量化 -> 存储 -> 检索 -> 生成

9.2 Chroma 向量库示例

python

# Embedding + Chroma 代码示例
from langchain_openai import OpenAIEmbeddings
from langchain_community.vectorstores import Chroma
from langchain_core.documents import Document

emb = OpenAIEmbeddings(model="text-embedding-3-small")
docs = [
    Document(page_content="LangChain可以构建Agent系统", metadata={"source": "a"}),
    Document(page_content="RAG用于外部知识增强", metadata={"source": "b"}),
]
vs = Chroma.from_documents(documents=docs, embedding=emb, collection_name="demo_docs")

hits = vs.similarity_search("什么是RAG", k=2)
for h in hits:
    print(h.page_content, h.metadata)
# 效果说明：返回最相近的文档片段

9.3 FAISS 示例

python

# Embedding + FAISS 代码示例
from langchain_openai import OpenAIEmbeddings
from langchain_community.vectorstores import FAISS

emb = OpenAIEmbeddings(model="text-embedding-3-small")
texts = ["苹果是水果", "汽车用于出行", "数据库用于存储数据"]
vs = FAISS.from_texts(texts, emb)
print(vs.similarity_search("什么用于存储信息", k=1)[0].page_content)
# 效果说明：检索到“数据库用于存储数据”

9.4 参数说明

k：召回文档数量，常用 3~8
score_threshold：相似度阈值（按库支持）
chunk_size/chunk_overlap：影响检索粒度与上下文完整性

十、RAG 的完整实现思路

核心概念

RAG(检索增强生成)= 先检索私有知识,再让模型基于检索到的上下文回答。它能让通用模型「开卷考试」,大幅降低幻觉,是知识库问答的标配方案。

生活类比

纯大模型答题像闭卷考试:全凭记忆,记错就瞎编(幻觉)。RAG 则是开卷考试:先翻到相关那几页资料(检索),再照着资料作答(生成)。答案有据可依,还能标出「答案来自第几页」方便复查。

10.1 全流程

文档加载（PDF/TXT/Word）
文本切分
向量化入库
Retriever 检索
组装问答链

10.2 可直接复用代码

python

# 知识库问答完整代码示例
import os
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
from langchain_community.document_loaders import PyPDFLoader, TextLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_community.vectorstores import Chroma
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

os.environ["OPENAI_API_KEY"] = "你的API_KEY"

# 1) 文档加载（按你的文件类型选择）
docs = TextLoader("kb.txt", encoding="utf-8").load()
# docs = PyPDFLoader("kb.pdf").load()

# 2) 切分
splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=80)
chunks = splitter.split_documents(docs)

# 3) 向量存储
emb = OpenAIEmbeddings(model="text-embedding-3-small")
vs = Chroma.from_documents(chunks, emb, collection_name="kb_collection")
retriever = vs.as_retriever(search_kwargs={"k": 4})

# 4) 问答链
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
prompt = ChatPromptTemplate.from_template(
    "你是知识库问答助手。仅基于上下文回答。\n\n上下文：\n{context}\n\n问题：{question}"
)
parser = StrOutputParser()

def ask(question: str) -> str:
    docs = retriever.invoke(question)
    context = "\n\n".join(d.page_content for d in docs)
    chain = prompt | llm | parser
    return chain.invoke({"context": context, "question": question})

print(ask("这份知识库主要讲了什么？"))
# 效果说明：回答内容受知识库约束，幻觉显著减少

10.3 注意事项

检索不准先调 chunk_size/k
对高精度场景加 rerank
答案要“带来源”便于追溯

十一、工具调用、Tool Calling 与 MCP

核心概念

模型本身只会「说」,不会「做」。Tool(工具)给模型装上「手」:查数据库、调天气 API、算数学。模型判断该用哪个工具、传什么参数,由框架实际执行并把结果喂回模型。

生活类比

模型像一位只会动嘴的项目经理:他能判断「这事得查一下数据库」,但自己不会敲 SQL。Tool 就是他手下的专业执行人员——PM 下指令(调用工具),执行人员干活(查库/算数)后把结果汇报回来,PM 再据此拍板。MCP 则像一套统一的对接协议,让任何外部系统都能标准化地成为可调用的「执行人员」。

11.1 内置 Tool 与自定义 Tool

python

# 自定义 Tool 代码示例
from langchain_core.tools import tool

@tool
def add_numbers(a: int, b: int) -> int:
    """计算两个整数之和"""
    return a + b

print(add_numbers.invoke({"a": 3, "b": 5}))
# 效果说明：返回 8

11.2 Tool 与 Chain 联动逻辑

Chain 负责语言理解
Tool 负责外部动作（查库/查天气/调用业务系统）
Agent 负责在二者之间“决策调度”

11.3 工具权限控制建议

只暴露必要工具
为工具输入做 schema 校验
对高风险工具（写操作）增加白名单和审批

11.4 MCP 说明

MCP 可把外部系统能力标准化为可调用工具资源，LangChain 可通过工具层接入，形成统一调度链路。

十二、Agent、ReAct 与多 Agent 协作

核心概念

Chain 是固定流程(步骤写死),Agent 是动态决策:模型自己判断「要不要用工具、用哪个、用完还要不要再用」,循环推理直到得出答案。ReAct 是最经典的「思考 → 行动 → 观察」循环范式。

生活类比

Chain 像自动售货机:投币 → 选商品 → 出货,流程完全固定。Agent 像便利店店员:你说「我想弄点吃的但不知道买啥」,他会反问、去货架看看、比价、最后给你推荐——每一步都在临场判断,而不是照本宣科。

ReAct 决策循环一图看懂

text

        用户问题
           │
           ▼
    ┌─────────────┐
    │  Thought    │  模型思考:我需要什么信息?
    │  (思考)     │
    └──────┬──────┘
           ▼
    ┌─────────────┐
    │  Action     │  决定调用某个工具(如 multiply)
    │  (行动)     │
    └──────┬──────┘
           ▼
    ┌─────────────┐
    │ Observation │  拿到工具返回结果
    │  (观察)     │
    └──────┬──────┘
           │  信息够了吗?
      不够 │ └──────▶ 回到 Thought 继续循环
           │  够了
           ▼
      最终答案 Final Answer

12.1 Agent 类型与适用场景

基础 Agent：简单问答 + 工具调用
ReAct Agent：边思考边行动，适合多步推理
Self-Ask：先拆问题再求解，适合复杂问答
Plan-and-Execute：先规划后执行，适合流程任务

12.2 ReAct Agent 示例

python

# ReAct Agent 代码示例
from langchain_openai import ChatOpenAI
from langchain.agents import create_react_agent, AgentExecutor
from langchain_core.prompts import PromptTemplate
from langchain_core.tools import tool

@tool
def multiply(a: int, b: int) -> int:
    """计算乘法"""
    return a * b

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
tools = [multiply]

prompt = PromptTemplate.from_template(
    """你可以使用工具解决问题。
问题: {input}
可用工具: {tools}
工具名称: {tool_names}
{agent_scratchpad}"""
)

agent = create_react_agent(llm=llm, tools=tools, prompt=prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
print(executor.invoke({"input": "7乘以9是多少？"}))
# 效果说明：Agent 会自动调用 multiply 工具

12.3 Plan-and-Execute 思路

python

# Plan-and-Execute 架构示例（伪代码）
"""
planner: 负责把目标拆成子任务
executor: 逐个执行子任务（可调用多个工具）
supervisor: 汇总结果并给出最终答复
"""
# 注意事项：计划要可观测、可中断、可重试

12.4 多 Agent 协作建议

角色分工明确：规划/执行/审查
共享上下文最小化：避免上下文污染
每个 Agent 限制工具权限

十三、记忆、状态与 LangGraph 的边界

核心概念

模型默认「金鱼记忆」——每次调用都是全新的,记不住上一句。要多轮对话,就得把历史消息一起传进去(记忆)。当流程复杂到需要状态机、分支回退、人工中断时,就该升级到 LangGraph。

生活类比

无记忆的模型像每次都失忆的客服:你说完退款问题,下一句他就忘了你是谁。加了 Memory 就像给客服配了通话记录本,能翻看你刚才说过什么。而 LangGraph 好比从「单人客服」升级到「有流程图的呼叫中心」:能转接、能挂起等你补材料、能按规则走不同分支。

13.1 多轮对话记忆（机器人场景）

python

# 多轮对话记忆代码示例（简化）
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, AIMessage, SystemMessage

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.3)
history = [SystemMessage(content="你是专业客服助手。")]

def chat(user_text: str) -> str:
    history.append(HumanMessage(content=user_text))
    resp = llm.invoke(history)
    history.append(AIMessage(content=resp.content))
    return resp.content

print(chat("我想了解你们的退款规则"))
print(chat("请结合我刚才的问题，再给一个简短版本"))
# 效果说明：第二轮可引用第一轮上下文

13.2 LangChain 与 LangGraph 边界

LangChain：线性/轻量编排快
LangGraph：复杂状态机、多分支回退、长流程更强

13.3 何时升级到 LangGraph

需要强状态控制
需要人工中断与恢复
需要多 Agent 工作流编排

十四、生产实践与常见坑

核心概念

从「能跑」到「上线可用」,中间隔着:错误重试、日志追踪、接口封装、幻觉与成本控制。这些工程化细节决定了 AI 应用能不能扛住真实流量。

生活类比

Demo 跑通像在自家厨房做了一道菜;上生产像开一家餐厅:得考虑客人点单高峰(并发)、食材坏了怎么办(重试)、每道菜谁做的可追溯(日志)、成本别超支(缓存/小模型)。少一环,餐厅就会翻车。

14.1 错误处理、日志、重试（可复用）

python

# 稳定性增强代码示例
import time
import logging
from langchain_openai import ChatOpenAI

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("llm_service")

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0, timeout=20)

def safe_invoke(messages, retry=3):
    last_err = None
    for i in range(retry):
        try:
            return llm.invoke(messages)
        except Exception as e:
            last_err = e
            logger.warning("调用失败，第%s次重试，错误=%s", i + 1, str(e))
            time.sleep(2 ** i)
    raise RuntimeError(f"模型调用失败: {last_err}")

14.2 FastAPI 封装（API 接口开发）

python

# FastAPI 接口实战代码示例
import os
from fastapi import FastAPI
from pydantic import BaseModel
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

os.environ["OPENAI_API_KEY"] = "你的API_KEY"

app = FastAPI(title="LangChain API Demo")
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.2)
prompt = ChatPromptTemplate.from_template("请回答问题：{question}")
chain = prompt | llm | StrOutputParser()

class AskReq(BaseModel):
    question: str

@app.post("/ask")
def ask(req: AskReq):
    answer = chain.invoke({"question": req.question})
    return {"answer": answer}

# 运行方式：
# uvicorn app:app --host 0.0.0.0 --port 8000 --reload

十五、部署上线、并发与避坑

核心概念

应用写好后,要考虑:如何脱离公网走本地推理(数据合规)、如何用并发扛住批量请求、如何用 Docker 一键部署,以及那些反复踩的坑怎么绕开。

生活类比

本地化部署像自建食堂:不依赖外卖平台(公网 API),数据不出门更安心。并发优化像多开几个收银台:高峰期不排长队,但收银台太多也会挤爆后厨(触发限流),得配合排队叫号(重试限速)。

15.1 本地化部署（离线可控）

python

# 本地模型接入示例（以本地OpenAI兼容网关为例）
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="qwen2.5-7b-instruct",
    api_key="EMPTY",
    base_url="http://127.0.0.1:8000/v1",  # 本地兼容OpenAI接口服务
    temperature=0.2,
)
print(llm.invoke("请用一句话介绍你自己").content)
# 效果说明：脱离公网API，走本地推理服务

15.2 批量处理与并发优化

python

# 批量并发调用示例
from concurrent.futures import ThreadPoolExecutor
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
questions = ["什么是RAG", "什么是Agent", "什么是Embedding"]

def run(q):
    return llm.invoke(q).content

with ThreadPoolExecutor(max_workers=4) as ex:
    results = list(ex.map(run, questions))

print(results)
# 注意事项：并发过高可能触发限流，需配合重试和速率控制

15.3 Docker 部署模板

dockerfile

# Dockerfile 示例
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

15.4 常见问题（错误代码 + 修正代码）

问题 1：API 密钥未配置

python

# 错误代码
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4o-mini")
print(llm.invoke("hello").content)
# 原因说明：未设置 OPENAI_API_KEY，调用会报认证错误

python

# 修正代码
import os
from langchain_openai import ChatOpenAI
os.environ["OPENAI_API_KEY"] = "你的API_KEY"
llm = ChatOpenAI(model="gpt-4o-mini")
print(llm.invoke("hello").content)

问题 2：向量检索不准确

python

# 常见原因：chunk_size 太大，语义混杂；k 太小召回不足
# 修正方向：减小 chunk_size、增加 k、增加 rerank

问题 3：Agent 逻辑混乱

python

# 常见原因：工具描述不清，Prompt 未约束动作顺序
# 修正方向：明确工具输入输出、限制最大迭代、增加中间日志

15.5 高级避坑技巧

降低幻觉：检索增强 + 输出引用来源 + 低温度
降低成本：缓存常见问答、优先小模型、批处理
提升速度：并发 + 流式输出 + 预热连接池
兼容多模型：抽象模型层，统一请求参数

十六、面试高频问题

核心概念

面试常问的不是 API 细节,而是「概念边界」与「工程权衡」:Chain vs Agent、什么时候上 RAG、什么时候上 LangGraph。答题抓住「固定 vs 动态」「记忆 vs 检索」「简单 vs 复杂状态」的对比即可。

16.1 LangChain 核心组件有哪些？

Prompt、Model、OutputParser、Retriever、Tool、Agent、Memory、Runnable

16.2 LLMChain 和 Agent 的差异？

LLMChain 是固定流程，Agent 是动态决策流程。

16.3 RAG 关键优化点？

文档切分、召回质量、重排、上下文压缩、答案引用。

16.4 什么时候用 LangGraph？

多状态、多分支、可恢复流程、人工介入场景。

十七、完整实战案例汇总

核心概念

把前面所有能力(模型/RAG/Tool/Agent/记忆/部署)组合起来,就是真实项目。下面 5 个案例覆盖了「需求 → 实现 → 优化 → 部署」的完整闭环,可作为选型参考模板。

生活类比

前面各章是单个乐高零件(模型、检索、工具...),这一节展示用这些零件拼出的成品:客服机器人、知识库、文档工具、离线助手、多工具 Agent。看懂拼法,你就能照着搭自己的项目。

17.1 智能客服机器人

需求：支持多轮对话与 FAQ
实现：ChatModel + 历史记忆 + 工具查询订单
优化：加入敏感词规则、重试和日志
部署：FastAPI + Docker

17.2 企业知识库问答

需求：PDF/TXT 文档检索问答
实现：Loader + Splitter + Chroma + Retriever + QA Chain
优化：chunk 参数调优 + rerank + 来源引用
部署：定时增量索引 + 监控检索命中率

17.3 文档分析工具

需求：批量总结文档并导出报告
实现：批量读取 + LCEL batch + 结构化输出
优化：并发池 + 缓存 + 失败重试
部署：任务队列 + API 查询任务状态

17.4 本地化离线助手

需求：内网可用、数据不出域
实现：本地 LLM（OpenAI 兼容网关）+ 本地向量库
优化：模型量化、索引预构建
部署：单机 Docker Compose

17.5 多工具协同 Agent

需求：自动查询数据并生成日报
实现：ReAct Agent + SQL Tool + Report Tool
优化：权限控制 + 审计日志 + 输出模板
部署：定时任务 + Webhook 推送

十八、参数手册与学习资源

核心概念

这里汇总最常调的参数与可直接复制的 Prompt 模板,外加权威学习资源。收藏本节,日常开发遇到参数忘了直接回来查。

18.1 核心参数手册（速查）

模型参数

model：模型名称，决定能力与成本
temperature：随机性，低值更稳定
max_tokens：输出长度上限
timeout：请求超时
top_p：核采样范围（部分模型支持）

检索参数

k：召回条数
chunk_size：切块大小
chunk_overlap：切块重叠
search_type：检索策略（similarity/mmr）

Agent 参数

max_iterations：最大推理步数
verbose：打印中间步骤
handle_parsing_errors：解析失败时容错

18.2 优质模板（可直接复制改造）

通用问答模板

python

TEMPLATE = """你是专业助手，请基于事实回答：
问题：{question}
要求：
1. 结论先行
2. 分点说明
3. 无依据时明确说明不知道
"""

RAG 问答模板

python

RAG_TEMPLATE = """你是知识库助手，只能依据上下文作答。
上下文：
{context}

问题：{question}
请输出：
1) 简短答案
2) 依据片段
"""

Agent 工具调用模板

python

AGENT_TEMPLATE = """你可以使用工具解决问题。
策略：
1) 先判断是否需要工具
2) 需要时仅调用最合适工具
3) 输出最终结论与依据
问题：{input}
"""

18.3 学习资源推荐

官方文档：https://python.langchain.com/
LangSmith（可观测平台）：https://smith.langchain.com/
Chroma 文档：https://docs.trychroma.com/
FAISS 文档：https://github.com/facebookresearch/faiss
FastAPI 文档：https://fastapi.tiangolo.com/

十九、总结

核心概念

LangChain 的学习路径是一条清晰的进阶线:三件套(Prompt/Model/Parser)→ 编排(LCEL/Chain)→ 检索(RAG)→ 工具与 Agent → 生产上线。先跑通最小示例,再逐层叠加能力,最后工程化封装。

一句话记住

LangChain = 给大模型配「流程 + 工具箱 + 记事本」。会说话靠 Prompt,会查资料靠 RAG,会动手靠 Tool,会决策靠 Agent,记得住靠 Memory,扛得住靠工程化。

19.1 依赖清单示例

txt

langchain
langchain-core
langchain-openai
langchain-community
chromadb
faiss-cpu
pypdf
fastapi
uvicorn
python-dotenv
pydantic

19.2 运行步骤（统一）

创建虚拟环境并安装依赖
配置 OPENAI_API_KEY（或本地兼容网关）
运行单文件示例验证模型可用
再集成 RAG / Tool / Agent
最后封装 FastAPI 并容器化上线

LangChain 从入门到实战精通 ​

导航目录 ​

一、LangChain 是什么 ​

1.1 核心说明 ​

1.2 最小可运行示例 ​

1.3 关键注意点 ​

二、为什么项目里会引入 LangChain ​

2.1 核心价值 ​

2.2 基础开发流程（完整） ​

2.3 完整入门流程代码 ​

三、核心包与安装建议 ​

3.1 Python 版本与核心依赖 ​

3.2 安装命令（pip + 镜像） ​

四、环境验证与避坑 ​

4.1 标准导入与验证 ​

4.2 新手常见误区与避坑 ​

五、模型、消息与 Prompt 模板 ​

5.1 核心概念速记 ​

5.2 PromptTemplate 基础与动态模板 ​

5.3 条件模板（通过分支实现） ​

5.4 批量模板生成 ​

5.5 参数说明（常用） ​

六、结构化输出与解析器 ​

6.1 为什么要结构化输出 ​

6.2 Pydantic 结构化输出 ​

6.3 常见问题 ​

七、Runnable 与 LCEL ​

7.1 核心说明 ​

7.2 Runnable 组合示例 ​

7.3 并行与映射 ​

八、链式调用与组合模式 ​

8.1 LLMChain / SequentialChain 说明 ​

8.2 对比代码示例 ​

8.3 复杂 Chain（分支/循环/多模型） ​

九、向量、Embedding 与 Retriever ​

9.1 核心说明 ​

9.2 Chroma 向量库示例 ​

9.3 FAISS 示例 ​

9.4 参数说明 ​

十、RAG 的完整实现思路 ​

10.1 全流程 ​

10.2 可直接复用代码 ​

10.3 注意事项 ​

十一、工具调用、Tool Calling 与 MCP ​

11.1 内置 Tool 与自定义 Tool ​

11.2 Tool 与 Chain 联动逻辑 ​

11.3 工具权限控制建议 ​

11.4 MCP 说明 ​

十二、Agent、ReAct 与多 Agent 协作 ​

12.1 Agent 类型与适用场景 ​

12.2 ReAct Agent 示例 ​

12.3 Plan-and-Execute 思路 ​

12.4 多 Agent 协作建议 ​

十三、记忆、状态与 LangGraph 的边界 ​

13.1 多轮对话记忆（机器人场景） ​

13.2 LangChain 与 LangGraph 边界 ​

13.3 何时升级到 LangGraph ​

十四、生产实践与常见坑 ​

14.1 错误处理、日志、重试（可复用） ​

14.2 FastAPI 封装（API 接口开发） ​

十五、部署上线、并发与避坑 ​

15.1 本地化部署（离线可控） ​

15.2 批量处理与并发优化 ​

15.3 Docker 部署模板 ​

15.4 常见问题（错误代码 + 修正代码） ​

问题 1：API 密钥未配置 ​

问题 2：向量检索不准确 ​

问题 3：Agent 逻辑混乱 ​

15.5 高级避坑技巧 ​

十六、面试高频问题 ​

16.1 LangChain 核心组件有哪些？ ​

16.2 LLMChain 和 Agent 的差异？ ​

16.3 RAG 关键优化点？ ​

16.4 什么时候用 LangGraph？ ​

十七、完整实战案例汇总 ​

17.1 智能客服机器人 ​

17.2 企业知识库问答 ​

17.3 文档分析工具 ​

17.4 本地化离线助手 ​

17.5 多工具协同 Agent ​

LangChain 从入门到实战精通

导航目录

一、LangChain 是什么

1.1 核心说明

1.2 最小可运行示例

1.3 关键注意点

二、为什么项目里会引入 LangChain

2.1 核心价值

2.2 基础开发流程（完整）

2.3 完整入门流程代码

三、核心包与安装建议

3.1 Python 版本与核心依赖

3.2 安装命令（pip + 镜像）

四、环境验证与避坑

4.1 标准导入与验证

4.2 新手常见误区与避坑

五、模型、消息与 Prompt 模板

5.1 核心概念速记

5.2 PromptTemplate 基础与动态模板

5.3 条件模板（通过分支实现）

5.4 批量模板生成

5.5 参数说明（常用）

六、结构化输出与解析器

6.1 为什么要结构化输出

6.2 Pydantic 结构化输出

6.3 常见问题

七、Runnable 与 LCEL

7.1 核心说明

7.2 Runnable 组合示例

7.3 并行与映射

八、链式调用与组合模式

8.1 LLMChain / SequentialChain 说明

8.2 对比代码示例

8.3 复杂 Chain（分支/循环/多模型）

九、向量、Embedding 与 Retriever

9.1 核心说明

9.2 Chroma 向量库示例

9.3 FAISS 示例

9.4 参数说明

十、RAG 的完整实现思路

10.1 全流程

10.2 可直接复用代码

10.3 注意事项

十一、工具调用、Tool Calling 与 MCP

11.1 内置 Tool 与自定义 Tool

11.2 Tool 与 Chain 联动逻辑

11.3 工具权限控制建议

11.4 MCP 说明

十二、Agent、ReAct 与多 Agent 协作

12.1 Agent 类型与适用场景

12.2 ReAct Agent 示例

12.3 Plan-and-Execute 思路

12.4 多 Agent 协作建议

十三、记忆、状态与 LangGraph 的边界

13.1 多轮对话记忆（机器人场景）

13.2 LangChain 与 LangGraph 边界

13.3 何时升级到 LangGraph

十四、生产实践与常见坑

14.1 错误处理、日志、重试（可复用）

14.2 FastAPI 封装（API 接口开发）

十五、部署上线、并发与避坑

15.1 本地化部署（离线可控）

15.2 批量处理与并发优化

15.3 Docker 部署模板

15.4 常见问题（错误代码 + 修正代码）

问题 1：API 密钥未配置

问题 2：向量检索不准确

问题 3：Agent 逻辑混乱

15.5 高级避坑技巧

十六、面试高频问题

16.1 LangChain 核心组件有哪些？

16.2 LLMChain 和 Agent 的差异？

16.3 RAG 关键优化点？

16.4 什么时候用 LangGraph？

十七、完整实战案例汇总

17.1 智能客服机器人

17.2 企业知识库问答

17.3 文档分析工具

17.4 本地化离线助手

17.5 多工具协同 Agent