大模型应用开发 / 系统课时
开发环境搭建
开发环境搭建
本课带你完成 LangChain 开发环境的搭建,包括安装核心依赖包、配置模型访问密钥,并通过一条最简命令验证安装是否成功,避免后续课程因环境问题卡住。
学习目标
- 掌握 LangChain 及配套依赖的安装方式
- 学会配置模型服务的访问密钥
- 能够验证环境是否安装成功并排查常见失败
前置检查
开始前确认已安装 Python 3.10 及以上版本(本次示例使用 Python 3.12),并准备好可用的 pip。如果使用虚拟环境,建议先创建并激活独立的虚拟环境,避免依赖冲突。
Linux/macOS 使用以下命令:
python --version
python -m venv .venv
source .venv/bin/activate预期结果:输出 Python 3.10 以上的版本号,随后创建并激活当前目录的 .venv。实际补丁版本随本机安装变化。Windows PowerShell 可直接运行 .venv/Scripts/python.exe,避免激活策略阻挡后误用全局解释器。
操作步骤
安装 LangChain 核心包以及对应模型服务商的适配包(以 OpenAI 为例):
python -m pip install "langchain>=1.4,<2" "langchain-openai>=1.7,<2"预期结果:依赖安装完成且无冲突;安装日志中的具体版本随解析时间变化。需要 Anthropic、Chroma 时再安装 langchain-anthropic、langchain-chroma,基础模型调用不要求一次安装所有集成包。
安装完成后,将模型访问密钥写入当前终端环境,避免把密钥硬编码进代码。以下 Bash 命令使用隐藏输入,不把真实密钥写进命令历史:
read -r -s -p "OpenAI API key: " OPENAI_API_KEY
export OPENAI_API_KEY
read -r -p "可用模型名称: " OPENAI_MODEL
export OPENAI_MODEL预期结果:输入密钥时不回显,OPENAI_API_KEY 与 OPENAI_MODEL 仅在当前终端及子进程中生效;模型名称填当前账户可调用的标识。不要打印密钥来验证。
Windows PowerShell 可使用下面的隐藏输入方式:
$anystackKey = Read-Host "OpenAI API key" -AsSecureString
$env:OPENAI_API_KEY = [System.Net.NetworkCredential]::new("", $anystackKey).Password
$env:OPENAI_MODEL = Read-Host "可用模型名称"预期结果:密钥输入被隐藏,两个环境变量在当前 PowerShell 会话中设置;关闭会话后不自动持久保存。
验证
运行以下命令确认安装版本:
python -c "import langchain; print(langchain.__version__)"预期输出:
1.x.x这里 1.x.x 表示实际的 1 系列版本,并非固定字符串。本次验证版本为 langchain 1.4.4、langchain-core 1.6.9、langchain-openai 1.7.0;只要成功导入并输出实际版本号,即说明核心包安装成功,尚未证明远端鉴权与模型访问正常。
典型失败处理
若提示 ModuleNotFoundError: No module named 'langchain',说明依赖未装入当前解释器,请确认虚拟环境已激活后重新安装;若后续调用模型时提示鉴权错误(如 401),需检查环境变量是否正确设置,以及密钥是否已过期或欠费。
区分安装成功与调用成功
虚拟环境隔离的是依赖,环境变量提供的是访问配置,两者解决不同问题。编辑器解释器也要选择 .venv 中的 Python;终端能导入不代表编辑器或部署进程使用同一个环境。优先通过 python -m pip 安装,避免 pip 指向另一套解释器。
项目跑通后用 python -m pip freeze 保存精确版本,并在干净环境重装验证。升级主版本前先运行示例测试;原文旧式 langchain.memory 与 AgentExecutor 不能在 1 系列命名空间下直接照搬,应按对应课时的迁移说明处理。版本边界参见 LangChain 安装文档。
鉴权失败、模型不存在、配额不足和网络超时属于不同故障:先保留不含密钥的异常类型与状态码,再检查对应配置。不要为了通过测试关闭 TLS 校验,也不要将令牌提交到仓库。真实模型请求可能计费,离线导入检查不会验证服务账户额度。