Langchain 1.3实战:从工具调用到智能体,构建本地与云端LLM应用
2026/8/6 7:06:41 网站建设 项目流程

这次我们来看一个基于 Langchain 1.3 框架实现 LLM 与 Agent 工具调用的实战教程。对于想要构建智能应用、让大模型“学会”使用外部工具的开发者来说,Langchain 是目前最主流的选择之一。但面对其庞大的生态和快速迭代的版本,很多人在入门和实战时会感到无从下手:工具调用和 Function Calling 有什么区别?如何配置本地大模型?Agent 的执行速度受什么影响?有没有完全离线的方案?

这篇文章将直接切入核心,手把手带你从环境搭建、核心概念理解,到完成一个可运行的 Agent 应用。我们重点关注 Langchain 1.3 版本下的关键变化、如何连接本地或云端 LLM、如何定义和调用工具,以及如何构建一个能稳定执行多步任务的 Agent。整个过程无需复杂硬件,普通开发机即可运行,目标是让你看完就能动手实现。

1. 核心能力速览

在深入代码之前,我们先快速了解 Langchain 在 LLM 与 Agent 工具调用方面的核心能力与门槛。

能力项说明
核心框架Langchain 1.3+,一个用于构建由 LLM 驱动的应用程序的框架。
主要功能1.工具调用 (Tool Calling):让 LLM 学会调用外部函数/API。
2.智能体 (Agent):赋予 LLM 规划、使用工具、迭代执行复杂任务的能力。
3.记忆 (Memory):管理对话或任务的历史上下文。
4.链 (Chain):将多个组件(提示词、模型、工具)组合成可执行的工作流。
LLM 支持支持 OpenAI GPT、Anthropic Claude、本地部署的 Llama、Qwen、GLM 等(通过 LiteLLM、Ollama 或自定义接口)。
硬件门槛无强制 GPU 要求。框架本身是 Python 库,资源消耗取决于你集成的 LLM。调用云端 API(如 GPT-4)仅需网络;调用本地大模型则需要满足该模型本身的硬件要求(通常需要 GPU 和足够显存)。
部署模式1.纯云端:Langchain + OpenAI API,开发最快。
2.混合模式:Langchain + 本地模型服务(如 Ollama、vLLM),完全离线可控。
3.一体化部署:可将整个 Agent 应用封装为 FastAPI 服务,提供 Web 或 API 接口。
是否支持批量任务支持。可以通过异步调用、队列或自定义链(Chain)来处理批量输入,但需注意 LLM 的速率限制和上下文管理。
关键优势标准化了与 LLM 交互的流程;提供了丰富的内置工具和 Agent 类型;社区活跃,易于集成到现有系统。
适合场景数据分析助手、自动化客服、智能文档处理、代码生成与解释、研究助理等需要 LLM 与外部系统交互的场景。

2. 适用场景与使用边界

Langchain 构建的 Agent 并非万能。明确其适用边界,能帮助你更高效地利用它。

它非常适合以下场景:

  • 需要连接外部数据和工具的对话系统:例如,用户问“今天北京天气如何?”,Agent 可以调用天气查询工具并返回结果。
  • 多步骤任务自动化:例如,“总结最近三篇关于 AI 的 arXiv 论文,并给我一个要点列表”。Agent 可以规划:搜索论文 -> 获取全文 -> 总结每篇 -> 汇总列表。
  • 基于私有知识的问答:结合 RAG(检索增强生成),让 LLM 能够回答关于你内部文档、数据库的问题。
  • 快速原型验证:当你有一个“让 AI 帮我做某事”的想法时,用 Langchain 可以快速搭建出可演示的雏形。

它可能不是最佳选择,或需要额外注意的场景:

  • 对延迟极其敏感的任务:Agent 的思考(调用 LLM)和行动(调用工具)是串行的,多轮交互会累积延迟。复杂任务可能需数秒或更久。
  • 需要极高确定性的流程:LLM 的输出具有随机性,Agent 的决策路径可能不稳定。对于金融交易、工业控制等场景,需加入严格的校验和回退机制。
  • 完全封闭、无网络的环境:如果使用云端 LLM API(如 GPT-4),则需要网络。若要完全离线,必须部署本地 LLM 服务(如 Ollama),并确保所有工具(如数据库连接、本地命令)也在内网可用。
  • 安全与合规要求严格的场景:Agent 可能根据用户输入执行外部工具(如读写文件、执行代码)。必须实施严格的输入过滤、权限控制和操作审计,防止恶意指令。

重要提醒:在使用任何工具调用功能,尤其是涉及文件操作、代码执行、网络访问时,务必在沙箱或严格受限的环境中进行测试,并明确告知用户其能力边界,避免造成数据泄露或系统损坏。

3. 环境准备与前置条件

我们将创建一个独立的 Python 环境来开始项目,避免依赖冲突。

基础环境要求:

  • 操作系统:Windows 10/11, macOS, 或 Linux (推荐 Ubuntu 20.04+)。
  • Python 版本:3.8 至 3.11(Langchain 1.3+ 对 3.12 支持可能需留意,建议使用 3.10 或 3.11)。
  • 包管理工具pip(建议版本 > 21.0)。
  • 代码编辑器:VS Code, PyCharm 等任选。

网络与 API 准备(二选一):

  1. 云端 LLM 路线:需要一个可用的 OpenAI API Key(或 Anthropic、Google Gemini 等)。这是最快上手的路径。
  2. 本地 LLM 路线:需要安装并运行一个本地大模型服务,例如Ollama。这可以实现完全离线运行。你需要确保机器有足够内存(通常 8GB+)来运行模型,使用 GPU 会更快。

4. 安装部署与启动方式

我们首先采用云端 LLM (OpenAI)路线进行演示,因为它设置最简单。之后会介绍如何切换为本地模型。

步骤 1:创建项目目录并初始化虚拟环境打开终端(或命令提示符/PowerShell),执行以下命令:

# 创建项目目录并进入 mkdir langchain-agent-tutorial && cd langchain-agent-tutorial # 创建虚拟环境 (Windows) python -m venv venv # 激活虚拟环境 (Windows) venv\Scripts\activate # 激活虚拟环境 (macOS/Linux) # source venv/bin/activate

步骤 2:安装核心依赖在激活的虚拟环境中,安装 Langchain 及其相关库。我们安装langchain-openai来集成最新的 OpenAI SDK。

pip install langchain langchain-openai langchain-community python-dotenv
  • langchain: 核心框架。
  • langchain-openai: 官方维护的 OpenAI 集成。
  • langchain-community: 包含许多第三方工具和集成。
  • python-dotenv: 用于管理环境变量(如 API Key)。

步骤 3:配置 API Key在项目根目录下创建一个名为.env的文件,用于安全存储你的 API Key。

# .env 文件内容 OPENAI_API_KEY=你的-openai-api-key-在这里

重要:确保.env文件被添加到.gitignore中,切勿提交到代码仓库。

5. 功能测试与效果验证:从工具调用到智能体

现在,我们从最简单的“工具调用”开始,逐步构建一个完整的 Agent。

5.1 基础工具调用 (Tool Calling)

工具调用是 Agent 的基石。它的本质是让 LLM 根据用户请求,决定是否调用以及如何调用一个预先定义好的 Python 函数。

测试目的:验证 Langchain 能否成功让 LLM 理解工具定义,并格式化输出一个结构化的工具调用请求。

操作步骤

  1. 在项目目录下创建basic_tool.py
  2. 编写以下代码:
# basic_tool.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.tools import tool from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate # 1. 加载环境变量 load_dotenv() # 2. 定义一个获取天气的“工具”(这里模拟,不真实调用API) @tool def get_weather(city: str) -> str: """根据城市名获取该城市的当前天气信息。""" # 这里应该是调用真实天气API的代码 return f"{city}的天气是晴朗,25摄氏度。" # 3. 初始化LLM (使用gpt-3.5-turbo,成本低响应快) llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0) # 4. 创建工具列表 tools = [get_weather] # 5. 创建提示词模板,告诉LLM它有哪些工具可用 prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个乐于助人的助手,可以调用工具来回答问题。"), ("human", "{input}"), ("placeholder", "{agent_scratchpad}"), # 这是Agent记录其思考过程的地方 ]) # 6. 创建Agent agent = create_tool_calling_agent(llm=llm, tools=tools, prompt=prompt) # 7. 创建Agent执行器 agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True) # 8. 测试! if __name__ == "__main__": # 测试用例1:需要调用工具 result1 = agent_executor.invoke({"input": "北京今天天气怎么样?"}) print("测试1结果:", result1["output"]) print("-" * 30) # 测试用例2:无需调用工具,直接回答 result2 = agent_executor.invoke({"input": "你好,请介绍一下你自己。"}) print("测试2结果:", result2["output"])

预期结果与判断: 运行python basic_tool.py,你应该看到类似以下的输出(verbose=True会显示详细思考过程):

> Entering new AgentExecutor chain... 我需要查询北京的天气,我有一个工具可以获取天气信息。 Action: get_weather Action Input: {"city": "北京"} 北京今天天气怎么样? 北京的天气是晴朗,25摄氏度。 > Finished chain. 测试1结果: 北京的天气是晴朗,25摄氏度。 ------------------------------ > Entering new AgentExecutor chain... 我是一个AI助手,可以调用工具来帮助你。例如,我可以查询天气信息。有什么我可以帮你的吗? > Finished chain. 测试2结果: 我是一个AI助手,可以调用工具来帮助你。例如,我可以查询天气信息。有什么我可以帮你的吗?

成功标准

  • LLM 正确识别出第一个问题需要调用get_weather工具,并生成了格式正确的Action Input(一个包含city参数的 JSON)。
  • Agent 执行器成功调用了工具函数,并返回了模拟的天气结果。
  • 对于第二个问题,LLM 判断无需调用工具,直接生成了回答。
  • 控制台打印了完整的思考链(Chain of Thought),这有助于调试。

5.2 构建多工具智能体 (Agent)

一个实用的 Agent 通常配备多个工具。我们来增加一个计算器和一个搜索网络(模拟)的工具。

测试目的:验证 Agent 能否在多个工具中做出正确选择,并处理需要多步推理的任务。

操作步骤

  1. 创建multi_tool_agent.py
  2. 编写以下代码:
# multi_tool_agent.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.tools import tool from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate from datetime import datetime load_dotenv() # 定义工具1:计算器 @tool def calculator(expression: str) -> str: """计算一个数学表达式的结果。支持加减乘除(+-*/)和括号。""" # 警告:在生产环境中,使用 `eval` 是极度危险的!这里仅用于演示。 # 应使用 `ast.literal_eval` 或专用数学库(如 `numexpr`)。 try: result = eval(expression) return f"表达式 `{expression}` 的计算结果是:{result}" except Exception as e: return f"计算错误:{e}" # 定义工具2:获取当前时间 @tool def get_current_time(timezone: str = "Asia/Shanghai") -> str: """获取指定时区的当前日期和时间。""" # 简化处理,实际应使用pytz等库 now = datetime.now() if "shanghai" in timezone.lower() or "beijing" in timezone.lower(): return f"当前北京时间是:{now.strftime('%Y-%m-%d %H:%M:%S')}" else: return f"当前系统时间是:{now.strftime('%Y-%m-%d %H:%M:%S')} (时区参数'{timezone}'未精确处理)" # 定义工具3:模拟网络搜索 @tool def search_web(query: str) -> str: """模拟网络搜索,返回一些模拟结果。""" # 这里模拟返回固定结果,真实场景应集成SerperAPI、Google Search等 mock_results = { "Langchain": "Langchain是一个用于构建LLM应用的框架。", "Python": "Python是一种流行的编程语言。", "天气": "天气是大气状态在短时间内的表现。" } for key in mock_results: if key.lower() in query.lower(): return f"搜索 '{query}' 的模拟结果:{mock_results[key]}" return f"搜索 '{query}' 未找到匹配的模拟结果。" # 初始化LLM和工具列表 llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0) tools = [calculator, get_current_time, search_web] # 构建提示词 prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个强大的助手,拥有计算、查询时间和搜索信息的能力。请根据用户问题,决定是否需要以及使用哪个工具。"), ("human", "{input}"), ("placeholder", "{agent_scratchpad}"), ]) # 创建并执行Agent agent = create_tool_calling_agent(llm=llm, tools=tools, prompt=prompt) agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True, handle_parsing_errors=True) if __name__ == "__main__": test_cases = [ "123乘以456等于多少?", "现在几点了?", "帮我搜索一下Langchain是什么?", "先计算(15+27)*3的值,然后告诉我现在的时间。", # 多步骤任务 "今天的天气真好,对吧?" # 无需工具 ] for question in test_cases: print(f"\n用户问题: {question}") print("-" * 40) try: result = agent_executor.invoke({"input": question}) print(f"助手回答: {result['output']}") except Exception as e: print(f"执行出错: {e}") print("=" * 60)

预期结果与判断: 运行此脚本,你将看到 Agent 为不同问题选择不同的工具。对于多步骤任务“先计算...然后告诉我时间”,观察 Agent 是否会执行两次工具调用。handle_parsing_errors=True参数能帮助处理一些 LLM 输出格式错误的情况。

关键观察点

  1. 工具选择准确性:LLM 是否能将数学问题映射到calculator,将时间问题映射到get_current_time
  2. 参数提取:LLM 是否能从自然语言中正确提取工具所需的参数(如数学表达式、时区)?
  3. 多步任务处理:Agent 是否能规划并顺序执行“计算”和“查询时间”两个动作?
  4. 思考过程:通过verbose输出,理解 Agent 的决策逻辑。

5.3 连接本地大模型 (Ollama)

要实现完全离线的 Agent,关键是将 LLM 从 OpenAI 切换到本地服务。Ollama 是目前最方便的本地 LLM 运行和管理的工具之一。

前置条件

  1. 根据你的操作系统,从 Ollama 官网 下载并安装 Ollama。
  2. 在终端中拉取一个模型,例如小巧的qwen2.5:3b或功能更强的llama3.2:3b
    ollama pull qwen2.5:3b
  3. 确保 Ollama 服务在运行(安装后通常会自动启动)。

操作步骤

  1. 安装 Langchain 与 Ollama 集成的库(如果尚未安装):
    pip install langchain-ollama
  2. 创建local_agent_with_ollama.py
  3. 编写以下代码,复用之前的工具,但更换 LLM:
# local_agent_with_ollama.py import os from langchain_ollama import ChatOllama from langchain.tools import tool from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate # 1. 定义工具(与之前相同) @tool def get_weather(city: str) -> str: """根据城市名获取该城市的当前天气信息。""" return f"{city}的天气是晴朗,25摄氏度。" @tool def calculator(expression: str) -> str: """计算一个数学表达式的结果。支持加减乘除(+-*/)和括号。""" try: result = eval(expression) return f"表达式 `{expression}` 的计算结果是:{result}" except Exception as e: return f"计算错误:{e}" # 2. 初始化本地LLM (连接到本机Ollama服务) # 默认地址是 http://localhost:11434 llm = ChatOllama( model="qwen2.5:3b", # 使用你拉取的模型名 temperature=0, # 对于较小的模型,可能需要调整一些参数来优化工具调用能力 # num_ctx=2048, # 上下文长度 ) # 3. 创建工具列表和Agent tools = [get_weather, calculator] prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个助手,可以调用工具。请严格根据工具描述来决定是否使用工具。"), ("human", "{input}"), ("placeholder", "{agent_scratchpad}"), ]) agent = create_tool_calling_agent(llm=llm, tools=tools, prompt=prompt) agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True, handle_parsing_errors=True, max_iterations=5) if __name__ == "__main__": print("正在使用本地模型 (Ollama) 运行Agent...") test_questions = ["上海天气如何?", "计算 98 + 102 * 2"] for q in test_questions: print(f"\n问题: {q}") try: result = agent_executor.invoke({"input": q}) print(f"回答: {result['output']}") except Exception as e: print(f"错误: {e}")

效果验证与注意事项

  • 首次运行可能较慢:本地模型需要加载到内存。
  • 小模型的能力限制:3B 参数的小模型在工具调用的格式遵循和复杂推理上可能不如 GPT-3.5/4 稳定。你可能会遇到:
    • 格式错误:LLM 没有输出标准化的ActionAction InputJSON。
    • 逻辑错误:错误地选择了工具或提取了参数。
    • 迭代次数超限:陷入循环,需要max_iterations来限制。
  • 调试:将verbose=True打开,仔细观察模型的“思考”输出,这是调试本地 Agent 最重要的手段。如果工具调用失败,可以尝试:
    1. 使用更大的模型(如llama3.1:8b)。
    2. 简化提示词(System Prompt)。
    3. 使用ChatPromptTemplatefew-shot示例来教导模型如何格式化输出。

6. 接口 API 与批量任务

将你的 Agent 封装成 API 服务,是集成到其他应用的标准方式。同时,处理批量任务也是常见需求。

6.1 使用 FastAPI 创建 Agent 服务

操作步骤

  1. 安装 FastAPI 和 Uvicorn:
    pip install fastapi uvicorn
  2. 创建agent_api.py
# agent_api.py import os from fastapi import FastAPI, HTTPException from pydantic import BaseModel from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.tools import tool from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate from contextlib import asynccontextmanager load_dotenv() # 定义工具 @tool def search_products(query: str) -> str: """根据关键词搜索产品信息。返回模拟数据。""" product_db = { "手机": "品牌A手机,售价2999元。品牌B手机,售价3999元。", "笔记本": "游戏本X,售价8999元。轻薄本Y,售价6999元。", "耳机": "无线降噪耳机,售价899元。" } return product_db.get(query, f"未找到关于'{query}'的产品信息。") # 初始化LLM和Agent (在服务启动时加载,避免每次请求重复初始化) llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0) tools = [search_products] prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个电商客服助手,可以帮用户搜索产品信息。"), ("human", "{input}"), ("placeholder", "{agent_scratchpad}"), ]) agent = create_tool_calling_agent(llm=llm, tools=tools, prompt=prompt) agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=False, handle_parsing_errors=True) # 定义请求/响应模型 class AgentRequest(BaseModel): query: str user_id: str | None = None # 可扩展用于用户会话管理 class AgentResponse(BaseModel): answer: str session_id: str | None = None # 生命周期管理:启动和关闭 @asynccontextmanager async def lifespan(app: FastAPI): # 启动逻辑,这里可以加载大模型等重型资源 print("Agent API 服务启动...") yield # 关闭逻辑 print("Agent API 服务关闭...") # 创建FastAPI应用 app = FastAPI(title="Langchain Agent API", lifespan=lifespan) @app.post("/chat", response_model=AgentResponse) async def chat_with_agent(request: AgentRequest): """ 与Agent对话的端点。 """ try: result = agent_executor.invoke({"input": request.query}) return AgentResponse(answer=result["output"]) except Exception as e: raise HTTPException(status_code=500, detail=f"Agent执行失败: {str(e)}") @app.get("/health") async def health_check(): return {"status": "healthy"} if __name__ == "__main__": import uvicorn uvicorn.run(app, host="0.0.0.0", port=8000)

启动与测试服务

  1. 运行服务:
    python agent_api.py
  2. 使用curl或浏览器访问http://localhost:8000/docs查看自动生成的 API 文档。
  3. 使用curl进行测试:
    curl -X POST "http://localhost:8000/chat" \ -H "Content-Type: application/json" \ -d '{"query": "帮我找一下手机"}'
    预期返回:{"answer":"品牌A手机,售价2999元。品牌B手机,售价3999元。","session_id":null}

6.2 处理批量任务

对于批量处理大量查询,直接串行调用 API 效率低下且可能触发速率限制。一个简单的改进是使用异步和队列。

示例:异步批量处理脚本batch_processor.py

# batch_processor.py import asyncio import aiohttp import json from typing import List async def query_agent(session: aiohttp.ClientSession, query: str, api_url: str) -> dict: """异步发送单个查询到Agent API""" payload = {"query": query} try: async with session.post(api_url, json=payload) as response: if response.status == 200: result = await response.json() return {"query": query, "success": True, "answer": result.get("answer")} else: return {"query": query, "success": False, "error": f"HTTP {response.status}"} except Exception as e: return {"query": query, "success": False, "error": str(e)} async def process_batch(queries: List[str], api_url: str = "http://localhost:8000/chat", concurrency: int = 5): """并发处理一批查询""" connector = aiohttp.TCPConnector(limit=concurrency) # 限制并发连接数 timeout = aiohttp.ClientTimeout(total=60) # 设置超时 async with aiohttp.ClientSession(connector=connector, timeout=timeout) as session: tasks = [query_agent(session, q, api_url) for q in queries] results = await asyncio.gather(*tasks, return_exceptions=False) return results if __name__ == "__main__": # 假设你的Agent服务已在运行 test_queries = [ "搜索手机", "笔记本有哪些?", "推荐一款耳机", "今天天气怎么样", # 这个可能超出工具范围 ] print("开始批量处理...") results = asyncio.run(process_batch(test_queries, concurrency=3)) for res in results: print(f"问题: {res['query']}") if res['success']: print(f" 回答: {res['answer']}") else: print(f" 失败: {res['error']}") print("-" * 30)

批量任务最佳实践

  1. 限流:通过concurrency参数控制并发数,避免压垮服务或触发 LLM API 的速率限制。
  2. 重试机制:为网络错误或暂时性失败添加重试逻辑。
  3. 结果持久化:将结果保存到文件或数据库,避免丢失。
  4. 进度监控:对于大量任务,添加进度条或日志。

7. 资源占用与性能观察

Langchain 框架本身是轻量级的,资源消耗主要来自集成的 LLM。

  • CPU/内存占用:运行 Langchain 脚本时,Python 进程本身占用内存通常为几百 MB。主要内存消耗在于加载的 LLM 模型。例如,运行一个 7B 参数的本地模型(通过 Ollama),可能需要 4-8GB 的 RAM/显存。
  • 显存占用(本地模型):如果你使用 GPU 运行本地模型(如通过transformers库或vLLM),显存占用取决于模型大小和精度。一个 7B 的 FP16 模型大约需要 14GB 显存,使用量化技术(如 GPTQ, AWQ)可大幅降低至 6GB 以下。
  • 网络延迟(云端 API):使用 OpenAI 等云端 API 时,延迟是主要性能因素。一次简单的工具调用(一问一答)通常在 1-3 秒。复杂 Agent 的多轮交互会累积延迟。
  • Agent 执行速度:影响速度的关键因素包括:
    1. LLM 响应速度:云端 API 的延迟或本地模型的推理速度。
    2. 工具执行时间:如果你的工具需要调用慢速的外部 API(如数据库查询、网络请求),这会成为瓶颈。
    3. 迭代次数:Agent 为完成任务所需的“思考-行动”循环次数。使用max_iterations防止无限循环。
  • 监控建议
    • 使用verbose=True在开发阶段观察每一步的耗时。
    • 对于生产 API,使用像prometheus-client这样的库来暴露指标(请求数、延迟、错误率)。
    • 在调用本地模型时,可以使用nvidia-smi(NVIDIA GPU) 或任务管理器来监控显存和 GPU 利用率。

8. 常见问题与排查方法

在开发 Langchain Agent 过程中,你会遇到一些典型问题。下表列出了常见现象和解决思路。

问题现象可能原因排查方式解决方案
ModuleNotFoundError: No module named 'langchain_xxx'缺少对应的 Langchain 集成包。检查错误信息中缺失的模块名。使用pip install langchain-xxx安装对应的包(如langchain-openai,langchain-ollama)。
openai.error.AuthenticationErrorOpenAI API Key 错误或未设置。检查.env文件中的OPENAI_API_KEY,或环境变量。1. 确认 Key 有效且未过期。
2. 确保.env文件被正确加载 (load_dotenv())。
3. 直接在代码中设置os.environ[‘OPENAI_API_KEY’]临时测试。
Agent 陷入循环,不断重复同一个工具调用1. 工具执行结果未能让 LLM 判断任务完成。
2.max_iterations设置过高。
查看verbose=True的输出,观察每次工具调用的输入输出。1. 优化工具的返回信息,使其更明确。
2. 在AgentExecutor中设置合理的max_iterations(如 5-10)。
3. 在系统提示词中明确告诉 Agent 何时停止。
本地模型 (Ollama) 不调用工具,直接胡言乱语小模型对工具调用的指令遵循能力弱。查看模型的原始输出(verbose模式),看它是否输出了正确的 JSON 格式。1. 换用更大或工具调用能力更强的模型(如llama3.1:8b)。
2. 简化提示词,使用更清晰的指令。
3. 使用few-shot示例在提示词中教导模型。
4. 尝试 Langchain 的JsonOutputToolsParser等专用输出解析器。
ConnectionError连接 Ollama 失败Ollama 服务未启动或地址端口不对。在终端运行ollama serve查看服务状态,或访问http://localhost:114341. 确保 Ollama 已安装并运行。
2. 检查ChatOllama初始化时的base_url参数是否正确(默认是http://localhost:11434)。
工具调用时参数提取错误LLM 未能从用户问题中正确解析出工具所需的参数。检查verbose输出中Action Input的内容。1. 在工具函数的docstring中更清晰地描述参数。
2. 使用StructuredToolPydantic来定义带有严格类型和描述的输入模型。
处理长文本或复杂任务时速度极慢1. 本地模型推理速度慢。
2. 上下文过长导致计算量增大。
3. 工具本身执行慢。
分析各环节耗时(LLM生成、工具执行、网络IO)。1. 对于本地模型,考虑使用量化版本或更高效的推理引擎(如vLLM)。
2. 优化提示词,减少不必要的上下文。
3. 对慢速工具进行异步调用或缓存。
‘Agent’ object has no attribute ‘invoke’Langchain 版本差异,旧版 API 与新版本不兼容。检查langchainlangchain-core的版本 (`pip listgrep langchain`)。

9. 最佳实践与使用建议

  1. 从简单开始,逐步复杂化:先让一个工具跑通,再增加第二个、第三个。先使用 GPT-3.5-turbo 等可靠的云端模型验证逻辑,再迁移到本地模型。
  2. 善用verbose=True:这是调试 Langchain Agent 最重要的开关。它能让你看到 LLM 的思考过程、工具的选择和调用参数,绝大多数问题都能从这里找到线索。
  3. 为工具编写清晰的文档字符串 (docstring):LLM 主要依靠工具的docstring来理解工具的用途和参数。描述务必准确、简洁。
  4. 管理好上下文长度:Agent 的每次交互都会将对话历史、工具结果等附加到上下文中。对于长对话,要使用ConversationBufferWindowMemory等记忆组件来限制历史长度,避免超出模型上下文窗口导致性能下降或错误。
  5. 实施严格的输入验证和工具权限控制:尤其是对于calculator中使用eval或能执行系统命令的工具,必须对输入进行清洗和校验,避免代码注入攻击。在生产环境中,考虑在沙箱环境中运行工具。
  6. 为生产环境设计容错和降级方案:LLM 可能输出非结构化内容导致解析失败,工具可能超时或返回错误。使用handle_parsing_errors=True,并为AgentExecutor设置max_iterationsmax_execution_time。准备一个默认回复或引导用户重新表述问题。
  7. 版本锁定:Langchain 生态变化迅速,在项目稳定后,在requirements.txt中锁定核心包的版本,例如langchain==0.1.0,以避免未来更新导致代码失效。

10. 总结与下一步

通过本教程,你已经完成了从零搭建一个具备工具调用能力的 Langchain Agent 的全过程。核心路径非常清晰:定义工具 -> 连接 LLM -> 组装 Agent -> 测试执行。无论是使用便捷的 OpenAI API,还是追求隐私可控的本地 Ollama 模型,这套流程都是通用的。

最值得尝试的下一步

  1. 集成真实工具:将模拟的get_weather替换为调用真实天气 API(如和风天气);将search_web替换为 SerperAPI 或 Tavily 的真实搜索。
  2. 探索不同类型的 Agent:Langchain 提供了ReAct,Plan-and-Execute,OpenAI Tools等多种 Agent 类型,适用于不同任务。尝试create_react_agent看看有何不同。
  3. 加入记忆 (Memory):让 Agent 记住之前的对话,实现多轮交互。集成ConversationBufferMemoryConversationSummaryMemory
  4. 构建 RAG 管道:结合向量数据库(如 Chroma, Pinecone),让 Agent 能够基于你提供的私有文档(公司知识库、个人笔记)进行问答。
  5. 前端交互:使用 Gradio 或 Streamlit 快速构建一个 Web 界面,将你的 Agent 变成可视化的聊天机器人。

最容易踩的坑

  • 版本兼容性:Langchain 版本更新可能导致 API 变化,务必查阅对应版本的官方文档。
  • 本地模型的不稳定性:小模型在复杂逻辑和格式遵循上可能表现不佳,需要更多的提示工程和调试。
  • 成本控制:使用云端 API 时,注意监控 Token 消耗,为AgentExecutor设置max_iterations也是控制成本的关键。

工具调用是让大模型从“聊天机器人”迈向“智能体”的关键一步。现在,你已经掌握了启动这项能力的基本工具和思路,可以开始构建真正能帮你处理实际任务的 AI 助手了。建议将本文中的代码作为起点,根据你的具体场景进行修改和扩展。

需要专业的网站建设服务?

联系我们获取免费的网站建设咨询和方案报价,让我们帮助您实现业务目标

立即咨询