LangGraph 基础入门
网站使用说明
概述
本文档参考 LangChain Academy 的基础入门模块,进行大幅补充和拓展。这是学习 LangGraph 的第一步,帮助你理解 LangChain 生态系统的核心组件、Chat Models(聊天模型)的使用,以及基础工具集成。通过本教程,你将掌握构建 Agentic AI 应用的基础知识。
📚 术语表
| 术语名称 | LangGraph 定义和解读 | Python 定义和说明 | 重要程度 |
|---|---|---|---|
| LangChain | 构建 LLM 应用的开发框架,提供模块化组件和标准化接口 | Python 包,包含 Chat Models、Prompts、Tools、Memory 等模块 | ⭐⭐⭐⭐⭐ |
| LangGraph | LangChain 生态的图编排框架,用于构建有状态的 Agent 系统 | Python 库,通过图结构(StateGraph)编排复杂工作流 | ⭐⭐⭐⭐⭐ |
| Chat Model | 聊天模型,接受消息列表输入并返回 AI 消息的 LLM 接口 | ChatOpenAI 等类,实现 Runnable 接口的统一调用方法 | ⭐⭐⭐⭐⭐ |
| Temperature | 温度参数,控制 LLM 输出的随机性和创造性 | 浮点数参数(0-2),0 为确定性输出,1 为最大创造性 | ⭐⭐⭐⭐ |
| Message Types | 消息类型,区分对话中的不同角色和用途 | HumanMessage、AIMessage、SystemMessage、FunctionMessage 类 | ⭐⭐⭐⭐⭐ |
| Runnable Interface | 可运行接口,LangChain 所有组件的统一调用标准 | 定义 invoke、stream、batch、ainvoke 等方法的接口 | ⭐⭐⭐⭐⭐ |
| Tavily Search | 为 LLM 优化的搜索引擎,提供结构化搜索结果 | TavilySearchResults 类,返回包含 url 和 content 的字典列表 | ⭐⭐⭐⭐ |
| Environment Variable | 环境变量,用于安全存储 API 密钥等敏感信息 | os.environ 字典,通过 get/set 方法访问系统环境变量 | ⭐⭐⭐⭐⭐ |
| getpass | 安全输入模块,隐藏用户输入内容(如密码) | Python 标准库模块,getpass.getpass() 方法实现隐藏输入 | ⭐⭐⭐⭐ |
| Streaming | 流式输出,逐 token 返回 LLM 生成结果而非一次性返回 | stream() 方法返回生成器,通过 for 循环逐个获取输出 | ⭐⭐⭐⭐ |
| Model Selection | 模型选择,根据任务需求选择合适的 LLM 模型 | 通过 model 参数指定,如 "gpt-4"、"gpt-3.5-turbo" 等 | ⭐⭐⭐⭐ |
| Token Usage | Token 使用量,记录 LLM 输入输出消耗的 token 数量 | response_metadata 中的 token_usage 字段,包含计费信息 | ⭐⭐⭐⭐ |
核心概念
什么是 LangChain?
LangChain 是一个用于构建 LLM(大语言模型)应用 的开发框架。它提供了:
- 模块化组件:Chat Models、Prompts、Tools、Memory 等
- 标准化接口:统一的 API,支持多种 LLM 提供商
- 链式组合:将多个组件组合成复杂的工作流
什么是 LangGraph?
LangGraph 是 LangChain 生态系统中的图编排框架,专门用于构建 Agent 和多 Agent 应用。它的核心优势:
- 循环支持(Cycles):支持带循环的工作流,而不仅仅是 DAG(有向无环图)
- 精确控制(Controllability):相对于拖拽式的 SDK,LangGraph 可以编程精确控制 Agent 的执行流程
- 状态持久化(Persistence):支持状态的保存和恢复
为什么需要 LangGraph?
传统的 Agent 框架存在问题:
- 缺乏对执行流程的控制
- 难以处理复杂的决策逻辑
- 无法可靠地投入生产环境
LangGraph 的解决方案:
- 将 Agent 工作流建模为状态图
- 通过节点和边精确控制执行路径
- 支持人工介入、错误恢复等生产级特性
LangGraph 的核心逻辑(重要!)
LangGraph 的核心目的,是让开发者能够:
- 定义复杂多智能体(multi-agent)工作流
- 让这些智能体可视化、可控、可回溯
- 支持有状态(stateful)对话与执行,而不仅是一次性调用
课程结构
本课程包含多个模块,每个模块聚焦特定主题:
《AgenticAI 与 LangGraph 飞速上手》/
├── 第 0 章/ # 基础入门(本教程)
├── 第 1 章/ # LangGraph 核心概念
├── 第 2 章/ # Agent 架构
├── 第 3 章/ # Multi-Agent 系统
├── 第 4 章/ # 高级模式(Map-Reduce、Sub-graphs 等)
└── ...每个模块包含:
- 可执行的:交互式网页,可在本书页面直接执行 Python 代码
- 视频教程:配套讲解视频
环境配置详解
1. 安装依赖(不同的操作系统、不同的 Python 环境配置可能会出现各种问题,需要一定的耐心处理)
pip install --quiet -U langchain_openai langchain_core langchain_community tavily-python依赖说明:
| 包名 | 用途 |
|---|---|
langchain_openai | OpenAI 模型集成(ChatGPT、GPT-4 等) |
langchain_core | LangChain 核心组件(Messages、Runnables 等) |
langchain_community | 社区工具(Tavily 搜索等) |
tavily-python | Tavily 搜索引擎 SDK |
2. 配置 API 密钥
import os, getpass
def _set_env(var: str):
if not os.environ.get(var):
os.environ[var] = getpass.getpass(f"{var}: ")
_set_env("OPENAI_API_KEY")Python 知识点:环境变量与安全性
# 检查环境变量是否存在
os.environ.get(var) # 返回值或 None
# 安全地获取密钥(输入时不显示)
getpass.getpass(f"{var}: ") # 类似密码输入
# 设置环境变量
os.environ[var] = "your-api-key"为什么使用环境变量?
- 🔒 安全性:避免将密钥硬编码在代码中
- 🔄 灵活性:可以在不同环境使用不同密钥
- ✅ 最佳实践:遵循 12-Factor App 原则
🤖 Chat Models 详解
什么是 Chat Model?
Chat Model 是一种接受消息列表作为输入,返回聊天消息作为输出的模型。与传统的文本生成模型不同,Chat Model 理解对话的上下文和角色。
核心特性
输入:[HumanMessage, AIMessage, SystemMessage, ...]
↓
Chat Model (如 GPT-4)
↓
输出:AIMessageLangChain 的 Chat Model 集成
LangChain 不托管模型,而是提供统一接口,支持多个提供商:
| 提供商 | 模型示例 | 集成包 |
|---|---|---|
| OpenAI | GPT-4, GPT-3.5 | langchain_openai |
| Anthropic | Claude | langchain_anthropic |
| Gemini | langchain_google_genai | |
| Azure | Azure OpenAI | langchain_openai |
好处:
- 统一 API,轻松切换模型
- 模型无关的应用设计
- 支持 70+ 模型提供商
💻 Chat Model 实战
1. 初始化 Chat Model
from langchain_openai import ChatOpenAI
# 初始化 GPT-4o
gpt4o_chat = ChatOpenAI(model="gpt-5-nano", temperature=0)
# 初始化 GPT-3.5(更便宜)
gpt35_chat = ChatOpenAI(model="gpt-3.5-turbo-0125", temperature=0)关键参数详解:
model(模型名称)
# GPT-4/5 系列 - 高质量、较贵
"gpt-5-nano" # 最新优化版本
"gpt-4-turbo" # GPT-4 Turbo
# GPT-3.5 系列 - 便宜、快速
"gpt-3.5-turbo-0125" # GPT-3.5 最新版本如何选择?
- 需要高质量输出 → GPT-5
- 需要降低成本 → GPT-5-nano
- 兼容性更好 → GPT-4o-mini(本课程默认)
temperature(温度参数)
控制输出的随机性和创造性:
temperature = 0 # 确定性输出(适合事实查询、代码生成)
temperature = 0.7 # 平衡(适合对话)
temperature = 1.0 # 最大创造性(适合创意写作)示例对比:
# Temperature = 0 (每次输出几乎相同)
"巴黎是法国的首都。"
"巴黎是法国的首都。"
# Temperature = 1.0 (每次输出不同)
"巴黎,这座浪漫之都,是法国的首都。"
"法国的首都是美丽的巴黎。"2. 调用 Chat Model
方法 1:使用消息对象
from langchain_core.messages import HumanMessage
# 创建消息
msg = HumanMessage(content="Hello world", name="Lance")
# 调用模型
response = gpt4o_chat.invoke([msg])输出:
AIMessage(
content='Hello! How can I assist you today?',
response_metadata={
'token_usage': {'completion_tokens': 9, 'prompt_tokens': 11, 'total_tokens': 20},
'model_name': 'gpt-5-nano-2024-05-13',
'finish_reason': 'stop'
},
id='run-d3c4bc85-ef14-49f6-ba7e-91bf455cffee-0'
)LangChain 知识点:消息类型
| 消息类型 | 作用 | 示例 |
|---|---|---|
HumanMessage | 用户输入 | 用户的问题、指令 |
AIMessage | AI 回复 | 模型的回答 |
SystemMessage | 系统指令 | 设定 AI 的角色、行为 |
FunctionMessage | 函数调用结果 | Tool 执行的返回值 |
消息对象结构:
HumanMessage(
content="Hello world", # 消息内容
name="Lance" # 可选:发送者名称
)方法 2:使用字符串(简化写法)
response = gpt4o_chat.invoke("hello world")内部转换:
"hello world" → HumanMessage(content="hello world")何时使用?
- ✅ 简单单轮对话
- ❌ 多轮对话(需要保留历史)
3. 切换模型
# GPT-4o 回复
gpt4o_chat.invoke("hello world")
# → AIMessage(content='Hello! How can I assist you today?', ...)
# GPT-3.5 回复(使用相同接口!)
gpt35_chat.invoke("hello world")
# → AIMessage(content='Hello! How can I assist you today?', ...)优势:
- 🔄 统一接口,无需修改代码
- 💰 灵活切换,优化成本
- 🧪 A/B 测试不同模型
🔍 搜索工具集成:Tavily
什么是 Tavily?
Tavily 是一个为 LLM 优化的搜索引擎,提供:
- 📊 结构化搜索结果
- ⚡ 快速响应(针对 RAG 优化)
- 💎 高质量内容(过滤低质量网页)
配置 Tavily API
_set_env("TAVILY_API_KEY")免费额度:
- 新用户赠送免费 credits
- 足够完成本课程的学习
使用 Tavily 搜索
from langchain_community.tools.tavily_search import TavilySearchResults
# 初始化搜索工具
tavily_search = TavilySearchResults(max_results=3)
# 执行搜索
search_docs = tavily_search.invoke("What is LangGraph?")输出示例:
[
{
'url': 'https://www.datacamp.com/tutorial/langgraph-tutorial',
'content': 'LangGraph is a library within the LangChain ecosystem designed to tackle these challenges head-on. LangGraph provides a framework for defining, coordinating, and executing multiple LLM agents (or chains) in a structured manner.'
},
{
'url': 'https://langchain-ai.github.io/langgraph/',
'content': 'Overview LangGraph is a library for building stateful, multi-actor applications with LLMs, used to create agent and multi-agent workflows. Compared to other LLM frameworks, it offers these core benefits: cycles, controllability, and persistence.'
},
{
'url': 'https://www.youtube.com/watch?v=nmDFSVRnr4Q',
'content': 'LangGraph is an extension of LangChain enabling Multi-Agent conversation and cyclic chains.'
}
]返回结构:
{
'url': str, # 来源 URL
'content': str # 提取的文本内容
}🎓 核心知识点总结
LangChain 核心概念
1. Runnable 接口
所有 LangChain 组件(Chat Models、Tools、Chains)都实现 Runnable 接口:
| 方法 | 作用 | 使用场景 |
|---|---|---|
invoke(input) | 同步调用 | 单次请求 |
stream(input) | 流式输出 | 长文本生成 |
batch(inputs) | 批量调用 | 并行处理多个输入 |
ainvoke(input) | 异步调用 | 高并发场景 |
示例:
# invoke - 等待完整响应
response = chat.invoke("Tell me a joke")
# stream - 逐 token 返回
for chunk in chat.stream("Tell me a joke"):
print(chunk.content, end="")2. Messages(消息系统)
LangChain 使用消息对象而非纯文本:
# ❌ 不推荐:纯文本
"What is the capital of France?"
# ✅ 推荐:消息对象
HumanMessage(content="What is the capital of France?")优势:
- 📋 保留对话历史
- 🎭 区分不同角色
- 🔧 支持多模态(文本、图片、音频)
3. 模型初始化最佳实践
# ✅ 在应用启动时初始化一次
chat = ChatOpenAI(model="gpt-5-nano", temperature=0)
# ❌ 不要在循环中重复初始化
for _ in range(10):
chat = ChatOpenAI(...) # 性能浪费Python 核心知识点
1. 环境变量管理
import os
# 读取环境变量
api_key = os.environ.get("OPENAI_API_KEY")
# 设置环境变量
os.environ["OPENAI_API_KEY"] = "sk-..."
# 检查是否存在
if "OPENAI_API_KEY" in os.environ:
print("API key is set")生产环境最佳实践:
# 使用 .env 文件(需要 python-dotenv)
# .env
OPENAI_API_KEY=sk-xxx
TAVILY_API_KEY=tvly-xxx
# Python 代码
from dotenv import load_dotenv
load_dotenv() # 自动加载 .env 文件2. getpass 模块(安全输入)
import getpass
# 不显示输入内容(类似密码输入)
password = getpass.getpass("Enter password: ")
# 用户输入时屏幕不显示
# 对比普通 input()
username = input("Enter username: ") # 输入内容可见3. 列表推导式
# 搜索结果处理示例
urls = [doc['url'] for doc in search_docs]
# → ['https://...', 'https://...', ...]
# 等价于:
urls = []
for doc in search_docs:
urls.append(doc['url'])💡 最佳实践
1. API 密钥安全
✅ 正确做法
# 1. 使用环境变量
os.environ["OPENAI_API_KEY"] = "sk-..."
# 2. 使用 .env 文件
# .env
OPENAI_API_KEY=sk-xxx
# 3. 使用密钥管理服务(生产环境)
# - AWS Secrets Manager
# - HashiCorp Vault
# - Azure Key Vault❌ 错误做法
# 不要硬编码在代码中
chat = ChatOpenAI(api_key="sk-xxxxxxxxxxxxxxxx") # ❌
# 不要提交到 Git
# config.py
API_KEY = "sk-xxxxxxxxxxxxxxxx" # ❌2. 模型选择策略
| 任务类型 | 推荐模型 | 原因 |
|---|---|---|
| 事实查询 | GPT-4o | 准确性高 |
| 创意写作 | GPT-4 | 质量好 |
| 简单分类 | GPT-3.5 | 成本低 |
| 代码生成 | GPT-4o | 代码质量高 |
| 批量处理 | GPT-3.5 | 成本优化 |
3. Temperature 设置指南
# 事实性任务 - 低 temperature
chat = ChatOpenAI(model="gpt-5-nano", temperature=0)
# 适合:数学、翻译、数据提取
# 创意任务 - 高 temperature
chat = ChatOpenAI(model="gpt-5-nano", temperature=0.8)
# 适合:故事创作、营销文案、头脑风暴
# 平衡任务 - 中等 temperature
chat = ChatOpenAI(model="gpt-5-nano", temperature=0.5)
# 适合:对话、摘要、问答4. 错误处理
from langchain_openai import ChatOpenAI
try:
chat = ChatOpenAI(model="gpt-5-nano", temperature=0)
response = chat.invoke("Hello")
except Exception as e:
print(f"错误:{e}")
# 处理错误:重试、降级到其他模型等常见错误:
AuthenticationError:API 密钥错误RateLimitError:超过速率限制APIError:OpenAI 服务错误
🚀 进阶技巧
1. 使用 SystemMessage 设定角色
from langchain_core.messages import SystemMessage, HumanMessage
messages = [
SystemMessage(content="你是一位专业的 Python 教师,善于用简单的例子解释复杂概念。"),
HumanMessage(content="什么是装饰器?")
]
response = chat.invoke(messages)
print(response.content)效果:
- AI 会以教师的角色回答
- 使用教学性的语言和示例
2. 流式输出优化用户体验
# 完整输出(用户等待较久)
response = chat.invoke("写一篇关于 AI 的文章")
print(response.content) # 等待 10 秒后一次性显示
# 流式输出(实时反馈)
for chunk in chat.stream("写一篇关于 AI 的文章"):
print(chunk.content, end="", flush=True) # 逐 token 显示3. 搜索结果后处理
# 提取所有 URL
urls = [doc['url'] for doc in search_docs]
# 合并所有内容
combined_content = "\n\n".join([doc['content'] for doc in search_docs])
# 结合搜索结果生成回答
messages = [
SystemMessage(content=f"基于以下信息回答问题:\n{combined_content}"),
HumanMessage(content="什么是 LangGraph?")
]
response = chat.invoke(messages)📊 成本优化
Token 使用统计
response = chat.invoke("Hello world")
# 查看 token 使用情况
metadata = response.response_metadata['token_usage']
print(f"输入 tokens: {metadata['prompt_tokens']}")
print(f"输出 tokens: {metadata['completion_tokens']}")
print(f"总计 tokens: {metadata['total_tokens']}")输出示例:
输入 tokens: 9
输出 tokens: 9
总计 tokens: 18成本估算
| 模型 | 输入价格($/1M tokens) | 输出价格($/1M tokens) |
|---|---|---|
| GPT-4o | $5.00 | $15.00 |
| GPT-3.5 | $0.50 | $1.50 |
计算示例:
# GPT-4o 处理 1000 tokens 输入 + 1000 tokens 输出
cost = (1000/1000000 * 5) + (1000/1000000 * 15)
# = $0.005 + $0.015 = $0.02(2 分钱)🎯 实际应用案例
案例 1:简单问答机器人
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, AIMessage
# 初始化模型
chat = ChatOpenAI(model="gpt-5-nano", temperature=0.7)
# 对话历史
history = []
def chat_bot(user_input):
# 添加用户消息
history.append(HumanMessage(content=user_input))
# 调用模型
response = chat.invoke(history)
# 添加 AI 回复到历史
history.append(response)
return response.content
# 使用
print(chat_bot("你好"))
print(chat_bot("我刚才说了什么?")) # 能记住上下文案例 2:搜索增强问答(简单 RAG)
from langchain_community.tools.tavily_search import TavilySearchResults
from langchain_openai import ChatOpenAI
chat = ChatOpenAI(model="gpt-5-nano", temperature=0)
search = TavilySearchResults(max_results=3)
def search_qa(question):
# 1. 搜索相关信息
search_results = search.invoke(question)
context = "\n\n".join([doc['content'] for doc in search_results])
# 2. 结合搜索结果生成答案
prompt = f"""基于以下信息回答问题:
信息:
{context}
问题:{question}
答案:"""
response = chat.invoke(prompt)
return response.content
# 使用
answer = search_qa("LangGraph 的主要优势是什么?")
print(answer)案例 3:多模型对比
models = {
"GPT-4o": ChatOpenAI(model="gpt-5-nano", temperature=0),
"GPT-3.5": ChatOpenAI(model="gpt-3.5-turbo", temperature=0)
}
question = "解释量子计算"
for name, model in models.items():
response = model.invoke(question)
print(f"\n{name} 的回答:")
print(response.content)
print(f"Token 使用:{response.response_metadata['token_usage']}")🔍 常见问题
Q1: 为什么要使用消息对象而不是字符串?
字符串方式:
chat.invoke("Hello") # 简单,但丢失上下文消息对象方式:
messages = [
SystemMessage(content="你是助手"),
HumanMessage(content="Hello")
]
chat.invoke(messages) # 保留角色、历史优势:
- 🔄 支持多轮对话
- 🎭 区分系统/用户/AI 角色
- 📊 更好的调试和日志
Q2: temperature=0 真的完全确定吗?
不完全确定!
chat = ChatOpenAI(temperature=0)
# 相同输入,99% 情况输出相同
response1 = chat.invoke("1+1=?") # → "2"
response2 = chat.invoke("1+1=?") # → "2"
# 但模型更新或其他因素可能导致微小差异何时使用 temperature=0?
- ✅ 需要一致性的任务(测试、评估)
- ✅ 事实性回答
- ❌ 不适合创意任务
Q3: 如何选择 max_results?
# 搜索结果数量权衡
search = TavilySearchResults(max_results=N)| max_results | 优势 | 劣势 |
|---|---|---|
| 1-3 | 快速、聚焦 | 可能遗漏信息 |
| 5-10 | 全面 | 成本高、噪音多 |
| 10+ | 最全面 | 超过 LLM 上下文限制 |
推荐:
- 简单问题:3
- 复杂研究:5-10
- 对比分析:3-5
📖 扩展阅读
🎉 下一步
恭喜你完成了 LangChain Academy 基础模块!你已经掌握了:
✅ LangChain 和 LangGraph 的核心概念 ✅ Chat Models 的初始化和调用 ✅ 消息系统的使用 ✅ 搜索工具的集成 ✅ API 密钥安全管理
接下来学习:
- Module 1:LangGraph 核心概念(State、Graph、Node、Edge)
- Module 2:构建你的第一个 Agent
- Module 4:高级模式(Map-Reduce、Sub-graphs)
实践建议:
- 🔨 动手修改代码,尝试不同参数
- 🧪 测试不同模型的效果
- 📝 记录遇到的问题和解决方法
- 💬 加入社区讨论
总结:本模块是 LangGraph 学习之旅的起点。通过掌握 Chat Models 和工具集成,你已经具备了构建 AI 应用的基础能力。记住:LangChain 提供组件,LangGraph 提供编排,两者结合才能构建强大的 Agent 系统!