LangChain+Llama.cpp 本地模型与Agent工具调用

本地大模型开发已经变得十分便捷，llama.cpp 作为轻量高效的 GGUF 模型推理引擎，可以在普通 PC 上运行 Qwen、Llama 系列量化模型。LangChain 作为大模型应用编排框架，除了对接云端 OpenAI，还能对接 llama‑server 的 OpenAI 兼容接口，不仅可以实现基础对话，还能开发具备工具调用能力的 Agent 智能代理。本文将依次演示LangChain框架的安装、基础对话调用、自定义工具 Agent 开发等功能实现。

1、承接《Windows 环境下 llama.cpp 编译运行指南》部分内容，通过命令工具llama‑server启动服务，端口监听127.0.0.1:11433，并加载 qwen2.5‑1.5b‑instruct‑q4_k_m.gguf 模型，确保本地服务已经启动。

C:> llama-server.exe -m qwen2.5-1.5b-instruct-q4_k_m.gguf --host 127.0.0.1 --port 11433 -c 4096
C:> 
init: llama threadpool init, n_threads = 12
load_model: initializing, n_slots = 4, n_ctx_slot = 4096, kv_unified = 'true'
llama_server: model loaded
llama_server: listening on http://127.0.0.1:11433

2、使用清华PyPI镜像加速安装langchain、langchain‑openai。langchain‑openai不只是调用 OpenAI 官方接口，也可以对接任意兼容 OpenAI 协议的本地推理服务，包括 llama‑server、vLLM 等。

C:> pip install -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple langchain langchain_openai
C:> 
C:> pip list
-------------------- -----------
Package              Version
-------------------- -----------
langchain            1.3.15
langchain-core       1.5.5
langchain-openai     1.5.1
langchain-protocol   0.0.18
langgraph            1.2.11
langgraph-checkpoint 4.2.0
langgraph-prebuilt   1.1.0
langgraph-sdk        0.4.2
langsmith            0.11.0

3、通过LangChain调用本地llama.cpp实现简单的对话功能，使用ChatOpenAI类，修改base_url指向本地 llama‑server 的/v1地址；本地服务不需要真实密钥，api_key随便填一个字符串例如dummy；model参数填写 llama‑server 正在加载的 GGUF 模型文件名。

完整基础对话代码：

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, SystemMessage

if __name__ == "__main__":
    llm = ChatOpenAI(
        model="qwen2.5-1.5b-instruct-q4_k_m.gguf",
        base_url="http://127.0.0.1:11433/v1",
        api_key="dummy",
        temperature=0.7,
        max_tokens=512,
    )

    resp = llm.invoke([
        SystemMessage(content="你是简短回答助手，你的名字是小张"),
        HumanMessage(content="你好，请简单介绍一下自己？")
    ])

    print(resp.content)

4、构建具备工具调用能力的Agent代理，使用代理调用功能，大模型可以根据用户问题，自主判断是否调用外部工具函数，获取外部信息，再整理答案返回用户。

示例实现两个自定义工具：

• get_weather(city) 模拟查询城市天气
• get_current_time() 获取系统当前时间

通过@tool装饰器封装普通 Python 函数为 LangChain 工具；create_agent创建代理，wrap_tool_call中间件捕获工具执行异常，统一错误处理。

完整 Agent 代码：

import os,sys,time,datetime
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from langchain.agents import create_agent
from langchain.agents.middleware import wrap_tool_call

# 定义系统提示
SYSTEM_PROMPT = '''
    你是一个助手，请简洁准确。

    你可以使用两个工具：
    - get_weather：获取给定城市的天气
    - get_current_time：获取当前系统中的日期与时间
'''

basic_model = ChatOpenAI(
    model="qwen2.5-1.5b-instruct-q4_k_m.gguf",
    base_url="http://127.0.0.1:11433/v1",
    api_key="dummy",
    temperature=0.1,
    max_tokens=512,
)

@tool
def get_weather(city: str) -> str:
    """
    获取给定城市的天气
    Args:
        city: 需要查询天气的城市名称，例如：泰安、济南
    """
    return f"城市 {city} 空气良好!"

@tool
def get_current_time():
    '''
    获取当前系统中的日期与时间
    '''
    return datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")

# 错误提示信息
@wrap_tool_call
def handle_tool_errors(request, handler):
    """使用自定义消息处理工具执行错误。"""
    try:
        return handler(request)
    except Exception as e:
        return ToolMessage(
            content=f"工具错误：请检查您的输入并重试。({str(e)})",
            tool_call_id=request.tool_call["id"]
        )

if __name__ == "__main__":
    agent = create_agent(
        basic_model,
        tools=[get_weather,get_current_time],
        middleware=[handle_tool_errors],
        system_prompt=SYSTEM_PROMPT
        )

    result = agent.invoke(
        {"messages": [("user", "查询当前日期与时间?")]}
    )

    for msg in result["messages"]:
        print(f"{msg.type}: {msg.content}")

利用 llama‑server 提供 OpenAI 兼容接口，几乎不用修改 LangChain 业务代码，仅更换base_url就可以无缝切换本地 GGUF 大模型。从普通对话到具备工具调用的 Agent，整套流程完全本地化，无需调用云端 API，非常适合私有化 AI 原型开发及验证。