LangChain 中文入门教程

一、核心概念与架构

1.1 什么是 LangChain？

LangChain 是一个用于构建大语言模型（LLM）驱动应用的开源框架，核心能力是将 LLM 与外部数据源、工具、记忆系统等灵活集成，让开发者能快速开发出具备复杂能力的 AI 应用（如知识库问答、数据分析、多智能体协作等）。

1.2 核心设计哲学

• 组件化：所有功能都拆分为标准化组件（如 Models、Prompts、Chains 等），像乐高积木一样自由组合。
• 链式调用：通过「链（Chain）」将多个组件串联成完整工作流，实现复杂任务自动化。
• 可扩展：支持对接 OpenAI、Anthropic、Hugging Face 等主流 LLM，以及各类向量数据库、工具库。

1.3 核心组件概览

组件类别	主要组件	功能说明
Models	LLMs、ChatModels、Embeddings	与各类语言模型交互，生成文本/向量
Prompts	PromptTemplate、FewShotPrompt	提示词模板化管理，保证输出一致性
Chains	LLMChain、SequentialChain	将多个组件链接成可执行的工作流
Agents	Agent、Tool、AgentExecutor	让 LLM 自主选择并调用工具完成复杂任务
Memory	ConversationBufferMemory	管理对话历史，实现上下文记忆
Indexes	Vectorstores、Retrievers	文档加载、分割、向量化与语义检索

---

二、快速开始

2.1 安装与环境配置

# 基础安装
pip install langchain

# 按需安装常用扩展
pip install langchain langchain-openai langchain-community
pip install langchain-chroma  # 本地向量数据库
pip install langchain-experimental  # 实验性功能

2.2 第一个 LangChain 程序（Chat 版）

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

# 完全对应你这段 Java 配置
llm = ChatOpenAI(
    model="gpt-4o-mini",        # 模型名称
    api_key="demo",             # API密钥（测试用）
    base_url="http://langchain4j.dev/demo/openai/v1",  # 接口地址
    temperature=0.7,            # 随机性（0=严谨，1=创意）
    max_tokens=1000,            # 最大响应长度
    streaming=False              # 开启流式输出
)

# 测试调用
messages = [
    SystemMessage(content="你是一个专业的Python编程助手"),
    HumanMessage(content="如何用Python读取CSV文件？")
]

res = llm.invoke(messages)
print(res.content)

# 设置环境变量（推荐用 .env 文件）
pip install python-dotenv

# .env 文件内容
OPENAI_MODEL=deepseek-chat
OPENAI_API_KEY=xxx
OPENAI_BASE_URL=https://api.deepseek.com
TEMPERATURE=0.7
MAX_TOKENS=1000

# 从环境变量读取配置
llm = ChatOpenAI(
    model=os.getenv("OPENAI_MODEL"),
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=os.getenv("OPENAI_BASE_URL"),
    temperature=float(os.getenv("TEMPERATURE")),
    max_tokens=int(os.getenv("MAX_TOKENS")),
    streaming=True
)

---

三、核心组件详解

3.1 Models（模型层）

支持多种 LLM 与嵌入模型：

• Chat 模型 ：ChatOpenAI（GPT-3.5/4）、ChatAnthropic（Claude）、ChatHuggingFace
• 文本补全模型 ：OpenAI（旧版接口）、HuggingFacePipeline（本地模型）
• 嵌入模型 ：OpenAIEmbeddings（生成文本向量，用于检索）

# 示例：OpenAI 嵌入模型
from langchain_openai import OpenAIEmbeddings
embeddings = OpenAIEmbeddings(model="text-embedding-ada-002")
vector = embeddings.embed_query("Hello, LangChain!")  # 生成 1536 维向量

3.2 Prompts（提示词模板）

通过模板化管理提示词，避免重复编写，支持动态变量注入：

from langchain.prompts import ChatPromptTemplate

# 聊天模板
prompt = ChatPromptTemplate.from_messages([
    ("system", "你是{role}助手，回答要简洁专业"),
    ("human", "{question}")
])

# 格式化提示词
formatted_prompt = prompt.format(role="技术支持", question="电脑无法开机怎么办？")

3.3 Chains（工作流链）

将多个组件串联成任务流，支持顺序执行、路由选择等：

from langchain.chains import LLMChain, SequentialChain

# 第一步：生成标题
title_chain = LLMChain(
    llm=llm,
    prompt=PromptTemplate(input_variables=["topic"], template="为{topic}生成标题："),
    output_key="title"
)

# 第二步：生成内容
# ====================== 1. 导入需要的工具包 ======================
# 提示词模板：用来定义让AI执行什么任务
from langchain_core.prompts import PromptTemplate
from langchain_openai import ChatOpenAI

# ====================== 2. 配置大模型（DeepSeek） ======================
# 初始化LLM模型对象，告诉程序用哪个AI、密钥、接口地址
llm = ChatOpenAI(
    model="gpt-4o-mini",        # 模型名称
    api_key="demo",             # API密钥（测试用）
    base_url="http://langchain4j.dev/demo/openai/v1",  # 接口地址
    temperature=0.7,            # 随机性（0=严谨，1=创意）
    max_tokens=1000,            # 最大响应长度
    streaming=False              # 开启流式输出
)

# ====================== 3. 定义第一步：生成标题 ======================
# 定义提示词模板：告诉AI"为某个主题生成标题"
# {topic} 是变量，后面会自动替换成具体内容（比如"人工智能"）
title_prompt = PromptTemplate.from_template("为{topic}生成一个吸引人的文章标题")

# 把【提示词】和【模型】串起来，形成一条可执行的"任务链"
# | 是新版LangChain的管道符，代表"把前面的输出传给后面"
title_chain = title_prompt | llm

# ====================== 4. 定义第二步：根据标题写正文 ======================
# 定义提示词：根据标题写正文
# {title} 变量会接收上一步生成的标题
content_prompt = PromptTemplate.from_template("根据这个标题写一段正文内容：{title}")

# 同样串成任务链
content_chain = content_prompt | llm

# ====================== 5. 定义顺序执行函数（串联两个步骤） ======================
# 自定义函数，实现：先生成标题 → 再用标题生成正文
def sequential_chain(inputs):
    # 从输入中取出主题（比如"人工智能"）
    topic = inputs["topic"]

    # -------------------- 执行第一步：生成标题 --------------------
    # 调用title_chain，传入{"topic": topic}，得到AI返回的标题内容
    # .content 是提取AI返回的纯文本
    title = title_chain.invoke({"topic": topic}).content

    # -------------------- 执行第二步：生成正文 --------------------
    # 把上一步得到的title传进去，让AI写正文
    content = content_chain.invoke({"title": title}).content

    # -------------------- 返回最终结果 --------------------
    # 返回一个字典，包含标题和正文
    return {
        "title": title,
        "content": content
    }

# ====================== 6. 执行整个流程 ======================
# 传入主题：人工智能 → 启动整个链式任务
result = sequential_chain({"topic": "人工智能"})

# ====================== 7. 打印输出结果 ======================
print("=" * 50)
print("标题：", result["title"])
print("=" * 50)
print("内容：", result["content"])

3.4 Memory（对话记忆）

让 AI 记住历史对话，实现上下文感知：

from langchain.memory import ConversationBufferMemory
from langchain.chains import ConversationChain

memory = ConversationBufferMemory(return_messages=True)
conversation = ConversationChain(llm=llm, memory=memory)

conversation.invoke({"input": "你好，我叫张三"})
conversation.invoke({"input": "我叫什么名字？"})  # 能正确回答「张三」

3.5 Indexes（文档检索与 RAG）

构建本地知识库，实现「基于文档问答」：

1. 文档加载：支持 PDF/Word/Markdown/网页等格式
2. 文本分割：将长文档切分成小块（避免超过 LLM 上下文限制）
3. 向量化存储：将文本块转为向量，存入向量数据库
4. 语义检索：根据用户问题，召回最相关的文档片段
5. 生成回答：将检索结果与问题一起喂给 LLM，生成精准答案

from langchain_community.embeddings import DashScopeEmbeddings
from langchain_community.document_loaders import PyPDFLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_community.vectorstores import Chroma
from langchain_classic.chains import RetrievalQA
from langchain_openai import ChatOpenAI
import sys
import io


# ===================== 1. 大模型配置 =====================
llm = ChatOpenAI(
    model="gpt-4o-mini",
    api_key="demo",
    base_url="http://langchain4j.dev/demo/openai/v1",
    temperature=0.7,
    max_tokens=1000,
    streaming=False
)

# ===================== 2. 阿里云 Embedding =====================
embeddings = DashScopeEmbeddings(
    model="text-embedding-v3",
    dashscope_api_key="xxxxx"
)

# ===================== 3. 加载PDF =====================
# 1. 文档加载
# 从文件加载
# loader = TextLoader("document.txt")
# documents = loader.load()

# 从网页加载
# web_loader = WebBaseLoader("https://example.com")
# web_docs = web_loader.load()

# 从PDF加载
loader = PyPDFLoader(r"C:\Users\fei\Desktop\运维\资源变更\20260319中审漏洞修复\中审漏洞修复.pdf")
docs = loader.load()

# 文本分割
splitter = RecursiveCharacterTextSplitter(
    chunk_size=1000,
    chunk_overlap=200
)
splits = splitter.split_documents(docs)


# 向量库
vectorstore = Chroma.from_documents(splits, embeddings)

# 问答链
qa_chain = RetrievalQA.from_chain_type(
    llm=llm,
    retriever=vectorstore.as_retriever(search_kwargs={"k": 5}),
    return_source_documents=True
)

# ===================== 4. 运行问答 =====================
print("=" * 60)
print("📄 RAG 问答结果：")
print("=" * 60)

result = qa_chain.invoke({"query": " nginx 版本漏洞修复是如何修复的？"})
print(result["result"])

print("\n" + "=" * 60)

3.6 Agents（智能体）

让 LLM 自主决策、调用工具完成复杂任务（如联网搜索、数学计算、发邮件等）：

from langchain.agents import (
    AgentExecutor,
    create_react_agent,
    Tool,
    load_tools
)
from langchain.agents.agent_types import AgentType
from langchain.tools import BaseTool

# 1. 自定义工具
class CalculatorTool(BaseTool):
    name = "calculator"
    description = "用于数学计算"
    
    def _run(self, query: str) -> str:
        """执行计算"""
        try:
            # 简单的安全计算
            import ast
            import operator
            
            # 只允许安全的操作符
            allowed_operators = {
                ast.Add: operator.add,
                ast.Sub: operator.sub,
                ast.Mult: operator.mul,
                ast.Div: operator.truediv,
                ast.Pow: operator.pow,
                ast.USub: operator.neg
            }
            
            def eval_expr(expr):
                return eval_node(ast.parse(expr, mode='eval').body)
            
            def eval_node(node):
                if isinstance(node, ast.Num):
                    return node.n
                elif isinstance(node, ast.BinOp):
                    left = eval_node(node.left)
                    right = eval_node(node.right)
                    op = allowed_operators.get(type(node.op))
                    if op is None:
                        raise ValueError(f"不支持的运算符: {node.op}")
                    return op(left, right)
                elif isinstance(node, ast.UnaryOp):
                    operand = eval_node(node.operand)
                    op = allowed_operators.get(type(node.op))
                    if op is None:
                        raise ValueError(f"不支持的运算符: {node.op}")
                    return op(operand)
                else:
                    raise TypeError(f"不支持的节点类型: {node}")
            
            result = eval_expr(query)
            return f"计算结果: {result}"
        except Exception as e:
            return f"计算错误: {str(e)}"
    
    async def _arun(self, query: str) -> str:
        """异步执行"""
        return self._run(query)

# 2. 加载预定义工具
tools = load_tools(
    ["serpapi", "requests_all", "wolfram-alpha"],
    llm=llm
)

# 添加自定义工具
tools.append(CalculatorTool())

# 3. 创建智能体
from langchain import hub

# 从LangChain Hub获取提示词
prompt = hub.pull("hwchase17/react")

agent = create_react_agent(
    llm=llm,
    tools=tools,
    prompt=prompt
)

# 4. 执行智能体
agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    memory=ConversationBufferMemory(
        memory_key="chat_history",
        return_messages=True
    ),
    verbose=True,
    handle_parsing_errors=True,
    max_iterations=5
)

result = agent_executor.invoke({
    "input": "北京现在的天气怎么样？然后计算(25 * 4) / 5的结果"
})

---

四、实战项目

项目1：智能文档问答系统

功能：支持多格式文档加载、向量化存储、对话式问答，可用于企业知识库、产品手册等场景。

核心代码：

import os
from typing import List
from langchain_community.document_loaders import (
    PyPDFLoader,  # PDF文档加载器
    Docx2txtLoader,  # Word文档加载器
    UnstructuredMarkdownLoader,  # Markdown文档加载器
    TextLoader  # 纯文本文件加载器
)
from langchain_community.vectorstores import Chroma  # Chroma向量数据库
from langchain_community.embeddings import DashScopeEmbeddings  # 阿里云Embedding模型
from langchain_openai import ChatOpenAI  # OpenAI格式的大模型接口
from langchain_text_splitters import RecursiveCharacterTextSplitter  # 文本分割器
from langchain_classic.memory import ConversationBufferMemory  # 对话记忆管理
from langchain_classic.chains import ConversationalRetrievalChain  # 对话式检索链


class DocumentQA:
    """
    智能文档问答系统
    支持PDF、Word、Markdown、TXT等格式文档的加载、向量化和智能问答
    """

    def __init__(self, persist_directory: str = "./chroma_db"):
        """
        初始化文档问答系统

        Args:
            persist_directory: 向量数据库持久化存储路径
        """
        self.persist_directory = persist_directory

        # ==================== 1. 配置 Embedding 模型 ====================
        # 用于将文本转换为向量（数字表示），便于语义检索
        # 使用阿里云 DashScope 的 text-embedding-v3 模型
        self.embeddings = DashScopeEmbeddings(
            model="text-embedding-v3",  # 阿里云Embedding模型名称
            dashscope_api_key="xxxxxx"  # API密钥
        )

        # ==================== 2. 配置大语言模型 ====================
        # 用于生成问答的回答
        self.llm = ChatOpenAI(
            model="gpt-4o-mini",  # 使用的模型名称（测试服务只支持这个）
            temperature=0,  # 温度参数，0表示输出更确定性，越高越随机
            api_key="demo",  # API密钥（测试服务使用demo即可）
            base_url="http://langchain4j.dev/demo/openai/v1"  # API服务地址
        )

        # ==================== 3. 初始化向量存储 ====================
        # 如果已存在向量数据库，则加载；否则为None，需要后续创建
        if os.path.exists(persist_directory):
            # 从持久化目录加载已存在的向量数据库
            self.vectorstore = Chroma(
                persist_directory=persist_directory,
                embedding_function=self.embeddings
            )
        else:
            self.vectorstore = None  # 尚未创建向量库

        # 初始化问答链（后续在process_documents中创建）
        self.qa_chain = None

    def load_documents(self, file_paths: List[str]) -> List:
        """
        加载多种格式的文档

        Args:
            file_paths: 文档文件路径列表

        Returns:
            加载的文档对象列表
        """
        documents = []  # 存储所有加载的文档

        # 遍历每个文件路径
        for file_path in file_paths:
            # 检查文件是否存在
            if not os.path.exists(file_path):
                print(f"文件不存在: {file_path}")
                continue

            # 获取文件扩展名（小写）
            ext = os.path.splitext(file_path)[1].lower()

            try:
                # 根据文件扩展名选择对应的加载器
                if ext == '.pdf':
                    # PDF文件加载器
                    loader = PyPDFLoader(file_path)
                elif ext in ['.doc', '.docx']:
                    # Word文件加载器
                    loader = Docx2txtLoader(file_path)
                elif ext == '.md':
                    # Markdown文件加载器
                    loader = UnstructuredMarkdownLoader(file_path)
                else:
                    # 其他文本文件，指定UTF-8编码避免中文乱码
                    loader = TextLoader(file_path, encoding='utf-8')

                # 执行文档加载
                docs = loader.load()
                documents.extend(docs)  # 添加到总文档列表
                print(f"成功加载: {file_path} ({len(docs)}个文档)")

            except Exception as e:
                print(f"加载文件失败 {file_path}: {str(e)}")

        return documents

    def process_documents(
            self,
            documents: List,
            chunk_size: int = 1000,
            chunk_overlap: int = 200
    ):
        """
        处理文档：分割和向量化，并创建问答链

        Args:
            documents: 要处理的文档列表
            chunk_size: 每个文本块的大小（字符数）
            chunk_overlap: 文本块之间的重叠字符数

        Returns:
            分割后的文本块数量
        """
        # ==================== 1. 文档分割 ====================
        # 将长文档切分成较小的文本块，便于检索和放入LLM上下文
        text_splitter = RecursiveCharacterTextSplitter(
            chunk_size=chunk_size,  # 每块最大字符数
            chunk_overlap=chunk_overlap,  # 块间重叠，保持上下文连贯
            length_function=len,  # 计算文本长度的函数
            separators=["\n\n", "\n", "。", "，", " ", ""]  # 优先在句子边界分割
        )

        # 执行分割
        splits = text_splitter.split_documents(documents)
        print(f"文档分割完成：共{len(splits)}个片段")

        # ==================== 2. 创建向量存储 ====================
        # 将文本块转换为向量并存储到Chroma数据库
        self.vectorstore = Chroma.from_documents(
            documents=splits,  # 分割后的文本块
            embedding=self.embeddings,  # Embedding模型
            persist_directory=self.persist_directory  # 持久化目录
        )
        print(f"✅ 向量库创建完成")

        # ==================== 3. 创建对话记忆 ====================
        # 用于存储多轮对话的历史，实现上下文理解
        memory = ConversationBufferMemory(
            memory_key="chat_history",  # 记忆存储的键名
            return_messages=True,  # 返回消息格式
            output_key="answer"  # 输出结果的键名
        )

        # ==================== 4. 创建问答链 ====================
        # 组合检索器和LLM，实现RAG（检索增强生成）
        self.qa_chain = ConversationalRetrievalChain.from_llm(
            llm=self.llm,  # 大语言模型
            retriever=self.vectorstore.as_retriever(
                search_type="mmr",  # MMR检索，平衡相关性和多样性
                search_kwargs={"k": 5, "fetch_k": 10}  # 返回5个，候选10个
            ),
            memory=memory,  # 对话记忆
            return_source_documents=True,  # 返回来源文档，便于溯源
            verbose=False  # 是否输出详细日志
        )
        print(f"✅ 问答链创建完成")

        return len(splits)

    def ask(self, question: str) -> dict:
        """
        向系统提问

        Args:
            question: 用户问题

        Returns:
            包含回答和来源的字典
        """
        # 检查问答链是否已初始化
        if not self.qa_chain:
            return {"error": "请先加载文档"}

        # 调用问答链，获取回答
        result = self.qa_chain.invoke({"question": question})

        # ==================== 格式化返回结果 ====================
        response = {
            "answer": result["answer"],  # 回答内容
            "sources": []  # 来源文档列表
        }

        # 提取来源文档信息（用于答案溯源）
        for doc in result.get("source_documents", []):
            source_info = {
                "content": doc.page_content[:200] + "...",  # 来源内容预览（前200字）
                "metadata": doc.metadata  # 来源元数据（如文件名、页码等）
            }
            response["sources"].append(source_info)

        return response

    def clear_memory(self):
        """清空对话记忆（开始新的对话会话）"""
        if self.qa_chain:
            self.qa_chain.memory.clear()


# ==================== 使用示例 ====================
def main():
    """
    主函数：演示如何使用DocumentQA类进行文档问答
    """
    # 1. 初始化问答系统（指定向量库存储路径）
    qa_system = DocumentQA(persist_directory="./doc_qa_db")

    # 2. 加载文档（替换为你的实际文档路径）
    documents = qa_system.load_documents([
        r"C:\Users\fei\Desktop\运维\资源变更\20260319中审漏洞修复\中审漏洞修复.pdf"
    ])

    # 3. 如果成功加载了文档，则处理并开始问答
    if documents:
        # 处理文档：分割、向量化、创建问答链
        qa_system.process_documents(documents)

        # 4. 定义要提问的问题列表
        questions = [
            "文档的主要内容是什么？",
            "有哪些关键技术要点？",
            "请总结一下最佳实践"
        ]

        # 5. 逐个提问并打印结果
        for question in questions:
            print(f"\n{'=' * 60}")
            print(f"问题: {question}")
            print('=' * 60)

            # 获取回答
            result = qa_system.ask(question)
            print(f"回答: {result['answer']}")

            # 如果有关联的来源文档，打印来源信息
            if result['sources']:
                print("\n📚 参考来源:")
                for i, source in enumerate(result['sources'], 1):
                    print(f"  {i}. {source['metadata'].get('source', '未知')}")
    else:
        print("未加载到任何文档，请检查文件路径！")


# 程序入口点
if __name__ == "__main__":
    main()

五、部署与生产化

5.1 FastAPI 服务搭建

基于 FastAPI 构建生产级 LangChain API 服务，支持单请求/批量请求、参数动态配置、异常处理。

# api_server.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List, Optional
import uvicorn
import time

from langchain_openai import ChatOpenAI
from langchain.chains import LLMChain
from langchain.prompts import PromptTemplate

app = FastAPI(title="LangChain API服务")

# 初始化模型与对话链
llm = ChatOpenAI(model="gpt-3.5-turbo")
prompt = PromptTemplate(
    input_variables=["question"],
    template="回答以下问题：{question}"
)
chain = LLMChain(llm=llm, prompt=prompt)

# 请求/响应数据模型（自动校验参数）
class ChatRequest(BaseModel):
    question: str
    temperature: Optional[float] = 0.7
    max_tokens: Optional[int] = 1000

class ChatResponse(BaseModel):
    answer: str
    tokens_used: int
    processing_time: float

# 健康检查（用于服务监控）
@app.get("/health")
async def health_check():
    return {"status": "healthy"}

# 核心聊天接口
@app.post("/chat", response_model=ChatResponse)
async def chat_endpoint(request: ChatRequest):
    try:
        start_time = time.time()
        
        # 动态覆盖模型参数
        llm.temperature = request.temperature
        llm.max_tokens = request.max_tokens
        
        # 执行 LangChain 链
        result = chain.invoke({"question": request.question})
        processing_time = time.time() - start_time
        
        return ChatResponse(
            answer=result["text"],
            tokens_used=len(result["text"]),  # 简化Token统计
            processing_time=round(processing_time, 3)
        )
    
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

# 批量处理接口（高并发场景优化）
@app.post("/batch-chat")
async def batch_chat_endpoint(requests: List[ChatRequest]):
    results = []
    for req in requests:
        try:
            result = chain.invoke({"question": req.question})
            results.append({
                "question": req.question,
                "answer": result["text"],
                "success": True
            })
        except Exception as e:
            results.append({
                "question": req.question,
                "error": str(e),
                "success": False
            })
    return {"results": results}

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

5.2 Docker 容器化

标准化打包服务，实现跨环境一键部署，符合生产安全规范。

# Dockerfile
FROM python:3.11-slim

WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    gcc \
    g++ \
    && rm -rf /var/lib/apt/lists/*

# 安装Python依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制项目代码
COPY . .

# 安全配置：使用非root用户运行
RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app
USER appuser

# 暴露服务端口
EXPOSE 8000

# 启动命令
CMD ["python", "api_server.py"]

5.3 生产级配置管理

统一管理环境变量、模型参数、缓存、数据库，支持 .env 本地配置。

# config.py
import os
from typing import Optional
from pydantic_settings import BaseSettings, Field
import langchain
from langchain.cache import SQLiteCache
from langchain_openai import ChatOpenAI

class Settings(BaseSettings):
    # API 密钥
    openai_api_key: str = Field(..., env="OPENAI_API_KEY")
    anthropic_api_key: Optional[str] = Field(None, env="ANTHROPIC_API_KEY")
    
    # 模型默认参数
    default_model: str = "gpt-3.5-turbo"
    default_temperature: float = 0.7
    default_max_tokens: int = 1000
    
    # 数据库与缓存
    database_url: str = Field("sqlite:///./app.db", env="DATABASE_URL")
    redis_url: Optional[str] = Field(None, env="REDIS_URL")
    cache_type: str = "memory"
    cache_ttl: int = 3600
    
    # 向量数据库
    vector_store_type: str = "chroma"
    chroma_persist_directory: str = "./chroma_db"
    
    # 性能与监控
    max_concurrent_requests: int = 10
    request_timeout: int = 30
    enable_langsmith: bool = False
    langsmith_api_key: Optional[str] = Field(None, env="LANGSMITH_API_KEY")
    
    class Config:
        env_file = ".env"
        env_file_encoding = "utf-8"

# 全局配置实例
settings = Settings()

# 一键初始化所有生产组件
def initialize_components():
    # 配置缓存（减少重复请求）
    if settings.cache_type == "sqlite":
        langchain.llm_cache = SQLiteCache(database_path=".langchain.db")
    
    # 初始化大模型
    llm = ChatOpenAI(
        api_key=settings.openai_api_key,
        model=settings.default_model,
        temperature=settings.default_temperature,
        max_tokens=settings.default_max_tokens
    )
    return llm

---

六、常见问题与解决方案

6.1 内存管理（生产环境必用）

解决大模型、大数据集导致的内存溢出问题。

# 内存清理工具
import gc

def cleanup_memory():
    """主动释放内存，适配CPU/GPU环境"""
    gc.collect()
    # 清理CUDA显存
    try:
        import torch
        if torch.cuda.is_available():
            torch.cuda.empty_cache()
    except ImportError:
        pass

# 分块处理大数据（避免一次性加载全部数据）
def process_large_dataset(data, chunk_size=100):
    results = []
    for i in range(0, len(data), chunk_size):
        chunk = data[i:i + chunk_size]
        # 自定义分块处理逻辑
        result = process_chunk(chunk)
        results.extend(result)
        # 定期释放内存
        if i % (chunk_size * 10) == 0:
            cleanup_memory()
    return results

# 流式读取文档（低内存占用）
def stream_documents(file_path):
    with open(file_path, 'r', encoding='utf-8') as f:
        chunk = ""
        for line in f:
            chunk += line
            if len(chunk) > 1000:
                yield chunk
                chunk = ""
        if chunk:
            yield chunk

6.2 调试技巧（快速定位问题）

# 1. 启用详细日志
import langchain
langchain.verbose = True

# 2. 实时打印中间结果
from langchain.callbacks import StdOutCallbackHandler
chain = LLMChain(llm=llm, prompt=prompt, callbacks=[StdOutCallbackHandler()])

# 3. 控制台全链路调试
def debug_chain(chain, inputs):
    from langchain.callbacks.tracers import ConsoleCallbackHandler
    print(f"输入参数: {inputs}")
    with ConsoleCallbackHandler() as callback:
        result = chain.invoke(inputs, callbacks=[callback])
    print(f"最终输出: {result}")
    return result

---

6.3 系统化学习路径

learning_path = [
    "1. 基础组件（Models, Prompts, Chains）",
    "2. 记忆与状态管理（Memory）",
    "3. 文档处理与检索（Indexes, Retrievers）",
    "4. 智能体与工具（Agents, Tools）",
    "5. 高级特性（Runnable，LangSmith，LCEL）",
    "6. 生产部署（FastAPI，Docker，监控）"
]