🏗️ LangChain 1.0 核心架构

📚 为什么需要了解架构？

LangChain 1.0 是一个重大版本更新， 相比 0.x 版本在架构和 API 设计上有本质变化。 理解核心架构可以帮助你：

🏛️ LangChain 1.0 整体架构

LangChain 1.0 采用分层架构， 从底层的 LangGraph 到高层的 Agent，每一层都有明确的职责：

架构分层说明

📦 langchain vs langchain-classic

LangChain 1.0 引入了两个包来区分新旧 API：

"""
langchain vs langchain-classic 对比示例
"""

# ❌ langchain-classic（0.x 版本，不推荐）
from langchain_classic import LLMChain
from langchain_classic.agents import initialize_agent, AgentType

llm = ChatOpenAI(model_name="gpt-4")
chain = LLMChain(llm=llm, prompt=prompt)
agent = initialize_agent(
    tools=tools,
    llm=llm,
    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION
)

# ✅ langchain（1.0 版本，推荐）
from langchain import init_chat_model
from langchain.agents import create_agent

model = init_chat_model("gpt-4o", model_provider="openai")
agent = create_agent(
    model="gpt-4o",
    tools=tools,
    system_prompt="你是专业的 AI 助手"
)

🧩 核心模块介绍

LangChain 1.0 围绕几个核心模块构建，每个模块都有清晰的职责和 API：

1. Models（模型接口）

提供统一的模型初始化和调用接口，支持 OpenAI、Anthropic、Google 等多个提供商。

"""
Models 模块 - 统一的模型接口
"""
from langchain import init_chat_model

# 自动推断提供商
model = init_chat_model("gpt-4o")

# 显式指定提供商
model = init_chat_model(
    "claude-3-5-sonnet-20241022",
    model_provider="anthropic",
    temperature=0.7
)

# 支持所有主流提供商
gemini = init_chat_model("gemini-2.0-flash-exp", model_provider="google")
ollama = init_chat_model("llama3.2", model_provider="ollama")

2. Messages（消息系统）

标准化的消息格式，引入 content_blocks 统一跨提供商的内容访问。

"""
Messages 模块 - 统一的消息格式
"""
from langchain_core.messages import HumanMessage, AIMessage

# 发送消息
response = model.invoke([
    HumanMessage(content="解释量子计算")
])

# 使用 content_blocks 访问内容（跨提供商标准化）
for block in response.content_blocks:
    if block["type"] == "text":
        print(f"文本: {block['text']}")
    elif block["type"] == "reasoning":
        print(f"推理过程: {block['reasoning']}")
    elif block["type"] == "tool_use":
        print(f"工具调用: {block['name']}")

3. Tools（工具系统）

使用 @tool 装饰器快速定义工具，支持参数验证和运行时上下文。

"""
Tools 模块 - 工具定义和调用
"""
from langchain.tools import tool, ToolRuntime
from typing_extensions import TypedDict

# 简单工具
@tool
def search_web(query: str) -> str:
    """搜索网络信息"""
    return f"搜索结果：{query}"

# 带运行时上下文的工具
class UserContext(TypedDict):
    user_id: str

@tool
def get_user_data(runtime: ToolRuntime[UserContext]) -> str:
    """获取用户数据"""
    user_id = runtime.context["user_id"]
    return f"用户 {user_id} 的数据"

# 在 Agent 中使用
agent = create_agent(
    model="gpt-4o",
    tools=[search_web, get_user_data],
    context_schema=UserContext
)

4. Agents（Agent 系统）

create_agent() 是 1.0 的核心 API， 替代了 0.x 版本的 initialize_agent()。

"""
Agents 模块 - 完整的 Agent 配置
"""
from langchain.agents import create_agent
from langchain.agents.middleware import PIIMiddleware
from langgraph.checkpoint.memory import InMemorySaver

# 创建完整的 Agent
checkpointer = InMemorySaver()
pii_middleware = PIIMiddleware(
    pii_types=["email", "phone_number"],
    strategy="redact"
)

agent = create_agent(
    # 模型配置
    model="gpt-4o",

    # 工具列表
    tools=[search_web, get_user_data],

    # 系统提示词
    system_prompt="你是专业的 AI 助手。请保护用户隐私。",

    # 中间件
    middleware=[pii_middleware],

    # 持久化
    checkpointer=checkpointer,

    # 运行时上下文
    context_schema=UserContext
)

# 调用 Agent
config = {
    "configurable": {"thread_id": "user_001"},
    "context": {"user_id": "user_123"}
}

result = agent.invoke(
    {"messages": [{"role": "user", "content": "你好"}]},
    config=config
)

5. Middleware（中间件系统）

中间件提供钩子机制，用于动态上下文工程、安全防护和可观测性。

💡 设计哲学和原则

LangChain 1.0 的架构设计遵循以下核心原则：

1. 可组合性（Composability）

通过管道操作符 | 和模块化设计，实现灵活的组合：

# LCEL 管道组合
from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_template("翻译: {text}")
chain = prompt | model

# 中间件组合
agent = create_agent(
    model="gpt-4o",
    tools=tools,
    middleware=[
        LoggingMiddleware(),
        PIIMiddleware(),
        ContentSafetyMiddleware()
    ]
)

2. 可观测性（Observability）

内置对 LangSmith 的支持，自动追踪执行轨迹：

import os

# 启用追踪（一行配置）
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = "your-api-key"

# 所有 Agent 调用自动追踪
result = agent.invoke({...})

3. 可扩展性（Extensibility）

通过中间件、自定义工具、子图等机制实现扩展：

• 自定义中间件：实现 CustomMiddleware 钩子
• 自定义工具：使用 @tool 装饰器
• 自定义图：使用 LangGraph 构建复杂工作流

4. 生产就绪（Production-Ready）

1.0 版本专注于生产环境需求：

❓ 常见问题

Q1: 为什么 1.0 基于 LangGraph？

LangGraph 提供了强大的图执行引擎，支持：

• 状态管理和持久化
• 复杂的控制流（条件分支、循环）
• 人工介入（Human-in-the-Loop）
• 时间旅行（Time Travel）调试

通过将 Agent 构建在 LangGraph 之上，LangChain 获得了这些能力， 同时保持了简单的高级 API。

Q2: langchain-classic 会一直维护吗？

不会。langchain-classic 仅用于过渡期， 不会获得新功能更新和长期维护。建议尽快迁移到 1.0 API。

Q3: 如何选择 Agent vs LCEL vs LangGraph？

Q4: content_blocks 和 content 有什么区别？

content：字符串形式的简单文本
content_blocks：结构化的内容块列表，支持：

• 多模态内容（文本、图像、工具调用）
• 跨提供商标准化（OpenAI、Anthropic、Google 等）
• 推理过程、思考链（Chain of Thought）

Q5: 如何理解"Context Engineering"？

Context Engineering（上下文工程）是 LangChain 1.0 的核心理念：

"以正确的格式提供正确的信息和工具，使 LLM 能够完成任务"

通过中间件和钩子，可以动态调整：

• 系统提示词（基于用户状态）
• 可用工具（基于权限）
• 对话历史（摘要或过滤）
• 模型选择（基于任务复杂度）

📖 参考资源

• LangChain 官方架构概述
• LangChain 1.0 发布说明
• Agent 架构文档
• LangGraph 官方文档
• 迁移指南 - 从 0.x 升级到 1.0