LangChain 超详细入门与实战教程（基于通义千问 Qwen3-Max）

适合人群：完全零基础，甚至不太会 Python，但想彻底掌握 LangChain 的你！ 核心模型：全程使用阿里云通义千问 Qwen3-Max（通过 DashScope API） 目标：学完后，你能自信地教别人如何用 LangChain 搭建 AI 应用！

1. 前言：LangChain 是什么？为什么你需要它？
2. 准备工作：安装 + 获取 Qwen3-Max API 密钥
3. 第 1 步：让 AI 开口说话 —— 接入 Qwen3-Max 模型
4. 第 2 步：给 AI 写“剧本” —— 提示词模板（Prompts）
5. 第 3 步：把多个步骤串起来 —— 链（Chains）
6. 第 4 步：让 AI 有“记忆” —— 记忆系统（Memory）
7. 第 5 步：让 AI 会“思考+行动” —— 智能体（Agents）
8. 第 6 步：让 AI 会“查资料” —— 检索增强生成（RAG）
9. 实战项目：搭建企业知识库问答机器人
10. 总结 & 下一步学习建议

想象一下：

• 大模型（如 Qwen3-Max） 就像一个超级聪明的“大脑”，但它没有手脚，不能自己做事。
• LangChain 就是给这个大脑装上“手脚”和“工具箱”的框架。它让 AI 能：
  • 记住你说过的话（记忆）
  • 查阅文档或数据库（检索）
  • 调用计算器、搜索网页等工具（智能体）
  • 按照你的剧本一步步执行任务（链）

💡 一句话总结：LangChain = 大模型 + 工具 + 记忆 + 流程控制

即使你不会编程，只要跟着本教程一步步操作，也能做出强大的 AI 应用！

第 1 步：安装必要工具

打开你的电脑终端（Mac/Linux 用 Terminal，Windows 用 PowerShell 或 CMD），运行：

# 创建虚拟环境（推荐，避免包冲突） python -m venv langchain_env # 激活虚拟环境 # Windows: langchain_envScriptsactivate # Mac/Linux: source langchain_env/bin/activate ​ # 安装 LangChain 和相关依赖 pip install langchain langchain-community langchain-core langchain-openai langchain-text-splitters langchain-chroma python-dotenv dashscope

✅ 注意：我们使用 而不是 OpenAI，因为我们要调用阿里云的 Qwen3-Max。

第 2 步：获取 DashScope API 密钥

1. 访问 阿里云 DashScope 控制台
2. 登录后，点击右上角「API-KEY 管理」
3. 点击「创建 API Key」，复制生成的密钥（一串字母数字组合）
4. 在项目根目录创建 文件，写入：

DASHSCOPE_API_KEY=你的密钥粘贴在这里

🔒 安全提示： 文件不要上传到 GitHub！它包含你的私钥。

LangChain 把大模型称为 LLM（Large Language Model）。我们要做的第一件事，就是让 Qwen3-Max 说话。

代码示例：最简单的 AI 对话

# 1_model_basic.py from langchain_community.chat_models import ChatTongyi from dotenv import load_dotenv import os ​ # 加载 .env 文件中的密钥 load_dotenv() ​ # 创建 Qwen3-Max 模型实例 # model_name="qwen-max" 表示使用 Qwen3-Max（阿里云最新最强版本） llm = ChatTongyi(    model_name="qwen-max",    dashscope_api_key=os.getenv("DASHSCOPE_API_KEY") ) ​ # 让 AI 回答一个问题 response = llm.invoke("你好！你是谁？") print(response.content)  # 打印 AI 的回答

🧠 比喻：这就像你第一次给新买的机器人插上电，问它“你是谁？”

运行结果可能是：

你好！我是通义千问（Qwen），阿里巴巴集团旗下的超大规模语言模型...

✅ 恭喜你！ 你已经成功让 AI 开口说话了！

直接问问题太随意了。我们想让 AI 按照固定格式回答，比如“用小学生能听懂的话解释”。

这就需要 提示词模板（PromptTemplate） —— 给 AI 的“剧本”。

示例 1：带变量的提示模板

# 2_prompt_template.py from langchain_core.prompts import ChatPromptTemplate from langchain_community.chat_models import ChatTongyi from dotenv import load_dotenv import os ​ load_dotenv() ​ # 创建模型 llm = ChatTongyi(model_name="qwen-max", dashscope_api_key=os.getenv("DASHSCOPE_API_KEY")) ​ # 定义提示模板：{topic} 是一个占位符，后面会被替换 template = "请用不超过 50 个字，向一个 10 岁的小朋友解释什么是 {topic}。" prompt = ChatPromptTemplate.from_template(template) ​ # 输入具体话题 topic = "人工智能" ​ # 生成完整提示 formatted_prompt = prompt.format(topic=topic) print("完整提示：", formatted_prompt) ​ # 让 AI 回答 response = llm.invoke(formatted_prompt) print("AI 回答：", response.content)

输出可能：

完整提示： 请用不超过 50 个字，向一个 10 岁的小朋友解释什么是 人工智能。 AI 回答： 人工智能就是让机器像人一样思考和做事的技术。

示例 2：结构化输出（让 AI 返回 JSON）

有时候我们需要 AI 返回固定格式的数据，比如姓名、年龄。

# 2_output_parser.py from langchain_core.output_parsers import JsonOutputParser from langchain_core.pydantic_v1 import BaseModel, Field from langchain_core.prompts import ChatPromptTemplate from langchain_community.chat_models import ChatTongyi from dotenv import load_dotenv import os ​ load_dotenv() ​ # 定义我们期望的输出结构 class PersonInfo(BaseModel):    name: str = Field(description="人的姓名")    age: int = Field(description="人的年龄") ​ # 创建解析器 parser = JsonOutputParser(pydantic_object=PersonInfo) ​ # 创建提示模板（自动加入格式说明） prompt = ChatPromptTemplate.from_template(    "从以下文本中提取人物信息：{text} {format_instructions}" ).partial(format_instructions=parser.get_format_instructions()) ​ llm = ChatTongyi(model_name="qwen-max", dashscope_api_key=os.getenv("DASHSCOPE_API_KEY")) ​ # 构建完整链：提示 → 模型 → 解析 chain = prompt | llm | parser ​ # 输入文本 text = "张三今年 25 岁，是一名程序员。" ​ # 执行 result = chain.invoke({"text": text}) print("结构化结果：", result) # 输出：{'name': '张三', 'age': 25}

💡 关键点： 符号表示“管道”，把多个组件串起来。

Chain（链） 就是把多个操作按顺序连接起来，像流水线一样。

示例 1：最简单的 LLMChain（已弃用，但概念重要）

⚠️ 注意：LangChain 0.2+ 推荐用 （即 管道），但理解 LLMChain 有助于入门。

# 3_chain_simple.py from langchain_core.prompts import PromptTemplate from langchain_community.chat_models import ChatTongyi from langchain.chains import LLMChain  # 旧方式，仅作演示 from dotenv import load_dotenv import os ​ load_dotenv() llm = ChatTongyi(model_name="qwen-max", dashscope_api_key=os.getenv("DASHSCOPE_API_KEY")) ​ prompt = PromptTemplate.from_template("写一首关于{主题}的五言诗。") chain = LLMChain(llm=llm, prompt=prompt) ​ result = chain.run("春天") print(result)

示例 2：现代方式 —— 使用 管道（推荐！）

# 3_chain_pipeline.py from langchain_core.prompts import ChatPromptTemplate from langchain_community.chat_models import ChatTongyi from langchain_core.output_parsers import StrOutputParser from dotenv import load_dotenv import os load_dotenv() llm = ChatTongyi(model_name="qwen-max", dashscope_api_key=os.getenv("DASHSCOPE_API_KEY")) # 定义链：模板 → 模型 → 字符串输出 prompt = ChatPromptTemplate.from_template("用幽默的方式解释：{concept}") chain = prompt | llm | StrOutputParser() result = chain.invoke({"concept": "量子力学"}) print(result)

示例 3：顺序链（SequentialChain）—— 多步处理

比如：先翻译，再总结。

# 3_sequential_chain.py from langchain_core.prompts import ChatPromptTemplate from langchain_community.chat_models import ChatTongyi from langchain_core.output_parsers import StrOutputParser from dotenv import load_env import os load_dotenv() llm = ChatTongyi(model_name="qwen-max", dashscope_api_key=os.getenv("DASHSCOPE_API_KEY")) # 第一步：翻译成中文 translate_prompt = ChatPromptTemplate.from_template("将以下英文翻译成中文：{english_text}") translate_chain = translate_prompt | llm | StrOutputParser() # 第二步：总结内容 summarize_prompt = ChatPromptTemplate.from_template("用一句话总结以下内容：{chinese_text}") summarize_chain = summarize_prompt | llm | StrOutputParser() # 组合链 full_chain = {"chinese_text": translate_chain} | summarize_chain english_text = "Artificial intelligence is transforming the world by enabling machines to learn from data and make decisions." result = full_chain.invoke({"english_text": english_text}) print("最终总结：", result)

🧩 比千问 Qwen 教程喻：Chain 就像做菜——洗菜 → 切菜 → 炒菜，每一步都依赖上一步的结果。

默认情况下，AI 每次对话都是“失忆”的。我们要让它记住上下文！

示例：对话记忆（ConversationBufferMemory）

# 4_memory_conversation.py from langchain_community.chat_models import ChatTongyi from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain_core.runnables.history import RunnableWithMessageHistory from langchain_community.chat_message_histories import ChatMessageHistory from langchain_core.output_parsers import StrOutputParser from dotenv import load_dotenv import os load_dotenv() llm = ChatTongyi(model_name="qwen-max", dashscope_api_key=os.getenv("DASHSCOPE_API_KEY")) # 存储对话历史 store = {} def get_session_history(session_id: str): if session_id not in store: store[session_id] = ChatMessageHistory() return store[session_id] # 带记忆的提示模板 prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个乐于助人的助手。"), MessagesPlaceholder(variable_name="history"), # 插入历史对话 ("human", "{input}") ]) chain = prompt | llm | StrOutputParser() # 包装成带记忆的链 with_message_history = RunnableWithMessageHistory( chain, get_session_history, input_messages_key="input", history_messages_key="history", ) # 第一轮对话 response1 = with_message_history.invoke( {"input": "我叫小明"}, config={"configurable": {"session_id": "abc123"}} ) print("AI 1:", response1) # 第二轮对话（AI 记得你叫小明！） response2 = with_message_history.invoke( {"input": "我叫什么名字？"}, config={"configurable": {"session_id": "abc123"}} ) print("AI 2:", response2)

输出：

AI 1: 你好，小明！有什么我可以帮你的吗？ AI 2: 你叫小明！

💾 记忆类型：

• ：记住全部对话（简单但占用内存）
• ：只记住摘要（适合长对话）
• ：用向量数据库存长期记忆（高级）

Agent（智能体） 是 LangChain 最酷的功能！它能让 AI：

1. 思考：分析问题该怎么做
2. 行动：调用工具（如计算器、搜索、查数据库）
3. 观察：看工具返回的结果
4. 重复直到解决问题（ReAct 原理）

步骤 1：定义工具（Tool）

# 5_agent_tool.py from langchain.tools import tool @tool def multiply(a: int, b: int) -> int: """将两个整数相乘""" return a * b @tool def add(a: int, b: int) -> int: """将两个整数相加""" return a + b

步骤 2：创建 Agent

# 5_agent_executor.py from langchain_community.chat_models import ChatTongyi from langchain import hub from langchain.agents import create_openai_tools_agent, AgentExecutor from dotenv import load_dotenv import os load_dotenv() llm = ChatTongyi(model_name="qwen-max", dashscope_api_key=os.getenv("DASHSCOPE_API_KEY")) # 获取预设的 ReAct 提示模板 prompt = hub.pull("hwchase17/openai-tools-agent") # 兼容 Qwen # 创建 Agent agent = create_openai_tools_agent(llm, [multiply, add], prompt) # 创建执行器 agent_executor = AgentExecutor(agent=agent, tools=[multiply, add], verbose=True) # 提问 result = agent_executor.invoke({"input": "3 乘以 4 再加上 5 等于多少？"}) print("最终答案：", result["output"])

🔍 verbose=True 会打印 AI 的思考过程，例如：

Thought: 我需要先计算 3*4，再加 5。 Action: multiply Action Input: {"a": 3, "b": 4} Observation: 12 Thought: 现在计算 12 + 5 Action: add Action Input: {"a": 12, "b": 5} Observation: 17 Final Answer: 17

🤖 ReAct 原理 = Reasoning（推理） + Action（行动）

RAG（Retrieval-Augmented Generation） 让 AI 能查阅你的私有文档，而不是只靠训练数据。

步骤 1：加载文档

# 6_rag_load.py from langchain_community.document_loaders import TextLoader # 假设你有一个 company_info.txt 文件 loader = TextLoader("company_info.txt", encoding="utf-8") docs = loader.load() print("文档内容：", docs[0].page_content[:100])

步骤 2：分割文本

大文档要切成小块，方便检索。

from langchain_text_splitters import RecursiveCharacterTextSplitter text_splitter = RecursiveCharacterTextSplitter( chunk_size=200, # 每块最多 200 字 chunk_overlap=20 # 相邻块重叠 20 字，避免断句 ) splits = text_splitter.split_documents(docs)

步骤 3：存入向量数据库

from langchain_chroma import Chroma from langchain_community.embeddings import DashScopeEmbeddings from dotenv import load_dotenv import os load_dotenv() # 使用 DashScope 的 embedding 模型（免费！） embedding = DashScopeEmbeddings( model_name="text-embedding-v2", dashscope_api_key=os.getenv("DASHSCOPE_API_KEY") ) # 存入 Chroma 向量数据库（本地存储） vectorstore = Chroma.from_documents(documents=splits, embedding=embedding)

步骤 4：检索 + 生成答案

from langchain.chains import create_retrieval_chain from langchain.chains.combine_documents import create_stuff_documents_chain from langchain_core.prompts import ChatPromptTemplate # 检索器 retriever = vectorstore.as_retriever() # 生成答案的链 prompt = ChatPromptTemplate.from_template(""" 根据以下上下文回答问题： <context> {context} </context> 问题：{input} """) document_chain = create_stuff_documents_chain(llm, prompt) # 完整 RAG 链 retrieval_chain = create_retrieval_chain(retriever, document_chain) # 提问 response = retrieval_chain.invoke({"input": "公司成立时间是？"}) print("答案：", response["answer"])

📚 RAG 比喻：就像学生考试前翻笔记——先查资料（检索），再组织语言答题（生成）。

现在，我们整合所有知识，做一个真正的应用！

项目需求

• 用户上传公司制度 PDF
• 机器人能回答关于制度的问题
• 支持多轮对话（带记忆）

完整代码

# 7_enterprise_bot.py import os from dotenv import load_dotenv from langchain_community.document_loaders import PyPDFLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_chroma import Chroma from langchain_community.embeddings import DashScopeEmbeddings from langchain_community.chat_models import ChatTongyi from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain.chains import create_history_aware_retriever, create_retrieval_chain from langchain.chains.combine_documents import create_stuff_documents_chain from langchain_core.runnables.history import RunnableWithMessageHistory from langchain_community.chat_message_histories import ChatMessageHistory load_dotenv() # === 1. 加载并处理文档 === loader = PyPDFLoader("company_policy.pdf") # 替换为你的 PDF docs = loader.load() text_splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50) splits = text_splitter.split_documents(docs) # === 2. 向量数据库 === embedding = DashScopeEmbeddings(model_name="text-embedding-v2") vectorstore = Chroma.from_documents(documents=splits, embedding=embedding) retriever = vectorstore.as_retriever() # === 3. 模型与提示 === llm = ChatTongyi(model_name="qwen-max") # 用于生成回答的提示 qa_prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个公司制度问答助手。请根据以下上下文回答问题： {context}"), MessagesPlaceholder("chat_history"), ("human", "{input}") ]) # 用于重写用户问题的提示（考虑历史） contextualize_q_prompt = ChatPromptTemplate.from_messages([ MessagesPlaceholder("chat_history"), ("human", "{input}"), ("ai", "请根据聊天历史，将用户的问题改写成一个独立的问题。") ]) # === 4. 构建链 === # 历史感知检索器 history_aware_retriever = create_history_aware_retriever( llm, retriever, contextualize_q_prompt ) # 文档问答链 question_answer_chain = create_stuff_documents_chain(llm, qa_prompt) # 完整 RAG 链 rag_chain = create_retrieval_chain(history_aware_retriever, question_answer_chain) # === 5. 添加对话记忆 === store = {} def get_session_history(session_id: str): if session_id not in store: store[session_id] = ChatMessageHistory() return store[session_id] conversational_rag_chain = RunnableWithMessageHistory( rag_chain, get_session_history, input_messages_key="input", history_messages_key="chat_history", output_messages_key="answer", ) # === 6. 测试 === session_id = "user_123" questions = [ "年假有多少天？", "那如果我工作满 5 年呢？" # AI 会结合上文理解“年假” ] for q in questions: response = conversational_rag_chain.invoke( {"input": q}, config={"configurable": {"session_id": session_id}} ) print(f"Q: {q}") print(f"A: {response['answer']} ")

✅ 效果：第二问“那如果我工作满 5 年呢？”会被自动理解为“工作满 5 年的年假有多少天？”

🎯 你已经掌握了：

🔜 下一步建议：

1. 尝试更多工具：让 Agent 调用天气 API、数据库等
2. 优化 RAG：使用更好的分块策略、混合检索
3. 部署上线：用 FastAPI + Streamlit 做 Web 界面
4. 监控与评估：用 LangSmith 跟踪 AI 表现