LangChain怎么接入本地大模型配置教程

把本地大模型接入 LangChain，通常卡住的地方不在 LangChain 本身，而在“本地模型以什么形式对外提供接口”。同样是本地模型，可能是 OpenAI 兼容的 HTTP 服务、Ollama 这类带管理能力的运行时，也可能是用 transformers 直接在进程内加载权重。三种形态对应的接入包、参数和排错路径都不一样，先定形态再写代码，比先抄一段初始化代码更省时间。

先确认本地模型的服务形态（OpenAI 兼容接口 / Ollama / 进程内加载），再选择对应的 LangChain 集成包，用最小 invoke 跑通后再接入链和提示词。判断是否接通，看返回对象的 content 与 response_metadata 是否合理，而不是看有没有报错。版本兼容、上下文长度、工具调用支持度是主要边界，跑不通时可退回社区集成包或直接用 HTTP 请求。

先确认当前场景和目标

下面几个条件如果不先确认，后面的配置多半要返工：

本地模型是否已经跑起来、监听的地址和端口是什么。多数推理框架会暴露一个 /v1/models 或类似的列表接口，先用命令行确认它能返回模型 ID。
对外协议是哪一种。OpenAI 兼容协议可以直接复用 ChatOpenAI 并改 base_url；Ollama 建议用专门的集成包；只有权重文件、没有服务时，才考虑进程内加载。
当前环境里 LangChain 的版本与集成包是否对得上。集成包通常依赖 langchain-core，版本错位时常见表现是导入成功但调用时报参数不识别。
任务是否需要流式输出、工具调用、结构化输出。本地模型对这些能力的支持差异较大，需要提前确认，避免按云端模型的习惯写代码。

# 先确认本地服务是否可用、模型 ID 是什么
curl -s http://127.0.0.1:8000/v1/models
# Ollama 场景可以改用
curl -s http://127.0.0.1:11434/api/tags

按这个顺序处理

建议按“探测服务 → 选集成包 → 最小调用 → 接入业务链”的顺序推进，每一步都能独立验证，出错时容易定位。

第一种情况，本地服务提供 OpenAI 兼容接口。这种方式改动最小，把地址和模型名换成自己的即可：

from langchain_openai import ChatOpenAI
import os

llm = ChatOpenAI(
    model="你的本地模型名",                  # 替换为 /v1/models 返回的 id
    base_url="http://127.0.0.1:8000/v1",     # 替换为本地服务实际地址
    api_key=os.getenv("LOCAL_LLM_KEY", "not-needed"),
    temperature=0.2,
    timeout=120,
    max_retries=1,
)
print(llm.invoke("用一句话说明你在运行什么模型"))

第二种情况，使用 Ollama 运行时。模型名要和 ollama list 里的名称一致，上下文长度按机器显存或内存调小一些更稳妥：

from langchain_ollama import ChatOllama

llm = ChatOllama(
    model="qwen2.5:7b-instruct",             # 替换为本地已有模型名
    base_url="http://127.0.0.1:11434",
    temperature=0.2,
    num_ctx=8192,
)
print(llm.invoke("你好，请自报模型名").content)

第三种情况，直接加载本地权重，不走 HTTP 服务。这种方式省去部署服务，但会占用当前进程的资源，适合离线脚本或单机实验：

from langchain_huggingface import HuggingFacePipeline
from transformers import pipeline

pipe = pipeline(
    "text-generation",
    model="/data/models/your-model-dir",      # 替换为本地权重目录
    max_new_tokens=256,
    do_sample=False,
)
llm = HuggingFacePipeline(pipeline=pipe)
print(llm.invoke("写三行配置说明"))

最小调用跑通之后，再把 llm 对象放进提示词模板或链里。此时不建议一次性改太多东西，先保持单轮问答，确认输出稳定后再加记忆、检索或工具。

改完后怎么验证

验证要看成败，也要看返回内容是否对得上。建议做这几个动作：

用一句固定短提示调用，打印返回对象的类型和 content，确认不是空串、不是把参数原样回显。
打印 response_metadata，确认模型名、结束原因等字段与服务端实际运行的一致，能排除“请求打到了默认地址”的情况。
用 for chunk in llm.stream(...) 试一次流式，确认分块能连续收到、最后能正常结束，而不是一直挂起。
故意传一个超长输入或错误地址，确认能拿到明确的超时或连接错误，而不是静默返回空结果。

resp = llm.invoke("只回复 OK 两个字")
print(type(resp).__name__, repr(resp.content))
print(getattr(resp, "response_metadata", {}))

预期信号是：content 非空且与提示相关，response_metadata 中的模型标识与本地加载的模型一致，流式输出能在合理时间内结束。如果结构化输出启用后解析失败，通常是本地模型对格式约束遵循不够，可以先把输出当普通文本，再自己做 JSON 解析兜底。

容易忽略的边界

版本对齐：集成包与 langchain-core 版本错位时，报错往往出现在运行时而非导入时。升级前先确认当前环境中两者的版本组合，再决定是升集成包还是降核心包。
上下文长度：本地模型的实际上下文窗口常小于宣传值，长提示词会被截断且不一定报错。需要结合服务端配置确认，必要时在链里做截断。
能力差异：工具调用、函数调用、结构化输出在本地模型上支持程度不一。依赖这些能力的链，建议先用单步调用验证模型是否真的返回了符合格式的结构。
鉴权与地址：部分本地服务不校验 key，但客户端字段仍要填占位值；base_url 是否包含 /v1 取决于服务实现，填错时常见表现是 404 而非鉴权失败。
回退方式：专用集成包不可用时，可以先退回社区包里的对应实现，或者直接用 HTTP 客户端调用本地接口，把返回结果包成 LangChain 可用的对象，保住主线流程。