LangChain 基础 on 扎塔-Zata

LangChain 常见报错与排查指南

Tue, 08 Sep 2026 13:30:00 +0800

LangChain 常见报错与排查指南

LangChain 应用报错时，最浪费时间的不是修，而是不知道问题出在哪一层。密钥、模型、提示、解析、编排——每一层的症状可能长得一样（都是「输出不对」），但修法完全不同。

最有效的第一步：先看模型的原始输出。把解析器临时换成 StrOutputParser（或直接 print 响应对象），原始输出正常，问题在解析层；原始输出本身就不对，问题在配置、提示或模型。这一步能省掉大半瞎猜时间。

先定位：问题出在哪一层

层	典型症状	排查手段
配置层	AuthenticationError、模型不存在	检查环境变量；用 curl 直接调平台 API 验证密钥
模型层	输出质量差、不按指令来	换 StrOutputParser 看原始输出；换模型对比
解析层	OutputParserException	确认原始输出没问题后，再调格式指令
编排层	Agent 死循环、链路数据对不上	`verbose=True`、LangSmith 追踪、astream_events

七类高频报错

1. API 密钥错误（AuthenticationError）

症状：提示 API 密钥无效、缺失或未设置。

原因：

环境变量没设置或没导出（OPENAI_API_KEY、DASHSCOPE_API_KEY 等）
密钥过期、被删或无效
账户余额不足（百炼这类预付费平台尤其常见）

解决：

print(os.getenv("OPENAI_API_KEY")) 确认进程内真的读到了
检查密钥有效性，必要时重新生成
确认账户状态和余额

2. 模型未找到（NotFoundError）

症状：提示指定的模型不存在或无法访问。

原因：

模型名拼写错误（比如把 qwen-plus 写成 qwen_plus）
模型对当前 API 密钥或账户不可用（部分模型需要专门开通权限）
API 服务区域问题

解决：

核对模型名拼写；模型名是精确匹配，多一个横线少一个点都不行
查提供商文档，确认模型可用性和访问权限

3. 提示模板错误（TemplateFormatError / MissingInputVariables）

症状：渲染提示时报错，或最终提示里出现了没被替换的 {variable}。

原因：

模板占位符与调用时传入的输入键不匹配
模板语法错误——f-string 风格里想输出字面量 { 却没写成 {{

解决：

确保调用链时提供了模板里所有占位符变量
单独测试渲染：prompt.invoke({...}) 看渲染结果是否符合预期

4. Agent 输出解析错误（OutputParserException）

症状：LLM 输出不符合 Agent 期望的格式（0.x 时代的 ReAct Agent 未能正确输出 “Thought:” / “Action:” 等）。

原因：

模型难以理解提示中的输出格式要求
提示过于复杂，或工具描述含糊导致模型困惑
模型能力不足

解决：

简化输出格式要求；在提示里加几个符合格式的 few-shot 示例
改进工具描述，写清楚功能和预期输入
handle_parsing_errors=True（0.x 的 AgentExecutor 参数）：把解析错误反馈给模型，让它自我纠正
换更强的模型

⚠️ 版本注记：这套症状主要属于 0.x 时代的文本协议 Agent（ReAct）。1.x 的 create_agent 走原生 tool calling，模型输出结构化 JSON，这类格式解析错误已大幅减少。自己写 Pydantic 解析时仍会遇到 OutputParserException，处理思路见本站《langchain_core 组件详解》。

5. 工具执行错误（ToolException）

症状：Agent 正确选中了工具，但工具执行失败。

原因：

传给工具的参数无效
工具依赖的外部服务不可用（限流、网络问题）
工具内部逻辑错误

解决：

工具内部用 try-except 捕获异常，返回有意义的错误信息给 Agent，而不是让它崩掉
在工具入口验证参数；把工具拿出来独立测试
在提示里引导 Agent：工具失败时换一种方法，或如实报告

6. 上下文长度超出（ContextWindowExceeded / InvalidRequestError）

症状：提示 + 对话历史 + 输出预留的总 token 超过模型上限。

原因：

对话历史无限累积
RAG 检索了过多的文档块
提示本身冗长

解决：

⚠️ 0.x 的 ConversationBufferWindowMemory / ConversationTokenBufferMemory / ConversationSummaryBufferMemory 已随 legacy memory 体系移除；现代等价做法是 LangGraph checkpointer + 消息裁剪（trim_messages），或对长输入做分块摘要（本站《订阅摘要 Agent 实战》有完整案例）
控制检索文档的数量和长度
精简提示；或换长上下文模型

7. Agent 死循环（MaxIterationsExceeded）

症状：Agent 反复执行同样的无效操作，直到达到迭代上限。

原因：

提示不清晰，无法引导 Agent 走向正确方向
工具集不完备，缺少解决任务所需的关键能力
LLM 在复杂推理中迷失

解决：

改进提示，给出明确的目标和终止条件
审查工具集是否齐备
谨慎加大迭代上限——0.x 是 AgentExecutor 的 max_iterations，LangGraph 时代对应 config 里的 recursion_limit；但先排查其他原因，调上限只是兜底
引入人工介入：Agent 卡住时让用户兜底

1.x 时代最常见的报错：import 一个已被移除的类

LangChain 1.0（2025 年 10 月发布）移除了全部 legacy 抽象。老教程代码今天最常见的死法不是逻辑错误，而是 import 直接报错：

ImportError: cannot import name 'LLMChain' from 'langchain.chains'

遇到这类报错，对照表查一下，基本都有明确的现代等价物：

被移除的老写法	现代等价物
`LLMChain`	LCEL 管道：`prompt \| llm \| parser`
`RetrievalQA`	LCEL 检索链，或 `create_retrieval_tool`
`ConversationChain`	LangGraph `StateGraph` + checkpointer
`initialize_agent` / `AgentExecutor`	`langchain.agents.create_agent`（1.x）/ `langgraph.prebuilt.create_react_agent`
`create_openai_functions_agent` 等旧 Agent 构造器	同上，统一到 `create_agent`，协议统一走 tool calling
`langchain.memory.*`（ConversationBufferMemory 等）	LangGraph checkpointer + 消息裁剪（`trim_messages`）
`load_summarize_chain`	LangGraph map-reduce，或 LCEL 手写
`langchain.text_splitter`	`langchain_text_splitters` 独立包
`langchain_community` 里的 ChatOllama / HuggingFaceEmbeddings	`langchain-ollama` / `langchain-huggingface` 独立包
`langchain_core.pydantic_v1`	直接用 pydantic v2

需要读存量老代码时，这份表反过来用就是「翻译词典」。

排查顺序清单

报错栈最底层是平台 API 的 4xx？→ 配置层，查密钥、模型名、余额
拿原始输出：StrOutputParser 或 print，判断问题在模型层还是解析层
是解析错？改格式指令 + few-shot + 重试
Agent 行为怪？开 verbose / 用 LangSmith 追踪，看每一步的消息流
还查不出来？把最小可复现片段剥出来单独跑

总结

报错先分层：配置 → 模型 → 解析 → 编排，症状会骗人，层不会
看原始输出是最快的定位手段
1.x 时代大半「奇怪的报错」其实是 import 了已移除的类，对照表一查便知
过程观测交给工具：LangSmith（见本站《LangSmith使用教程》）+ astream_events

LangChain 与 MCP 极简教程：让 Agent 接入外部工具的另一种方式

Tue, 08 Sep 2026 13:00:00 +0800

LangChain 与 MCP 极简教程

给 Agent 接工具，最常见的做法是把所有工具函数都写在应用代码里，再逐个注册给模型。工具少的时候没问题；一旦工具多起来、或者想跨项目复用，这条路就会越来越累——同样的工具，每个应用都要重新写一遍。

MCP（Model Context Protocol，模型上下文协议）是 Anthropic 在 2024 年底推出的开放协议，解决的就是这个问题：把「工具的定义和执行」从应用代码里拆出来，放到独立的服务器上，客户端按需发现和调用。本文用一个最小的双文件例子——FastMCP 起一个数学工具服务，langchain.mcp 把它接进 Agent——把这条链路跑通。

客户端这一侧，2026 年 9 月有个值得注意的变化：MCP 支持已经进到 LangChain 主干里。LangChain v1.4.0 新增了 langchain.mcp 命名空间，基于 FastMCP 实现，把原先独立的 langchain-mcp-adapters 包整个取代了——MultiServerMCPClient 收敛成一个 MCPAdapter。所以现在装依赖是 pip install "langchain[mcp]"，不再是单独装一个适配器包。本文代码全部按新写法给。

MCP 和 Function Call 是什么关系

先说结论：两者不是竞争关系，而是工作在两层的东西。

Function calling 是模型的能力：模型根据工具的名称、描述和参数 schema，决定「该调哪个工具、传什么参数」，并以结构化 JSON 输出。
MCP 是工具的供给协议：约定客户端如何发现服务器上有哪些工具（tool list）、如何调用（tool call）、如何取回结果。

也就是说，MCP 解决的不是「模型会不会调工具」，而是「工具从哪来、谁来维护、能不能复用」。写一次 MCP server，任何支持 MCP 的客户端（Claude Desktop、Cursor、你自己的 Agent）都能连。

最小实战：两个文件跑通

项目就两个文件：

math_server.py：MCP 服务端，提供数学工具
client.py：LangChain 客户端，把 MCP 工具接进 Agent

服务端：FastMCP 起服务

# math_server.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Math")

@mcp.tool()
def add(a: int, b: int) -> int:
 """Add two numbers"""
 return a + b

@mcp.tool()
def multiply(a: int, b: int) -> int:
 """Multiply two numbers"""
 return a * b

if __name__ == "__main__":
 mcp.run(transport="stdio")

两个细节值得注意：

工具用 @mcp.tool() 装饰器定义，函数签名和 docstring 就是模型看到的工具说明——和 LangChain @tool 的玩法一致，类型注解必须写清楚。
transport="stdio" 表示通过标准输入/输出通信，客户端会以子进程方式拉起这个脚本，本地工具用它最省事；要跨机器就走 HTTP（streamable HTTP / SSE）。

客户端：把 MCP 工具接进 Agent

# client.py
import asyncio
import os
from pathlib import Path

from langchain.agents import create_agent
from langchain.mcp import MCPAdapter
from langchain_openai import ChatOpenAI

# 模型走阿里云百炼的 OpenAI 兼容模式
model = ChatOpenAI(
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
 model="qwen-plus",
)

# 目标类型决定传输方式：Path = stdio 子进程，字符串 = 必须是 http(s) URL
adapter = MCPAdapter(Path("math_server.py"))


async def run_agent():
 async with adapter:
 # 把 MCP 工具加载为 LangChain 工具
 tools = await adapter.list_tools()

 # 创建并运行 agent
 agent = create_agent(model, tools)
 return await agent.ainvoke({"messages": "what's (3 + 5) x 12?"})


if __name__ == "__main__":
 print(asyncio.run(run_agent()))

MCPAdapter 最省事的地方是它从你交给它的目标自己推断传输方式，不需要再写 transport 字段：

传给 `MCPAdapter` 的目标	推断出的传输
`"https://example.com/mcp"`	Streamable HTTP
`Path("math_server.py")`	stdio 子进程（每个 adapter 一个）
一个 `FastMCP` 实例	进程内直连，不走子进程也不走 socket，跑测试最合适
`{"mcpServers": {...}}` 配置字典	多服务器，工具名自动加 `{server}_` 前缀
现成的 `fastmcp.Client`	完全自定义（transport、缓存、认证）

有个坑值得单独说：脚本路径必须传 Path 而不是 str。FastMCP 解析字符串时会先当文件路径试，再当 URL 试，所以一个字符串形式的 "math_server.py" 有被当成本地脚本拉起的风险；MCPAdapter 的做法更保守——直接拒绝所有不符合 URL 形状的字符串。想跑本地脚本，明确写 Path(...)。

运行

pip install "langchain[mcp]" langchain-openai mcp

export DASHSCOPE_API_KEY=your_api_key

python client.py

客户端会自己拉起 math_server.py，提出问题 “what’s (3 + 5) x 12?"，并输出计算结果。

运行时发生了什么

MCPAdapter(Path("math_server.py")) 从目标类型推断出 stdio 传输
进入 async with adapter 时以子进程方式启动 math_server.py，完成 MCP 握手
adapter.list_tools() 把服务器上的工具转换成 LangChain 工具列表
create_agent(model, tools) 用这些工具构建 Agent
Agent 收到问题，决定调用哪个工具；实际执行发生在 MCP server 侧，结果经客户端回传给模型

关键点在第 3 步：对 Agent 来说，MCP 工具和本地 @tool 定义的工具没有任何区别，适配器把协议细节全部藏掉了。另外返回的每个工具自己持有连接、每次调用各开一个会话，所以**async with 退出后 agent 依然可用**——不必把整轮推理都关在上下文里。

Function Call vs MCP

维度	Function Calling	MCP
解决的问题	模型如何表达「调这个工具、参数是这些」	工具如何被外部程序发现、提供和复用
所在层	模型 API 的能力	客户端与服务端之间的协议
工具定义位置	应用代码里（`@tool` / JSON Schema）	独立的 MCP server
复用性	换个应用基本要重写	一个 server 服务所有支持 MCP 的客户端
传输方式	随模型 API 请求一起发送	stdio / HTTP，工具在进程外执行

一句话总结：function calling 决定模型「怎么说」，MCP 决定工具「从哪来」；MCP 工具最终还是要靠 function calling 让模型真正用起来。

版本注记：从 langchain-mcp-adapters 迁移过来

这篇教程最早写在 MCP 适配器还是独立包的时期，当时的客户端长这样：

from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent

client = MultiServerMCPClient({
 "math": {"transport": "stdio", "command": "python", "args": ["math_server.py"]},
})
tools = await client.get_tools()
agent = create_react_agent(model, tools)

LangChain v1.4.0（2026-09-01）之后，这套写法整体退休。对应关系如下：

旧（`langchain-mcp-adapters`）	新（`langchain.mcp`）
`MultiServerMCPClient(...)`	`MCPAdapter(target)`
`await client.get_tools()`	`await adapter.list_tools()`
`load_mcp_tools(session)`	直接用 `adapter.list_tools()`
`convert_mcp_tool_to_langchain_tool`	`as_langchain_tool`（改名，且变成协程）
`tool_name_prefix`	多服务器时自动加 `{server}_` 前缀
`handle_tool_errors` 开关	移除。行为固定：`isError=True` 变成 `ToolMessage(status="error")`，传输故障直接抛异常
`Callbacks(on_elicitation=...)`	取消回调，改为默认开启的 LangGraph `interrupt()`
`tool_interceptors`	用 LangChain `@wrap_tool_call` 中间件（能拦所有工具，不止 MCP 的）
连接上的 `auth` / `headers`	挪到 `fastmcp.Client` 上

三个必须知道的边界：

langchain.mcp 目前是 beta（需要 langchain[mcp]>=1.4.0），import 时会抛一次 LangChainBetaWarning，API 可能变。
elicitation 变成 interrupt：服务端中途要输入时，不再是回调，而是暂停整个 run，用 Command(resume={"responses": {key: 答案}}) 恢复。这是设计变化，不是 bug。
prompts / resources 还没有包装：load_mcp_prompt、load_mcp_resources 这些没有对应实现，需要的话直接用 FastMCP 客户端的 client.get_prompt(...) / client.read_resource(...)。sampling 和 roots 则是因为 MCP 协议本身在无会话时代移除了，会抛 NotImplementedError。

依赖包名也顺便更新一下：现在装的是 langchain[mcp]，不再需要 pip install langchain-mcp-adapters。

收藏的参考资料：

资源
MCP 终极指南（很值得读）
LangChain 官方 MCP 文档
从 langchain-mcp-adapters 迁移
Using LangChain With Model Context Protocol (MCP)
知乎：一文看懂 MCP（大模型上下文协议）
Function Call vs MCP（本文配图出处）

下一步

把数学工具换成你真正需要的东西：查数据库、调内部 API、文件处理，思路完全一样
工具链路稳定之后，如果要做长周期、多步骤的 Agent 工程（文件系统、子智能体、上下文管理），看本站的《DeepAgents完全指南》

langchain_core 组件详解：Prompt 模板与 Output Parsers

Tue, 08 Sep 2026 11:30:00 +0800

langchain_core 组件详解：Prompt 模板与 Output Parsers

把一个 LangChain 应用拆到最小，真正绕不开的是一条链：prompt | llm | parser。prompt 决定喂给模型什么，llm 吐出一段自由文本，parser 再把文本变成程序能用的数据。langchain_core 把这条链的两头做成了两个模块——prompts 管输入侧，output_parsers 管输出侧。

这篇是这两个模块笔记的合并整理：输入侧讲 Prompt 模板家族怎么选、FewShot 怎么从固定示例进化到动态选例；输出侧讲五种常用解析器和解析失败后的 async 重试实战；解析报错的排查方法放在末尾。带运行输出和截图的部分来自我的实践记录，代码跑在 LangChain 0.3 时期的 langchain_core 上，个别老 API 的位置会标 ⚠️ 说明。

两个核心判断先放在这里：

输入侧默认 ChatPromptTemplate。 它吃一组消息、吐一组消息，和现代聊天模型的接口天然对齐；字符串版 PromptTemplate 退居二线，主要做内部格式化片段。
要结构化输出，优先 with_structured_output。 LangChain 1.x 时代的主流做法是把 schema 绑在模型上，走 tool calling 或 JSON mode 通道，结构由模型原生保证。PydanticOutputParser 这一族文本解析器是备选：模型不支持原生结构化输出，或需要把格式说明精确嵌进提示词时才用。但 format_instructions、解析、重试这套思路依然值得吃透——排查结构化输出问题时，最终都要回到这条最原始的链上。

一、Prompt 模板（输入侧）

langchain_core.prompts 解决的问题只有一个：把动态变量填进固定结构，生成模型输入。模板类有一族，日常主力只有一个。

ChatPromptTemplate：默认选择

ChatPromptTemplate 生成的不是一段字符串，而是一组结构化消息（List[BaseMessage]），正好对齐聊天模型的输入格式：

from langchain_core.prompts import ChatPromptTemplate

template = [
 ("system", "You are a helpful AI assistant named {name}."),
 ("human", "Tell me a joke about {topic}."),
]
prompt_template = ChatPromptTemplate.from_messages(template)

prompt = prompt_template.invoke({"name": "Grok", "topic": "dogs"})
print(prompt.messages)
# [SystemMessage(content='You are a helpful AI assistant named Grok.'),
# HumanMessage(content='Tell me a joke about dogs.')]

from_messages 接受 ("角色", "模板") 元组，也接受消息模板对象和占位符，可以任意混搭。日常写角色字符串就够了；SystemMessagePromptTemplate、HumanMessagePromptTemplate、AIMessagePromptTemplate 这些细粒度的类，只在需要程序化拼装单条消息时才用得上。

真正解决独立问题的类是 MessagesPlaceholder——往模板中间插一段动态消息列表，最典型的用途是对话历史：

from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_core.messages import HumanMessage, AIMessage

chat_prompt = ChatPromptTemplate.from_messages([
 ("system", "You are a helpful assistant."),
 MessagesPlaceholder(variable_name="history"),
 ("human", "{input}")
])

history = [
 HumanMessage(content="What's the weather like?"),
 AIMessage(content="It's sunny!")
]

prompt = chat_prompt.invoke({"history": history, "input": "What's the forecast tomorrow?"})
print(prompt.messages)
# [SystemMessage(...), HumanMessage(content="What's the weather like?"),
# AIMessage(...), HumanMessage(...)]

注意 variable_name 必须和 invoke 时传入的键一致，写模板时就对清楚。

Prompt 模板家族速查表

完整班底如下，大部分场景只用到前几行：

类	功能	适用场景
`ChatPromptTemplate`	构建对话消息列表，支持多角色	聊天机器人、多轮对话（日常默认）
`MessagesPlaceholder`	插入动态消息列表	对话历史、动态上下文
`PromptTemplate`	格式化字符串提示，支持动态变量	字符串模板、内部格式化片段
`FewShotChatMessagePromptTemplate`	把少样本示例格式化成对话消息	对话任务需要示例引导
`SystemMessagePromptTemplate`	系统消息模板	程序化拼装 system 消息
`HumanMessagePromptTemplate`	用户消息模板	程序化拼装 human 消息
`AIMessagePromptTemplate`	AI 回复模板	少样本对话、预置示例回答
`ChatMessagePromptTemplate`	自定义角色消息模板（如 `"Jedi"`）	非标准角色的创意对话
`FewShotPromptTemplate`	少样本示例，生成字符串	⚠️ 官方已标记 deprecated
`PipelinePromptTemplate`	组合多个子模板	⚠️ 已废弃

两个 deprecated 的类多说两句。FewShotPromptTemplate（字符串版少样本）官方已标记 deprecated，现代做法是 ChatPromptTemplate + FewShotChatMessagePromptTemplate 组合，再配 ExampleSelector 做动态选例（见下节）；PipelinePromptTemplate 原本用来嵌套组合多段子模板，同样废弃了，多段模板的组合用普通变量嵌套或 LCEL 就能解决，不再需要专门的类。

安全上有一条红线：字符串模板默认用 f-string 语法，PromptTemplate 也支持 jinja2，但不要用 jinja2 加载来源不可信的模板——jinja2 模板可以执行代码，是一个真实的注入面。没有特殊语法需求，留在默认的 f-string。

FewShot：从固定示例到动态选例

少样本提示的思路是用示例教模型任务模式。对话版写法是把示例格式化成 human/ai 消息对，作为一个整体嵌进主模板：

from langchain_core.prompts import FewShotChatMessagePromptTemplate, ChatPromptTemplate

examples = [
 {"question": "What is 2+2?", "answer": "4"},
 {"question": "What is 3+3?", "answer": "6"},
]

example_prompt = ChatPromptTemplate.from_messages([
 ("human", "{question}"),
 ("ai", "{answer}")
])

few_shot_prompt = FewShotChatMessagePromptTemplate(
 examples=examples,
 example_prompt=example_prompt
)

final_prompt = ChatPromptTemplate.from_messages([
 ("system", "You are a math expert."),
 few_shot_prompt,
 ("human", "{input}")
])

prompt = final_prompt.invoke({"input": "What is 4+4?"})

固定示例有两个天然限制：示例一多就挤占上下文窗口，示例和当前输入不相关时还会稀释注意力。进阶做法是接一个 ExampleSelector，按语义相似度动态挑出与当前输入最相近的几条示例再拼进提示——等于把 RAG 的检索思路用在了示例库上，官方实现里 SemanticSimilarityExampleSelector 是最常用的一个。

我试过的玩法是把相近对话入库，请求时按相似度取回再传入 FewShot 模板，跑通后的效果：

具体代码：

这套做法的关键在示例库质量和 embedding 的匹配度，示例数量适中即可。再想提升效果，该调的是检索策略，不是往提示里硬塞更多示例。

二、Output Parsers（输出侧）

输出解析器负责把 LLM 的自由文本转换成结构化数据：从自然语言句子、JSON 字符串或列表里提取关键信息，转成 Python 对象、字典或列表这类程序友好的格式。没有它，每个应用都得自己写一遍"从文本里抠 JSON"的脏活，格式约定还会散落在提示词和解析代码两处，很难保持一致。

在链上的位置就是开头那条：

PromptTemplate → LLM → OutputParser

提示模板定义输入和输出格式要求，LLM 生成原始文本，解析器完成最后一步转换。输入侧要求什么格式，输出侧就得配对应的 parser，两头的约定靠 get_format_instructions() 生成的格式说明对齐。

五种常用解析器

解析器	干什么	典型场景
`StrOutputParser`	原样返回字符串	简单问答、文本生成
`JsonOutputParser`	解析为 JSON 字典	API 返回数据、键值对提取
`PydanticOutputParser`	解析为 Pydantic 模型	数据验证、复杂对象处理
`CommaSeparatedListOutputParser`	逗号分隔文本 → 列表	列表提取（选项、标签）
自定义 `BaseOutputParser`	自己实现 `parse`	特殊格式（分号分隔、表格解析）

下面五个示例共用同一个 llm 初始化（OpenAI 兼容接口，配置从 .env 读取），后文不再重复：

import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI

load_dotenv()
llm = ChatOpenAI(
 model=os.getenv("model"),
 api_key=os.getenv("api_key"),
 base_url=os.getenv("base_url"),
 streaming=True
)

StrOutputParser：什么都不做

最简单的解析器，直接返回字符串，不需要任何格式化指令：

from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import StrOutputParser

prompt = PromptTemplate(template="今天是星期几？（假设今天是 2025 年 3 月 16 日）")
parser = StrOutputParser()

chain = prompt | llm | parser
response = chain.invoke({})
print(response)

输出：

今天是星期日。

JsonOutputParser：拿到字典

from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import JsonOutputParser

parser = JsonOutputParser()
prompt = PromptTemplate(
 template="以 JSON 格式返回两种水果及其颜色。\n{format_instructions}",
 partial_variables={"format_instructions": parser.get_format_instructions()}
)

chain = prompt | llm | parser
response = chain.invoke({})
print(response)

输出：

{'apple': 'red', 'banana': 'yellow'}

get_format_instructions() 自动生成"请按 JSON 格式返回"的说明嵌进模板，提示和解析器的约定永远对得上。但硬约束不存在：LLM 输出的不是合法 JSON 时直接抛异常。

PydanticOutputParser：强类型 + 字段校验

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

class Book(BaseModel):
 title: str = Field(description="书名")
 author: str = Field(description="作者")
 year: int = Field(description="出版年份")

parser = PydanticOutputParser(pydantic_object=Book)
prompt = PromptTemplate(
 template="推荐一本书，并以指定格式返回。\n{format_instructions}\n推荐什么书？",
 input_variables=["question"],
 partial_variables={"format_instructions": parser.get_format_instructions()}
)

chain = prompt | llm | parser
response = chain.invoke({"question": "推荐什么书？"})
print(response)

输出：

Book(title='《活着》', author='余华', year=1993)

Pydantic 保证字段类型（year 必须是整数），格式化指令里还会带上每个字段的 description。get_format_instructions() 生成的说明长这样：

Please provide your response in the following JSON format:
{
 "title": "string",
 "author": "string",
 "year": "integer"
}

实例运行截图：

CommaSeparatedListOutputParser：拿到列表

from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import CommaSeparatedListOutputParser

parser = CommaSeparatedListOutputParser()
prompt = PromptTemplate(
 template="列出三种编程语言，用逗号分隔。\n{format_instructions}",
 partial_variables={"format_instructions": parser.get_format_instructions()}
)

chain = prompt | llm | parser
response = chain.invoke({})
print(response) # type: list

输出：

['Python', 'Java', 'C++']

实例：

自定义解析器：继承 BaseOutputParser

内置解析器覆盖不到的格式，继承 BaseOutputParser 实现 parse 方法就行，比如解析分号分隔的列表：

from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import BaseOutputParser

class SemicolonListParser(BaseOutputParser):
 def parse(self, text: str) -> list:
 return [item.strip() for item in text.split(";")]

parser = SemicolonListParser()
prompt = PromptTemplate(template="列出三种城市，用分号分隔，例如：北京;上海;广州")

chain = prompt | llm | parser
response = chain.invoke({})
print(response)

输出：

['北京', '上海', '广州']

解析失败重试：async 实战

文本解析器没有硬约束，LLM 输出不稳定或格式要求严格时，解析失败是常态而不是异常，重试应该直接设计进链路。下面是完整跑通的 async 版本：PydanticOutputParser 解析动词提取结果，外层 for 循环控制最多三次尝试，全部失败后再兜底一次。

from langchain_openai import ChatOpenAI
from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import PydanticOutputParser
from langchain_core.runnables import RunnableSequence
from pydantic import BaseModel, Field
import os
from dotenv import load_dotenv
import asyncio

# 加载环境变量
load_dotenv()
model = os.getenv("model")
api_key = os.getenv("api_key")
base_url = os.getenv("base_url")

# 初始化 LLM
llm = ChatOpenAI(
 model=model,
 api_key=api_key,
 base_url=base_url,
 streaming=True
)

# 定义输出结构使用 Pydantic
class ParseResult(BaseModel):
 result: str = Field(description="解析出的参数结果")

# 创建输出解析器
output_parser = PydanticOutputParser(pydantic_object=ParseResult)

# 创建提示模板
prompt_template = PromptTemplate.from_template(
 "请解析以下输入并返回结果：{input}\n\n返回格式：\n{format_instructions}",
 partial_variables={"format_instructions": output_parser.get_format_instructions()}
)

# 创建可运行序列
# chain = RunnableSequence(
# prompt_template,
# llm,
# output_parser
# )
chain = prompt_template | llm | output_parser

# 输入数据
user_input = "提取这句话中的动词：'我喜欢跑步和游泳'"

async def run_parsing():
 max_attempts = 3

 for attempt in range(max_attempts):
 try:
 # 使用 invoke 方法运行链
 result = await chain.ainvoke({"input": user_input})

 print(f"第 {attempt + 1} 次尝试成功")
 print(f"解析结果: {result.model_dump()}")
 return result

 except Exception as e:
 print(f"第 {attempt + 1} 次尝试失败，错误: {e}")
 if attempt < max_attempts - 1:
 print("正在重试...")
 else:
 print("已达到最大尝试次数")
 try:
 result = await chain.ainvoke(
 {"input": user_input},
 config={"max_retries": 1}
 )
 print(f"最终修复结果: {result.model_dump()}") # 使用 model_dump() 替代 dict()
 return result
 except Exception as final_error:
 print(f"最终尝试失败，错误: {final_error}")
 return None

# 在已有事件循环中运行
async def main():
 await run_parsing()

# 如果在已有的事件循环中（比如 Jupyter），直接运行
if asyncio.get_event_loop().is_running():
 await main() # 在已有循环中运行
else:
 asyncio.run(main())

输出示例：

解析结果： {'result': '喜欢,跑步,游泳'}

关于这段代码有一点必须澄清（原笔记在这里有误导）：重试全部来自手工调用——外层 for 循环跑满三次，都失败后再兜底调一次。最后那次 ainvoke 传的 config={"max_retries": 1} 并不是解析重试的开关——prompt | llm | parser 这条链上，解析失败抛出的异常只会向上传给调用方，库不会自动重跑；max_retries 至多影响底层 API 请求层面的重试（网络错误、限流），跟解析失败是两回事，真正需要 API 层重试应该设在 ChatOpenAI 的初始化参数里。想让模型重新生成合规输出，只能像上面这样自己捕获异常、重新调用整条链。

重跑整条链之所以有效，是因为 LLM 输出有随机性：同一个输入再来一次，经常就能给出合规格式。捕获异常后重跑，是成本最低的重试方案。

和 with_structured_output 怎么选

回到开头第二个判断。1.x 时代做结构化输出，第一选择是模型侧的 with_structured_output——还是上面那个 Book schema，但玩法完全变了：

structured_llm = llm.with_structured_output(Book)
book = structured_llm.invoke("推荐一本书，返回书名、作者和出版年份")
# 直接拿到 Book 实例

	`with_structured_output`	文本解析器一族
结构由谁保证	schema 绑在模型上，走 tool calling / JSON mode	格式说明嵌进提示词，靠模型遵守约定
提示词	不需要 format_instructions	`get_format_instructions()` 嵌入 partial_variables
解析	库内部完成	链上显式一环，失败自己处理

怎么选：模型支持 tool calling 或 JSON mode（主流模型都支持），直接 with_structured_output，代码更少、格式更有保障；模型不支持原生结构化输出，或需要把格式说明精确控制进提示词（特定提示策略、兼容老链路），用文本解析器。StrOutputParser 不受这场选型影响——拿纯文本时它仍是标准配件，也是后面排查解析问题的关键工具。

三、解析报错排查

Agent 场景：OutputParserException 与 handle_parsing_errors

解析报错最密集的场景是 Agent。ReAct 式 Agent 靠解析模型文本来决定下一步动作（Thought / Action / Final Answer 的固定格式），模型一旦不合规矩就抛 OutputParserException——典型的坏输出比如同一段回复里同时包含 Action 和 Final Answer。

我跑 ReAct Agent 时撞到过这个错，解法是初始化代理时传 handle_parsing_errors=True：

agent = initialize_agent(
 tools=tools,
 llm=llm,
 agent_type="zero-shot-react-description",
 verbose=True,
 handle_parsing_errors=True # 自动处理解析错误
)

response = agent.run("告诉我关于 LangChain 的信息")
print(response)

机制：解析失败时代理不抛异常，而是把错误信息反馈给模型，要求它重新生成符合预期的输出格式——相当于框架替你做了上一节手写的那层重试循环。

⚠️ 此为 0.x 时代写法：initialize_agent / AgentExecutor 属于 legacy API，LangChain 1.x 已将其移出主线。更根本的变化是，现代 tool-calling Agent 让模型直接输出结构化的 tool call，不再靠解析自由文本决定动作，这一类解析报错从源头就少了一大截。这段经验的价值在机制本身：解析失败时把错误反馈给模型让它自我修正，这个思路在哪个版本都适用。

调试心法：先定位问题在模型还是解析器

解析失败时第一个动作不是改提示词，是看原始输出。把链尾换成 StrOutputParser 跑一遍，问题在哪一侧立刻清楚：原始输出本身不符合约定格式，问题在模型侧；原始输出看着合规但 parser 仍报错，问题在解析器侧——多半是格式约定和实际输出没对上。

try:
 response = chain.invoke({})
 print(response)
except Exception as e:
 print(f"解析失败：{e}")
 # 用 StrOutputParser 检查原始输出
 raw_chain = prompt | llm | StrOutputParser()
 raw_output = raw_chain.invoke({})
 print(f"原始输出：{raw_output}")

定位到模型侧之后，两个常用手段：

把格式要求写得更硬。 在提示里重复强调，比如"严格按照 JSON 格式返回，不要添加额外说明"；格式说明用 get_format_instructions() 生成后经 partial_variables 嵌入，不要自己手写一份——手写的和解析器的约定迟早对不上。
降低 temperature。 对格式遵从度差的模型，降低采样温度能减少格式漂移。

总结

输入侧默认 ChatPromptTemplate + MessagesPlaceholder，细粒度消息类按需取用；FewShot 的进阶形态是 ExampleSelector 按相似度动态选例，示例库质量比数量重要。
输出侧要结构化数据，1.x 优先 with_structured_output；文本解析器是备选，五种里 PydanticOutputParser（要校验）和 JsonOutputParser（要字典）最常用，特殊格式继承 BaseOutputParser 自己写 parse。
解析失败按常态路径处理：普通链上自己包一层循环重跑；Agent 场景（0.x）用 handle_parsing_errors=True 让框架把错误喂回模型。
排查顺序固定：先换 StrOutputParser 看原始输出，定位模型侧还是解析器侧，再对应改提示（格式说明、temperature）或改解析约定。
字符串模板留在默认的 f-string，不要用 jinja2 加载来源不可信的模板。

LangChain 模型接入指南：OpenAI 兼容协议与多平台调用

Tue, 08 Sep 2026 11:00:00 +0800

LangChain 模型接入指南：OpenAI 兼容协议与多平台调用

langchain_openai 名字里带 openai，能做的事却比名字大得多：任何兼容 OpenAI 接口协议的模型服务，它都能接。而到今天，OpenAI API 格式已经成了事实上的工业标准——阿里百炼、DeepSeek、vLLM、Ollama，无一例外都把"兼容 OpenAI 协议"当成默认姿势。

所以在 LangChain 里接模型这件事，可以收敛成一套打法：用 ChatOpenAI 和 OpenAIEmbeddings，配合目标平台的三要素。我把这套打法叫**“换头”**——换平台时业务代码一行不动，只改三处：base_url、api_key、model。一个原本基于 GPT-4 写的应用，改完这三处就直接跑在通义千问上。

这篇文章做两件事：以阿里百炼为例，把对话、流式、嵌入、工具调用四类调用完整走一遍（嵌入那里有个很容易漏的坑）；然后给一份多平台速查表，覆盖 6 家 ChatModel 和 5 家 Embeddings 的包名与初始化要点，换平台时直接查表。

一、百炼实战：用 ChatOpenAI 跑通四类调用

1.1 准备：包、Key 和 Base URL

pip install langchain-openai langchain-core

去阿里云百炼控制台拿两样东西：

API Key（sk- 开头）
Base URL：百炼的 OpenAI 兼容端点是 https://dashscope.aliyuncs.com/compatible-mode/v1

组件上只需要认识两个类，正好对应 LLM 应用的两块基石：

类	用途	百炼上的对应模型
`ChatOpenAI`	对话、指令跟随、逻辑推理、工具调用（Function Calling）	通义千问系列（`qwen-plus`、`qwen-max`、`qwen-turbo`、`qwen-long`）
`OpenAIEmbeddings`	文本转向量，构建 RAG 的基础	向量模型（`text-embedding-v2`、`text-embedding-v3` 等）

ChatOpenAI 走 Chat Completion 接口：输入是消息列表（SystemMessage、HumanMessage、AIMessage），输出是 AIMessage。千问的具体型号清单见百炼官方的模型列表。

1.2 基础对话

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, SystemMessage

# 为清晰起见先写成明文变量；生产环境放环境变量，做法见第三节
ALIBABA_API_KEY = "sk-你的阿里百炼API_KEY"
ALIBABA_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"

chat_model = ChatOpenAI(
 model="qwen-plus", # 指向百炼的模型 ID
 api_key=ALIBABA_API_KEY,
 base_url=ALIBABA_BASE_URL,
 temperature=0.7,
 streaming=True,
)

messages = [
 SystemMessage(content="你是一个专业的Python代码助手。"),
 HumanMessage(content="请用Python写一个冒泡排序，并解释其时间复杂度。"),
]

print(chat_model.invoke(messages).content)

除了 model / api_key / base_url 三处"换头"参数，其余写法与调 GPT-4 完全一致——这正是兼容协议的价值。

1.3 流式输出

把 invoke 换成 stream 就是流式：

for chunk in chat_model.stream(messages):
 print(chunk.content, end="", flush=True)

chunk.content 是每次生成的一小段文本。流式对大模型应用的用户体验提升非常直接，做对话类产品基本是必选项。

1.4 向量嵌入：最不能漏的一行

做 RAG（知识库助手）时用 OpenAIEmbeddings 调百炼的向量模型。这里有个坑，也是全文最值得记住的一行参数：

from langchain_openai import OpenAIEmbeddings

embeddings = OpenAIEmbeddings(
 model="text-embedding-v2",
 api_key=ALIBABA_API_KEY,
 base_url=ALIBABA_BASE_URL,
 check_embedding_ctx_length=False, # 关键：关掉 OpenAI 特有的长度检查，防止报错
)

vector = embeddings.embed_query("阿里百炼是一个大模型服务平台。")
print(f"生成的向量维度: {len(vector)}")
print(f"向量前 5 位: {vector[:5]}")

OpenAIEmbeddings 默认开着一段 OpenAI 特有的逻辑：发送前先按 OpenAI 的分词器做上下文长度检查，超长文本会在本地被切块再分批发送。接到百炼这种非 OpenAI 端点上，这套本地检查既无必要，又可能在调用时直接报错。显式传 check_embedding_ctx_length=False 把它关掉就正常了。第一次接百炼嵌入如果莫名报错，先看是不是漏了这个参数。

1.5 工具调用：bind_tools

百炼的 Qwen 模型对 Function Calling 的支持很好，且完全走 OpenAI 的格式。用 bind_tools 把工具绑定到模型上，模型决定调用时，请求会出现在返回消息的 tool_calls 属性里，而不是正文里：

from langchain_core.tools import tool

@tool
def get_weather(city: str):
 """查询某个城市的天气信息。"""
 return f"{city} 的天气是晴天，气温 25 度。"

llm_with_tools = chat_model.bind_tools([get_weather])

response = llm_with_tools.invoke("杭州今天天气怎么样？")
print(f"工具调用请求: {response.tool_calls}")

拿到 tool_calls 之后，取出参数、真正执行工具、把结果作为 ToolMessage 回传给模型，就是一个完整的工具调用循环——LangChain 的 Agent 封装和 LangGraph 处理的就是这个循环。

二、为什么推荐用 langchain_openai 接百炼

一个自然的疑问：阿里有官方 SDK，LangChain 里也有 ChatTongyi 这种原生类，为什么绕道 langchain_openai？理由有三。

代码零迁移成本。 项目原本基于 GPT-4 开发的话，不需要改动任何业务逻辑，把环境变量里的 BASE_URL 和 API_KEY 换掉，应用就从 OpenAI 切到了百炼 Qwen。把 langchain_openai 当默认接入层，各平台互为"平替"，切换成本约等于零。
生态支持最完善。 LangChain 社区对 OpenAI 类的支持是优先级最高的；走标准接口，后续接 LangGraph、LangSmith 这些工具也最顺。
工具调用格式统一。 OpenAI 的 Tool Calling 格式是当前的黄金标准。百炼通过兼容接口让 Qwen 像 GPT 一样精准地调用工具，不需要自己处理格式转换。

反过来说，只有当你要用 DashScope 原生协议里、兼容层没覆盖的能力时，才需要回到原生 SDK——这条备选路线放在第五节。

三、环境变量与 Key 管理

3.1 永久环境变量：CMD / GUI / zsh / bash

以百炼的 DASHSCOPE_API_KEY 为例。这个名字不是随便起的：第五节的 ChatTongyi、DashScopeEmbeddings 都默认读它。

# Windows CMD
setx DASHSCOPE_API_KEY "YOUR_DASHSCOPE_API_KEY"
echo %DASHSCOPE_API_KEY% # 验证

# Windows 图形界面
# 系统属性 → 环境变量，手动添加，不再赘述

# zsh
echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.zshrc
source ~/.zshrc
echo $DASHSCOPE_API_KEY # 验证

# bash
echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.bashrc
source ~/.bashrc
echo $DASHSCOPE_API_KEY # 验证

3.2 .env 模板：多平台共存

写进 shell 配置不适合多项目切换，更常见的做法是每个项目放一个 .env，用 python-dotenv 加载：

# 阿里云百炼
DASHSCOPE_API_KEY=sk-你的key
DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

# OpenAI 官方（或另一个兼容端点）
OPENAI_API_KEY=sk-你的key
# OPENAI_BASE_URL=

from dotenv import load_dotenv
import os

load_dotenv()

llm = ChatOpenAI(
 model="qwen-plus",
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url=os.getenv("DASHSCOPE_BASE_URL"),
 streaming=True,
)

再进一步还有个偷懒技巧：openai 官方 SDK 本身就认 OPENAI_API_KEY 和 OPENAI_BASE_URL 两个环境变量。把这两个变量指向百炼，代码里连 api_key、base_url 都不用写，ChatOpenAI(model="qwen-plus") 就能直接跑——切换平台时只动环境变量，一行代码不改。

3.3 百炼计费预警

百炼有个和 OpenAI 不一样的计费方式，要提前知道：它没办法单独充值消费，费用会直接从控制台里扣钱。所以动手跑代码之前，先把控制台的高消费预警设上。

四、多平台速查表

“换头"的前提是各家有自己的接入包。LangChain 0.2 之后，集成被拆成一个个独立的合作包，下面两张表按"提供商 → 安装包 → 初始化要点"整理。表里的型号名只是写作时存在过的示例，各家更新很快，使用前以官方现役型号为准。

4.1 ChatModel（6 家）

提供商	安装包	初始化要点
OpenAI / 任意 OpenAI 兼容端点	`langchain-openai`	`ChatOpenAI(model="gpt-4o-mini")`，默认读 `OPENAI_API_KEY`；接百炼则加 `base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"`，`model` 换成 `qwen-plus` 等
Anthropic	`langchain-anthropic`	`ChatAnthropic(model="claude-sonnet-4-5-20250929")`，默认读 `ANTHROPIC_API_KEY`
Google	`langchain-google-genai` / `langchain-google-vertexai`	Gemini API 走 `ChatGoogleGenerativeAI(model="gemini-2.5-flash")`，读 `GOOGLE_API_KEY`；GCP 走 `ChatVertexAI`，需要 gcloud 登录或 `GOOGLE_APPLICATION_CREDENTIALS`
Hugging Face	`langchain-huggingface`	`HuggingFaceEndpoint(repo_id="google/flan-t5-large", task="text-generation")`，读 `HUGGINGFACEHUB_API_TOKEN`；本地 pipeline 用 `HuggingFacePipeline`
Cohere	`langchain-cohere`	`ChatCohere(model="command-r")`，默认读 `COHERE_API_KEY`
Ollama（本地）	`langchain-ollama`	`ChatOllama(model="llama3.2")`；服务默认在 `http://localhost:11434`，不在默认地址时传 `base_url`

4.2 Embeddings（5 家）

提供商	安装包	初始化要点
OpenAI / 任意 OpenAI 兼容端点	`langchain-openai`	`OpenAIEmbeddings(model="text-embedding-3-small")`；接百炼：`model="text-embedding-v2"` + `base_url` + `check_embedding_ctx_length=False`
Google	`langchain-google-genai` / `langchain-google-vertexai`	`GoogleGenerativeAIEmbeddings(model="models/gemini-embedding-001")`；Vertex 用 `VertexAIEmbeddings(model_name="text-embedding-005")`
Hugging Face（本地）	`langchain-huggingface` + `sentence-transformers`	`HuggingFaceEmbeddings(model_name="sentence-transformers/all-MiniLM-L6-v2")`，可用 `model_kwargs={'device': 'cuda'}` 指定设备
Cohere	`langchain-cohere`	`CohereEmbeddings(model="embed-v4.0")`
Ollama（本地）	`langchain-ollama`	`OllamaEmbeddings(model="nomic-embed-text")`

4.3 相对旧版速查的更新

这张表由 2025 年初那版速查表更新而来，几处变化需要说明：

langchain_community.llms.HuggingFaceHub → langchain-huggingface 包的 HuggingFaceEndpoint。Hugging Face 的推理接入这几年变动很大（Inference API 已让位给 Inference Providers），这条路线以官方文档为准。
langchain_community.chat_models.ChatOllama → langchain-ollama 包的 ChatOllama，OllamaEmbeddings 同步从 langchain_community.embeddings 迁到 langchain-ollama。
langchain_community.embeddings.HuggingFaceEmbeddings → langchain-huggingface 的同名类。
旧表里的 gpt-3.5-turbo、claude-3-sonnet-20240229、gemini-pro、llama2 等型号已过时，表中换成了更新的型号；它们同样会过期，以各家官方型号页为准。

4.4 两个容易忽略的差异

embed_query 与 embed_documents 分工不同：前者嵌入单条查询文本（用户搜索的那句话），返回一个向量；后者批量嵌入多个文档，返回向量列表。检索系统的两侧——入库文档和用户查询——必须用同一个嵌入模型，否则维度和语义空间都对不上。
向量维度因模型而异：text-embedding-3-small 是 1536 维，text-embedding-3-large 是 3072 维，常见的 sentence-transformers 模型多为 384 或 768 维。维度决定了向量库的结构和相似度计算，入库后换嵌入模型基本等于重建整个库。

五、备选路线：原生 DashScope 与 init_chat_model

5.1 ChatTongyi / DashScopeEmbeddings（legacy）

LangChain 社区包里保留了走 DashScope 原生 SDK 的两个类。⚠️ 以下是 0.x 时代的社区包写法，能用，但新项目建议优先走 OpenAI 兼容层：

pip install langchain-community dashscope

# ⚠️ 此为 langchain_community 0.x 时代写法
from langchain_community.chat_models.tongyi import ChatTongyi
from langchain_core.messages import HumanMessage

chatLLM = ChatTongyi(
 model="qwen-max",
 streaming=True,
)
res = chatLLM.stream([HumanMessage(content="hi")], streaming=True)
for r in res:
 print("chat resp:", r.content)

嵌入对应 DashScopeEmbeddings：

# ⚠️ 此为 langchain_community 0.x 时代写法
from langchain_community.embeddings import DashScopeEmbeddings

embeddings = DashScopeEmbeddings(model="text-embedding-v2")

query_result = embeddings.embed_query("This is a test document.")
print("文本向量长度：", len(query_result))

doc_results = embeddings.embed_documents(
 ["Hi there!", "Oh, hello!", "What's your name?",
 "My friends call me World", "Hello World!"])
print("文本向量数量：", len(doc_results), "，文本向量长度：", len(doc_results[0]))

两个类都默认读 DASHSCOPE_API_KEY 环境变量。什么时候才需要这条路线：要用 DashScope 原生协议里、兼容层没覆盖的能力时。纯粹跑对话和嵌入，没有理由不用兼容层。

5.2 init_chat_model

LangChain 官方还提供了统一初始化入口 init_chat_model，按模型名和 provider 一步创建实例，不用记各家类名：

from langchain.chat_models import init_chat_model

llm = init_chat_model(
 "qwen-plus",
 model_provider="openai", # 指定走 langchain_openai 的 ChatOpenAI
 api_key="sk-你的key",
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

其余参数原样透传给对应类，细节以官方文档为准。

总结

把这篇文章压成几条可执行的结论：

把 langchain_openai 当默认接入层。OpenAI API 格式已是事实工业标准，ChatOpenAI + OpenAIEmbeddings 能接一切兼容端点。
换平台只改三处：base_url、api_key、model，业务代码不动；配合环境变量或 .env，可以做到一行代码不换平台。
接百炼做嵌入，check_embedding_ctx_length=False 必加，这是最容易漏的一行。
跑代码前先设百炼高消费预警，它的费用直接从控制台账户扣，没有独立余额。
新项目直接装独立集成包（langchain-ollama、langchain-huggingface 等），langchain_community 里的模型类当 legacy 看。

下一步：拿 1.2 的基础对话代码，把三个"换头"参数换成你手上的平台——百炼、DeepSeek 或本地 Ollama——跑通第一条消息。然后做两件事：用 bind_tools 试一次工具调用，用 OpenAIEmbeddings 把一段文本打成向量。这三步走完，LangChain 接模型这件事就算真正上手了。

LangSmith使用教程

Fri, 30 May 2025 16:15:40 +0800

LangSmith使用教程

LangSmith 是 LangChain 官方的 LLM 应用观测平台：调试、追踪、评估、监控都在上面。LLM 应用最麻烦的一点是行为不透明——同一份提示，换个模型、换个参数、换个措辞，结果就可能完全不同，只靠 print 调试很快就会失控。我的判断是：追踪不是可选项，而是基础设施；在 LangChain 生态里，LangSmith 是接入成本最低的那个。

本文是我 2025 年 5 月的上手记录（截图都是当时的实拍）；2026 年 9 月整合博客时修订了环境变量命名和评估 API，过时的旧写法在文中用注记标出。

核心概念

概念	一句话说明
Tracing（追踪）	记录应用每个组件的输入、输出、耗时、token，还原完整执行路径
Debugging（调试）	基于 trace 定位错误和非预期行为
Evaluation（评估）	用数据集 + 评估器量化应用表现，比较不同版本
Datasets（数据集）	评估用的输入/期望输出样本集合，可从生产 trace 提取
Monitoring（监控）	部署后持续追踪错误率、延迟、token 消耗
Project（项目）	trace 的归属单位，一个应用一个项目

接入设置

账户与 API Key

到 smith.langchain.com 注册，登录后创建组织（Organization）。

在组织的 Settings → API Keys 里创建密钥，妥善保管，不要公开分享。

安装 SDK

pip install langsmith

环境变量

2026-09 修订：官方现在的推荐前缀是 LANGSMITH_。本文写作时用的还是 LANGCHAIN_ 旧前缀（下方注记），两者目前兼容，新项目直接用新写法。

export LANGSMITH_TRACING_ENABLED="true"
export LANGSMITH_ENDPOINT="https://api.smith.langchain.com"
export LANGSMITH_API_KEY="YOUR_LANGSMITH_API_KEY"
export LANGSMITH_PROJECT="YOUR_PROJECT_NAME" # 可选，默认 "default"

LANGSMITH_TRACING_ENABLED：总开关，设为 true 后 LangChain / LangGraph 应用自动上报
LANGSMITH_PROJECT：trace 归属的项目名，可在界面上创建和管理

⚠️ 旧写法：LANGCHAIN_TRACING_V2="true" / LANGCHAIN_ENDPOINT / LANGCHAIN_API_KEY / LANGCHAIN_PROJECT。仍兼容，但已弃用。

追踪 LangChain 应用

环境变量设好之后，LangChain 应用零代码改动自动上报——这是它比手动埋点省事的核心原因。

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

# 模型：阿里云百炼的 OpenAI 兼容模式
# （修订：原文这里误用了未导入的 Tongyi 类，统一改为博客其他文章一致的 ChatOpenAI 写法）
llm = ChatOpenAI(
 model="qwen-plus",
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

prompt = ChatPromptTemplate.from_messages([
 ("system", "You are a helpful assistant that translates {input_language} to {output_language}."),
 ("human", "{text}")
])

chain = prompt | llm | StrOutputParser()

result = chain.invoke({
 "input_language": "English",
 "output_language": "Chinese",
 "text": "Hello, how are you?"
})
print(result)

运行后登录 LangSmith，在对应项目下就能看到这次运行的追踪记录：链的每个步骤、输入、输出、耗时、token，以及可能发生的任何错误。

追踪任意函数：@traceable

不在 LangChain 链里的函数，用 @traceable 装饰器也能纳入追踪：

from langsmith import traceable

@traceable(name="My Custom Function") # name 可选，用于在 UI 中显示
def my_data_processing_function(data: str) -> str:
 return data.upper()

@traceable
def my_llm_logic(user_input: str):
 # 里面可以调 LLM、调其他被追踪函数，调用链会串在一条 trace 里
 return my_data_processing_function(user_input)

output = my_llm_logic("This is some input text.")
print(output)

被装饰的函数每次调用都会生成一条 trace，和 LangChain 链的 trace 在同一个视图里查看。

从 Callbacks 到 astream_events：观测方式的变化

本节为 2026-09 整合时补充。

LangChain 0.x 时代，想监听应用内部发生的事，要写 CallbackHandler——继承 BaseCallbackHandler，实现 on_llm_start / on_llm_new_token 等一串回调。能用，但啰嗦，和异步、流式代码搅在一起还容易出错。

1.x 时代的官方答案是 astream_events：一条流式事件管道，把链内部每个组件的开始/结束/token 都作为事件吐出来，不用写 handler 类：

async for event in chain.astream_events(
 {"input_language": "English", "output_language": "Chinese", "text": "Hello, how are you?"},
 version="v2",
):
 if event["event"] == "on_chat_model_stream":
 print(event["data"]["chunk"].content, end="", flush=True)

分工可以这样理解：给用户看中间步骤、做流式 UI，用 astream_events；沉淀全量记录、做评估和监控，交给 LangSmith。两者不冲突。

查看追踪数据

登录平台后：

Projects 视图：所有项目的概览——运行次数、错误率
Traces 视图：项目下每条 trace 对应一次完整执行；点进去能看到 Chain / LLM / Tool / Retriever 的调用层级、输入输出、耗时
出错时，错误信息和堆栈直接展示在 trace 里
可以给 trace 打 metadata 和 tags，方便组织和筛选

Playground

Playground 是交互式的提示试验台：改提示、换模型、调参数（temperature、max_tokens），立即看输出；所有运行自动留 trace。compare 模式可以把两个版本的输出并排对比——调提示词时特别有用。

Prompt Hub

Prompt Hub 用来存放、版本化、复用提示模板。界面上创建模板，{xxx} 占位符会自动识别成 inputs；修改模板会留 commit 记录，可以回溯。（文档地址）

代码里直接拉取调用：

创建模板，右边自动出现 inputs：

修改有 commit 记录：

数据集与评估

评估是 LangSmith 对我来说价值最大的部分：凭感觉调提示，和拿数据说话，是两回事。

创建数据集

三种方式：

UI 里手动创建，添加输入和期望输出（Ground Truth）
从生产 trace 里筛选样本，「Add to Dataset」存进数据集——基于真实用户交互做评估，这是最推荐的路子
SDK 代码创建（见下）

SDK 创建数据集并运行评估

from langsmith import Client, evaluate

client = Client()

dataset_name = "My Translation Evaluations"
try:
 dataset = client.create_dataset(dataset_name, description="Dataset for evaluating translations.")
 client.create_example(
 inputs={"input_language": "English", "output_language": "French", "text": "Hello"},
 outputs={"expected_translation": "Bonjour"},
 dataset_id=dataset.id,
 )
except Exception:
 # 大概率是数据集已存在，取现成的
 dataset = client.list_datasets(dataset_name_contains=dataset_name)[0]

# 被评估的目标：包装成「接收 inputs、返回 dict」的函数（chain 即上文的翻译链）
def predict(inputs: dict) -> dict:
 translation = chain.invoke({
 "input_language": inputs["input_language"],
 "output_language": inputs["output_language"],
 "text": inputs["text"],
 })
 return {"output": translation}

# 自定义评估器：精确匹配
def exact_match(run, example) -> dict:
 expected = example.outputs["expected_translation"]
 score = int(run.outputs["output"].strip() == expected)
 return {"key": "exact_match", "score": score}

results = evaluate(
 predict,
 data=dataset_name,
 evaluators=[exact_match],
 experiment_prefix="translation-eval",
)

修订说明：原文这里原本是两行省略号占位（没有可运行代码），上面是按 langsmith SDK 的 evaluate() 补全的最小示例，具体参数以官方文档为准。

评估器除了自定义函数，常用的几类：

字符串评估器：精确匹配、正则、包含性判断
LLM-as-Judge：用另一个模型按标准打分（相关性、质量、有害性）
轨迹评估器：评 Agent 的完整执行轨迹（工具用得对不对），而不只是最终答案
比较评估器：两个版本在同一输入上并排比

⚠️ 版本注记：旧文档里的 RunCollector / QAEvalChain（langchain.evaluation 体系）已被 LangSmith 平台和 SDK 的 evaluate() 取代，这里留个名字备查。

我的建议

先在 LangSmith UI 里熟悉评估流程，再上 SDK
应用跑起来、有 trace 上报是评估的前提——评估的对象就是这些运行记录
数据集从真实 trace 里攒，比凭空编造更接近真实分布

监控与协作

应用部署后，LangSmith 可以持续监控：仪表盘看延迟、错误率、token 消耗、用户反馈；指标超阈值可设警报；用户点赞/点踩能关联到对应 trace。团队协作方面，组织内共享 trace、数据集和评估结果。

总结

接入成本几乎为零：环境变量一设，LangChain 应用自动上报
调试靠 trace，迭代靠 Playground + Prompt Hub，质量靠数据集 + 评估
观测分工：给用户看的中间过程用 astream_events，记录和分析交给 LangSmith
官方文档：docs.smith.langchain.com