如何打造 Gate.AI 與 LlamaIndex 的整合

Gate.AI LlamaIndex 集成指南

Gate.AI 提供與 OpenAI 相容的 API，允許 LlamaIndex 應用程式透過自訂 API 基礎位址與 API 金鑰呼叫 Gate.AI 模型，使開發者能將 LLM 請求導入索引與查詢工作流程中。根據 Gate.AI 文件，截至2026年6月，OpenAI 相容的基礎 URL 為 https://api.gate.ai/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(…)	https://api.gate.ai/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。
  • 原因：基礎 URL 錯誤，常見為 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。