Gate.AI›博客›如何將 Gate.AI 整合至 LangChain 與 LangGraph

    如何將 Gate.AI 整合至 LangChain 與 LangGraph

    指南

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

    • 建立並啟用虛擬環境：

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

    • Windows PowerShell 環境下啟用命令：

      1. .venv\Scripts\Activate.ps1

    安裝完成後，應可正常匯入 langchain_openai 與 langgraph。

    步驟 2：儲存 Gate.AI API 金鑰

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

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

      1. export GATEAI_API_KEY="YOUR_API_KEY"

    • Windows PowerShell 環境下設定：

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

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

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

    • 範例：

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

    預期輸出：

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

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

    步驟 4：建構 LangChain 提示鏈

    本步驟將可重複使用的提示、Gate.AI 支援的模型，以及字串輸出解析器串接起來。

    • 範例：

      1. import os
      2. from langchain_openai import ChatOpenAI
      3. from langchain_core.prompts import ChatPromptTemplate
      4. from langchain_core.output_parsers import StrOutputParser
      6. llm = ChatOpenAI(
      7.     model="auto",
      8.     api_key=os.environ["GATEAI_API_KEY"],
      9.     base_url="https://api.gate.ai/openai/v1",
      10.     temperature=0,
      11. )
      13. prompt = ChatPromptTemplate.from_messages(
      14.     [
      15.         ("system", "You are a concise technical assistant."),
      16.         ("human", "Explain {topic} in three bullet points."),
      17.     ]
      18. )
      20. chain = prompt | llm | StrOutputParser()
      22. result = chain.invoke({"topic": "Gate.AI API routing"})
      23. 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(

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

      )

      class WorkflowState(TypedDict):

      1. topic: str
      2. draft: str
      3. review: str

      def draft_node(state: WorkflowState) -> dict:

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

      def review_node(state: WorkflowState) -> dict:

      1. response = llm.invoke(
      2.     [
      3.         ("system", "You review technical writing for clarity."),
      4.         ("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”]) 

    2. 你將看到產生的草稿與審核建議。若工作流程僅回傳草稿，請確認 `draft` 至 `review` 的邊已正確設定。
    4. ## 步驟 6：將自動路由替換為指定模型
    6. 如需固定模型行為，使整合更可控，可依下列方式操作：
    8. - 若已啟用 Gate.AI 自動路由且帳戶支援，初次測試可用 `model="auto"`
    9. - 需結果可重現、評測一致性、延遲測試或生產審核時，請使用具體的 Gate.AI 模型 ID
    11. - 範例：
    13.   ```python
    14.   llm = ChatOpenAI(
    15.       model="YOUR_MODEL_ID",
    16.       api_key=os.environ["GATEAI_API_KEY"],
    17.       base_url="https://api.gate.ai/openai/v1",
    18.       temperature=0,
    19.   )

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

    哪些配置項最為關鍵？

    配置項 範例值 使用場景 重要性說明
    API 金鑰變數 GATEAI_API_KEY Shell 及 Python 程式碼 確保憑證不出現在原始碼檔案
    Base URL https://api.gate.ai/openai/v1 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 為 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

    下一步可配置或建構哪些內容？

    常見問題解答

    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 設定中完成。

    相關文章

    使用 Gate.AI 構建多模型 AI 應用

    使用 Gate.AI 構建多模型 AI 應用

    打造適用於生產環境的 Gate.AI 智能代理工作流程

    打造適用於生產環境的 Gate.AI 智能代理工作流程

    Gate.AI 快速入門指南：使用 Python、Node.js 與 curl 存取 API

    Gate.AI 快速入門指南：使用 Python、Node.js 與 curl 存取 API