跳转到主要内容

LangChain

03 · 配置

API Key、OpenAI 兼容服务、模型参数

  • LangChain
  • Python

本节速览

这一节的每一块内容,分别是干什么的:

内容是干什么的
dotenvAPI Key 放 .env 读入环境变量,不硬编码
OpenAI 兼容服务换 base_url 直连 DeepSeek / Kimi / GLM 等服务
常用模型参数temperature、max_tokens 等控制生成行为
多模型分工便宜模型做改写、强模型做生成的搭配策略
LangSmith 追踪网页上看每次调用的完整链路(可选)

配置分三块:API Key 的注入方式、模型服务的接入、模型参数的取舍。

API Key 与 dotenv

没有它会怎样——key 硬编码在源码里:换台机器要改代码;更糟的是提交进 git,公开仓库里扫 key 的爬虫几分钟就能盯上你,额度一夜刷光。

有了它——key 放 .env、代码从环境变量读,.gitignore 掉 .env,源码随便提交。

Key 不写进代码,放在项目根目录的 .env 文件。本课程统一用 GLM,需要这几个变量:

GLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4   # 智谱接口地址(自建/中转端点换成对应地址)
GLM_API_KEY=xxx.xxx.xxx                             # 服务方的 Key
GLM_MODEL_ID=glm-4-flash                            # 聊天模型名
EMBEDDING_ID=embedding-3                            # 向量模型名,第 11 章起用它

聊天模型读 GLM_MODEL_ID、向量模型读 EMBEDDING_ID,两者分开配,换模型只改 .env、不动代码。代码入口加载一次:

import os   # 读取环境变量

from dotenv import load_dotenv   # 从 .env 读环境变量

load_dotenv()

print(os.environ["GLM_API_KEY"])

要点:

  • load_dotenv() 必须在读取环境变量的代码之前执行,放在入口文件最前面最稳。
  • .env 加进 .gitignore,不要提交到 git 或任何公开渠道。
  • ChatOpenAI 和 OpenAIEmbeddings 不传 api_key 时,自动读取 OPENAI_API_KEY。用 GLM 等兼容服务时必须显式传 api_key 和 base_url——只配 OPENAI_API_KEY 会让请求发去 OpenAI 官方地址,用别家的 key 打官方端点必然 401。
  • 代码里用 os.environ["EMBEDDING_ID"] 这种下标读法:变量没配时立刻 KeyError 报出来,好过静默用空值继续跑(os.getenv 缺失时返回 None,坑更隐蔽)。

忘掉 load_dotenv()(或把它放在读取之后)时,报错长这样:

import os   # 读取环境变量

print(os.environ["OPENAI_API_KEY"])
# KeyError: 'OPENAI_API_KEY'

现象是「.env 里明明有 Key 却读不到」。修法只有一个:确认 load_dotenv() 在这一行之前执行过。

接入 OpenAI 兼容服务

没有它会怎样——直接用各家官方 SDK:DeepSeek 一套客户端、智谱一套客户端,参数名还不一样;想从 OpenAI 换 GLM,调用代码全部重写。

有了它——ChatOpenAI 换个 base_url 和 model 名就完成切换,业务代码一行不动。

DeepSeek、Kimi、GLM 等服务遵循 OpenAI 接口规范,换三个参数即可接入:

import os   # 读取环境变量

from langchain_openai import ChatOpenAI   # OpenAI 聊天模型

model = ChatOpenAI(
    base_url="https://api.deepseek.com/v1",   # 服务方的接口地址
    api_key=os.environ["DEEPSEEK_API_KEY"],   # 服务方的 Key
    model="deepseek-chat",                    # 服务方的模型名
)

接口地址、模型名、Key 都以服务方文档为准。Azure OpenAI 与官方直连的环境变量体系不同,两套变量不要混配。

以 GLM 为例,完整跑通一次对话:

import os   # 读取环境变量

from dotenv import load_dotenv   # 从 .env 读环境变量
from langchain_openai import ChatOpenAI   # OpenAI 聊天模型

load_dotenv()

model = ChatOpenAI(
    base_url="https://open.bigmodel.cn/api/paas/v4",   # 智谱的接口地址
    api_key=os.environ["GLM_API_KEY"],
    model="glm-4-flash",
)

print(model.invoke("用一句话介绍你自己").content)

示例输出:

我是智谱 AI 训练的通用大语言模型,可以回答问题、写作、分析文本。

最常见的错误是只换 Key 不换地址:用 GLM 的 Key 构造 ChatOpenAI(api_key=...) 却不传 base_url,请求发往 api.openai.com,程序会长时间卡在建立连接上,最后超时。三个参数(base_url、api_key、model)必须配套出现。

常用模型参数

没有它会怎样——全用默认值:temperature 偏高,事实类问答每次答案都不一样;「只翻译」的任务模型给你加戏注释;长输出撞上 max_tokens 被拦腰截断。

有了它——按任务调参:事实任务 temperature→0,创作任务调高,输出长度用 max_tokens 管住。

参数说明
api_key不传时自动读取 OPENAI_API_KEY
base_urlOpenAI 兼容服务的接口地址
model模型名,建议显式指定。模型名直接透传给 API,新模型上线后不用升级包
temperature采样温度,越高输出越随机。事实型任务(改写、提取、分类)调到 0~0.2,创作型可调高
max_retries请求失败自动重试次数,默认 2。只有网络错误、429 限流、5xx 会重试,401 等客户端错误不重试。设 0 关闭

逐项看例子。

model:不传会用包内默认模型,和你实际想用的可能不是同一个,始终显式指定:

import os   # 读取环境变量

from dotenv import load_dotenv   # 从 .env 读环境变量
from langchain_openai import ChatOpenAI   # OpenAI 聊天模型

load_dotenv()

# 不传 model:用 langchain-openai 的默认模型,你未必知道它是哪个
ChatOpenAI(
    base_url=os.environ["GLM_BASE_URL"],
    api_key=os.environ["GLM_API_KEY"],
).invoke("hi")

# 显式传 model:用哪个模型一目了然
ChatOpenAI(
    base_url=os.environ["GLM_BASE_URL"],
    api_key=os.environ["GLM_API_KEY"],
    model="glm-4-flash",
).invoke("hi")

temperature:同一问题问三次,对比两个极端。创作型任务(起名、文案)调高后每次不同:

import os   # 读取环境变量

from dotenv import load_dotenv   # 从 .env 读环境变量
from langchain_openai import ChatOpenAI   # OpenAI 聊天模型

load_dotenv()

creative = ChatOpenAI(
    base_url=os.environ["GLM_BASE_URL"],
    api_key=os.environ["GLM_API_KEY"],
    model=os.environ["GLM_MODEL_ID"],
    temperature=1.2,   # 创作型任务调高,同一问题每次输出都不同
)

for _ in range(3):
    print(creative.invoke("给咖啡店起一个两个字的名字").content)

示例输出(三次各不相同):

慢煮
拾光
山雾

分类、提取、改写这类要稳定的任务反过来,调到 0~0.2,同样的问题答案基本一致。

max_retries:网络抖动、限流时自动重试,默认 2 次。调试时想立刻看到错误,设 0 关闭:

from langchain_openai import ChatOpenAI   # OpenAI 聊天模型
import os   # 读取环境变量
from dotenv import load_dotenv   # 从 .env 读环境变量

load_dotenv()

model = ChatOpenAI(
    base_url=os.environ["GLM_BASE_URL"],
    api_key=os.environ["GLM_API_KEY"],
    model=os.environ["GLM_MODEL_ID"],
)

model.invoke("hi")   # 网络一抖动立刻抛 APIConnectionError,不再等待重试

注意 401(Key 无效)这类客户端错误本来就不会重试:重试没有意义,换 Key 才有用。

多模型分工

没有它会怎样——所有环节都用最强模型:改写问题这种不需要聪明的活也上顶配,账单和延迟全是顶配价格。

有了它——便宜模型干杂活、强模型干主活,成本直接降一个量级。

一个应用里可以混用多个模型,按任务难度分配:

  • 主链用高配模型,负责最终回答;
  • 摘要、问题改写、格式修复交给便宜模型。这些任务对模型能力要求低。

一次调用里两个模型各干各的活:

import os   # 读取环境变量
from dotenv import load_dotenv   # 从 .env 读环境变量
from langchain_openai import ChatOpenAI   # OpenAI 聊天模型

load_dotenv()

main_model = ChatOpenAI(
    base_url=os.environ["GLM_BASE_URL"],
    api_key=os.environ["GLM_API_KEY"],
    model="glm-4-plus",   # 高配:负责最终回答
)

cheap_model = ChatOpenAI(
    base_url=os.environ["GLM_BASE_URL"],
    api_key=os.environ["GLM_API_KEY"],
    model="glm-4-flash",  # 便宜:负责压缩原文
)

summary = cheap_model.invoke("把下面这段会议记录压缩成三句话:\n……")
answer = main_model.invoke(f"基于这份纪要回答问题:\n{summary.content}\n\n问题:下一步谁跟进部署?")
print(answer.content)

实际用法见记忆系统的 SummarizationMiddleware 和输出解析器的 OutputFixingParser。

LangSmith 追踪(可选)

没有它会怎样——链上 5 个组件,结果不对,你不知道是 prompt、检索还是模型的锅,只能挨个 print 重跑。

有了它——每次调用的每一步输入输出都在网页上,点开就能定位是哪一环出了错。

chain 超过三步,调试就变难:报错不知道挂在哪个环节;agent 跑完只看到最终答案,中间调了几次工具、每次传了什么参数全是黑盒;token 花在哪里也没有数。LangSmith 是 LangChain 官方的调用追踪平台,解决这三件事:

  • 每次调用自动生成一棵 trace 树:chain 的每一步、agent 的每一轮,输入输出全记录;
  • 出错的环节在树上直接标红,定位问题不用二分注释代码;
  • token 用量和耗时按调用汇总,优化成本有数据支撑。

开启只要两行环境变量,代码一行不改。先到 smith.langchain.com 注册账号,在左下角 Settings → API Keys 页面点 Create API Key 生成一个,写进 .env:

LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=xxx
# LANGCHAIN_PROJECT=my-rag-demo   # 可选:项目名,不写归到 default

load_dotenv() 之后,任何已有代码照常跑,每次 invoke 自动上报:

from langchain_openai import ChatOpenAI   # OpenAI 聊天模型
import os   # 读取环境变量
from dotenv import load_dotenv   # 从 .env 读环境变量
from langchain_core.output_parsers import StrOutputParser   # 提取纯文本
from langchain_core.prompts import ChatPromptTemplate   # 带角色的消息模板

llm = ChatOpenAI(
    base_url=os.environ["GLM_BASE_URL"],
    api_key=os.environ["GLM_API_KEY"],
    model=os.environ["GLM_MODEL_ID"],
)

load_dotenv()   # 从这一行起,下面的调用都会上报

chain = ChatPromptTemplate.from_messages([
    {"role": "human", "content": "{question}"},
]).pipe(llm).pipe(StrOutputParser())

chain.invoke({"question": "装饰器是什么"})

查看结果:浏览器打开 smith.langchain.com 并登录,左侧栏进 Projects,点进你的项目(没设 LANGCHAIN_PROJECT 就叫 default),在 Traces 列表里点最新一条,展开就是这次调用的 trace 树:

RunnableSequence                          总耗时 1.9s,tokens 418
├─ ChatPromptTemplate   {question: …} → 1 条 human 消息
├─ ChatOpenAI           消息 → AIMessage,1.8s,418 tokens
└─ StrOutputParser      AIMessage → 纯文本

点开任意节点,能看到该步骤完整的输入和输出原文。排查 agent 的多轮工具调用(第 16 节)时,逐轮展开比命令行重定向日志高效得多。本地快速排查用 set_debug(True),三档观测手段的对比见第 05 节。

平台有免费额度,超出按用量计费,以官网为准。


上一节:环境与安装 · 下一节:Models 与 Messages