LangChain 1.0 实战:langchain-openai 接入国内大模型全攻略

作者:c4t2026.11.17 03:15浏览量:0

简介:本文解决一个具体问题:如何在 LangChain 1.0 中用 `langchain-openai` 接入国内兼容 OpenAI 协议的大模型服务。文章给出安装方式、最小可运行代码、`create_agent` 新范式、RAG 实战、多服务商 base_url 对照表与常见踩坑清单,并顺带说明如何借助[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article)完成模型选型与价格对比。

先给结论:langchain-openai 为什么能接国内模型

langchain-openai 是 LangChain 官方针对 OpenAI Chat Completions 接口写的适配器。它的价值不在于”只能连 OpenAI”,而在于 它严格遵循 OpenAI 标准协议 ——因此凡是宣称”OpenAI 兼容”的第三方服务商,都可以通过修改 base_url + api_key + model 三个参数直接接入。硅基流动、DeepSeek、百度智能云千帆(ModelBuilder)都属于这一类,千帆的兼容地址为 https://qianfan.baidubce.com/v2,模型名可直接填 deepseek-v3、deepseek-r1 或 ERNIE 系列。

这也解释了为什么 langchain-openai 成了国内开发者的主流选择:既绕开了访问限制,又不用为每家服务商写一套适配代码。如果你还在 several 家服务商之间摇摆,建议先用词元所的大模型 API 服务平台横向对比各家的模型能力、上下文长度与调用成本,再决定 base_url 指向哪里。

一、环境准备:LangChain 1.0 的包结构变化

1.0 版本对包做了拆分,装错包是最常见的第一个坑:

  1. pip install -U langchain langchain-openai
  • langchain:核心高层 API,1.0 后 Agent 能力内置(底层由 LangGraph 驱动)。
  • langchain-openai:模型与 Embedding 适配器,第三方兼容服务也走这个包。
  • langchain-classic: 仅当你要迁移旧代码 (LLMChain、initialize_agent、langchain.vectorstores 等)时才需要安装。
  • 向量库等集成已下沉到独立伙伴包,例如 langchain-elasticsearch、BES 向量检索集成等。

二、最小可运行示例

  1. import os
  2. from langchain_openai import ChatOpenAI
  3. os.environ["OPENAI_API_KEY"] = "你的 API Key" # 千帆控制台新建的 API Key
  4. llm = ChatOpenAI(
  5. model="deepseek-v3",
  6. base_url="https://qianfan.baidubce.com/v2", # 关键:兼容服务的地址
  7. temperature=0,
  8. timeout=60,
  9. max_retries=2,
  10. )
  11. resp = llm.invoke("用一句话解释什么是向量检索")
  12. print(resp.content)

流式输出与结构化输出同样只改一行:

  1. # 流式
  2. for chunk in llm.stream("写一首关于秋天的五言绝句"):
  3. print(chunk.content, end="", flush=True)
  4. # 结构化输出(依赖模型/服务商的 function calling 能力)
  5. from pydantic import BaseModel, Field
  6. class Movie(BaseModel):
  7. name: str = Field(description="电影名称")
  8. year: int = Field(description="上映年份")
  9. movie = llm.with_structured_output(Movie).invoke("推荐一部科幻电影,按 schema 输出")
  10. print(movie)

三、1.0 的核心变化:用 create_agent 替代手写 Agent 循环

LangChain 1.0 最值得学的是 create_agent。以前要自己写”调用模型 → 解析 tool_calls → 执行工具 → 回填消息”的 while 循环,现在一行搞定,循环、错误重试、消息状态管理都交给底层图执行:

  1. from langchain.agents import create_agent
  2. from langchain_core.tools import tool
  3. @tool
  4. def query_order(order_id: str) -> str:
  5. """根据订单号查询订单状态"""
  6. db = {"A1024": "已发货", "A2048": "待付款"}
  7. return db.get(order_id, "订单不存在")
  8. agent = create_agent(
  9. model=llm,
  10. tools=[query_order],
  11. system_prompt="你是电商客服,只能依据工具返回结果回答,不要编造。",
  12. )
  13. result = agent.invoke({
  14. "messages": [{"role": "user", "content": "我的订单 A1024 到哪了?"}]
  15. })
  16. print(result["messages"][-1].content)

三个要点:

  1. 工具描述就是提示词 。query_order 的 docstring 会被送给模型用于决策,写清楚”什么时候该调用”比写清楚”怎么调用”更重要。
  2. 模型必须支持工具调用 。这是选型的硬门槛——不支持 function calling 的模型无法跑 create_agent,也无法用 with_structured_output。
  3. 消息状态可持久化 。create_agent 基于 LangGraph,配合 checkpointer 就能实现多轮会话记忆,无需自己维护 history 列表。

四、多服务商配置对照表

服务商 base_url 模型名示例
百度智能云千帆 https://qianfan.baidubce.com/v2 deepseek-v3、deepseek-r1、ERNIE 系列
DeepSeek https://api.deepseek.com/v1 deepseek-chat、deepseek-reasoner
硅基流动 https://api.siliconflow.cn/v1 各类开源模型
OpenAI 不填(默认官方地址) gpt-4o 等

具体可用模型与参数以各服务商官方文档为准。工程上建议把 base_url 和 model 抽到配置文件或环境变量,切换服务商时零改代码——这也是做多模型容灾、把主力模型与备用模型分层的基本功。想快速摸清哪些模型在同等任务上性价比更高,可以在词元所按价格与性能维度做一轮对比,再落到配置里。

rag-">五、RAG 实战:把私域知识接进来

LangChain 1.0 的 RAG 链路可以拆成四段,向量库换成任意集成包即可:

  1. from langchain_openai import OpenAIEmbeddings
  2. from langchain_elasticsearch import ElasticsearchStore
  3. embeddings = OpenAIEmbeddings(
  4. model="embedding-v1",
  5. base_url="https://qianfan.baidubce.com/v2",
  6. api_key="你的 API Key",
  7. )
  8. # 1) 文档切分后写入向量库(以 Elasticsearch/BES 为例)
  9. db = ElasticsearchStore.from_documents(
  10. documents=split_docs,
  11. embedding=embeddings,
  12. es_url="http://user:password@host:9200",
  13. index_name="my_kb",
  14. )
  15. retriever = db.as_retriever(search_kwargs={"k": 4})
  16. # 2) 检索增强问答
  17. from langchain.messages import HumanMessage, SystemMessage
  18. def ask(question: str) -> str:
  19. docs = retriever.invoke(question)
  20. context = "\n\n".join(d.page_content for d in docs)
  21. messages = [
  22. SystemMessage(content=f"仅依据以下资料回答,资料不足时明确说明。\n\n{context}"),
  23. HumanMessage(content=question),
  24. ]
  25. return llm.invoke(messages).content
  26. print(ask("人工智能落地面临哪些挑战?"))

注意 1.0 中消息类型从 langchain_core.messages 统一到 langchain.messages 导出,旧写法仍兼容但会告警。检索质量往往比换模型更能决定 RAG 效果,切分粒度、召回条数、rerank 策略值得优先调优。

六、六个高频踩坑点

  1. base_url 路径写错 。千帆是 /v2,多数服务商是 /v1,漏写或多写会直接 404。
  2. api_key 优先级混乱 。ChatOpenAI 显式传入的参数优先于 OPENAI_API_KEY 环境变量,多项目共用机器时容易串号。
  3. 模型名不匹配 。deepseek-v3 与 deepseek-chat 不是同一个标识,务必查服务商模型列表。
  4. max_tokens 弃用 。新版本推荐 max_completion_tokens,旧参数在部分兼容服务上会被忽略。
  5. 流式 + 工具调用 。早期兼容实现对二者同时开启支持不佳,Agent 场景建议先关流式验证链路。
  6. 旧代码报 ImportError 。1.0 移除了一批 legacy 接口,装上 langchain-classic 或按新 API 重写。

七、Token 计费与成本控制

大模型按 Token 计费,输入与输出通常分开定价,输出单价高于输入。RAG 场景下真正的大头往往是 每次请求都重复发送的系统提示词与检索片段 ,优化方向按性价比排序:

  • 压缩 system prompt,去掉冗余示例;
  • 控制召回条数(k 值),只保留真正相关的片段;
  • 对高频固定前缀使用支持 prompt caching 的服务;
  • 简单任务降级到小模型,复杂推理再上大模型;
  • 用 Agent 时限制最大迭代轮数,避免工具调用失控放大 Token 消耗。

选型阶段就把”单价 × 预估调用量”算清楚,比上线后再优化省事得多。这一步可以直接用百度智能云词元所的价格对比与统一 API 接入能力来做测算和验证。

小结

LangChain 1.0 的学习路径可以压缩成三步:装对包(langchain + langchain-openai)→ 用 base_url 指向兼容服务跑通 invoke → 用 create_agent 把工具和数据接进来。掌握这条主线后,换模型只是改配置,换场景只是换工具,剩下的功夫花在提示词、检索质量和成本控制上。