如何建立 Gate.AI 與 LlamaIndex 的整合

Gate.AI LlamaIndex 整合指南

Gate.AI 提供與 OpenAI 相容的 API，讓 LlamaIndex 應用程式能透過自訂 API 基礎位址（base URL）與 API 金鑰呼叫 Gate.AI 模型，使開發者能將 LLM 請求路由到索引與查詢工作流程中。根據 Gate.AI 文件，截至 2026 年 6 月，OpenAI 相容的基礎 URL 為 /openai/v1，而 LlamaIndex 的 OpenAILike 封裝是專為第三方 OpenAI 相容 API 設計的。本指南涵蓋基於 Python 的 gate.ai llamaindex 整合，不涉及生產環境的嵌入模型選型、向量資料庫部署，或企業等級的存取控制設計。

前置條件

• 擁有 Gate.AI API 金鑰，且帳戶餘額充足。
• 本機開發環境已安裝 Python 3.10 以上版本。

如需更完整的 API 設定背景，請參考 Gate.AI API 整合指南。

完成本指南後你將能做什麼？

完成 gate.ai llamaindex 整合後，你可以透過 LlamaIndex 呼叫 Gate.AI 模型，使用直接聊天請求來驗證連線，並執行簡單的查詢引擎冒煙測試。

本指南主要介紹 OpenAI 相容的 LlamaIndex LLM 設定，不涉及生產用嵌入模型、文件匯入流程，或託管式向量儲存的配置。

步驟 1：建立 Gate.AI API 金鑰

此步驟用於準備 LlamaIndex 驗證 Gate.AI 請求所需的憑證。

• 打開 Gate.AI，進入 Dashboard → Settings → API Keys，建立 API 金鑰，並將金鑰複製到本機安全的 secret 儲存中。Gate.AI 文件顯示，API 金鑰在設定範例中以 sk-or-v1- 開頭（截至 2026 年 6 月）。
• 不要將 API 金鑰寫死在應用程式程式碼中。建議使用環境變數進行管理。

步驟 2：安裝 LlamaIndex 相關套件

此步驟安裝 LlamaIndex，以及 gate.ai llamaindex 整合所需的 OpenAI 相容 LLM 封裝套件。

python -m venv .venv
source .venv/bin/activate
pip install llama-index llama-index-llms-openai-like

llama-index-llms-openai-like 套件是針對 OpenAI 相容 API 發布的，提供下文使用的 OpenAILike 整合。

步驟 3：匯出 Gate.AI 環境變數

此步驟會將 API 金鑰與模型識別碼保存在 Python 檔案之外。

export GATEAI_API_KEY="YOUR_API_KEY"
export GATEAI_MODEL_ID="YOUR_MODEL_ID"

將 YOUR_API_KEY 取代為你的 Gate.AI API 金鑰，將 YOUR_MODEL_ID 取代為 Gate.AI 模型清單，或在模型市場中複製的模型 ID。首次測試建議使用固定的模型 ID，方便排查錯誤。

步驟 4：設定 OpenAILike LLM

此步驟讓 LlamaIndex 將 LLM 呼叫送往 Gate.AI 的 OpenAI 相容端點，而不是預設的 OpenAI API。

import os
from llama_index.core.llms import ChatMessage
from llama_index.llms.openai_like import OpenAILike
gateai_api_key = os.environ["GATEAI_API_KEY"]
gateai_model_id = os.environ["GATEAI_MODEL_ID"]
llm = OpenAILike(
    model=gateai_model_id,
    api_base="https://api.gate.ai/openai/v1",
    api_key=gateai_api_key,
    context_window=3900,
    max_tokens=512,
    is_chat_model=True,
    is_function_calling_model=False,
)
response = llm.chat([
    ChatMessage(
        role="user",
        content="Reply with one sentence: Gate.AI is connected to LlamaIndex."
    )
])
print(response.message.content)

你應該會看到模型回傳簡短的回應，以確認 Gate.AI 已連接到 LlamaIndex。若請求回傳 401，請檢查 API 金鑰；若回傳 404，請確認基礎 URL 精確為 https://api.gate.ai/openai/v1，而不是 https://api.gate.ai/v1。

步驟 5：將 Gate.AI 連接到 LlamaIndex 查詢引擎

此步驟驗證 LlamaIndex 能在基本查詢工作流程中使用已設定的 Gate.AI LLM。

import os
from llama_index.core import Document, Settings, VectorStoreIndex
from llama_index.core import MockEmbedding
from llama_index.llms.openai_like import OpenAILike
llm = OpenAILike(
    model=os.environ["GATEAI_MODEL_ID"],
    api_base="https://api.gate.ai/openai/v1",
    api_key=os.environ["GATEAI_API_KEY"],
    context_window=3900,
    max_tokens=512,
    is_chat_model=True,
    is_function_calling_model=False,
)
Settings.llm = llm
# 僅用於冒煙測試。實際 RAG 請使用生產用嵌入模型取代 MockEmbedding。
Settings.embed_model = MockEmbedding(embed_dim=384)
documents = [
    Document(
        text="Gate.AI is configured as the LLM provider for this LlamaIndex test."
    )
]
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
answer = query_engine.query("Which LLM provider is configured?")
print(answer)

LlamaIndex 文件顯示 MockEmbedding 是可配置的嵌入物件；本指南僅為避免在冒煙測試階段引入生產用嵌入依賴而使用 MockEmbedding。實際檢索增強生成（RAG）情境請改用生產用嵌入模型，並確保嵌入模型能符合你的資料、成本與安全需求。

這些設定項目分別控制什麼？

設定項目	使用位置	輸入內容
api_base	OpenAILike(…)	/openai/v1
api_key	OpenAILike(…)	Gate.AI API 金鑰（GATEAI_API_KEY）
model	OpenAILike(…)	Gate.AI 模型 ID（GATEAI_MODEL_ID）
context_window	OpenAILike(…)	模型上下文長度（若已知）；冒煙測試建議使用保守數值
is_chat_model	OpenAILike(…)	聊天模型呼叫請設為 True
is_function_calling_model	OpenAILike(…)	若所選 Gate.AI 模型與工作流程支援工具，則設為 True，否則為 False

最重要的設定項目是 api_base。Gate.AI 文件指出 OpenAI 相容 API 的路徑需使用 /openai/v1，常見錯誤是只填 /v1 而漏掉 /openai 前綴。

Gate.AI LlamaIndex 整合無法正常運作？排查清單

• 症狀：請求回傳 401 或驗證失敗。
  • 原因：API 金鑰遺漏、過期、複製錯誤，或未在目前的 shell 匯出。
  • 解法：重新匯出 GATEAI_API_KEY，必要時重新啟動終端機工作階段，並在 Gate.AI Dashboard → Settings → API Keys 確認金鑰無誤。
• 症狀：請求回傳 404。
  • 原因：基礎位址錯誤，常見為 https://api.gate.ai/v1 或使用了完整端點路徑而非基礎 URL。
  • 解法：將 api_base 設為 https://api.gate.ai/openai/v1。
• 症狀：LlamaIndex 丟出「未知模型」錯誤。
  • 原因：應用可能使用標準 OpenAI 封裝，導致只驗證 OpenAI 的模型名稱，而非第三方模型 ID。
  • 解法：從 llama_index.llms.openai_like 匯入 OpenAILike，並透過 model 傳入 Gate.AI 模型 ID。
• 症狀：直接 LLM 測試正常，但查詢引擎測試在索引階段失敗。
  • 原因：查詢引擎需要嵌入模型來建立向量索引。
  • 解法：冒煙測試可用 MockEmbedding；實際 RAG 流程需設定生產用嵌入模型。
• 症狀：回應為空，或模型不可用。
  • 原因：所選模型 ID 未對你的 Gate.AI 帳戶開放，或請求路由未設定正確。
  • 解法：從 Gate.AI 複製目前的模型 ID，確認帳戶餘額，並用簡短提示重試。

下一步可以設定或建置什麼？

當 gate.ai llamaindex 整合完成本機測試後，你可以將相同的 Gate.AI API 設定連到開發工具與相關框架：

• 需要在編輯器中使用 AI 程式碼輔助時，可用 Gate.AI in Cursor。
• 需要透過 Anthropic 相容設定實作終端機編碼工作流程時，可用 Gate.AI with Claude Code。
• 比較代理或基於圖的工作流程編排框架時，可用 Gate.AI with LangChain and LangGraph。

生產級 LlamaIndex 應用的下一步通常是：替換 MockEmbedding、新增文件載入，並選擇符合你檢索需求的向量儲存。

常見問題解答

我可以用一般的 LlamaIndex OpenAI 封裝連接 Gate.AI 嗎？
首次 gate.ai llamaindex 整合建議使用 OpenAILike，因為它是專為第三方 OpenAI 相容 API 設計。標準 OpenAI 封裝在部分情境下也可用，但模型名稱驗證可能導致不必要的設定錯誤。

模型參數可以用 auto 嗎？
首次測試建議使用固定的 Gate.AI 模型 ID，方便診斷連線問題。自動路由通常只在確認 Gate.AI 帳戶與工作流程支援後再使用。

LlamaIndex 一定要用嵌入模型嗎？
直接 LLM 呼叫不需要嵌入模型。基於向量的 RAG 工作流程通常需要嵌入模型。本例使用 MockEmbedding 只是為了聚焦在 Gate.AI LLM 連線的冒煙測試。

LlamaIndex 應用要使用哪個 Gate.AI 基礎 URL？
api_base 請使用 https://api.gate.ai/openai/v1。不要使用 https://api.gate.ai/v1，也不要在 api_base 中額外加入 /chat/completions。