Gate.AI LangChain 与 LangGraph 集成指南

Gate.AI 提供了兼容 OpenAI 的 API 端点，开发者可通过该端点结合 LangChain 和 LangGraph，实现通过 Gate.AI 路由的模型调用。当 Python 应用需要基于链的提示、基于图的智能体工作流，或希望构建一个无需为每个模型服务商重写应用逻辑的统一模型网关时，这一方案尤为重要。本文将介绍本地环境搭建、LangChain 测试调用、LangChain 提示链以及一个简单的 LangGraph 工作流。内容不涵盖生产部署、向量数据库、可观测性、计费配置或企业访问策略。

前置条件

• 已通过 Gate.AI 账户创建 Gate.AI API 密钥
• Python 3.10 或更高版本，并具备安装依赖包权限

内容来源：Gate.AI 官方文档及产品资料，时间截至 2026年6月。

完成本指南后，你将获得哪些能力？

你将能够通过 ChatOpenAI 将 Gate.AI 接入 LangChain，并在 LangGraph 工作流中复用相同的模型配置。

本方案可帮助你：

• 在本地 Python 脚本中调用 Gate.AI
• 测试 Gate.AI 路由的 model="auto" 配置
• 需要时将 auto 替换为已验证的 Gate.AI 模型 ID
• 运行 LangChain 提示链
• 执行两步 LangGraph 工作流

如需了解更广泛的 API 集成背景，请参见 Gate.AI 开发者 API 集成。

步骤 1：安装 Python 依赖包

本步骤将安装本地工作流所需的 LangChain OpenAI 集成与 LangGraph 包。

• 创建并激活虚拟环境：

  python -m venv .venv
  source .venv/bin/activate
  pip install -U langchain langchain-openai langgraph

• Windows PowerShell 环境下激活命令：

  .venv\Scripts\Activate.ps1

安装完成后，应可正常导入 langchain_openai 和 langgraph。

步骤 2：存储 Gate.AI API 密钥

本步骤将 Gate.AI API 密钥保存在源码之外。

• 在 bash 环境中设置环境变量：

  export GATEAI_API_KEY="YOUR_API_KEY"

• Windows PowerShell 环境下设置：

  setx GATEAI_API_KEY "YOUR_API_KEY"

使用 setx 后需重启 PowerShell 会话。

请勿将真实 API 密钥提交至 Git。团队项目建议使用 密钥管理器、CI 密钥配置或经批准的内部环境变量流程。

步骤 3：在 LangChain 中配置 Gate.AI

本步骤将在 LangChain 中创建一个聊天模型，使其向 Gate.AI 发送兼容 OpenAI 协议的请求。

• 根据 2026年6月的 Gate.AI 文档，OpenAI 兼容的 Base URL 为：

  https://api.gate.ai/openai/v1

• 在 LangChain 中，将该地址作为 base_url。无需在 base_url 后添加 /chat/completions，LangChain 会自动处理路径。

• 示例：

  import os
  from langchain_openai import ChatOpenAI
  llm = ChatOpenAI(
      model="auto",
      api_key=os.environ["GATEAI_API_KEY"],
      base_url="https://api.gate.ai/openai/v1",
      temperature=0,
  )
  response = llm.invoke("Write one sentence explaining what an AI model router does.")
  print(response.content)

预期输出：

AI 模型路由器会根据任务、路由规则或配置，将请求分发至合适的模型。

实际返回内容可能有所不同，因为 Gate.AI 路由会根据所选模型动态响应。

步骤 4：构建 LangChain 提示链

本步骤将可复用的提示、Gate.AI 支持的模型以及字符串输出解析器连接起来。

• 示例：

  import os
  from langchain_openai import ChatOpenAI
  from langchain_core.prompts import ChatPromptTemplate
  from langchain_core.output_parsers import StrOutputParser
  llm = ChatOpenAI(
      model="auto",
      api_key=os.environ["GATEAI_API_KEY"],
      base_url="https://api.gate.ai/openai/v1",
      temperature=0,
  )
  prompt = ChatPromptTemplate.from_messages(
      [
          ("system", "You are a concise technical assistant."),
          ("human", "Explain {topic} in three bullet points."),
      ]
  )
  chain = prompt | llm | StrOutputParser()
  result = chain.invoke({"topic": "Gate.AI API routing"})
  print(result)

你将看到三条要点的简明解释。如果脚本在返回文本前报错，请先检查 API 密钥、Base URL 和模型配置，而非直接修改链结构。

步骤 5：在 LangGraph 中配置 Gate.AI

本步骤将在 LangGraph 状态工作流中复用相同的 Gate.AI 模型配置。

下例通过一个节点生成简短说明，另一个节点进行审核，保持流程简洁，便于在添加工具、记忆、检索或条件路由前验证基本功能。

• 示例：

  ```python
  import os
  from typing_extensions import TypedDict
  from langchain_openai import ChatOpenAI
  from langgraph.graph import StateGraph, START, END

  llm = ChatOpenAI(

  model="auto",
  api_key=os.environ["GATEAI_API_KEY"],
  base_url="https://api.gate.ai/openai/v1",
  temperature=0,

  )

  class WorkflowState(TypedDict):

  topic: str
  draft: str
  review: str

  def draft_node(state: WorkflowState) -> dict:

  response = llm.invoke(
      [
          ("system", "You write short technical explanations."),
          ("human", f"Write a two-sentence explanation of {state['topic']}."),
      ]
  )
  return {"draft": response.content}

  def review_node(state: WorkflowState) -> dict:

  response = llm.invoke(
      [
          ("system", "You review technical writing for clarity."),
          ("human", f"Review this draft and suggest one improvement:

{state[‘draft’]}”),
]
)
return {“review”: response.content}

builder = StateGraph(WorkflowState)
builder.add_node(“draft”, draft_node)
builder.add_node(“review”, review_node)

builder.add_edge(START, “draft”)
builder.add_edge(“draft”, “review”)
builder.add_edge(“review”, END)

app = builder.compile()

result = app.invoke({“topic”: “Gate.AI with LangGraph”})

print(“Draft:
“, result[“draft”])
print(“
Review:
“, result[“review”])

你将看到生成的草稿和审核意见。如果工作流只返回草稿，请确认 `draft` 到 `review` 的边已正确设置。
## 步骤 6：将自动路由替换为指定模型
如需固定模型行为，使集成更可控，可按如下方式操作：
- 若已启用 Gate.AI 自动路由且账户支持，初次测试可用 `model="auto"`
- 需要结果可复现、评测一致性、延迟测试或生产审核时，请使用具体的 Gate.AI 模型 ID
- 示例：
  ```python
  llm = ChatOpenAI(
      model="YOUR_MODEL_ID",
      api_key=os.environ["GATEAI_API_KEY"],
      base_url="https://api.gate.ai/openai/v1",
      temperature=0,
  )

模型 ID 请从 Gate.AI 模型目录或 Gate.AI 控制台获取。请勿凭空猜测模型 ID，因为可用性受账户、产品状态及模型服务商规则影响（截至 2026年6月）。

哪些配置项最为关键？

如需保持路由行为一致，建议在 LangChain 与 LangGraph 中共用同一个 llm 对象。仅在从路由测试切换到固定模型测试时修改 model 参数。

Gate.AI LangChain 与 LangGraph 集成常见故障排查

现象： 请求返回 401、invalid_api_key 或认证错误

• 原因： Gate.AI API 密钥缺失、过期、拼写错误或当前 shell 无法读取
• 解决： 在同一终端运行 echo $GATEAI_API_KEY，确认密钥有效且已在 Gate.AI 配置，若在其他会话设置变量请重启终端

现象： 请求返回 404、连接失败或找不到端点

• 原因： Base URL 配置错误。正确的 OpenAI 兼容 Base URL 为 https://api.gate.ai/openai/v1
• 解决： 确保每个 ChatOpenAI 实例的 base_url 设置为 https://api.gate.ai/openai/v1

现象： Python 返回 ModuleNotFoundError

• 原因： 当前虚拟环境未安装 langchain-openai 或 langgraph
• 解决： 激活虚拟环境后运行 pip install -U langchain langchain-openai langgraph

现象： 认证成功但模型请求失败

• 原因： 所选模型不可用、拼写错误或不支持当前请求
• 解决： 先用 model="auto" 测试。若需固定模型，请从 Gate.AI 复制有效模型 ID

现象： LangGraph 工作流返回状态不完整

• 原因： 某节点未返回预期状态键，或图结构缺少边
• 解决： 确认每个节点返回包含正确键的字典，并确保 图结构 包含 START、各节点边和 END

下一步可配置或构建哪些内容？

• 通过 Gate.AI 开发者 API 集成，将本地工作流接入更广泛的 Gate.AI API 体系
• 若需在 AI 编程编辑器中集成 Gate.AI，可参考 Gate.AI Cursor 集成指南
• 若开发流程涉及 Claude Code 及兼容 Anthropic 的配置，可参考 Gate.AI Claude Code 集成指南

常见问题解答

LangChain 和 LangGraph 可以共用同一份 Gate.AI 配置吗？
可以。只需创建一个包含 Gate.AI API 密钥、Base URL 及所选模型的 ChatOpenAI 对象，在 LangChain 链或 LangGraph 节点函数中复用即可。

应选择 auto 还是指定模型 ID？
若已开启 Gate.AI 自动路由，初次测试建议用 auto。如需结果可复现、评测可控或生产审核，请使用具体 Gate.AI 模型 ID。

Base URL 为什么要包含 /openai/v1？
Gate.AI 使用 https://api.gate.ai/openai/v1 作为兼容 OpenAI 的请求路径。LangChain 的 ChatOpenAI 应指向该 Base URL，而非更短的 /v1 路径。

本集成是否需要修改 LangGraph 本身？
不需要。LangGraph 仅在节点函数内调用模型对象，Gate.AI 相关配置全部在 ChatOpenAI 设置中完成。