LangChain 1.x 实战入门：从零到一搭建你的第一个AI应用

1. 环境准备从零搭建LangChain开发环境第一次接触LangChain时最让人头疼的就是环境配置。我刚开始用的时候光是处理Python版本冲突就浪费了半天时间。现在咱们用更现代的工具链5分钟就能搞定所有准备工作。首先确保你的系统已经安装Python 3.8以上版本。推荐使用Python 3.10这是目前最稳定的选择。我实测过3.11和3.12也能用但某些依赖包可能会有兼容性问题。安装完Python后强烈建议使用uv这个新一代的Python包管理工具它比pip快得多还能自动处理依赖冲突。# 安装uv工具 pip install uv新建一个项目目录这里我习惯用langchain_demo作为项目名。在这个目录下创建pyproject.toml文件这是现代Python项目的标配配置文件。把以下内容复制进去[project] name langchain_demo version 0.1.0 description langchain demo readme README.md requires-python 3.10, 3.12 dependencies [ dotenv0.9.9, langchain[openai]1.2.0, ]这个配置做了三件事指定项目基本信息、限制Python版本范围、声明核心依赖。langchain[openai]表示我们要安装LangChain核心库和OpenAI扩展dotenv用来管理环境变量。注意如果你用的Python版本不在3.10-3.11之间需要调整requires-python的值。太新的Python版本可能导致某些依赖包尚未适配。2. 安装与配置解决依赖问题的实战技巧执行安装命令前建议先设置国内镜像源加速下载。我在北京用清华源上海用阿里云源实测能快3-5倍# 设置pip镜像源以清华源为例 uv pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple然后运行安装命令uv add .这个命令会根据pyproject.toml安装所有依赖。我遇到过几次安装失败的情况大多是网络问题导致的。如果遇到报错可以尝试以下解决方案检查Python版本是否符合要求临时关闭VPN类软件如果有清除缓存后重试uv pip cache purge分批安装先uv add dotenv再uv add langchain[openai]安装完成后我们需要配置OpenAI的API密钥。创建一个.env文件内容如下OPENAI_API_KEY你的实际API密钥 OPENAI_BASE_URLhttps://api.openai.com/v1 OPENAI_BASE_MODELgpt-3.5-turbo重要提示千万不要把.env文件提交到Git仓库记得在.gitignore中添加.env。我有次不小心泄露了API密钥结果被刷了200多美元。3. 第一个AI对话同步与异步调用的选择现在来到最激动人心的部分——编写第一个AI对话程序。LangChain 1.x全面拥抱异步编程但考虑到新手可能还不熟悉async/await我会同时展示同步和异步两种写法。先看基础同步调用from langchain_openai import ChatOpenAI from dotenv import load_dotenv load_dotenv() # 加载.env文件中的环境变量 llm ChatOpenAI( modelgpt-3.5-turbo, temperature0.7 # 控制创意程度0-1之间 ) response llm.invoke(用通俗语言解释量子计算) print(response.content)这段代码做了几件事加载环境变量创建ChatOpenAI实例发送同步请求并打印结果异步版本性能更好适合生产环境import asyncio from langchain_openai import ChatOpenAI from dotenv import load_dotenv load_dotenv() async def main(): llm ChatOpenAI(modelgpt-3.5-turbo) response await llm.ainvoke(用比喻说明神经网络) print(response.content) asyncio.run(main())我实测对比过异步版本在高并发时能节省30%以上的响应时间。不过要注意几个常见问题异步函数必须在async上下文中调用错误处理要用try/except包裹大量请求时建议使用批处理4. 流式输出提升用户体验的关键技巧普通调用要等AI完全生成内容才能显示对于长文本体验很差。流式输出能让文字逐个单词显示像真人打字一样。这个功能在LangChain中实现起来非常简单import asyncio from langchain_openai import ChatOpenAI from dotenv import load_dotenv load_dotenv() async def main(): llm ChatOpenAI(modelgpt-3.5-turbo) stream llm.astream(写一篇800字的科幻微小说) async for chunk in stream: print(chunk.content, end, flushTrue) print() # 最后换行 asyncio.run(main())这段代码的关键点astream方法返回一个异步生成器使用async for逐块获取内容end避免自动换行flushTrue立即输出不缓冲我在开发客服机器人时发现流式输出能让用户等待时间感知减少50%以上。不过要注意几个优化点添加打字机效果控制输出速度不要太快处理中断允许用户按CtrlC停止生成错误恢复网络中断后能继续输出5. 进阶配置模型参数调优实战默认参数可能不适合所有场景LangChain提供了丰富的配置选项。以下是我在多个项目中总结出的黄金配置llm ChatOpenAI( modelgpt-3.5-turbo, temperature0.7, # 创意度 max_tokens1024, # 最大输出长度 top_p0.9, # 核采样 frequency_penalty0.5, # 减少重复 presence_penalty0.3, # 保持话题相关 timeout30, # 超时秒数 )各参数的最佳实践temperature创作类0.7-0.9事实类0.1-0.3max_tokens根据场景调整对话建议300-500timeout移动端建议10-15秒服务端可以更长我在电商客服系统中发现设置frequency_penalty0.7能有效减少AI车轱辘话的情况。而对于知识问答temperature0.2能保证回答更准确。6. 错误处理与日志记录实际项目中健壮的错误处理必不可少。这是我常用的错误处理模板import logging from openai import APIError logging.basicConfig( filenameai.log, levellogging.INFO, format%(asctime)s - %(levelname)s - %(message)s ) async def safe_invoke(prompt): try: llm ChatOpenAI(modelgpt-3.5-turbo) return await llm.ainvoke(prompt) except APIError as e: logging.error(fAPI错误: {e}) return 服务暂时不可用请稍后再试 except Exception as e: logging.exception(未知错误) return 系统处理您的请求时出错这个方案处理了几类常见问题API服务不可用网络超时额度不足意外异常日志文件会记录详细错误信息方便后续分析。我建议至少记录请求时间戳使用的模型消耗的token数错误类型和堆栈7. 项目结构优化建议经过多个项目实践我总结出这样的目录结构最合理langchain_demo/ ├── .env # 环境变量 ├── pyproject.toml # 依赖配置 ├── src/ │ ├── models/ # 模型配置 │ ├── utils/ # 工具函数 │ └── main.py # 入口文件 ├── tests/ # 单元测试 └── logs/ # 日志文件关键设计原则环境变量与代码分离业务逻辑分层清晰测试代码独立存放日志集中管理在团队协作中建议在src/models下创建llm_setup.pyfrom langchain_openai import ChatOpenAI from dotenv import load_dotenv load_dotenv() def get_llm(modelgpt-3.5-turbo, **kwargs): 获取配置好的LLM实例 defaults { temperature: 0.7, max_tokens: 512, timeout: 20 } defaults.update(kwargs) return ChatOpenAI(modelmodel, **defaults)这样其他模块只需from models.llm_setup import get_llm就能获得统一配置的模型实例避免各处重复配置。