1. Agent开发快速入门:从零到一的实战指南
Agent开发听起来高大上,但老司机告诉你,根本不用从零造轮子。就像搭积木一样,我们只需要掌握"搭骨架+填大脑+连手脚"这三个核心步骤,就能快速构建一个可用的Agent系统。下面我就用Python生态中的Ollama和LangChain这两个利器,带你走通全流程。
提示:本文所有代码示例基于Python 3.8+环境,建议使用conda或venv创建隔离环境。实测在16GB内存的MacBook Pro上运行流畅,大模型推理建议使用至少24GB显存的GPU服务器。
2. 开发环境准备与工具选型
2.1 基础环境配置
首先确保你的开发环境已经就绪:
bash复制# 创建Python虚拟环境
python -m venv agent-env
source agent-env/bin/activate # Linux/Mac
# agent-env\Scripts\activate # Windows
# 安装核心依赖
pip install langchain ollama python-dotenv
我强烈建议使用.env文件管理敏感配置:
ini复制# .env文件示例
OLLAMA_HOST=127.0.0.1
OLLAMA_PORT=11434
MODEL_NAME=llama3.1
2.2 为什么选择Ollama+LangChain组合?
-
Ollama:让你能在本地轻松运行开源大模型,解决了模型部署的痛点。它把模型权重、配置和数据打包成单一包,自动处理GPU优化等细节。
-
LangChain:提供了构建Agent所需的标准接口和组件,就像乐高积木一样可以自由组合。其模块化设计让开发者能专注业务逻辑而非底层实现。
实测对比其他方案,这个组合有三大优势:
- 本地化部署,数据隐私有保障
- 社区活跃,遇到问题容易找到解决方案
- 开发效率高,API设计符合直觉
3. 搭建Agent骨架:构建基础框架
3.1 初始化核心组件
先创建一个基础Agent骨架:
python复制from langchain.agents import AgentExecutor, create_react_agent
from langchain import hub
from langchain_community.llms import Ollama
# 初始化大模型
llm = Ollama(
model=os.getenv("MODEL_NAME"),
temperature=0.7, # 控制创造性,业务场景建议0.3-0.7
top_p=0.9,
repeat_penalty=1.1
)
# 加载预设的ReAct提示模板
prompt = hub.pull("hwchase17/react")
# 定义工具集(先留空,后面会填充)
tools = []
# 创建Agent实例
agent = create_react_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
这个骨架已经具备:
- 大模型推理能力
- ReAct决策框架
- 执行流水线
- 日志输出
3.2 骨架设计要点
-
温度参数:
temperature控制输出的随机性。对于需要精确结果的场景(如数学计算)设为0.1-0.3,创意场景可以0.7-1.0。 -
执行策略:
AgentExecutor提供了max_iterations参数防止死循环,建议设为5-10次。 -
内存管理:长时间运行的Agent需要添加
ConversationBufferMemory,否则会丢失上下文。
4. 为Agent填充"大脑":模型集成与优化
4.1 本地模型部署
使用Ollama在本地启动大模型:
bash复制# 下载模型(约4-8GB,取决于模型版本)
ollama pull llama3.1
# 启动服务(默认端口11434)
ollama serve
如果下载慢,可以改用国内镜像源:
bash复制# 使用清华镜像加速
OLLAMA_MODELS_SOURCE=https://mirrors.tuna.tsinghua.edu.cn/ollama ollama pull llama3.1
4.2 模型性能调优
在Ollama初始化时可以通过这些参数提升效果:
python复制llm = Ollama(
model="llama3.1",
num_ctx=4096, # 上下文窗口大小
num_gpu=1, # 使用的GPU数量
num_thread=8, # CPU线程数
stop=["\nObservation:", "\n\tObservation:"], # 停止标记
top_k=40 # 采样策略
)
踩坑记录:在Windows WSL2中运行Ollama时,需要设置
OLLAMA_HOST=0.0.0.0才能从宿主机访问,否则会报连接拒绝错误。
5. 连接Agent的"手脚":工具集成实战
5.1 内置工具的使用
LangChain提供了丰富的内置工具,比如:
python复制from langchain_community.tools import WikipediaQueryRun, ArxivQueryRun
from langchain_community.utilities import WikipediaAPIWrapper
wikipedia = WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
arxiv = ArxivQueryRun()
tools = [wikipedia, arxiv]
5.2 自定义工具开发
实现一个获取实时天气的工具:
python复制from langchain.tools import tool
import requests
@tool
def get_weather(city: str) -> str:
"""获取指定城市的当前天气情况"""
api_key = os.getenv("WEATHER_API_KEY")
url = f"http://api.weatherapi.com/v1/current.json?key={api_key}&q={city}"
response = requests.get(url)
data = response.json()
return f"{city}当前天气:{data['current']['condition']['text']},温度{data['current']['temp_c']}℃"
5.3 工具注册与测试
将自定义工具加入Agent:
python复制tools.append(get_weather)
# 更新Agent实例
agent = create_react_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
# 测试工具链
result = agent_executor.invoke({
"input": "北京现在的天气怎么样?然后查查维基百科上关于北京的历史"
})
print(result["output"])
6. 高级功能与性能优化
6.1 记忆机制实现
让Agent记住对话历史:
python复制from langchain.memory import ConversationBufferMemory
memory = ConversationBufferMemory(memory_key="chat_history")
agent_executor = AgentExecutor(
agent=agent,
tools=tools,
memory=memory,
verbose=True
)
6.2 异步处理提升响应速度
对于耗时操作,使用异步执行:
python复制async def async_query():
agent = create_react_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
return await agent_executor.ainvoke({"input": "请用中文总结Llama3的技术特点"})
import asyncio
result = asyncio.run(async_query())
6.3 流式输出体验优化
实现逐字输出效果:
python复制from langchain.callbacks.streaming_stdout import StreamingStdOutCallbackHandler
llm = Ollama(
model="llama3.1",
callbacks=[StreamingStdOutCallbackHandler()],
stream=True
)
# 后续使用方式与之前相同
7. 避坑指南与常见问题
7.1 模型响应慢的优化方案
- 降低
num_ctx值(如2048→1024) - 使用量化模型(如
llama3.1-4bit) - 设置合理的
max_iterations避免长思考 - 启用GPU加速(需CUDA环境)
7.2 工具调用失败排查步骤
- 单独测试工具函数是否正常工作
- 检查工具的描述文档是否清晰(Agent依赖描述做决策)
- 查看verbose日志确认输入输出格式
- 尝试简化prompt模板
7.3 中文处理优化技巧
- 在prompt中明确要求"请用中文回答"
- 对中文工具添加中文描述
- 使用
stop=["\nObservation", "。"]改善断句 - 考虑使用
chat-models而非纯LLM
8. 完整示例:天气预报查询Agent
下面是一个可直接运行的完整示例:
python复制import os
from dotenv import load_dotenv
from langchain.agents import AgentExecutor, create_react_agent
from langchain import hub
from langchain_community.llms import Ollama
from langchain.tools import tool
import requests
# 加载环境变量
load_dotenv()
# 自定义天气工具
@tool
def get_weather(city: str) -> str:
"""获取指定城市的当前天气情况(中文工具)"""
api_key = os.getenv("WEATHER_API_KEY")
url = f"http://api.weatherapi.com/v1/current.json?key={api_key}&q={city}&lang=zh"
response = requests.get(url)
data = response.json()
return f"{city}天气:{data['current']['condition']['text']},温度{data['current']['temp_c']}℃"
# 初始化组件
llm = Ollama(model="llama3.1", temperature=0.5)
prompt = hub.pull("hwchase17/react")
tools = [get_weather]
# 创建Agent
agent = create_react_agent(llm, tools, prompt)
agent_executor = AgentExecutor(
agent=agent,
tools=tools,
verbose=True,
handle_parsing_errors=True
)
# 运行查询
response = agent_executor.invoke({
"input": "请问上海和北京的天气怎么样?用中文回答"
})
print("最终答案:", response["output"])
这个Agent已经具备:
- 多城市天气查询能力
- 中文处理优化
- 错误处理机制
- 详细执行日志
9. 部署与扩展建议
9.1 生产环境部署方案
- 容器化部署:
dockerfile复制FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "app.py"]
-
性能监控:集成Prometheus监控工具调用耗时和资源占用
-
限流保护:使用FastAPI的
RateLimiter防止API滥用
9.2 后续扩展方向
- 接入知识库实现RAG功能
- 添加网页抓取工具扩展信息源
- 集成语音输入输出模块
- 开发可视化调试界面
我在实际项目中发现,用langchain-cli初始化项目结构能节省大量配置时间。对于复杂Agent,建议采用langgraph来管理控制流,它比基础Agent更适合处理长工作流。
