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 套件。

• 建立並激活虛擬環境：

  bash python -m venv .venv source .venv/bin/activate

  pip install -U langchain langchain-openai langgraph

• Windows PowerShell 環境下激活命令：

  powershell .venv\Scripts\Activate.ps1

安裝完成後，應可正常導入 langchain_openai 和 langgraph。

步驟 2：存放 Gate.AI API 密鑰

本步驟將 Gate.AI API 密鑰儲存在原始碼之外。

• 在 bash 環境中設定環境變數：

  bash export GATEAI_API_KEY="YOUR_API_KEY"

• Windows PowerShell 環境下設定：

  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 為：

• 在 LangChain 中，將該地址作為 base_url。無需在 base_url 後加入 /chat/completions，LangChain 會自動處理路徑。

• 範例：

  python import os from langchain_openai import ChatOpenAI

  llm = ChatOpenAI( model="auto", api_key=os.environ["GATEAI_API_KEY"], base_url="", temperature=0, )

  response = llm.invoke("寫一句話說明 AI 模型路由器的作用。") print(response.content)

預期輸出：

AI 模型路由器會根據任務、路由規則或配置，將請求分發至合適的模型。

實際返回內容可能有所不同，因為 Gate.AI 路由會根據所選模型動態回應。

步驟 4：建立 LangChain 提示鏈

本步驟將可復用的提示、Gate.AI 支援的模型以及字串輸出解析器連結起來。

• 範例：

  python 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="", temperature=0, )

  prompt = ChatPromptTemplate.from_messages( [ ("system", "你是一個簡潔的技術助手。"), ("human", "用三個要點解釋 {topic}。"), ] )

  chain = prompt | llm | StrOutputParser()

  result = chain.invoke({"topic": "Gate.AI API 路由"}) 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="", temperature=0, )

  class WorkflowState(TypedDict): topic: str draft: str review: str

  def draft_node(state: WorkflowState) -> dict: response = llm.invoke( [ ("system", "你會寫簡短的技術說明。"), ("human", f"寫一個 {state['topic']} 的兩句話說明。"), ] ) return {"draft": response.content}

  def review_node(state: WorkflowState) -> dict: response = llm.invoke( [ ("system", "你會審核技術寫作的清晰度。"), ("human", f"審核這個草稿並提出一個改進建議：\n\n{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": "使用 LangGraph 的 Gate.AI"})

  print("草稿：", result["draft"]) print("審核：", 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="", temperature=0, )

模型 ID 請從 Gate.AI 模型目錄或 Gate.AI 控制台取得。請勿憑空猜測模型 ID，因為可用性受帳號、產品狀態及模型服務商規則影響（截至 2026年6月）。

哪些配置項最為關鍵？

| 配置項 | 範例值 | 使用場景 | 重要性說明 | | ----------------- | ------------------------------------------------------- | ----------------------------- | ------------------------------------------------ | | API 密鑰變數 | GATEAI_API_KEY | Shell 及 Python 程式碼 | 保證憑證不出現在原始碼檔案 | | Base URL | | ChatOpenAI(base_url=...) | 將兼容 OpenAI 的請求路由至 Gate.AI | | 模型 | auto 或 YOUR_MODEL_ID | ChatOpenAI(model=...) | 選擇自動路由或指定模型 | | 溫度 | 0 | ChatOpenAI(temperature=0) | 測試環境下減少輸出波動 |

如需保持路由行為一致，建議在 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 為
• 解決： 確保每個 ChatOpenAI 實例的 base_url 設為

現象： 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 使用 作为兼容 OpenAI 的請求路徑。LangChain 的 ChatOpenAI 應指向該 Base URL，而非更短的 /v1 路徑。

本整合是否需要修改 LangGraph 本身？
不需要。LangGraph 僅在節點函數內調用模型物件，Gate.AI 相關配置全部在 ChatOpenAI 設定中完成。