LangChain on 男娘教主

LangChain

Tue, 25 Aug 2026 07:56:58 +0800

LangChain

一、LangChain 是什么（架构总览）

一句话定位

LangChain = 调模型之上的"编排层"。 它不替你调模型（那还是 OpenAI/DeepSeek 的活），它解决的是"调完模型之后那一堆 plumbing"：拼提示词、解析输出、接记忆、接检索、接工具、把流程串成管道。

你之前 W1-W3 手写过的 RealLLM / prompt_lib / fc_loop / MemoryManager / Chroma，在 LangChain 里都有标准件对应。学 LangChain 不是学新东西，是把你的"手动接线"换成"标准管道"。

全景架构图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


┌──────────────────────────────────────────────────────────────┐
│ 你的应用 / Agent │
├──────────────────────────────────────────────────────────────┤
│ LangChain 编排层（本文重点） │
│ │
│ Prompt ──▶ Model ──▶ OutputParser （基础链 LCEL） │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ Memory Retriever Tool ◀── Agent（决定调谁） │
│ (记忆) (RAG检索) (工具) │
│ │
│ RunnableParallel / Passthrough / Lambda / Branch（组合件） │
│ LangGraph（状态图：把上面这些编排成有环的流程） │
├──────────────────────────────────────────────────────────────┤
│ langchain-core / langchain-openai / community（接入层） │
├──────────────────────────────────────────────────────────────┤
│ 模型供应商 API（DeepSeek / OpenAI / 通义 / Kimi ...） │
└──────────────────────────────────────────────────────────────┘

包结构 —— 别一股脑 `pip install langchain` 就完事

1
2
3
4
5
6


pip install langchain-core # 核心抽象：Runnable / Prompt / Parser / 基础接口（必装）
pip install langchain-openai # OpenAI 及兼容协议（DeepSeek 走这）的模型接入
pip install langchain-community # 社区集成：各种向量库、文档加载器、第三方工具
pip install langchain # 高层封装：agent / chain / 一些 conveniences（可选）
pip install langgraph # 状态图编排（W5 用，独立包）
pip install python-dotenv # 读 .env 里的密钥

包	干啥	你现在用得到吗
`langchain-core`	Runnable 协议、Prompt、Parser、Message 类型	✅ 必用
`langchain-openai`	`ChatOpenAI` 模型封装	✅ 必用
`langchain-community`	Chroma / FAISS / 各类 loader	✅ 做 RAG 用
`langchain`	旧的 `LLMChain`、`Agent` 封装	⚠️ 历史包袱多，新项目优先用 core + LCEL
`langgraph`	状态图 / 多轮循环编排	✅ W5 进阶

⚠️ 版本兼容是头号坑：LangChain 迭代极快，旧博客里的 LLMChain(...)、ConversationChain 在新版已弃用。本文全部基于 LCEL（core 0.2+） 写法，这是目前最稳、官方主推的范式。

裸调 vs LangChain 对照（先理解痛点）

1
2
3
4
5
6
7


# ===== 裸调（你 W1 的写法）=====
import openai
resp = openai.ChatCompletion.create(
 model="deepseek-chat",
 messages=[{"role": "user", "content": "你好"}]
)
text = resp["choices"][0]["message"]["content"] # 每次都要抠这一长串

1
2
3
4
5
6
7


# ===== LangChain（声明式）=====
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from langchain_core.output_parsers import StrOutputParser

chain = ChatPromptTemplate.from_messages([("user", "{q}")]) | ChatOpenAI(...) | StrOutputParser()
text = chain.invoke({"q": "你好"}) # 一行拿到字符串，不用抠 dict

差别：裸调你写 plumbing，LangChain 你只声明"要什么流程"。

二、安装与环境

`pip install` —— 装依赖

1

pip install -U langchain langchain-openai langchain-core langchain-community python-dotenv

-U 升级到最新版；建议锁版本做笔记：pip freeze > requirements.txt。

`.env` + `load_dotenv` —— 密钥分离

1
2
3
4
5


import os
from dotenv import load_dotenv

load_dotenv() # 自动读取项目根目录的 .env 文件
api_key = os.getenv("DEEPSEEK_API_KEY") # 从环境变量取，绝不硬编码进代码

.env 文件内容（放项目根目录）：

1

DEEPSEEK_API_KEY=sk-xxxxxxx

⚠️ 密钥红线：.env 必须写进 .gitignore，绝对不能 commit 进仓库。一旦泄露，第一时间去平台注销密钥并换新的（你一直强调的安全意识，这里再次强调）。

三、Model 模型：ChatModel

`ChatOpenAI` —— 统一接口调任意兼容模型

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


from langchain_openai import ChatOpenAI
import os

# DeepSeek 走 OpenAI 兼容协议：换 base_url 就行
model = ChatOpenAI(
 model="deepseek-chat", # 模型名（DeepSeek 用 deepseek-chat / deepseek-reasoner）
 api_key=os.getenv("DEEPSEEK_API_KEY"), # 从环境变量取
 base_url="https://api.deepseek.com", # 兼容协议入口
 temperature=0.7, # 随机性：0= deterministic，1= 发散
 max_tokens=1024, # 单次最多生成多少 token
)

参数	作用	常用值
`model`	模型名	`deepseek-chat` / `gpt-4o` / `qwen-max`
`temperature`	采样温度	0（严谨）/ 0.7（创意）/ 1（发散）
`max_tokens`	上限	按任务定，默认往往偏小
`streaming`	是否流式	`True` 时支持 `.stream()`
`base_url`	兼容入口	DeepSeek=`https://api.deepseek.com`

你 W1 的 RealLLM 其实就是这个 ChatOpenAI 的封装。所谓"统一厨师证"——不管底层是 DeepSeek 还是通义，接口都长一样，换模型只改两个字段。

`invoke` / `stream` / `batch` —— 三种调用方式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 1) invoke：一次拿完整结果（最常用）
msg = model.invoke("你好") # 返回 AIMessage 对象
print(msg.content) # 取文本用 .content

# 2) stream：流式，一个字一个字冒（适合聊天界面）
for chunk in model.stream("写一首诗"):
 print(chunk.content, end="", flush=True)

# 3) batch：一次塞多个输入，并发处理（比循环 invoke 快）
results = model.batch(["1+1=?", "2+2=?"])
print([r.content for r in results])

这三个方法来自 Runnable 协议，后面所有组件（Prompt/Parser/Chain）都支持，这是 LCEL 能串起来的底层原因。

四、Prompt 提示词模板：ChatPromptTemplate

`ChatPromptTemplate.from_messages` —— 构造消息模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


from langchain_core.prompts import ChatPromptTemplate

# 用 (角色, 文本) 元组列表；{q} 是占位变量
prompt = ChatPromptTemplate.from_messages([
 ("system", "你是一个乐于助人的助手。"), # system 角色
 ("user", "{q}"), # user 角色，{q} 待填
])

# 调用时传字典填充变量
messages = prompt.invoke({"q": "什么是 LCEL？"})
print(messages.to_messages()) # 得到 [SystemMessage, HumanMessage]

你 W1 的 prompt_lib 干的就是这事——ChatPromptTemplate 是它的框架标准版，支持 {变量} 插值。

`MessagesPlaceholder` —— 历史消息占位

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

prompt = ChatPromptTemplate.from_messages([
 ("system", "你是有记忆的助手。"),
 MessagesPlaceholder("history"), # 这里会展开成一串历史消息对象
 ("user", "{question}"),
])

# 调用时 history 必须传"消息对象列表"（不是 dict）
from langchain_core.messages import HumanMessage, AIMessage
chain.invoke({
 "question": "我叫什么？",
 "history": [HumanMessage(content="我叫小明"), AIMessage(content="你好小明")]
})

⚠️ placeholder 要配消息对象列表，不是 dict 列表。你自研记忆返回的是 dict，必须先用 _to_lc 转换（见第八节）。

`partial` —— 预填部分变量

1
2
3
4


# 有些变量每次都一样（如固定语言），可以提前 partial 掉
prompt = ChatPromptTemplate.from_messages([("system", "用{lang}回答：{q}")])
prompt_zh = prompt.partial(lang="中文") # 预填 lang，之后只需传 {q}
print(prompt_zh.invoke({"q": "你好"}).to_messages())

五、OutputParser 输出解析器

`StrOutputParser` —— 把 AIMessage 变成纯字符串

1
2
3
4
5


from langchain_core.output_parsers import StrOutputParser

parser = StrOutputParser()
text = parser.invoke(model.invoke("你好")) # AIMessage → str
print(type(text)) # <class 'str'>

`JsonOutputParser` —— 解析 JSON 输出

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


from langchain_core.output_parsers import JsonOutputParser
from langchain_core.prompts import ChatPromptTemplate

parser = JsonOutputParser()
prompt = ChatPromptTemplate.from_messages([
 ("system", "只输出 JSON，不要解释。{format_instructions}"),
 ("user", "列出三种水果和颜色"),
])

# JsonOutputParser 会给你一段"格式说明"塞进 prompt
chain = prompt | model | parser
data = chain.invoke({"format_instructions": parser.get_format_instructions()})
print(data) # 已经是 dict，不用自己 json.loads

`PydanticOutputParser` —— 强类型结构化（进阶）

1
2
3
4
5
6
7
8
9


from pydantic import BaseModel, Field
from langchain_core.output_parsers import PydanticOutputParser

class Person(BaseModel):
 name: str = Field(description="姓名")
 age: int = Field(description="年龄")

parser = PydanticOutputParser(pydantic_object=Person)
# parser.get_format_instructions() 会生成"必须输出符合 Person schema 的 JSON"

你平时手动 json.loads(...)，就是 StrOutputParser/JsonOutputParser 的活。框架的价值：连"格式说明"都帮你自动生成。

⚠️ 验收坑：StrOutputParser 在某些版本内部可能把结果裹一层包装类型（如旧版的 TextAccessor）。稳健验收写 isinstance(result, str)，别断言具体类名——类名会变，str 子类关系不会变。

六、LCEL 链：Runnable 与管道

`chain = prompt | model | parser` —— 一条最小链

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from langchain_core.output_parsers import StrOutputParser
import os

prompt = ChatPromptTemplate.from_messages([("system", "你是一个简洁助手"), ("user", "{question}")])
model = ChatOpenAI(model="deepseek-chat", api_key=os.getenv("DEEPSEEK_API_KEY"),
 base_url="https://api.deepseek.com")
parser = StrOutputParser()

# | 就是传送带：前一个输出自动变成后一个输入
chain = prompt | model | parser

# 调用
print(chain.invoke({"question": "什么是 LCEL？"})) # 直接拿到 str

工厂流水线类比：

prompt = 配料机（dict → 消息列表）
model = 加工机（消息 → AIMessage）
parser = 包装机（AIMessage → 纯字符串）
| = 传送带（自动流转）

`get_graph().print_ascii()` —— 可视化整条链

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


chain.get_graph().print_ascii()
# 输出：
# PromptInput
# |
# ChatPromptTemplate
# |
# ChatOpenAI
# |
# StrOutputParser
# |
# StrOutputParserOutput

排错神器：链不工作时先打印结构图，看数据流向对不对。

Runnable 协议 —— 为什么能 `|`

所有 LangChain 组件都实现 Runnable 接口，至少有 invoke / stream / batch 三个方法。| 运算符本质是"把左边输出喂给右边输入"。普通 Python 函数没有这接口，必须先包成 RunnableLambda（见第七节）才能入链。

七、Runnable 组合件

`RunnableParallel` —— 一条输入，并行出多个结果

1
2
3
4
5
6
7
8
9


from langchain_core.runnables import RunnableParallel

# 同一条 question 同时喂给"回答链"和"关键词链"
parallel = RunnableParallel(
 answer=answer_chain, # 键名 answer 会成为结果 dict 的键
 keywords=kw_chain,
)
res = parallel.invoke({"question": "什么是 LCEL？"})
# res = {"answer": "...", "keywords": "..."} 返回 dict

你 W1-W3 没有"并行"概念，这是框架新增能力：一条输入复制多份，同时跑不同子链。

`RunnablePassthrough.assign` —— 保留原输入，再追加新字段

1
2
3
4
5
6
7
8
9


from langchain_core.runnables import RunnablePassthrough

# 原输入 {"question": "..."} 被保留，再追加 长度 / 前5字 两个字段
enrich = RunnablePassthrough.assign(
 长度=lambda x: len(x["question"]),
 前5字=lambda x: x["question"][:5],
)
out = enrich.invoke({"question": "什么是LCEL？"})
# out = {"question": "什么是LCEL？", "长度": 7, "前5字": "什么是LC"}

这等价于字典解包 {**x, "新字段": ...}——你 W3 get_context 里"保留原消息 + 插新消息"的思路，框架用 .assign 标准化了。

`RunnableLambda` —— 任意 Python 函数入链（适配器）

1
2
3
4
5
6
7


from langchain_core.runnables import RunnableLambda

def 清洗(text: str) -> str:
 return " ".join(text.split())[:50] # 普通函数，参数类型要对接上一个 Runnable 的输出

chain = answer_chain | RunnableLambda(清洗) # 把函数包成 Runnable，才能用 |
print(chain.invoke({"question": "介绍 LangChain"}))

类比"插头转换器"：普通函数是两脚插头，LangChain 管道是三脚插座，套个 RunnableLambda 就通了。这也是你把 W3 自研 MemoryManager / compress() 接进链的桥。

`RunnableBranch` —— 条件分支（按判断走不同子链）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


from langchain_core.runnables import RunnableBranch

branch = RunnableBranch(
 (lambda x: "天气" in x["question"], weather_chain), # 条件1 成立 → 天气链
 (lambda x: "计算" in x["question"], calc_chain), # 条件2 成立 → 计算链
 default_chain, # 都不成立 → 默认链（必须放最后）
)

for q in ["北京天气？", "计算 12*8", "你好"]:
 print(branch.invoke({"question": q}))

条件短路：从上到下匹配，命中第一个就走，所以默认链必须置底。这是 W5 LangGraph 条件 edge 的雏形。

八、Memory 记忆

三种记忆模式

模式	存啥	对应你 W3
短期（窗口）	最近 N 轮对话	`ShortTermMemory`
长期（向量）	用户事实 / 知识	`LongTermMemory` + Chroma
压缩	老历史 → 一条摘要	`compress.py`

用 `RunnableLambda` 接入自研 `MemoryManager`（重点）

你的 MemoryManager.get_context() 返回 dict 列表，但 prompt 的 MessagesPlaceholder 要 消息对象列表。中间必须有一道"格式转换"——这就是 _to_lc：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


from langchain_core.messages import SystemMessage, HumanMessage, AIMessage
from langchain_core.runnables import RunnableLambda

# 桥的包装器：dict 消息 → LangChain BaseMessage
def _to_lc(m: dict):
 role, content = m.get("role", "user"), m.get("content", "")
 if role == "system":
 return SystemMessage(content=content)
 if role == "assistant":
 return AIMessage(content=content)
 return HumanMessage(content=content)

# 接入 W3 自研 MemoryManager（失败则降级最小窗口版）
try:
 from memory.memory_manager import MemoryManager
 _mm = MemoryManager(window=6, max_tokens=500)

 def get_history(x):
 # 真实版：query=本轮问题 → 长期召回 + 滚动窗口
 return [_to_lc(m) for m in _mm.get_context(query=x.get("question"))]
except Exception as e:
 print(f"[降级]未找到 memory 包({e})，使用最小窗口版")
 class _MiniMM:
 def __init__(self, window=6):
 self.buf, self.window = [], window
 def get_context(self, query=None):
 return self.buf[-self.window:]
 def add_user(self, t):
 self.buf.append({"role": "user", "content": t})
 def add_ai(self, t):
 self.buf.append({"role": "assistant", "content": t})
 _mm = _MiniMM()
 def get_history(x):
 return [_to_lc(m) for m in _mm.get_context()]

# 链首用 RunnableLambda 加料：保留 question，追加 history 字段
load_mem = RunnableLambda(lambda x: {**x, "history": get_history(x)})
chain = load_mem | prompt | model | StrOutputParser()

def ask(question: str) -> str:
 ans = chain.invoke({"question": question})
 if hasattr(_mm, "add_user"):
 _mm.add_user(question); _mm.add_ai(ans)
 else:
 _mm.add({"role": "user", "content": question})
 _mm.add({"role": "assistant", "content": ans})
 return ans

for q in ["我叫小明，喜欢打篮球", "我刚说的爱好是什么？", "我名字叫什么？"]:
 print(f"Q: {q}\nA: {ask(q)}\n")

⚠️ 相对导入坑：上面的 from memory.memory_manager import ... 直接 python lc_memory.py 跑会炸（脚本被当顶层模块，.. / 包路径解析不了）。修法有二：① sys.path.insert(0, 项目根目录) + 绝对导入；② 用 python -m 包名.模块名 启动。你 W3 调试时踩过同款坑，这里是标准解法。

关键设计：MemoryManager 不重写，只包一层——延续你 W3 的"调度者不重写逻辑"原则。get_context / compress 原样复用，框架只是多了一个入口适配器。

九、Retriever 检索与 RAG

RAG 流程：文档 → 切分 → 向量化 → 存入 → 检索 → 拼进 prompt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


from langchain_community.vectorstores import Chroma
from langchain_community.embeddings import HuggingFaceEmbeddings
from langchain_text_splitters import RecursiveCharacterTextSplitter

# 1) 切分文档
splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50)
docs = splitter.create_documents([open("知识库.txt", encoding="utf-8").read()])

# 2) 向量化 + 存入 Chroma（你 W3 的 Chroma 长期记忆就是它）
embeddings = HuggingFaceEmbeddings(model_name="BAAI/bge-small-zh-v1.5")
vectordb = Chroma.from_documents(docs, embeddings, persist_directory="./chroma_db")

# 3) 检索器：query → 相关片段
retriever = vectordb.as_retriever(search_kwargs={"k": 3})
hits = retriever.invoke("退款政策是什么？")
print([d.page_content for d in hits])

你 W3 的"长期向量记忆"和 RAG 的"知识检索"是同一个东西——Chroma 接一次复用，不用另起炉灶。

接进链（检索增强问答）

1
2
3
4
5
6
7


from langchain_core.runnables import RunnablePassthrough

# 用 .assign 把检索结果拼进上下文，原 question 保留
rag_chain = (
 {"context": retriever, "question": RunnablePassthrough()}
 | rag_prompt | model | parser
)

十、Tool 工具与 @tool

`@tool` —— 把函数变成模型可调用的工具

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


from langchain_core.tools import tool

@tool
def calculator(expr: str) -> str:
 """计算一个数学表达式。"""
 return str(eval(expr))

@tool
def get_weather(city: str) -> str:
 """查询某城市天气。"""
 return f"{city} 今天晴，25℃"

# 模型能"看到"工具的描述和参数，自己决定调哪个
tools = [calculator, get_weather]
model_with_tools = model.bind_tools(tools)

你 W2 的 fc_loop 手写了"拼 tool schema + 解析 tool_calls + 循环"。@tool 装饰器把函数自动变成标准接口，省掉手写 schema。

`bind_tools` + 工具调用循环

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


from langchain_core.messages import HumanMessage, ToolMessage

msg = model_with_tools.invoke("北京天气怎么样？计算 12*8")
# msg.tool_calls 里有模型想调的工具和参数
for call in msg.tool_calls:
 fn = {"calculator": calculator, "get_weather": get_weather}[call["name"]]
 result = fn.invoke(call["args"]) # 执行工具
 # 把结果回灌给模型，让它继续决定下一步（这就是 Agent 循环）
 follow = model_with_tools.invoke([
 HumanMessage("北京天气怎么样？计算 12*8"),
 msg,
 ToolMessage(content=str(result), tool_call_id=call["id"]),
 ])

十一、Agent 智能体

本质：模型决定调哪个工具 → 执行 → 结果喂回 → 再决定

你 W2 的 fc_loop 就是这个循环的标准化版本。LangChain 提供 create_react_agent 等高级封装：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


from langchain.agents import create_react_agent, AgentExecutor

prompt = ChatPromptTemplate.from_messages([
 ("system", "你是一个助手，可用工具完成任务。"),
 ("user", "{input}"),
 ("assistant", "{agent_scratchpad}"), # 思考轨迹占位
])
agent = create_react_agent(model_with_tools, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

print(executor.invoke({"input": "北京天气怎么样？再算下 12*8"})["output"])

AgentExecutor 帮你把"调模型 → 解析 tool_calls → 执行 → 回灌"的循环跑完。你自研的 fc_loop 逻辑完全等价，只是它更通用。

十二、Callbacks 回调

监听链路每一步事件（调试 / 日志 / 计费）

1
2
3
4


from langchain_core.callbacks import StdOutCallbackHandler

# verbose 等价写法：把回调传进 invoke
chain.invoke({"question": "你好"}, config={"callbacks": [StdOutCallbackHandler()]})

生产环境常用自定义 callback 统计 token 消耗、记录每次 LLM 调用——对应你 Vibe Coding 手册里"操作透明、禁止黑盒"的纪律。

十三、LangGraph 状态图（进阶）

`StateGraph` —— 把流程编排成"有状态 + 可有环"的图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


from langgraph.graph import StateGraph, END
from typing import TypedDict, Annotated
import operator

class State(TypedDict):
 question: str
 answer: str
 steps: Annotated[list, operator.add] # 累加型字段，每步追加

def call_model(state: State):
 state["answer"] = chain.invoke({"question": state["question"]})
 state["steps"].append("call_model")
 return state

def should_continue(state: State):
 return END if "结束" in state["answer"] else "call_model" # 条件边

graph = StateGraph(State)
graph.add_node("call_model", call_model)
graph.add_edge("call_model", "call_model") # 自环：可多轮
graph.add_conditional_edges("call_model", should_continue)
app = graph.compile()

print(app.invoke({"question": "你好", "steps": []}))

LangGraph = LCEL 的"有环升级版"。你 W4 学的 RunnableLambda（node）、RunnableBranch（conditional edge）在这里成了 add_node / add_conditional_edges 的一等公民。W5 你会把手写 Agent 的循环搬进状态图。

十四、常用技巧与踩坑

技巧 1：流式 + 解析器组合

1
2


for chunk in chain.stream({"question": "数到5"}):
 print(chunk, end="", flush=True) # StrOutputParser 保证每块是 str

技巧 2：batch 并发提速

1

results = chain.batch([{"question": "1+1"}, {"question": "2+2"}]) # 比循环 invoke 快

技巧 3：降级保护

生产代码用 try/except 包住导入，导入失败就退回最小实现（见第八节 _MiniMM），保证程序不崩。

踩坑 1：相对导入直接跑脚本会炸 ⚠️

from ..memory import X 在 python xxx.py 下必然失败。改用 sys.path.insert(0, 根目录) + 绝对导入，或 python -m 包.模块。

踩坑 2：版本弃用 ⚠️

旧教程的 LLMChain、ConversationChain、initialize_agent 已弃用。坚持用 LCEL（core）+ create_react_agent + LangGraph。

踩坑 3：parser 输出类型 ⚠️

验收用 isinstance(result, str)，别写死类名（跨版本包装层会变）。

踩坑 4：流式不能用普通函数截断 ⚠️

RunnableLambda 包的函数在 .stream() 下要支持流式透传，否则丢字。简单场景用 StrOutputParser 最稳。

十五、小结

LangChain 看着庞大，日常 80% 的场景只用这几样：ChatPromptTemplate 拼提示 + ChatOpenAI 调模型 + StrOutputParser 解析 + | 串成链 + RunnableLambda 接你的老代码。先把这条主线跑熟，记忆/检索/工具/Agent 都是往这条主线上挂模块。

回顾你 W1-W3 的手写轮子，对应关系是：

你自研的	LangChain 标准件
`RealLLM` / `llm_client`	`ChatOpenAI`
`prompt_lib`	`ChatPromptTemplate`
手动取 `.content` / `json.loads`	`StrOutputParser` / `JsonOutputParser`
`fc_loop` 工具循环	`Agent` / `bind_tools` / `ToolMessage`
`MemoryManager`	`Memory` + `RunnableLambda` 接入
Chroma 长期记忆	`VectorStore` / `Retriever`
`tools/` 注册表	`@tool` 装饰器

框架化不是学新东西，是把手动接线变成标准管道。 你已有的底层认知（token、记忆、压缩、工具循环）全部复用，只是换了更通用的语法。

下一篇建议深入 LangGraph：把 Agent 的多轮循环、条件分支、状态共享，用状态图标准化——那是 W5 的主战场，也是你手写 fc_loop / MemoryManager 的自然归宿。

记住一条铁律：凡是接你自研代码的，先想"它实现 Runnable 了吗？没实现就包一层 RunnableLambda"；凡是接 dict 消息的，先想"prompt 要的是消息对象吗？要就过一道 _to_lc"。这两道桥通了，LangChain 的大门就彻底打开了。

LangChain_Memory

Tue, 25 Aug 2026 07:44:10 +0800

辛辛苦苦写的 MemoryManager（短期窗口 + 长期 Chroma + 滚动压缩），它的 get_context() 返回的是一串 dict 消息。而 LangChain 的 prompt 里 ("placeholder", "{history}") 需要的，是 BaseMessage 对象（HumanMessage / AIMessage / SystemMessage）。

这中间隔着一层「格式不对」——dict 直接喂进去，prompt 展开不了，链就哑火。

D3 要做的，就是补上这层转换，让「取记忆」成为链的头一个环节。而补这层只需要三件东西，刚好对应你给的 lc_memory.py 里「入口适配层」的三大件：

_to_lc = 把 dict 翻成 LangChain 消息对象（格式转换器）
lambda = 一次性匿名函数 + 字典解包（在链首「加料」）
RunnableLambda = 把函数包成能入 | 管道的零件（适配器）

一句话：W3 的决策逻辑一行不改，只在外面套一层「适配器」，就能进 LangChain 的链。 这和你 W3 博客里说的「最小侵入」是一回事。

一、大局：记忆接在链的哪个位置

先看整条链的数据流向——记忆是「链首的第一道工序」：

1
2
3
4
5
6
7


用户输入 {"question": "我叫什么？"}
 ↓
load_mem (RunnableLambda) ← ① 给输入"加料"：补上 history 字段
 ↓
prompt (ChatPromptTemplate) ← ② {history} 和 {question} 这下都有值了
 ↓
model → parser ← ③ 生成回答

拆开看三大件各自在哪、干嘛：

部件	角色	一句话
`_to_lc(m: dict)`	格式转换器	dict 消息 → LangChain `BaseMessage` 对象
`lambda x: {...}`	一次性函数	在链首把 `history` 字段「加」进输入
`RunnableLambda(...)`	适配器	把上面的函数包成能进 `

接下来逐个拆。

二、`_to_lc`：dict → LangChain 消息对象（快递打包）

一句话：把「散装 dict 消息」翻译成「LangChain 标准消息对象」。

你的 MemoryManager.get_context() 返回的是普通 dict 列表：

1
2


[{"role": "user", "content": "我叫小明"},
 {"role": "assistant", "content": "你好小明"}]

但 LangChain 的 prompt 里 ("placeholder", "{history}") 需要的是消息对象，不是 dict。所以必须转换：

1
2
3
4
5
6
7


def _to_lc(m: dict):
 role, content = m.get("role", "user"), m.get("content", "") # 取出角色和内容，role 缺省默认 user
 if role == "system":
 return SystemMessage(content=content) # system → SystemMessage
 if role == "assistant":
 return AIMessage(content=content) # assistant → AIMessage
 return HumanMessage(content=content) # 其他（user）→ HumanMessage

类比：快递打包。你的记忆模块产出的是「散装货物」（dict：一张纸写着「谁说的 + 说了啥」），而 LangChain 的传送带只认「标准包装箱」（BaseMessage 对象）。_to_lc 就是打包员——按「谁说的」（role）选不同规格的箱子（Human/AI/System），把货装进去。

为什么 m.get("role", "user") 要带默认值？ 因为 get 是「有就拿，没有给默认」——万一某条消息漏写了 role，就按用户消息处理，不崩。这是防御性写法，跟你在 auto_select / MemoryManager 里用的「宽容解析」一个思路。

对照自研：你 W3 写 compress.py 时，把消息喂给 LLM 做摘要前，其实也隐含了这一层「dict → 文本」的转换（你当时用了 _fmt 拍平成纯文本）。只不过 LangChain 这边的「标准箱」是对象而不是字符串——道理一样：框架要的是它认得的格式，你得先把货装进它的箱子。

三、`lambda` 表达式 + 字典解包（链首加料）

lambda = 一次性匿名函数。语法只有一句话：lambda 参数: 返回值表达式。

1
2
3
4
5
6
7


# 你的代码里：
lambda x: {**x, "history": get_history(x)}
# ↑参数 ↑ 返回表达式（一个字典）

# 它等价于这个 def：
def 匿名函数(x):
 return {**x, "history": get_history(x)}

类比：便利贴 vs 正式文件。def 是正式文件（有名字、能反复用）；lambda 是便利贴——写完就用、用完就扔，适合「只在这一个地方用一次」的小函数。

为什么用 lambda 而不是 def？ 因为 RunnableLambda 只需要一个「输入→输出」的函数，而这个函数只在这一行用一次，没必要单独起个名字占地方。

{**x, "history": ...} 字典解包是什么？ **x 是把字典 x 的所有键值对「展开」，然后放进一个新字典：

1
2
3
4


x = {"question": "我叫什么？"}

{**x, "history": ["..."]}
# 展开 x → {"question": "我叫什么？", "history": ["..."]}

为什么不直接写 x["history"] = ...？ 因为那会修改原字典（副作用）。链式调用里要保持「纯函数」——输入不被改动，只产出新结果。{**x, ...} 是复制一份再追加，原输入 x 完好无损。

类比：复印并加批注——原文件不动，复印件上多了一行批注。这正是 D2 学的 RunnablePassthrough.assign 干的事，这里用字典解包手动实现了一遍。

所以这一行 lambda x: {**x, "history": get_history(x)} 的含义就是：拿到用户的 {"question": ...}，复印一份，再往里塞一个 history 字段（内容是记忆系统的召回结果），原样返回给下一个环节。

四、`RunnableLambda`：把函数变成能入链的零件（插头转换器）

一句话：把普通 Python 函数包装成「能参与 | 管道的零件」。

LangChain 的 | 传送带有规矩：每个零件都必须实现 Runnable 协议（有 invoke / stream / batch 方法）。你的 get_history() 是普通函数，没有这些方法，直接放管道里会崩：

1
2
3
4
5
6


# ❌ 直接放普通函数：
chain = get_history | prompt | model | parser # 报错：get_history 不是 Runnable

# ✅ 包一层 RunnableLambda：
load_mem = RunnableLambda(get_history)
chain = load_mem | prompt | model | parser # 能跑！

类比：插头转换器。你的函数是「两脚插头」（普通函数），LangChain 的管道是「三脚插座」（Runnable 协议）——直接插不进去，套个转换器（RunnableLambda）就通了。

这你其实在 D2 步骤 E 已经亲手跑过：RunnableLambda(TextCleansing)——当时是给链尾加了个「清洗加工站」，现在是给链首加了个「加载历史加工站」，同一个东西，位置不同。所以 D3 的桥，D2 就已经修好了，你只是把它从链尾挪到了链首。

⚠️ 类型对接（跟 D2 踩坑记④一致）：RunnableLambda 收到的是管道里上一个的输出类型。这里 load_mem 是链首，它收到的是你 .invoke({"question": ...}) 传进去的 dict，所以 lambda x 的参数 x 是 dict，x.get("question") 才对得上。如果上一个产出是 str，参数就得是 str。

五、完整可运行演示（不需要 API key）

先跑这个，把三个概念一次看懂——它不调模型，纯演示「转换 + 加料 + 入链」：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


# concepts_demo.py —— 三个概念一次看懂（无需 API key）
from langchain_core.messages import SystemMessage, HumanMessage, AIMessage
from langchain_core.runnables import RunnableLambda

# ---------- 1. _to_lc：dict → 消息对象 ----------
def _to_lc(m: dict):
 role, content = m.get("role", "user"), m.get("content", "")
 if role == "system":
 return SystemMessage(content=content)
 if role == "assistant":
 return AIMessage(content=content)
 return HumanMessage(content=content)

raw = [{"role": "user", "content": "我叫小明"},
 {"role": "assistant", "content": "你好小明"}]
msgs = [_to_lc(r) for r in raw]
for m in msgs:
 print(type(m).__name__, "→", m.content)
# HumanMessage → 我叫小明
# AIMessage → 你好小明

# ---------- 2. lambda 语法 ----------
f = lambda x: x + "！" # lambda 参数: 返回表达式
def f_def(x): return x + "！" # 等价 def
print(f("你好"), "==", f_def("你好")) # 你好！ == 你好！

# ---------- 3. RunnableLambda + 字典解包 ----------
def get_history(x):
 return [_to_lc(r) for r in raw] # 返回消息对象列表（就是 _to_lc 的用武之地）

load_mem = RunnableLambda(lambda x: {**x, "history": get_history(x)})

result = load_mem.invoke({"question": "我叫什么？"})
print(result.keys()) # dict_keys(['question', 'history'])
print(result["history"]) # [HumanMessage, AIMessage] —— prompt 的 {history} 就能展开了

跑一下，你会看到：lambda 收到 {"question": ...}，返回一个新字典，原字段保留、history 字段追加——然后 prompt 里的 {question} 和 {history} 就都有值了。

六、`lc_memory.py` 完整代码（真实接 MemoryManager）

下面是把 W3 的 MemoryManager 真正接进链的版本。get_history 调的是 _mm.get_context(query=...)（带长期召回），_to_lc 负责格式转换，load_mem 用 RunnableLambda 包起来放到链首：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83


# lc_memory.py —— W3 MemoryManager 接进 LCEL 链（入口适配层）
import os
from dotenv import load_dotenv
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from langchain_core.output_parsers import StrOutputParser
from langchain_core.runnables import RunnableLambda
from langchain_core.messages import SystemMessage, HumanMessage, AIMessage

load_dotenv()

# 桥的包装器：dict 消息 → LangChain BaseMessage
def _to_lc(m: dict):
 role, content = m.get("role", "user"), m.get("content", "")
 if role == "system":
 return SystemMessage(content=content)
 if role == "assistant":
 return AIMessage(content=content)
 return HumanMessage(content=content)

# 接入 W3 自研 MemoryManager（失败则降级最小窗口版）
# ⚠️ 注意：直接 `python lc_memory.py` 运行时，下面这行相对导入会找不到包——
# 因为直接运行脚本时 Python 把它当顶层模块，无法解析 "..memory" 这类上级路径。
# 正确做法（二选一）：
# 1) 把项目根目录加入 sys.path 再用绝对导入（见下方注释）；
# 2) 用 `python -m 包名.模块名` 启动，而非直接执行脚本文件。
try:
 from memory.memory_manager import MemoryManager
 _mm = MemoryManager(window=6, max_tokens=500)
 def get_history(x):
 # 真实版：query=本轮问题 → 长期召回 + 滚动窗口
 return [_to_lc(m) for m in _mm.get_context(query=x.get("question"))]
except Exception as e:
 print(f"[降级]未找到memory包({e}),使用最小窗口版")
 class _MinilMM:
 def __init__(self, window=6):
 self.buf, self.window = [], window
 def get_context(self, query=None):
 return self.buf[-self.window:]
 def add_user(self, t):
 return self.buf.append({"role": "user", "content": t})
 def add_ai(self, t):
 self.buf.append({"role": "assistant", "content": t})
 _mm = _MinilMM()
 def get_history(x):
 return [_to_lc(m) for m in _mm.get_context()]

# 链：链首选历史，再 prompt | model | parser
model = ChatOpenAI(
 model="deepseek-v4-flash",
 api_key=os.getenv("DEEPSEEK_API_KEY"),
 base_url="https://api.deepseek.com",
)

prompt = ChatPromptTemplate.from_messages([
 ("system", "你是一个有记忆的助手，记得之前聊过的内容。"),
 ("placeholder", "{history}"), # 关键：展开历史 messages
 ("human", "{question}"),
])

load_mem = RunnableLambda(lambda x: {**x, "history": get_history(x)})
chain = load_mem | prompt | model | StrOutputParser()

def ask(question: str) -> str:
 ans = chain.invoke({"question": question})
 if hasattr(_mm, "add_user"):
 _mm.add_user(question); _mm.add_ai(ans)
 else:
 _mm.add({"role": "user", "content": question})
 _mm.add({"role": "assistant", "content": ans})
 return ans

if __name__ == "__main__":
 # 验收：第 2、3 问能答出「篮球」「小明」=> 记忆生效
 for q in ["我叫小明，喜欢打篮球", "我刚说的爱好是什么？", "我名字叫什么？"]:
 print(f"Q: {q}\nA: {ask(q)}\n")

 # 确认 load_mem 在链首 + 看历史在累积
 print("=== 链结构图（load_mem 应排最前）===")
 chain.get_graph().print_ascii()
 print("=== 当前记忆历史 ===")
 for m in _mm.get_context():
 print(f" {m.get('role')}: {m.get('content')}")

("placeholder", "{history}") 是 LangChain 专门用来「展开一个消息列表」的占位符——它和 ("human", "{question}") 不同：后者填的是字符串，前者填的是消息对象列表，会被逐条展开成多轮对话历史。这就是 _to_lc 存在的意义。

七、踩坑记 & 知识点

① 相对导入在「直接运行脚本」时会炸 from memory.memory_manager import MemoryManager 只在「包上下文」里成立。你 python lc_memory.py 直接跑，Python 把文件当顶层脚本，__package__ 为空，解析不了 ..memory 这种上级路径，就抛 ModuleNotFoundError。

两种修法（二选一）：

加 sys.path 补丁：在导入前把项目根目录塞进 sys.path，再绝对导入（注释里写了模板）；
用 -m 启动：cd 到 AgentLearn\ 后 python -m memory.lc_memory（或对应包路径），Python 基于 cwd 找顶层包，自然能 import。

我上面的代码用 try/except 做了优雅降级——找不到真实 MemoryManager 就退回到一个最小窗口版，保证链一定能跑通、你能先看效果。但生产里你还是得用上面两种修法之一把真实版接上。

② placeholder 占位符要配「消息对象列表」，不是字符串 {history} 用 ("placeholder", ...) 声明，传进去的必须是 [HumanMessage, AIMessage, ...] 这种列表。如果你直接传字符串，LangChain 会不知道怎么展开。所以 _to_lc 把 dict 翻成对象这步，不能省。

③ lambda 里用 {**x, ...} 而不是 x["k"]=...（纯函数） 前面讲过：前者复制一份再追加，原输入不动；后者直接改原 dict，会在链式调用里留下副作用，导致后面环节拿到被偷偷改过的输入，极难排查。进 | 管道的函数，尽量写成纯函数。

④ RunnableLambda 的「输入输出类型」要对接上一个 Runnable load_mem 是链首，收到的是你 .invoke({"question": ...}) 传的 dict，所以 lambda x 里 x 是 dict、x.get("question") 对得上。若把 load_mem 挪到链中间（比如接在 prompt 后面），它收到的就会是 prompt 的输出了——类型全变，得重写函数。改完链先 get_graph().print_ascii() 看一眼流向（跟 D1/D2 踩坑记一脉相承）。

⑤ _mm.add_user / add_ai 是降级版的「自造」方法 真实 MemoryManager 的接口是 add({"role":..., "content":...})（你 W5 博客里写过）。降级类 _MinilMM 是我手写的最小版，用了 add_user/add_ai 方便演示——所以 ask() 里用 hasattr(_mm, "add_user") 来区分「降级版」和「真实版」，分别走不同写入路径。这提醒你：接第三方/自研模块时，先确认它的真实接口长啥样，别凭想象调方法。

八、总结

今天把 W3 的 MemoryManager 接进了 LangChain 链，靠的是「入口适配层三件套」——而且 W3 的决策逻辑一行没改，只是外面套了层适配器：

_to_lc = 格式转换器（dict → BaseMessage），快递打包员：按 role 选箱子
lambda + {**x, ...} = 链首加料（保留原输入 + 追加 history），便利贴 + 复印加批注
RunnableLambda = 适配器（普通函数 → 能进 | 管道），插头转换器：D2 的加工站从链尾挪到了链首

整条链：load_mem | prompt | model | parser——记忆从此成为「链的首道工序」，而不是链外的黑盒。

这印证了你 W3 博客那句结论：「最小侵入」——框架化不是重写逻辑，是把旧轮子套上标准接口。 你前三周手写的所有零件，到 W4 一个个「认领」进 LangChain，没有任何一个被推倒重来。

九、下一篇预告

D4：把 Retriever / RAG 也接进链（长期记忆的「知识版」）

今天接的是「对话记忆」（短期窗口 + 你手动落的事实）。但 W3 你还有一个更重的资产——Chroma 长期向量记忆，那东西在 LangChain 里叫 Retriever。

D4 要做的，是把 MemoryManager 里「长期召回」那部分，用 LangChain 的 Retriever 标准接口重写一遍——让你 W3 手写的向量召回，变成 chain 里的一环。而「对话记忆」和「知识召回」这两种 history，会在链首被 RunnableParallel / assign 一起拼进 prompt。

再往后，W5 LangGraph 会把今天这条「线性带记忆的链」升级成「有状态图」：每个零件变成 node，MemoryManager 变成图里一个会读写状态的节点。你 W4 这四天铺的路，正好接上 W5 的 node/edge。

一句话收尾：D1-D3 你学会了「零件怎么串、函数怎么进链、记忆怎么接入」；D4 补上「知识怎么召回」，W5 就轮到「流程怎么分叉」。

LangChain 入门 + LCEL

Sun, 23 Aug 2026 02:39:38 +0800

W4 · LCEL：用管道把零件串成流水线

关键词：LCEL / Runnable / 声明式 / 零件库 + 组装流水线前置：W1 llm_client、W2 fc_loop、W3 MemoryManager（全是手撸）收尾预告：W5 LangGraph —— node/edge 的雏形

翻车前的自白

W1 你写 llm_client，每次调完模型都要手动抠 resp.choices[0].message.content； W2 你写 fc_loop，自己拼 tools schema、解析 tool_calls、再写循环； W3 你写 MemoryManager，短期窗口、长期 Chroma、滚动压缩，全自己管。

回头看，这三周你一直在做同一件事：手动接线。

每加一个功能，就多一串「把 A 的输出塞进 B 的输入」的胶水代码。功能一多，胶水比功能还多——这就是手写 Agent 的隐性成本。

W4 要解决的，就是这团胶水。LCEL 不是新概念，是把你 W1-W3 的手动接线，标准化成一条「传送带」。

零、LangChain 是什么？

如果你之前只用手写 requests 或 openai SDK 直连大模型，第一次听到「LangChain」大概率会懵：这玩意儿和「直接调 API」差在哪？

一句话：LangChain 是一套给 LLM 应用用的「乐高积木 + 说明书」。

先想清楚：不用框架，你怎么调大模型？

裸调一个模型，你其实要手写一堆「杂活」：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


# 没有框架时，一次问答你要操心的事
import openai

# 1. 自己拼消息格式
messages = [
 {"role": "system", "content": "你是一个简洁的助手"},
 {"role": "user", "content": "什么是 LCEL？"},
]

# 2. 自己发起请求
resp = openai.chat.completions.create(
 model="xxx",
 messages=messages,
)

# 3. 自己从嵌套结构里抠出文本
text = resp.choices[0].message.content

# 4. 想要流式？再写一套 chunk 拼接逻辑
# 5. 想要批量？再写一套并发
# 6. 想接数据库/工具/记忆？每一块都自己接线

上面 6 步，每一步都是「胶水」。功能越复杂，胶水越多。这就是你 W1-W3 手写 Agent 的真实体感——你不是在写业务，是在写「让零件转起来的 plumbing」。

LangChain 把这堆杂活标准化了

LangChain 做的事，本质上是把上面那些重复的 plumbing 抽成可复用的标准零件，再用统一的接口（Runnable）接起来：

1
2
3
4
5
6


没有框架： 有了 LangChain：
你写 plumbing ──→ 你只声明「要什么」：
requests请求 chain = prompt | model | parser
手抠 .content 框架自动：拼消息→请求→抠结果→流式/批量
自己写流式/批量
自己接工具/记忆

所以它不是「另一个能调模型的库」——openai SDK 也能调模型。它是「调模型之上的那层编排」：当你需要的不是「问一句话」，而是「带记忆、能查资料、会调工具、能多轮决策」的应用时，框架的价值才显出来。

LangChain 全家福（你后面会陆续碰到）

包名	干什么	你现在用到没
`langchain-core`	最核心：Runnable 接口、LCEL 管道、`	`
`langchain-openai`	把 OpenAI / DeepSeek(兼容) 等模型接进来	✅ 本文用到
`langchain-community`	社区集成：各种向量库、工具、检索器	⏳ 后面接 Chroma/工具时
`langchain`	上层高级封装（chains/agents 老接口）	⏳ 渐进接触
`langgraph`	有状态图编排（W5 主角）	⏳ 下周

记住一句话就够了：LangChain = 「调模型之上的编排层」。你 W1-W3 手写的那些零件，它都有现成的；你手写那些胶水，它用 | 一条管道替你接好。

回到开头那句自白：你前三周手写的所有东西，不是白写——它们让你亲手踩过每个零件的坑，所以现在看 LangChain，你是在「认领」自己造过的轮子，而不是从天书开始学。

一、LCEL 到底是什么？

LCEL（LangChain Expression Language）= 用 | 把零件串成流水线。

它是 LLM 应用的「零件库 + 组装流水线」：零件（模型、提示词、解析器、记忆、检索、工具）是标准化的，组装方式（管道 |）也是标准化的。

一句话记忆：| 就是传送带，前一个的输出自动变成后一个的输入。

为什么需要它（对照你的自研）

你自研的（W1-W3）	LangChain 里的名字	一句话
`RealLLM` / `llm_client`	`ChatOpenAI` / `ChatModel`	调模型的封装
`prompt_lib`（W1）	`ChatPromptTemplate`	提示词模板
手动取 `.content` / `json.loads`	`StrOutputParser` / `JsonOutputParser`	解析 AI 输出
`fc_loop` 工具循环（W2）	`Agent` / Tool Calling	工具调用循环
`MemoryManager`（W3）	`Memory`（或包一层自研）	记忆
Chroma 长期记忆（W3）	`Retriever` / `VectorStore`	向量召回
`tools/` 注册表（天气/计算器）	`@tool` 装饰器	工具标准接口

关键认知：框架化不是「学新东西」，是「把你的手动接线变成标准管道」。右边每一格，你左边都写过一遍——所以你不是在从零学，是在给旧东西换统一接口。

LangChain / LangGraph 是 Agent 岗位出现率最高的框架。会这套「通用语言」，比会某个手写实现更有市场价值。

二、八个零件：从你的自研到 LangChain

LangChain 把 LLM 应用拆成 8 个标准化零件。下面每个都对应你 W1-W3 的代码——你早就造过它们，只是名字不同。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


┌──────────────────────────────────────────────────────────┐
│ 1. Model（模型）= 厨师 │
│ 你已有 RealLLM。ChatOpenAI 是"统一厨师证"—— │
│ DeepSeek/通义/Kimi 都一个接口，走 OpenAI 兼容协议， │
│ 换 base_url 就行（你早就这么干了） │
├──────────────────────────────────────────────────────────┤
│ 2. Prompt（提示词模板）= 菜谱模板 │
│ 你 W1 的 prompt_lib。ChatPromptTemplate 支持 {变量} 插值： │
│ "请翻译成英文：{text}"，传 {"text":"你好"} 自动填 │
├──────────────────────────────────────────────────────────┤
│ 3. OutputParser（输出解析器）= 装盘 │
│ 你平时手动 json.loads(...)。StrOutputParser 把复杂输出 │
│ 变纯字符串；JsonOutputParser 帮你做 json.loads │
├──────────────────────────────────────────────────────────┤
│ 4. Chain / LCEL（链）= 传送带 ⭐ 本周核心 │
│ 前者的输出自动变后者的输入。"声明式"：你描述"要什么流程"， │
│ 不用写"怎么一步步调" │
├──────────────────────────────────────────────────────────┤
│ 5. Memory（记忆）= 记忆 │
│ 你 W3 的 MemoryManager 已经很强（短期窗口+长期Chroma+ │
│ 滚动压缩）。本周 D3 把它接进链，而不是重写 │
├──────────────────────────────────────────────────────────┤
│ 6. Retriever（检索器）= 档案室管理员 │
│ 你 W3 的 Chroma 就是这个。RAG 的"知识记忆"和你的 │
│ "长期向量记忆"是同一个东西——接一次复用，不另起炉灶 │
├──────────────────────────────────────────────────────────┤
│ 7. Tool（工具）= 工具箱 │
│ 你 W2 的天气、计算器。LangChain 用 @tool 装饰器把函数 │
│ 变成"模型可调用的工具" │
├──────────────────────────────────────────────────────────┤
│ 8. Agent（智能体）= 服务员 │
│ 你 W2 的 fc_loop：模型决定调哪个工具→执行→结果喂回→再决定。│
│ LangChain 的 Agent 把这个循环标准化了 │
└──────────────────────────────────────────────────────────┘

三个核心概念先记住（它们是 W5 LangGraph 的 node/edge 雏形）：

Chain = 组合：把零件用 | 串起来
Retriever = 取数：从外部/向量库取上下文
Tool = 可调函数：模型能主动调用的函数

三、工厂流水线：prompt | model | parser

LCEL 最小形态就是一条三件套链。| 是传送带——配料出来自动进加工机，加工完自动进包装机。

1
2
3
4
5
6
7
8
9


PromptInput ← 入口：你传的 {"question": "..."}（dict）
 ↓
ChatPromptTemplate ← 配料机：dict → [system, user] 消息列表
 ↓
ChatOpenAI ← 加工机：消息 → AIMessage
 ↓
StrOutputParser ← 包装机：AIMessage → 纯字符串
 ↓
StrOutputParserOutput ← 出口：str

声明式 vs 命令式（这是 LCEL 的精髓，面试爱问）：

命令式（你 W1-W3 的写法）：resp = client.chat(...); text = resp.choices[0].message.content——你写「怎么一步步调」
声明式（LCEL）：chain = prompt | model | parser——你只描述「要什么流程」，中间的传递、类型转换全交给框架

这就是为什么叫「表达式语言」：你写的是一个表达式（一条链），不是一串语句。

四、最小可跑代码（逐块讲解）

先装依赖（一行命令）：

1
2


pip install langchain langchain-openai langchain-community python-dotenv
pip install -U langchain langchain-openai langchain-core

① 配料机：ChatPromptTemplate

1
2
3
4
5
6
7


from langchain_core.prompts import ChatPromptTemplate

# {question} 是占位符，invoke 时传 dict 自动填
prompt = ChatPromptTemplate([
 ("system", "你是一个简洁的助手"),
 ("user", "{question}"),
])

对应你 W1 的 prompt_lib：把「系统提示 + 用户问题」拼成消息列表，但不用你手写 f-string 拼接了。

② 加工机：ChatOpenAI（接 DeepSeek）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI

load_dotenv()

# DeepSeek 走 OpenAI 兼容协议：换 model 名 + base_url 即可
model = ChatOpenAI(
 model="deepseek-v4-flash",
 api_key=os.getenv("DEEPSEEK_API_KEY"),
 base_url="https://api.deepseek.com",
)

对应你 W1 的 RealLLM：你当时就是靠 base_url 切到 DeepSeek 的。ChatOpenAI 是「统一厨师证」——DeepSeek、通义、Kimi 都是同一套接口，换 model + base_url 就行，不用为每家重写客户端。

③ 包装机：StrOutputParser

1
2
3
4


from langchain_core.output_parsers import StrOutputParser

# AIMessage → 纯字符串，对应你平时手写的 .content 提取
parser = StrOutputParser()

对应你 W1 手动抠的 resp.choices[0].message.content——现在一句 StrOutputParser() 替代，而且流式/批量场景自动适配。

④ 传送带：一条链

1
2


# 核心就这一行：前一个的输出自动喂给后一个
chain = prompt | model | parser

这就是本周核心。| 把三个零件声明式地组装成 Runnable。

⑤ 三种调用方式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


# invoke：一次性拿到完整结果
result = chain.invoke({"question": "什么是 LCEL？"})
print(isinstance(result, str)) # True ← 这才是验收

# stream：流式，一个字一个字往外冒（对应你 W3 博客里写的 streaming）
for chunk in chain.stream({"question": "数到5"}):
 print(chunk, end="", flush=True)

# batch：一次处理多个输入，框架自动并行
results = chain.batch([
 {"question": "1+1=?"},
 {"question": "2+2=?"},
])
print(results)

# get_graph：把链结构打印成 ASCII 图，肉眼确认流向
chain.get_graph().print_ascii() # 应看到 prompt → model → parser

invoke / stream / batch 是 LCEL 所有 Runnable 的统一三件套——你写的任何链都自动获得这三种能力，不用自己实现。

五、完整代码（可直接抄）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52


# 安装依赖
# pip install langchain langchain-openai langchain-community python-dotenv
# pip install -U langchain langchain-openai langchain-core

# 最小 LCEL 链：管道 prompt | model | parser

import os
from dotenv import load_dotenv
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from langchain_core.output_parsers import StrOutputParser

load_dotenv()

# 配料机：{question} → [system, user] 消息
prompt = ChatPromptTemplate([
 ("system", "你是一个简洁的助手"),
 ("user", "{question}"),
])

# 加工机：ChatOpenAI 接 DeepSeek（OpenAI 兼容协议，换 base_url 即可）
model = ChatOpenAI(
 model="deepseek-v4-flash",
 api_key=os.getenv("DEEPSEEK_API_KEY"),
 base_url="https://api.deepseek.com",
)

# 包装机：AIMessage → 纯字符串
parser = StrOutputParser()

# 传送带：一条链
chain = prompt | model | parser

# 调用
print("=== invoke ===")
result = chain.invoke({"question": "什么是 LCEL？"})
# StrOutputParser 返回 Python str
print(isinstance(result, str)) # True ← 这才是验收

print("\n=== stream（流式，一个字一个字冒）===")
for chunk in chain.stream({"question": "数到5"}):
 print(chunk, end="", flush=True)

print("\n\n=== batch（一次处理多个）===")
results = chain.batch([
 {"question": "1+1=?"},
 {"question": "2+2=?"},
])
print(results)

print("\n=== 链结构图 ===")
chain.get_graph().print_ascii() # 应看到 prompt → model → parser 的流向

六、踩坑记 & 知识点

① 验收用 isinstance(result, str)，别 assert 具体类名 StrOutputParser 在不同 LangChain 版本里，底层返回类型可能裹一层包装类型（比如某些版本会看到 TextAccessor 这类名字）。跨版本会变的是具体类名，不会变的是「它是 str 的子类」。所以稳健验收写 isinstance(result, str) == True，不要写 type(result).__name__ == 'str'，后者会在版本升级时假红。

② DeepSeek 是 OpenAI 兼容协议，不是特例 你 W1 的 RealLLM 已经验证了 base_url="https://api.deepseek.com" 这套走法。ChatOpenAI 只是把这套走法做成标准接口——model 名按 DeepSeek 官方给的填（笔记里写的 deepseek-v4-flash 按你当时环境填，真实环境以官方模型名为准），api_key 走环境变量，别硬编码进代码（呼应你 Vibe Coding 手册里的「密钥不上库」红线）。

③ 「声明式」省的是胶水，不是脑子 chain = prompt | model | parser 看起来比手写 resp = ...; text = ... 短，但它没替你设计流程——你 still 得想清楚「先配料、再加工、再装盘」的顺序。LCEL 把「传递」自动化了，把「架构决策」留给你。这也是为什么 W3 的 MemoryManager 不用重写、直接包一层接进链——决策逻辑是你的，管道只是载体。

④ get_graph().print_ascii() 是你的排错眼 链一复杂（尤其后面接 Retriever / Tool / Memory），print_ascii() 能一眼看出「数据从哪流到哪、有没有断」。每次改完链先打一张图，比对着报错猜快十倍。

七、总结

LangChain 是 LLM 应用的编排框架：模型、提示词、解析器、记忆、检索、工具都标准化成 Runnable，用 LCEL 管道（|）声明式组合。

它和你 W1-W3 的自研一一对应——RealLLM=ChatModel、prompt_lib=ChatPromptTemplate、手动解析=OutputParser、fc_loop=Agent、MemoryManager=Memory、Chroma=Retriever。所以框架化不是学新东西，是把你的手动接线变成标准管道。

三个核心概念记住：Chain=组合、Retriever=取数、Tool=可调函数——这正是 W5 LangGraph 的 node/edge 雏形。

LangChain on 男娘教主

LangChain

LangChain

目录

一、LangChain 是什么（架构总览）

一句话定位

全景架构图

包结构 —— 别一股脑 pip install langchain 就完事

裸调 vs LangChain 对照（先理解痛点）

二、安装与环境

pip install —— 装依赖

.env + load_dotenv —— 密钥分离

三、Model 模型：ChatModel

ChatOpenAI —— 统一接口调任意兼容模型

invoke / stream / batch —— 三种调用方式

四、Prompt 提示词模板：ChatPromptTemplate

ChatPromptTemplate.from_messages —— 构造消息模板

MessagesPlaceholder —— 历史消息占位

partial —— 预填部分变量

五、OutputParser 输出解析器

StrOutputParser —— 把 AIMessage 变成纯字符串

JsonOutputParser —— 解析 JSON 输出

PydanticOutputParser —— 强类型结构化（进阶）

六、LCEL 链：Runnable 与管道

chain = prompt | model | parser —— 一条最小链

get_graph().print_ascii() —— 可视化整条链

Runnable 协议 —— 为什么能 |

七、Runnable 组合件

RunnableParallel —— 一条输入，并行出多个结果

RunnablePassthrough.assign —— 保留原输入，再追加新字段

RunnableLambda —— 任意 Python 函数入链（适配器）

RunnableBranch —— 条件分支（按判断走不同子链）

八、Memory 记忆

三种记忆模式

用 RunnableLambda 接入自研 MemoryManager（重点）

九、Retriever 检索与 RAG

RAG 流程：文档 → 切分 → 向量化 → 存入 → 检索 → 拼进 prompt

接进链（检索增强问答）

十、Tool 工具与 @tool

@tool —— 把函数变成模型可调用的工具

bind_tools + 工具调用循环

十一、Agent 智能体

本质：模型决定调哪个工具 → 执行 → 结果喂回 → 再决定

十二、Callbacks 回调

监听链路每一步事件（调试 / 日志 / 计费）

十三、LangGraph 状态图（进阶）

StateGraph —— 把流程编排成"有状态 + 可有环"的图

十四、常用技巧与踩坑

技巧 1：流式 + 解析器组合

技巧 2：batch 并发提速

技巧 3：降级保护

踩坑 1：相对导入直接跑脚本会炸 ⚠️

踩坑 2：版本弃用 ⚠️

踩坑 3：parser 输出类型 ⚠️

踩坑 4：流式不能用普通函数截断 ⚠️

十五、小结

LangChain_Memory

一、大局：记忆接在链的哪个位置

二、_to_lc：dict → LangChain 消息对象（快递打包）

三、lambda 表达式 + 字典解包（链首加料）

四、RunnableLambda：把函数变成能入链的零件（插头转换器）

五、完整可运行演示（不需要 API key）

六、lc_memory.py 完整代码（真实接 MemoryManager）

七、踩坑记 & 知识点

八、总结

九、下一篇预告

LangChain 入门 + LCEL

W4 · LCEL：用管道把零件串成流水线

翻车前的自白

零、LangChain 是什么？

先想清楚：不用框架，你怎么调大模型？

LangChain 把这堆杂活标准化了

LangChain 全家福（你后面会陆续碰到）

一、LCEL 到底是什么？

为什么需要它（对照你的自研）

二、八个零件：从你的自研到 LangChain

三、工厂流水线：prompt | model | parser

四、最小可跑代码（逐块讲解）

① 配料机：ChatPromptTemplate

② 加工机：ChatOpenAI（接 DeepSeek）

包结构 —— 别一股脑 `pip install langchain` 就完事

`pip install` —— 装依赖

`.env` + `load_dotenv` —— 密钥分离

`ChatOpenAI` —— 统一接口调任意兼容模型

`invoke` / `stream` / `batch` —— 三种调用方式

`ChatPromptTemplate.from_messages` —— 构造消息模板

`MessagesPlaceholder` —— 历史消息占位

`partial` —— 预填部分变量

`StrOutputParser` —— 把 AIMessage 变成纯字符串

`JsonOutputParser` —— 解析 JSON 输出

`PydanticOutputParser` —— 强类型结构化（进阶）

`chain = prompt | model | parser` —— 一条最小链

`get_graph().print_ascii()` —— 可视化整条链

Runnable 协议 —— 为什么能 `|`

`RunnableParallel` —— 一条输入，并行出多个结果

`RunnablePassthrough.assign` —— 保留原输入，再追加新字段

`RunnableLambda` —— 任意 Python 函数入链（适配器）

`RunnableBranch` —— 条件分支（按判断走不同子链）

用 `RunnableLambda` 接入自研 `MemoryManager`（重点）

`@tool` —— 把函数变成模型可调用的工具

`bind_tools` + 工具调用循环

`StateGraph` —— 把流程编排成"有状态 + 可有环"的图

二、`_to_lc`：dict → LangChain 消息对象（快递打包）

三、`lambda` 表达式 + 字典解包（链首加料）

四、`RunnableLambda`：把函数变成能入链的零件（插头转换器）

六、`lc_memory.py` 完整代码（真实接 MemoryManager）