agent-platform-inference

Agent Platform GenAI 推論技能

本技能提供驗證與連線至 Google Cloud Agent Platform 以使用生成式 AI 模型的說明，涵蓋第一方（Gemini）與第三方（OpenMaaS）模型。

安全與確認層級（重要）

在代表使用者執行任何指令或腳本之前，你必須根據要求的動作遵守以下安全層級。（本技能為唯讀；其他安全層級已省略）：

1. 層級 R：唯讀 / 推論（client.models.generate_content、client.chat.completions.create、client.completions.create、client.embeddings.create）
   • 在代表使用者執行模型推論前，需要互動式確認，提供「是」/「否」選項，以避免非預期的費用或配額消耗。確認提示必須清楚說明提議的推論執行及其關鍵參數（例如目標模型 ID、SDK 選擇、輸入提示）。僅以自然語言改寫而未指定參數是不夠的。
   • 同輪限制：請勿在提出確認提示的同一輪中執行推論腳本或指令。請停止並等待使用者回覆；僅在獲得明確的「是」/核准後才執行。
   • 黃金標準範例：

     我將使用以下參數執行模型推論。請在繼續前確認以下資訊：

     • 模型 ID：deepseek-ai/deepseek-v3.2-maas
     • SDK：OpenAI SDK（透過 Vertex AI 端點）
     • 輸入提示：「解釋量子計算的概念...」
       您確認嗎？[是/否]

階段 0：環境設定

重要：在執行 scripts/ 目錄中的任何 Python 範例腳本（例如 scripts/openmaas_openai_sdk.py）之前，你必須按照以下步驟確保環境正確初始化：

1. Google Cloud 驗證：使用你的 Google Cloud 憑證進行驗證，並為 Agent Platform 存取設定有效的應用程式預設憑證 (ADC)：

   gcloud auth login
   gcloud auth application-default login
   

2. 啟用 API（如果尚未啟用）：

   gcloud services enable aiplatform.googleapis.com
   

3. 虛擬環境：建立並啟用專用的本機虛擬環境：

   python3 -m venv .venv
   source .venv/bin/activate
   

4. 安裝相依套件：安裝所需的 SDK：

   pip install -r scripts/requirements.txt
   

5. 驗證設定（選用）：一次執行所有範例腳本以驗證環境是否端到端正常運作：

   ./scripts/verify_all.sh
   

6. 執行：告知使用者每次執行本技能的 Python 程式碼片段時，必須確保已先啟用此虛擬環境。

<!-- disableFinding(LINE_OVER_80) -->

[!IMPORTANT]
重要：模型 ID 與可用性

• Gemini 模型：請參閱 Gemini 模型 以取得有效的模型 ID 與區域。
• OpenMaaS 模型：請參閱在 Agent Platform 上使用開放模型以取得 Llama、DeepSeek、Qwen 等資訊。
• 不完整清單：本技能中列出的模型 ID 僅為範例，可能不完整或已過時。
• 行動：在產生程式碼前，務必使用上方連結驗證模型 ID 與區域。

<!-- enableFinding(LINE_OVER_80) -->

工作流程決策樹

1. 模型系列識別：使用者是否已指定要呼叫 Gemini（第一方）模型或 OpenMaaS（第三方，例如 Llama、DeepSeek、Qwen）模型？

   • 否 -> 詢問使用者想使用哪個模型系列。如果他們提供特定模型名稱，則從名稱推斷系列。
   • 是 -> 前往步驟 2。

2. SDK 選擇：使用者想使用哪個 SDK？

   • Gemini + GenAI SDK（Gemini 的首選） -> 前往 [1. Gemini 模型]。
   • Gemini + 舊版 Vertex AI SDK -> 前往 [1. Gemini 模型]。
   • OpenMaaS + OpenAI SDK（OpenMaaS 的首選） -> 前往 [2. OpenMaaS 模型]。
   • OpenMaaS + GenAI SDK -> 前往 [2. OpenMaaS 模型]。
   • 不確定 -> 預設使用所選系列的首選 SDK。

3. 疑難排解：使用者是否回報錯誤（429 Resource Exhausted、400 User Validation、404 Not Found 等）？

   • 是 -> 前往 [3. 疑難排解與常見錯誤代碼]。
   • 否 -> 繼續步驟 2 的 SDK 選擇。

1. Gemini 模型

對於 Gemini 模型（例如 gemini-2.5-pro、gemini-3-flash-preview），GenAI SDK（google-genai）是首選方法。舊版 vertexai SDK 仍受支援，但新專案建議使用 GenAI SDK。

[!IMPORTANT]
預覽模型（包括 Gemini 3.1）通常僅在 global 區域可用。穩定模型可在 us-central1 及其他區域使用。

選擇正確的 SDK

• Gemini 模型：GenAI SDK（google-genai）是首選。如需相容性可使用 OpenAI SDK，或視需要改用舊版 SDK（vertexai）。
• OpenMaaS 模型：高度建議使用 OpenAI SDK。若有特定基礎架構需求，可使用 GenAI SDK 或舊版 SDK。

安裝

pip install google-genai

Python 範例（GenAI SDK - 首選）

完整程式碼請參閱 scripts/gemini_genai_sdk.py。

替代方案：OpenAI SDK（Chat Completions）

使用標準 OpenAI SDK 搭配 Agent Platform 端點。這非常適合跨相容性。

完整程式碼請參閱 scripts/gemini_openai_sdk.py。

舊版：Agent Platform SDK

舊版 vertexai SDK 仍廣泛使用，但新 Gemini 專案建議使用 google-genai。

完整程式碼請參閱 scripts/gemini_vertexai_sdk.py。

文件：Google GenAI SDK

文件：Agent Platform Gemini 模型

2. OpenMaaS 模型（Llama、DeepSeek、Qwen 等）

對於 OpenMaaS（模型即服務）模型，高度建議的方法是使用標準 OpenAI SDK 搭配特定的 Vertex AI 端點。

[!WARNING]
雖然 GenerativeModel 可以支援某些 OpenMaaS 模型，但不建議這麼做。請使用 OpenAI SDK 以獲得最佳相容性（尤其是 Chat Completions）。

安裝

pip install openai google-auth

OpenAI SDK 的驗證

你必須使用 Google Cloud OAuth 存取權杖作為 OpenAI SDK 的 API 金鑰。

import google.auth
from google.auth.transport.requests import Request

def get_gcp_access_token():
    creds, _ = google.auth.default()
    creds.refresh(Request())
    return creds.token

[!NOTE]
Google Cloud 存取權杖通常會在 1 小時後過期。上述 get_gcp_access_token() 函式會在呼叫時取得新的權杖。
<!-- disableFinding(LINE_OVER_80) -->
對於長時間執行的應用程式，請實作重新整理機制。詳細資訊請參閱重新整理存取權杖。
<!-- enableFinding(LINE_OVER_80) -->

設定（Base URL）

<!-- disableFinding(LINE_OVER_80) -->

• 全域端點（建議用於需要全域可用性的多數模型）：
  https://aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/global/endpoints/openapi
• 區域端點：
  https://{REGION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{REGION}/endpoints/openapi
  <!-- enableFinding(LINE_OVER_80) -->

Python 範例（OpenMaaS - Chat Completions）

完整程式碼請參閱 scripts/openmaas_openai_sdk.py。

[!TIP]
替代方案：環境變數
你可以在 shell 中設定環境變數，而無需更新程式碼。

export OPENAI_BASE_URL="https://aiplatform.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/global/endpoints/openapi"
export OPENAI_API_KEY="$(gcloud auth print-access-token)"

然後在沒有引數的情況下初始化用戶端：client = OpenAI()

Python 範例（OpenMaaS - Completions API）

以下模型支援舊版 Completions API：zai-org/glm-5-maas、moonshotai/kimi-k2-thinking-maas、minimaxai/minimax-m2-maas、deepseek-ai/deepseek-v3.1-maas 及 deepseek-ai/deepseek-v3.2-maas。

response = client.completions.create(
    model="deepseek-ai/deepseek-v3.2-maas",
    prompt="Once upon a time",
    max_tokens=100
)
print(response.choices[0].text)

Python 範例（OpenMaaS - Embeddings）

# 在 Model Garden 上驗證特定的 Embedding 模型 ID（例如 intfloat/multilingual-e5-small）
response = client.embeddings.create(
    model="intfloat/multilingual-e5-large-maas",
    input="The quick brown fox jumps over the lazy dog",
)
print(response.data[0].embedding)

替代方案：GenAI SDK

google-genai SDK 也可以透過 vertexai 後端存取 OpenMaaS 模型。

完整程式碼請參閱 scripts/openmaas_genai_sdk.py。

[!IMPORTANT]
模型 ID 格式：對於搭配 OpenMaaS 使用的 GenAI SDK，你必須使用完整路徑：publishers/PUBLISHER/models/MODEL（例如 publishers/zai-org/models/glm-5-maas）。

舊版：Agent Platform SDK（OpenMaaS）

對於 OpenMaaS，你也可以使用 GenerativeModel（如果支援）。

完整程式碼請參閱 scripts/openmaas_vertexai_sdk.py。

[!IMPORTANT]
模型 ID 格式：對於搭配 OpenMaaS 使用的 Agent Platform SDK，你必須使用完整路徑：publishers/PUBLISHER/models/MODEL。

模型參考與可用性

文件：在 Agent Platform 上使用開放模型

[!TIP]
自行部署以取得控制權：如果你需要專用硬體（GPU/TPU）、保證容量或 MaaS 未提供的特定區域配置，你可以將這些模型自行部署至 Agent Platform 端點。在 Model Garden 中搜尋模型，然後按一下「部署」以選擇你的機器類型。

[!IMPORTANT]
尋找推論範例：以上清單僅為起點。如需確定性的推論程式碼片段（尤其是 Chat Completions 酬載結構）：

1. 查閱在 Agent Platform 上使用開放模型清單。
2. 按一下特定模型的連結（例如「DeepSeek-V3」）以造訪其 Model Garden 頁面。
3. 在 Model Garden 頁面上尋找**「範例程式碼」或「使用此模型」**按鈕，以取得該特定模型版本的確切 curl 或 Python 程式碼。

[!NOTE]
此清單不完整。請參閱在 Agent Platform 上使用開放模型以取得支援模型的完整清單。

模型系列	模型 ID 範例	位置	備註
Llama 4	meta/llama-4-maverick-17b-128e-instruct-maas	us-east5
Llama 4	meta/llama-4-scout-17b-16e-instruct-maas	us-east5
Llama 3.3	meta/llama-3.3-70b-instruct-maas	us-central1
DeepSeek	deepseek-ai/deepseek-v3.2-maas	global	僅限全域
DeepSeek	deepseek-ai/deepseek-v3.1-maas	us-west2	僅限美西2
DeepSeek	deepseek-ai/deepseek-r1-0528-maas	us-central1
Qwen 3	qwen/qwen3-coder-480b-a35b-instruct-maas	global
Qwen 3	qwen/qwen3-next-80b-a3b-instruct-maas	global
Kimi	moonshotai/kimi-k2-thinking-maas	global
MiniMax	minimaxai/minimax-m2-maas	global
GLM	zai-org/glm-4.7-maas、zai-org/glm-5-maas	global

3. 疑難排解與常見錯誤代碼

429：Resource Exhausted

• 原因：OpenMaaS 與 Gemini 模型使用動態共用配額 (DSQ)。資源會根據可用性進行集區與動態分配。429 錯誤表示共用集區暫時耗盡，不一定表示你的特定專案配額已達上限（雖然也有可能）。
• 解決方案：實作嚴格的指數退避與重試策略。
• 高吞吐量：對於需要高吞吐量或保證容量的生產工作負載，請考慮佈建吞吐量 (PT)。
• 重要：透過一般雲端程序（Cloud Console）進行的配額增加不適用於 DSQ 限制。
• 文件：配額與限制 (DSQ)

400：User Validation Error

• 原因：請求格式無效、不支援的參數或模型 ID 錯誤。
• 行動：仔細檢查你的請求酬載與參數。驗證模型 ID 與區域是否正確。

404：Not Found / Model Not Available

• 原因：模型未啟用，或在指定的專案或區域中不可用。
• 行動：
  1. 檢查位置可用性：
     • OpenMaaS：驗證模型在你的區域中是否可用。請參閱依位置查看模型可用性。
     • Gemini：
       <!-- disableFinding(LINE_OVER_80) -->
       • 真相來源：務必查看 Gemini 模型位置以取得權威清單。
         <!-- enableFinding(LINE_OVER_80) -->
       • 預覽模型：所有預覽模型（例如 Gemini 3.1、實驗版本）通常僅在 us-central1 或 global 區域可用。
       • 穩定模型：（例如 Gemini 2.5 Pro）可在 us-central1、europe-west4 及許多其他區域使用。
       • 重要：如果你收到 404/400 錯誤，請嘗試將用戶端位置切換至 us-central1 或 global。
  2. 啟用 Llama 模型：對於 Llama 3.3 與 Llama 4，你必須先在 Model Garden 中啟用模型才能使用。前往 Model Garden，搜尋模型卡片（例如「Llama 3.3 API Service」），然後按一下啟用。之後才能進行推論請求。