LangChain 项目跑通 Demo 容易，为什么团队协作就崩了？-三亩地-编程学习日记

《我把LangChain接进项目后，先推翻了几个想当然》看起来是个大话题，但真落到项目里，常常就是几个具体选择。下面我尽量按实际开发时会遇到的问题来讲。

摘要

之前我带团队做了一个内部知识库助手，用 LangChain 搭起来，本地跑一切正常。结果上线后，权限问题、日志缺失、工具调用失败，一个接一个。最后回滚了三轮，才发现我们当时写的代码，根本撑不起团队协作的场景。

这件事让我意识到：LangChain 从 Demo 到生产，中间差的不是调 API 的能力，而是工程化的细节。

今天就把这个复盘过程写出来，希望能帮你少走点弯路。

---

LangChain 能解决什么问题

很多人第一反应是：LangChain 就是个调模型的框架嘛，直接调 API 不就行了？

确实，如果你只是想发一条消息拿到回复，OpenAI 的 SDK 够用了。但真正做应用的时候，你会发现需求开始变复杂：

需要把用户的提问拆成多个步骤
需要调用外部工具，比如查数据库、搜索文档
需要管理对话上下文，让模型记住之前的内容
需要处理工具调用的错误和重试

这些场景，LangChain 提供了一套标准化的抽象。它不是必须用的，但用了之后，代码结构会更清晰，后续维护成本会低很多。

我们团队一开始也是自己写代码，后来发现代码越来越乱，才决定用 LangChain 重构。重构后，工具调用的逻辑和模型调用的逻辑分开了，加新工具也变得简单。

---

核心组件

LangChain 的核心组件不多，但理解它们的关系很重要。

Language Model：封装了各种模型的调用接口，包括 OpenAI、Anthropic、国产模型等。统一接口的好处是，切换模型时不用改太多代码。

Prompt：管理提示词模板。用ChatPromptTemplate可以把多个消息模板组合在一起，支持动态填充变量。

Chain：把多个组件串联起来，形成一个完整的流程。比如"接收用户输入 → 查询知识库 → 调用模型 → 返回结果"。

Memory：管理对话历史。LangChain 提供了多种内存实现，比如ConversationBufferMemory、VectorStoreRetrieverMemory。

Tools：让模型能够调用外部工具。定义一个工具，模型就能在需要时主动调用它。

这几个组件之间的关系，可以用一张图来理解：用户输入经过 Prompt 处理后，交给模型，模型可能调用工具，结果经过 Chain 组装后返回给用户，Memory 负责保存对话历史。

---

Prompt 与 Chain

Prompt 是 AI 应用的灵魂，好的 Prompt 能让模型表现更好。

LangChain 的ChatPromptTemplate支持多消息模板的组合。比如一个客服场景，可以这样写：

from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个专业的客服助手，请用简洁的语言回答问题。"), MessagesPlaceholder("chat_history"), ("human", "{question}"), ])

这里MessagesPlaceholder用来插入历史对话，{question}是动态变量。

Chain 则是把多个步骤串起来。LangChain 提供了LCEL（LangChain Expression Language），可以用管道符号|把组件连接起来：

from langchain.chat_models import ChatOpenAI from langchain.prompts import ChatPromptTemplate from langchain.chains import LLMChain llm = ChatOpenAI(model="gpt-3.5-turbo") chain = prompt | llm

这种链式写法很直观，也容易调试。每一步的输出都能看到，方便定位问题。

---

工具调用

工具调用是 LangChain 里最实用的功能之一。模型可以根据用户的问题，自动选择调用哪个工具。

定义工具的方式很简单：

from langchain.tools import tool @tool def get_weather(city: str) -> str: """查询指定城市的天气""" # 这里调用天气 API return f"{city}今天晴，气温25度"

然后把这个工具传给模型：

from langchain.agents import create_openai_functions_agent, AgentExecutor from langchain import OpenAI agent = create_openai_functions_agent(llm, [get_weather], prompt) executor = AgentExecutor(agent=agent, tools=[get_weather]) result = executor.invoke({"input": "北京今天天气怎么样？"}) print(result["output"])

模型会自动识别"天气"这个意图，调用get_weather工具，把结果返回给用户。

踩坑点：工具返回的格式要规范，否则模型可能解析失败。另外，工具调用的错误处理也很重要，比如 API 超时、权限不足等情况，需要捕获并给出友好的提示。

---

项目实战

我之前做的知识库助手，基本结构是这样的：

1. 用户提问
2. 用向量检索查询相关文档
3. 把检索结果和问题一起传给模型
4. 模型生成回答

代码大致如下：

from langchain.vectorstores import Chroma from langchain.embeddings import OpenAIEmbeddings from langchain.chat_models import ChatOpenAI from langchain.prompts import ChatPromptTemplate from langchain.chains import RetrievalQA embeddings = OpenAIEmbeddings() vectorstore = Chroma(persist_directory="./db", embedding_function=embeddings) prompt_template = """基于以下已知信息，简洁准确地回答用户问题。 如果无法从已知信息中找到答案，请说"抱歉，我不知道"。 已知信息： {context} 用户问题：{question} """ prompt = ChatPromptTemplate.from_messages([ ("system", prompt_template), ("human", "{question}"), ]) llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0) qa_chain = RetrievalQA.from_chain_type( llm=llm, retriever=vectorstore.as_retriever(), chain_type="stuff", chain_type_kwargs={"prompt": prompt} ) result = qa_chain.invoke({"query": "公司请假流程是什么？"}) print(result["result"])

这个 Demo 在本地跑得很顺。但上线后问题就来了：

权限问题：不同部门的员工能看到的内容不同，但我们没有做权限控制
日志缺失：不知道谁在什么时候问了什么问题，出了问题没法排查
超时处理：向量检索有时候很慢，但没有超时机制，请求一直挂着

这些问题解决起来比调 API 麻烦多了。后来我们加了权限过滤、日志记录、超时设置，才真正能用。

简历建议：如果你要在简历上写 LangChain 项目，不要只写"用了 LangChain 做了个知识库"。要写清楚：做了什么、用了哪些组件、解决了什么问题、有什么指标。比如：

> 基于 LangChain + Chroma 搭建内部知识库助手，支持多部门权限隔离，日均查询 500+ 次，平均响应时间 < 2s。

这样的表达更有说服力。

---

总结

LangChain 确实能帮我们快速搭起 AI 应用的原型，但从 Demo 到生产，中间还有很多工程化的细节要处理：

权限控制：不同用户看到的内容要隔离
日志记录：每一次调用都要有迹可循
错误处理：工具调用、模型调用都要有兜底
性能优化：检索、生成都要控制时间

我们团队踩了三轮坑，才把这些补齐。希望我的经验能帮你少走点弯路。

如果你在写 LangChain 项目时遇到问题，欢迎评论区交流。

资料展示

下面是我整理的AI大模型学习资料和工具包预览，适合收藏后按主题逐步学习。

如果你想看完整资料目录，可以在评论区留言「资料」；也欢迎告诉我你更关注AI大模型里的哪类内容。

日记详情

LangChain 项目跑通 Demo 容易，为什么团队协作就崩了？

摘要

目录