LangChain写Demo很顺，为什么一上线团队就集体翻车？

codeingg

88人浏览 · 2026-08-15 10:00:52

codeingg · 2026-08-15 10:00:52 发布

这篇我按“先跑起来、再讲取舍”的方式写《LangChain跑通那天，我才发现前面的学习顺序反了》。概念会讲，但重点放在代码怎么组织、哪里容易踩坑。

摘要

摘要：LangChain 从入门到实战，教程满天飞，但真正的项目上线却往往卡在权限、日志、可观测这些"不起眼"的地方。本文结合一个真实项目经历，从 Demo 到可维护应用，拆解 LangChain 的核心组件与工程化陷阱，给出可复用的实战建议。

---

LangChain 能解决什么问题

文章插图 1

很多人第一次接触 LangChain 是在 B 站或公众号，看到一段 30 秒的代码，调一下模型，输出个答案，就觉得"我会了"。

但真正上手做项目的时候，问题就来了：

Prompt 写死了，换场景就崩
模型输出不可控，解析经常出错
工具调用逻辑混乱，调试像抓瞎
上线后不知道请求去哪了，日志一塌糊涂

LangChain 的本质是一个抽象层，把大模型调用、Prompt 管理、工具链、工作流这些重复劳动封装起来，让开发者专注业务逻辑而不是底层细节。

但它不是银弹。用得好，效率翻倍；用不好，坑能埋到你怀疑人生。

---

核心组件：别被名词吓到

文章插图 2

LangChain 的组件名听起来很高大上，但其实就几类：

1. Models（模型层）
不管是 OpenAI、Claude，还是国内的大模型，LangChain 统一了调用接口。你不需要为每个模型写一套代码。

2. Prompts（提示词层）
把模板和变量分离，方便复用和版本管理。这是 Demo 阶段最容易忽视的部分。

3. Chains（链式调用）
把多个步骤串起来，比如"提取信息 → 调用工具 → 生成回答"。

4. Tools（工具）
让模型能调用外部 API，比如搜索、数据库、代码执行。这是 Agent 能力的基础。

5. Memory（记忆）
短期记忆靠 Context Window，长期记忆靠向量数据库。别指望模型"记住"什么，该存还是得存。

---

CSDN资料领取方式

Prompt 与 Chain：Demo 阶段最容易踩的坑

Demo 阶段，很多人会这样写：

from langchain.chat_models import ChatOpenAI
from langchain.prompts import ChatPromptTemplate
from langchain.chains import LLMChain

llm = ChatOpenAI(model="gpt-4", temperature=0)
prompt = ChatPromptTemplate.from_template("帮我总结这段文字：{text}")
chain = LLMChain(llm=llm, prompt=prompt)
result = chain.run(text="这是一段测试文字...")

能跑，输出也正常。但一旦进入项目阶段，问题就来了：

问题一：Prompt 硬编码，无法复用

每个功能都写一个 Prompt 模板，项目大了之后根本维护不了。

问题二：输出格式不可控

模型可能返回 JSON，也可能返回纯文本，解析代码写得像灾难现场。

问题三：错误处理几乎为零

模型超时、输出异常、工具调用失败，这些在 Demo 里不需要考虑，但上线后就是 P0 问题。

我的建议是，Prompt 应该版本化管理，用配置文件或者专门的 Prompt 仓库，而不是散落在代码里。输出格式用 Structured Output 或者 Pydantic 模型约束，错误处理要写清楚重试逻辑。

---

工具调用：从玩具到生产的关键一跃

工具调用是 LangChain 最强大的能力，也是 Demo 和上线之间最大的鸿沟。

一个简单的工具调用 Demo：

from langchain.tools import Tool
from langchain.agents import initialize_agent, AgentType
import requests

def search_web(query: str) -> str:
    """搜索网页，返回结果摘要"""
    # 这里调用真实搜索 API
    return f"搜索结果：{query}"

web_search_tool = Tool(
    name="web_search",
    func=search_web,
    description="用于搜索网页信息"
)

agent = initialize_agent(
    tools=[web_search_tool],
    llm=llm,
    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True
)

agent.run("今天 AI 领域有什么大新闻？")

这段代码能跑，但有几个致命问题：

1. 工具权限没有管控

模型可以调用任何工具，包括可能危险的接口。生产环境必须做权限隔离。

2. 调用日志缺失

不知道模型调用了什么工具、传了什么参数、返回了什么结果。排查问题全靠猜。

3. 超时和错误处理缺失

工具调用可能超时、可能返回异常，Demo 里不会暴露，上线后就是线上事故。

4. 可观测性为零

请求链路断了，你不知道是模型问题、工具问题，还是网络问题。

这是 Demo 到生产最大的坎。很多人卡在这里，要么不敢上线，要么上线后天天救火。

---

项目实战：Demo 到可维护应用的完整路径

我最近接手了一个内部 AI 助手项目，初期也是 Demo 阶段，模型调通、工具能跑，但一上测试环境就翻车。

以下是我们最终的解决方案：

1. 工具权限分层

不同角色能调用的工具不同，普通用户只能搜索，管理员可以执行操作。用中间件做权限校验，而不是依赖模型"自觉"。

2. 全链路日志

每次请求记录：用户输入、模型响应、工具调用（参数和结果）、耗时。日志结构化输出，方便后续分析和排查。

import logging
import json
from datetime import datetime

logger = logging.getLogger("agent_trace")

def trace_tool_call(tool_name, input_params, output_result, duration_ms):
    logger.info(json.dumps({
        "timestamp": datetime.now().isoformat(),
        "tool": tool_name,
        "input": input_params,
        "output": output_result,
        "duration_ms": duration_ms
    }, ensure_ascii=False))

3. 可观测性接入

用 OpenTelemetry 或者 LangSmith 这类工具，追踪每次请求的完整链路。模型调用了什么、参数是什么、结果如何，一目了然。

4. 错误处理规范化

工具调用失败要重试，重试失败要降级，降级失败要给用户明确的错误提示。不能让用户看到一堆技术报错。

5. Prompt 模板化

用 Jinja2 或者 LangChain 的 PromptTemplate，把 Prompt 和代码分离，方便非技术人员修改。

---