如何將 Gate.AI 整合到 LangChain 與 LangGraph
Gate.AI 提供兼容 OpenAI 的 API 端點，開發者可透過該端點結合 LangChain 與 LangGraph，實現透過 Gate.AI 路由進行模型呼叫。當 Python 應用需要基於鏈（chain）的提示、基於圖（graph）的智能體工作流程，或希望建構一個不必為每家模型服務商重寫應用程式邏輯的統一模型閘道時，這套方案特別重要。本文將介紹本地環境搭建、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 .venvsource .venv/bin/activatepip 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 中建立一個聊天模型，並讓它送出符合 OpenAI 協議的請求給 Gate.AI。
根據 2026年6月的 Gate.AI 文件，OpenAI 相容的 Base URL 為：
https://api.gate.ai/openai/v1
在 LangChain 中，將此地址設定為
base_url。無需在base_url後再加上/chat/completions，LangChain 會自動處理路徑。範例：
import osfrom langchain_openai import ChatOpenAIllm = 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 osfrom langchain_openai import ChatOpenAIfrom langchain_core.prompts import ChatPromptTemplatefrom langchain_core.output_parsers import StrOutputParserllm = ChatOpenAI(model="auto",api_key=os.environ["GATEAI_API_KEY"],base_url="XX/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, ENDllm = ChatOpenAI(
model="auto",api_key=os.environ["GATEAI_API_KEY"],base_url="https://api.gate.ai/openai/v1",temperature=0,
)
class WorkflowState(TypedDict):
topic: strdraft: strreview: 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- 範例：```pythonllm = 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月）。
哪些設定項最為關鍵？
| 設定項 | 範例值 | 使用情境 | 重要性說明 |
|---|---|---|---|
| API 金鑰變數 | GATEAI_API_KEY | Shell 與 Python 程式碼 | 確保憑證不會出現在原始碼檔案中 |
| Base URL | /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
下一步可以設定或建構哪些內容？
- 透過 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 的設定中完成。
