01 Python 环境配置与 LangChainLangGraph 依赖安装

Python 环境配置与 LangChain/LangGraph 依赖安装

关联：索引

注：大家已有 Python 基础且熟悉 Conda，本节重点强调本项目特定的版本要求。

1. 项目硬性要求（企业主流标准）

Python 版本：3.10 或 3.11（推荐 3.10.12，稳定且兼容性最好）。
环境隔离：必须使用 Conda 虚拟环境。
核心组件版本（记笔记）：
LangChain: 1.2.7 (企业级稳定版)
LangChain Core: 1.2.17 (核心逻辑库)
LangChain Community: 0.4.1 (社区集成库)
LangGraph: 1.0.10 (升级版本，解决兼容性冲突)
FastAPI: 0.111.0 (完整版，含 uvicorn[standard])
Uvicorn: 0.23.2 (ASGI 服务器)
SDK: dashscope==1.25.13 (通义千问官方 SDK)
工具库: python-dotenv==1.2.2 (环境变量管理)

2. 核心命令清单（速查）

操作	命令 (Windows/Ubuntu 通用)	备注
建环境	`conda create -n langchain_env python=3.10.12 -y`	推荐 3.10
激活	`conda activate langchain_env`	必做
装依赖	`pip install langchain==1.2.7 langchain-core==1.2.17 langgraph==1.0.10 langchain-community==0.4.1 "fastapi[all]==0.111.0" uvicorn==0.23.2 dashscope==1.25.13 python-dotenv==1.2.2 -i https://pypi.tuna.tsinghua.edu.cn/simple`	企业标准栈
退环境	`conda deactivate`

检查 Conda：终端输入 conda --version。

创建并激活：

# 推荐使用 Python 3.10
conda create -n langchain_env python=3.10.12 -y
conda activate langchain_env

验证：终端前缀变为 (langchain_env)。

2. 安装核心依赖（关键步骤）

在激活的环境中，执行以下命令安装 LangChain 1.x、LangGraph 1.x、FastAPI (完整版) 及 通义千问 SDK：

# 建议使用清华源加速
# 注意：fastapi[all] 需加引号，防止终端识别错误
pip install langchain==1.2.7 langchain-core==1.2.17 langgraph==1.0.10 langchain-community==0.4.1 "fastapi[all]==0.111.0" uvicorn==0.23.2 dashscope==1.25.13 python-dotenv==1.2.2 -i https://pypi.tuna.tsinghua.edu.cn/simple

⚠️ 注意：
LangChain 1.2.7 依赖 langgraph >= 1.0.7。如果安装时遇到 Conflict 报错，请务必指定 langgraph==1.0.10 或更高版本，不要使用旧版 1.0。

验证安装：
输入 pip list，重点检查以下包的版本：

langchain: 1.2.7
langchain-core: 1.2.17
langgraph: 1.0.10
langchain-community: 0.4.1
fastapi: 0.111.0
uvicorn: 0.23.2
dashscope: 1.25.13
python-dotenv: 1.2.2

目标：不涉及复杂原理，仅仅通过运行两段简单的代码，验证你的环境是否真的“活”了。
前提：确保虚拟环境 langchain_env 已激活。

1. 体验 LangChain：通过模版生成一句话

LangChain 最基础的功能就是管理提示词（Prompt）。我们来运行一个最简单的 PromptTemplate 示例。

步骤：

在终端输入 python 进入交互式命令行，或者新建文件 hello_langchain.py。
输入以下代码：

# 引入 LangChain 的提示词模版组件
from langchain_core.prompts import PromptTemplate

# 1. 定义一个模版：就像做填空题
template = PromptTemplate.from_template("你好，我是{name}，我正在学习{course}。")

# 2. 填入内容并生成最终句子（这一步不需要大模型参与）
result = template.format(name="AI练习生", course="LangChain智能体开发")

# 3. 打印结果
print(">>> LangChain 运行成功！生成内容如下：")
print(result)

成功标志：
终端输出：你好，我是AI练习生，我正在学习LangChain智能体开发。
这意味着 LangChain 核心组件已成功安装并能正常工作。

2. 体验 LangGraph：构建一个最简单的“图”

LangGraph 是用来定义智能体流程的“图”。我们来画一个最简单的“起点 -> 节点 -> 终点”的图。

步骤：

新建文件 hello_langgraph.py。
输入以下代码：

from typing import TypedDict
from langgraph.graph import StateGraph, START, END

# 1. 定义状态：就像图的“内存”，用于在节点间传递数据
class State(TypedDict):
    content: str

# 2. 定义节点函数：接收状态，返回更新后的状态
def hello_node(state: State):
    current_content = state["content"]
    print(f"--- 节点执行中：收到内容 '{current_content}' ---")
    return {"content": f"Hello, {current_content}!"}

# 3. 创建图构建器（使用 StateGraph）
builder = StateGraph(State)

# 4. 添加节点
builder.add_node("hello_node", hello_node)

# 5. 设置连线（Edge）：起点 -> 节点 -> 终点
builder.add_edge(START, "hello_node")
builder.add_edge("hello_node", END)

# 6. 编译图
graph = builder.compile()

# 7. 运行图
print(">>> 准备启动 LangGraph...")
result = graph.invoke({"content": "World"})
print(f">>> LangGraph 运行结束，最终结果：{result['content']}")

成功标志：
终端输出包含 --- 节点执行中：收到内容 'World' --- 和 LangGraph 运行结束，最终结果：Hello, World!。
这意味着 LangGraph 已准备就绪，可以进行后续复杂的智能体开发了！

快速回顾（举手回答）：Conda 虚拟环境激活的命令？安装 LangChain 时指定版本的作用是什么？

1. 基础准备：密钥配置（必须先行）

无论使用哪种方式，首先必须完成 API-KEY 的配置。

步骤：

在项目根目录新建 .env 文件（若已有则跳过）。
写入内容：DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxx (替换为你的真实 Key)。
确保安装了 python-dotenv 库。

2. 进阶实战：三种方式调用通义千问

我们将通过三个脚本，分别体验不同的调用层次。

方式一：官方 SDK 直连（原生方式）
特点：最底层，控制力最强，但代码繁琐，不易切换模型。

新建 test_sdk.py：

import dashscope
from dotenv import load_dotenv
import os
from dashscope import Generation

load_dotenv()

dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

def test_sdk():
    print("--- 方式 1: 官方 SDK 调用 ---")
    try:
        messages = [{'role': 'user', 'content': '用一句话介绍 Python。'}]
        response = Generation.call(model='qwen-turbo', messages=messages, result_format='message')
        if response.status_code == 200:
            print(f"回复: {response.output.choices[0].message.content}")
        else:
            print(f"报错: {response.message}")
    except Exception as e:
        print(f"异常: {e}")

if __name__ == '__main__':
    test_sdk()

方式二：LangChain 接入（统一接口）
特点：接口统一，更换模型只需改一行代码，便于集成提示词模版。

新建 test_langchain.py：

from dotenv import load_dotenv
import os
from langchain_community.chat_models import ChatTongyi  # 改用这个

load_dotenv()

def test_langchain():
    llm = ChatTongyi(
        model="qwen-turbo",
        dashscope_api_key=os.getenv("DASHSCOPE_API_KEY")
    )
    try:
        response = llm.invoke("用一句话介绍LangChain")
        print("回复：", response.content)
    except Exception as e:
        print("错误：", e)

if __name__ == '__main__':
    test_langchain()

方式三：LangGraph 接入（智能体架构）
特点：将大模型调用封装为“节点”，适合构建有循环、有状态的复杂智能体。

新建 test_langgraph.py：

from typing import TypedDict
from dotenv import load_dotenv
from langgraph.graph import StateGraph, START, END

# 改用 langchain_community 里的 ChatTongyi
from langchain_community.chat_models import ChatTongyi

load_dotenv()

# 1. 定义状态
class State(TypedDict):
    question: str
    answer: str

# 2. 定义节点任务
def call_model_node(state: State):
    # 这里已经是 langchain_community 的 ChatTongyi
    llm = ChatTongyi(model="qwen-turbo")
    print(f"-> 节点正在处理问题: {state['question']}")
    response = llm.invoke(state["question"])
    return {"answer": response.content}

# 3. 构建图
def test_langgraph():
    print("\n--- 方式 3: LangGraph 调用 ---")
    builder = StateGraph(State)
    builder.add_node("model_node", call_model_node)
    builder.add_edge(START, "model_node")
    builder.add_edge("model_node", END)
    
    graph = builder.compile()
    
    try:
        result = graph.invoke({"question": "用一句话介绍 LangGraph。"})
        print(f"回复: {result['answer']}")
    except Exception as e:
        print(f"LangGraph 调用失败: {e}")

if __name__ == '__main__':
    test_langgraph()

3. 核心对比（考试必考）

特性	官方 SDK (DashScope)	LangChain	LangGraph
定位	厂商提供的原生工具包	大模型应用开发的统一接口	智能体开发的流程编排引擎
优点	功能最新、最全，无中间层损耗	兼容性强，换模型方便，组件丰富	支持循环、记忆、复杂状态管理
缺点	绑定特定厂商，代码复用性差	对复杂逻辑（如循环）支持较弱	学习曲线较陡峭，代码量相对多
适用场景	简单的单一模型测试	搭建 RAG、工具链等线性应用	开发自主智能体（Agent）

1. 小组任务要求

配置密钥：确保 .env 文件生效。
编写代码：在项目中分别创建 test_sdk.py, test_langchain.py, test_langgraph.py。
运行验证：依次运行三个脚本，确保均能成功输出大模型的回复。
报错排查：如果遇到 ImportError，检查是否正确安装了 dashscope。
思考题：如果要把模型从“通义千问”换成“文心一言”，哪种方式修改代码最少？（答案：LangChain/LangGraph，只需改模型类配置）

2. 常见报错速查

ModuleNotFoundError: No module named 'dashscope': 运行 pip install dashscope。
ValidationError: 1 validation error for ChatTongyi: 检查环境变量 DASHSCOPE_API_KEY 是否读取成功。
401 Unauthorized: API Key 无效或余额不足。

AI 生成脚本示例：

提问：“生成使用 Conda 创建 Python 3.10 虚拟环境，并安装 LangChain 1.2.7 + LangGraph 1.0 + FastAPI 0.111.0 + 通义千问 SDK 的完整脚本，带注释，适配 Windows/Ubuntu 系统”；

AI 排查报错示例：

复制完整报错信息，提问：“帮我分析这个报错原因并给出解决步骤：[粘贴报错信息]（环境：Python 3.10 + LangChain 1.2.7）”；

核心技巧：

用 AI 生成的脚本替换手动输入，减少指令错误；
把 AI 给出的解决方案整理成 “报错 - 解决” 清单，便于小组共享；
用 AI 验证环境配置是否完整（如提问 “如何检查 LangChain 1.x + FastAPI 环境是否配置成功”）。

小知识：Python 环境配置、依赖版本管理是工业级 AI 智能体开发的第一道门槛，不管是企业的智能客服项目，还是大模型应用开发，工程师都需精准配置环境，避免因依赖问题导致项目上线失败。
职业习惯：严谨的环境配置流程 + 借助 AI 高效排查问题，是现代 AI 开发者的必备素养。规范的版本管理、清晰的报错记录，能让小组项目开发更高效，也能为未来进入产业界打下基础。
小鼓励：大家要熟练掌握环境配置的核心技巧，学会用 AI 解决实操问题，把基础环境搭稳，后续的 AI 智能体开发才能事半功倍。